|
| 1 | +# @finos/calm-server |
| 2 | + |
| 3 | +The `calm-server` executable provides a standalone HTTP server implementation of CALM validation functionality. |
| 4 | + |
| 5 | +## Architecture |
| 6 | + |
| 7 | +The calm-server provides: |
| 8 | + |
| 9 | +- **Bundled CALM Schemas** - All CALM schemas (release and draft) are bundled during build |
| 10 | +- **Health Check Endpoint** (`/health`) - Status endpoint for monitoring |
| 11 | +- **Validation Endpoint** (`/calm/validate`) - POST endpoint for validating CALM architectures |
| 12 | +- **Rate Limiting** - Protects against abuse with 100 requests per 15 minutes per IP |
| 13 | + |
| 14 | +## Project Structure |
| 15 | + |
| 16 | +``` |
| 17 | +calm-server/ |
| 18 | +├── src/ |
| 19 | +│ ├── index.ts # Entry point, CLI argument parsing |
| 20 | +│ ├── server/ |
| 21 | +│ │ ├── cli-server.ts # Express server startup |
| 22 | +│ │ └── routes/ |
| 23 | +│ │ ├── routes.ts # Router setup |
| 24 | +│ │ ├── health-route.ts # Health check endpoint |
| 25 | +│ │ └── validation-route.ts # Architecture validation endpoint |
| 26 | +│ └── *.spec.ts # Unit tests |
| 27 | +├── dist/ |
| 28 | +│ ├── index.js # Compiled executable |
| 29 | +│ └── calm/ # Bundled CALM schemas |
| 30 | +│ ├── release/ # Released schema versions |
| 31 | +│ └── draft/ # Draft schema versions |
| 32 | +├── package.json |
| 33 | +├── tsconfig.json |
| 34 | +├── tsconfig.build.json |
| 35 | +├── tsup.config.ts # Build configuration |
| 36 | +├── vitest.config.ts # Test configuration |
| 37 | +└── eslint.config.mjs # Linting configuration |
| 38 | +``` |
| 39 | + |
| 40 | +## Building & Running |
| 41 | + |
| 42 | +### Build the package |
| 43 | +```bash |
| 44 | +npm run build:calm-server |
| 45 | +``` |
| 46 | + |
| 47 | +This builds the TypeScript code and copies all CALM schemas from `calm/release` and `calm/draft` into `dist/calm/`. |
| 48 | + |
| 49 | +### Run the server locally |
| 50 | +```bash |
| 51 | +# Using bundled schemas (default) |
| 52 | +./calm-server/dist/index.js --port 3000 --verbose |
| 53 | + |
| 54 | +# Or with custom schemas |
| 55 | +./calm-server/dist/index.js -s ../calm/release --port 3000 --verbose |
| 56 | + |
| 57 | +# Or using npm |
| 58 | +npm run build:calm-server |
| 59 | +node calm-server/dist/index.js --port 3000 |
| 60 | +``` |
| 61 | + |
| 62 | +### Global installation (for development) |
| 63 | +```bash |
| 64 | +npm run link:calm-server |
| 65 | + |
| 66 | +# Use bundled schemas (default) |
| 67 | +calm-server --port 3000 |
| 68 | + |
| 69 | +# Or provide custom schemas |
| 70 | +calm-server -s /path/to/schemas --port 3000 |
| 71 | +``` |
| 72 | + |
| 73 | +## Command-Line Options |
| 74 | + |
| 75 | +``` |
| 76 | +Usage: calm-server [options] |
| 77 | +
|
| 78 | +CALM Server - A server implementation for the Common Architecture Language Model |
| 79 | +
|
| 80 | +Options: |
| 81 | + -V, --version output the version number |
| 82 | + --port <port> Port to run the server on (default: "3000") |
| 83 | + --host <host> Host to bind the server to (default: "127.0.0.1") |
| 84 | + -s, --schema-directory <path> Path to the directory containing the meta schemas to use. |
| 85 | + (default: bundled schemas in dist/calm) |
| 86 | + -v, --verbose Enable verbose logging (default: false) |
| 87 | + -c, --calm-hub-url <url> URL to CALMHub instance |
| 88 | + --rate-limit-window <ms> Rate limit window in milliseconds (default: 900000 = 15 minutes) |
| 89 | + --rate-limit-max <requests> Max requests per IP within the rate limit window (default: 100) |
| 90 | + -h, --help display help for command |
| 91 | +``` |
| 92 | + |
| 93 | +### Security Notes |
| 94 | + |
| 95 | +- **Default Host**: The server binds to `127.0.0.1` (localhost) by default |
| 96 | +- **No Authentication**: The server has **NO authentication or authorization controls** |
| 97 | +- **Network Exposure Warning**: If you bind to a non-localhost host (e.g., `0.0.0.0`, `::`, public IP), a warning will be logged. Only do this in trusted network environments |
| 98 | + |
| 99 | +## Testing |
| 100 | + |
| 101 | +### Run tests |
| 102 | +```bash |
| 103 | +npm run test:calm-server |
| 104 | +``` |
| 105 | + |
| 106 | +### Test the health endpoint |
| 107 | +```bash |
| 108 | +# Start the server (uses bundled schemas) |
| 109 | +node calm-server/dist/index.js & |
| 110 | +SERVER_PID=$! |
| 111 | + |
| 112 | +# Test health |
| 113 | +curl http://localhost:3000/health |
| 114 | + |
| 115 | +# Clean up |
| 116 | +kill $SERVER_PID |
| 117 | +``` |
| 118 | + |
| 119 | +### Test the validation endpoint |
| 120 | +```bash |
| 121 | +# With a CALM architecture JSON |
| 122 | +curl -X POST http://localhost:3000/calm/validate \ |
| 123 | + -H "Content-Type: application/json" \ |
| 124 | + -d '{"architecture": "{\"$schema\": \"https://...\"...}"}' |
| 125 | +``` |
| 126 | + |
| 127 | +## Dependencies |
| 128 | + |
| 129 | +- `@finos/calm-shared` - Shared utilities, validation logic, schema handling |
| 130 | +- `express` - HTTP server framework |
| 131 | +- `express-rate-limit` - Rate limiting middleware |
| 132 | +- `commander` - CLI argument parsing |
| 133 | + |
| 134 | +## Development Notes |
| 135 | + |
| 136 | +### Copying from CLI |
| 137 | + |
| 138 | +The calm-server implementation mirrors the server functionality from the CLI package (`cli/src/server/`): |
| 139 | + |
| 140 | +- `src/server/cli-server.ts` - Express server setup |
| 141 | +- `src/server/routes/routes.ts` - Route configuration |
| 142 | +- `src/server/routes/health-route.ts` - Health check |
| 143 | +- `src/server/routes/validation-route.ts` - Architecture validation |
| 144 | + |
| 145 | +Both implementations share the same core logic for validation and schema handling through the `@finos/calm-shared` package. |
| 146 | + |
| 147 | +### Build Configuration |
| 148 | + |
| 149 | +The tsup configuration: |
| 150 | +- Bundles shared packages (`@finos/calm-shared`, `@finos/calm-models`, `@finos/calm-widgets`) |
| 151 | +- Adds Node.js shebang via banner for executable |
| 152 | +- Outputs CommonJS format with tree-shaking enabled |
| 153 | +- Marks external `node_modules` as external (not bundled) |
| 154 | + |
| 155 | +## Linking for Development |
| 156 | + |
| 157 | +After building, you can link the executable globally: |
| 158 | + |
| 159 | +```bash |
| 160 | +npm run link:calm-server |
| 161 | +calm-server --help |
| 162 | +``` |
| 163 | + |
| 164 | +This allows testing the executable without needing to build or reference the dist directory. |
| 165 | + |
| 166 | +## License |
| 167 | + |
| 168 | +Apache-2.0 |
0 commit comments