@finos/calm-server

A standalone HTTP server for the Common Architecture Language Model (CALM) validation functionality.

The calm-server executable provides HTTP endpoints for CALM architecture validation.

Features

• Bundled CALM Schemas - All CALM schemas (release and draft) are bundled with the executable
• Health Check Endpoint (GET /health) - Status endpoint for monitoring
• Validation Endpoint (POST /calm/validate) - Validate CALM architectures against schemas

Usage

Starting the Server

# Basic usage (uses bundled schemas by default)
calm-server

# With custom port
calm-server --port 8080

# With verbose logging
calm-server --port 3000 --verbose

# Or provide a custom schema directory
calm-server -s /path/to/calm/schemas --port 3000

Command-Line Options

Usage: calm-server [options]

Options:
  -V, --version                   output the version number
  --port <port>                   Port to run the server on (default: "3000")
  --host <host>                   Host to bind the server to (default: "127.0.0.1")
  -s, --schema-directory <path>   Path to the directory containing the meta schemas
                                  (default: bundled schemas in dist/calm)
  -v, --verbose                   Enable verbose logging (default: false)
  -c, --calm-hub-url <url>        URL to CALMHub instance
  --rate-limit-window <ms>        Rate limit window in milliseconds (default: 900000 = 15 minutes)
  --rate-limit-max <requests>     Max requests per IP within the rate limit window (default: 100)
  -h, --help                      display help for command

Security Considerations

• Default Host is Localhost: By default, the server binds to 127.0.0.1 for security
• No Built-in Authentication: This server has no authentication or authorization controls
• Network Exposure: When binding to non-localhost addresses, a security warning is logged. Only expose to the network in trusted environments

API Endpoints

Health Check

Check if the server is running:

curl http://localhost:3000/health

Response:

{
  "status": "OK"
}

Validate Architecture

Validate a CALM architecture document:

curl -X POST http://localhost:3000/calm/validate \
  -H "Content-Type: application/json" \
  -d '{
    "architecture": "{\"$schema\":\"https://calm.finos.org/release/1.2/meta/calm.json\",\"nodes\":[]}"
  }'

Response (success):

{
  "jsonSchemaValidationOutputs":[],
  "spectralSchemaValidationOutputs":[],
  "hasErrors":false,
  "hasWarnings":false
}

Response (validation errors):

{
  "jsonSchemaValidationOutputs":[],
  "spectralSchemaValidationOutputs":[...],
  "hasErrors":true,
  "hasWarnings":false
}

Development

Building

# From repository root
npm run build:calm-server

# Or from calm-server directory
cd calm-server
npm run build

Testing

# From repository root
npm run test:calm-server

# Or from calm-server directory
cd calm-server
npm test

# With coverage
npm test -- --coverage

Linting

# From calm-server directory
npm run lint
npm run lint-fix

License

Apache-2.0