From af9d4761dcb76a141fcf427bcc61274e220bbf66 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jes=C3=BAs=20Fern=C3=A1ndez?= <7312236+fernandezcuesta@users.noreply.github.com> Date: Mon, 14 Sep 2026 09:31:21 +0200 Subject: [PATCH 1/9] feat: leverage reusable cli standard options, add gprc max recv message size MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Jesús Fernández <7312236+fernandezcuesta@users.noreply.github.com> --- README.md | 39 ++++++ USAGE.md | 92 +++++++++++-- package-lock.json | 48 ++----- src/cli/cli.test.ts | 272 +++++++++++++++++++++++++++++++++++++++ src/cli/cli.ts | 232 +++++++++++++++++++++++++++++++++ src/function/function.ts | 12 +- src/index.ts | 3 + src/runtime/runtime.ts | 14 +- src/serve/serve.ts | 4 +- 9 files changed, 662 insertions(+), 54 deletions(-) create mode 100644 src/cli/cli.test.ts create mode 100644 src/cli/cli.ts diff --git a/README.md b/README.md index 84822f3..45db847 100644 --- a/README.md +++ b/README.md @@ -58,6 +58,36 @@ import { compose } from "./my-function.js"; serve(compose); ``` +### Custom Flags with the Shareable CLI + +If your function needs its own command-line flags or environment variables, use the +`CLI` class instead of calling `serve()` directly. It provides the same standard +flags that `serve()` uses, plus a way to register your own: + +```typescript +import { CLI, serve } from "@crossplane-org/function-sdk-typescript"; +import { compose } from "./my-function.js"; + +const cli = new CLI({ + flags: { + "cache-size": { type: "string", default: "100", env: "CACHE_SIZE", description: "Number of entries to cache." }, + }, +}); + +const parsed = cli.parse(); +if (parsed.help) { + process.stdout.write(cli.helpText() + "\n"); + process.exit(0); +} + +serve(compose, { argv: [], serverOptions: cli.standardOptions(), logger: cli.logger() }); +``` + +See [USAGE.md](USAGE.md#custom-flags-with-the-shareable-cli) for the full list of +standard flags, environment variables, flag spec options, and a more complete example. + +### Using the Full FunctionHandler Interface + If your function needs the full interface, implement `FunctionHandler` — `serve()` accepts either: @@ -667,11 +697,20 @@ import { ComposeFunction, ComposeResponse, ServeOptions, + + // Shareable CLI + CLI, + CLIOptions, + FlagSpec, } from "@crossplane-org/function-sdk-typescript"; ``` ### Core Functions +#### CLI + +- **`CLI`** - Shareable, extensible CLI with standard flags, env var support, and custom flag registration. See [USAGE.md](USAGE.md#shareable-cli) for the full method list. + #### Server Functions - **`serve(fn, opts?)`** - Run a `ComposeFunction` or `FunctionHandler` as a gRPC server diff --git a/USAGE.md b/USAGE.md index 3adc4e2..b8fde04 100644 --- a/USAGE.md +++ b/USAGE.md @@ -153,18 +153,14 @@ and `SIGTERM`. It accepts either a `ComposeFunction` or a `FunctionHandler`. Every function served this way accepts the same flags: -``` -Usage: main.js [flags] - -A Crossplane composition function. - -Flags: - --address Address to listen for gRPC connections. Default 0.0.0.0:9443. - -d, --debug Emit debug logs. - --insecure Run without mTLS credentials. - --tls-server-certs-dir Directory holding tls.key, tls.crt and ca.crt. Default /tls/server. - -h, --help Show this help. -``` +| Flag | Env | Default | Description | +|------|-----|---------|-------------| +| `--address` | `ADDRESS` | `0.0.0.0:9443` | gRPC listen address | +| `--debug` / `-d` | `DEBUG` | `false` | Emit debug logs | +| `--insecure` | `INSECURE` | `false` | Run without mTLS | +| `--tls-server-certs-dir` | `TLS_SERVER_CERTS_DIR` | `/tls/server` | mTLS certificate directory | +| `--max-recv-message-size` | `MAX_RECV_MESSAGE_SIZE` | `4` | Max gRPC message size in MB | +| `--help` / `-h` | — | `false` | Show help text | `serve()` takes an options object for the cases where the defaults do not fit: @@ -192,6 +188,69 @@ node dist/main.js --tls-server-certs-dir /path/to/certs ## Advanced Usage +### Custom Flags with the Shareable CLI + +If your function needs its own command-line flags or environment variables, use the +`CLI` class. It provides the same standard flags that `serve()` uses, plus a way to +register your own: + +```typescript +#!/usr/bin/env node + +import { CLI, serve } from "@crossplane-org/function-sdk-typescript"; +import { compose } from "./my-function.js"; + +const cli = new CLI({ + flags: { + "cache-size": { + type: "string", + default: "100", + env: "CACHE_SIZE", + description: "Number of entries to cache.", + }, + "verbose": { + type: "boolean", + default: false, + short: "v", + env: "VERBOSE", + description: "Enable verbose output.", + }, + }, +}); + +try { + const parsed = cli.parse(); + if (parsed.help) { + process.stdout.write(cli.helpText() + "\n"); + process.exit(0); + } + + // Pass the CLI's standard options and logger to serve, skipping its + // internal argument parsing by supplying an empty argv. + serve(compose, { + argv: [], + serverOptions: cli.standardOptions(), + logger: cli.logger(), + }); + + const cacheSize = Number(parsed["cache-size"]); +} catch (error) { + process.stderr.write(`${cli.name}: ${error instanceof Error ? error.message : error}\n`); + process.exit(2); +} +``` + +Each custom flag supports: + +- **`type`** — `"string"` or `"boolean"`. +- **`default`** — Value used when neither the CLI argument nor the env var is set. +- **`short`** — Single-character alias (e.g. `-v`). +- **`env`** — Environment variable name. Resolution order: CLI argument > env var > default. +- **`description`** — Shown in `--help` output. + +Custom flag names must not collide with the standard flags; the constructor throws if +they do. + ### Building the Server Yourself `serve()` is the recommended entry point, but the pieces it uses are exported, so a @@ -365,6 +424,15 @@ normal(rsp, "Function completed successfully"); - `normal(rsp, message)` - Add normal info result - `update(source, target)` - Deep merge resources using ts-deepmerge +### Shareable CLI + +- `new CLI(opts?)` - Create a CLI with optional custom flags +- `cli.parse(argv?)` - Parse arguments (CLI arg > env var > default) +- `cli.standardOptions()` - Get `ServerOptions` from the standard flags +- `cli.logger()` - Get a pino Logger configured from `--debug` +- `cli.helpText()` - Generate help text including custom flags +- `cli.name` - The program name used in help text + ### Runtime - `serve(fn, opts?)` - Run a `ComposeFunction` or `FunctionHandler` as a gRPC server: parses flags, builds a logger, starts the server, handles shutdown diff --git a/package-lock.json b/package-lock.json index c7469c8..dc29a46 100644 --- a/package-lock.json +++ b/package-lock.json @@ -479,6 +479,7 @@ "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.20.0.tgz", "integrity": "sha512-Thbli+OlOj+iMPYFBVBfJ3OmCAnaSyNn4M1vz9T6Gka5Jt9ba/HIR56joy65tY6kx/FCF5VXNB819Y7/GUrBGA==", "license": "MIT", + "peer": true, "dependencies": { "fast-deep-equal": "^3.1.3", "fast-uri": "^3.0.1", @@ -511,7 +512,6 @@ "integrity": "sha512-1Duyg48TdJNdyhEB8Xn1L36bT9Pv6GUtlKjHxOys8xkaF/rQq3XJE+bAurSK/AgIz5mGFsb77cn9Pb20+WCScw==", "dev": true, "license": "MIT", - "peer": true, "funding": { "url": "https://github.com/sponsors/oxc-project" } @@ -592,7 +592,6 @@ "os": [ "android" ], - "peer": true, "engines": { "node": "^20.19.0 || >=22.12.0" } @@ -610,7 +609,6 @@ "os": [ "android" ], - "peer": true, "engines": { "node": "^20.19.0 || >=22.12.0" } @@ -628,7 +626,6 @@ "os": [ "darwin" ], - "peer": true, "engines": { "node": "^20.19.0 || >=22.12.0" } @@ -646,7 +643,6 @@ "os": [ "darwin" ], - "peer": true, "engines": { "node": "^20.19.0 || >=22.12.0" } @@ -664,7 +660,6 @@ "os": [ "freebsd" ], - "peer": true, "engines": { "node": "^20.19.0 || >=22.12.0" } @@ -682,7 +677,6 @@ "os": [ "linux" ], - "peer": true, "engines": { "node": "^20.19.0 || >=22.12.0" } @@ -703,7 +697,6 @@ "os": [ "linux" ], - "peer": true, "engines": { "node": "^20.19.0 || >=22.12.0" } @@ -724,7 +717,6 @@ "os": [ "linux" ], - "peer": true, "engines": { "node": "^20.19.0 || >=22.12.0" } @@ -745,7 +737,6 @@ "os": [ "linux" ], - "peer": true, "engines": { "node": "^20.19.0 || >=22.12.0" } @@ -766,7 +757,6 @@ "os": [ "linux" ], - "peer": true, "engines": { "node": "^20.19.0 || >=22.12.0" } @@ -787,7 +777,6 @@ "os": [ "linux" ], - "peer": true, "engines": { "node": "^20.19.0 || >=22.12.0" } @@ -808,7 +797,6 @@ "os": [ "linux" ], - "peer": true, "engines": { "node": "^20.19.0 || >=22.12.0" } @@ -826,7 +814,6 @@ "os": [ "openharmony" ], - "peer": true, "engines": { "node": "^20.19.0 || >=22.12.0" } @@ -844,7 +831,6 @@ "os": [ "win32" ], - "peer": true, "engines": { "node": "^20.19.0 || >=22.12.0" } @@ -862,7 +848,6 @@ "os": [ "win32" ], - "peer": true, "engines": { "node": "^20.19.0 || >=22.12.0" } @@ -872,8 +857,7 @@ "resolved": "https://registry.npmjs.org/@rolldown/pluginutils/-/pluginutils-1.0.1.tgz", "integrity": "sha512-2j9bGt5Jh8hj+vPtgzPtl72j0yRxHAyumoo6TNfAjsLB04UtpSvPbPcDcBMxz7n+9CYB0c1GxQFxYRg2jimqGw==", "dev": true, - "license": "MIT", - "peer": true + "license": "MIT" }, "node_modules/@tsconfig/node10": { "version": "1.0.12", @@ -947,6 +931,7 @@ "resolved": "https://registry.npmjs.org/@types/node/-/node-26.6.6.tgz", "integrity": "sha512-MzQj+8Kx3XI40OmUAE6Qoh58ZMNstNNMwn2nfd3qWsfe7nDNSqJNzes4njhz6AHwrSHOffSLwXU6yb474Q4aog==", "license": "MIT", + "peer": true, "dependencies": { "undici-types": "~8.9.0" } @@ -996,6 +981,7 @@ "integrity": "sha512-ZGwZP4OCfyA0AQTpEAMWz+rtX01DRhQWW5hB0ucKDEIX5U7jdmPSaMx94rQfaPAQzIYz2BimOgKOJtjfpRFQ9g==", "dev": true, "license": "MIT", + "peer": true, "dependencies": { "@typescript-eslint/scope-manager": "8.72.1", "@typescript-eslint/types": "8.72.1", @@ -1578,6 +1564,7 @@ "integrity": "sha512-4KpkGdIrSqBihx/JyP/e+S+IKB98etg1XDQiLAxksLfcShnwi1VReGeOT9NI43hLHbknosKp/1CCLn9Zgcs8mg==", "dev": true, "license": "MIT", + "peer": true, "dependencies": { "@bcoe/v8-coverage": "^1.0.2", "@vitest/istanbul-lib-coverage": "^1.0.2", @@ -1668,6 +1655,7 @@ "integrity": "sha512-UVJyE9MttOsBQIDKw1skb9nAwQuR5wuGD3+82K6JgJlm/Y+KI92oNsMNGZCYdDsVtRHSak0pcV5Dno5+4jh9sw==", "dev": true, "license": "MIT", + "peer": true, "bin": { "acorn": "bin/acorn" }, @@ -1703,6 +1691,7 @@ "resolved": "https://registry.npmjs.org/ajv/-/ajv-6.14.0.tgz", "integrity": "sha512-IWrosm/yrn43eiKqkfkHis7QioDleaXQHdDVPKg0FSwwd/DuvyX79TZnFOnYpB7dcsFAMmtFztZuXPDvSePkFw==", "license": "MIT", + "peer": true, "dependencies": { "fast-deep-equal": "^3.1.1", "fast-json-stable-stringify": "^2.0.0", @@ -2064,6 +2053,7 @@ "integrity": "sha512-T0pNsxkb9IKmtQjhpK3d7nWOpFv+YHuMbTJnSVMoQblF0onvXfErrtp4V1jHtsQPan7dKaGVD0q1WCXnzMF31A==", "dev": true, "license": "MIT", + "peer": true, "workspaces": [ "packages/*" ], @@ -2349,7 +2339,6 @@ "os": [ "darwin" ], - "peer": true, "engines": { "node": "^8.16.0 || ^10.6.0 || >=11.0.0" } @@ -2531,7 +2520,6 @@ "integrity": "sha512-WkUDrojuJs0xkgGf2udWxa3yGBRxPtxUkB79i6aCZLRgc7PM8fZe9TosfPDcvEpQZbuFASnHYmRLBLUbmLOIIA==", "dev": true, "license": "MPL-2.0", - "peer": true, "dependencies": { "detect-libc": "^2.0.3" }, @@ -2569,7 +2557,6 @@ "os": [ "android" ], - "peer": true, "engines": { "node": ">= 12.0.0" }, @@ -2591,7 +2578,6 @@ "os": [ "darwin" ], - "peer": true, "engines": { "node": ">= 12.0.0" }, @@ -2613,7 +2599,6 @@ "os": [ "darwin" ], - "peer": true, "engines": { "node": ">= 12.0.0" }, @@ -2635,7 +2620,6 @@ "os": [ "freebsd" ], - "peer": true, "engines": { "node": ">= 12.0.0" }, @@ -2657,7 +2641,6 @@ "os": [ "linux" ], - "peer": true, "engines": { "node": ">= 12.0.0" }, @@ -2682,7 +2665,6 @@ "os": [ "linux" ], - "peer": true, "engines": { "node": ">= 12.0.0" }, @@ -2707,7 +2689,6 @@ "os": [ "linux" ], - "peer": true, "engines": { "node": ">= 12.0.0" }, @@ -2732,7 +2713,6 @@ "os": [ "linux" ], - "peer": true, "engines": { "node": ">= 12.0.0" }, @@ -2757,7 +2737,6 @@ "os": [ "linux" ], - "peer": true, "engines": { "node": ">= 12.0.0" }, @@ -2779,7 +2758,6 @@ "os": [ "win32" ], - "peer": true, "engines": { "node": ">= 12.0.0" }, @@ -2801,7 +2779,6 @@ "os": [ "win32" ], - "peer": true, "engines": { "node": ">= 12.0.0" }, @@ -2816,7 +2793,6 @@ "integrity": "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==", "dev": true, "license": "Apache-2.0", - "peer": true, "engines": { "node": ">=8" } @@ -2919,7 +2895,6 @@ } ], "license": "MIT", - "peer": true, "bin": { "nanoid": "bin/nanoid.cjs" }, @@ -3054,8 +3029,7 @@ "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz", "integrity": "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==", "dev": true, - "license": "ISC", - "peer": true + "license": "ISC" }, "node_modules/picomatch": { "version": "4.0.7", @@ -3133,7 +3107,6 @@ } ], "license": "MIT", - "peer": true, "dependencies": { "nanoid": "^3.3.20", "picocolors": "^1.1.1", @@ -3314,7 +3287,6 @@ "integrity": "sha512-bWvlMpFKiTfDKfnK7FC2MPgPeWCf/Kpwsq49ApdW+FQaBZb6O6dZ4MAPbPUjp7hYQrw/RobqCzn64BRrQecGHw==", "dev": true, "license": "MIT", - "peer": true, "dependencies": { "@oxc-project/types": "=0.156.0", "@rolldown/pluginutils": "^1.0.0" @@ -3651,6 +3623,7 @@ "integrity": "sha512-mbCddXd+jm7hfx7w2YU64/Av4/NqqeG3GoRZgxPcgoTxYjhrcfJRw9ULch71SS4G+Q3bOXFhRvPqjguN0Hyp5w==", "dev": true, "license": "Apache-2.0", + "peer": true, "dependencies": { "@typescript/old": "npm:typescript@^6" }, @@ -3789,6 +3762,7 @@ "integrity": "sha512-cPODOMF8YnkiiYtDdHo6n4wWmBrOBBbOIYH2d33M4l3CdNn72h+qMmO6uXffUN6A5AZFXNND/d+krS9mgkXRfg==", "dev": true, "license": "MIT", + "peer": true, "dependencies": { "@types/chai": "^5.2.2", "@vitest/mocker": "5.0.5", diff --git a/src/cli/cli.test.ts b/src/cli/cli.test.ts new file mode 100644 index 0000000..75f19ce --- /dev/null +++ b/src/cli/cli.test.ts @@ -0,0 +1,272 @@ +import { describe, it, expect, beforeEach, afterEach } from 'vitest'; +import { CLI } from './cli.js'; + +describe('CLI', () => { + const savedEnv: Record = {}; + const envVars = ['ADDRESS', 'DEBUG', 'INSECURE', 'TLS_SERVER_CERTS_DIR', 'MAX_RECV_MESSAGE_SIZE', 'MY_FLAG']; + + beforeEach(() => { + for (const key of envVars) { + savedEnv[key] = process.env[key]; + delete process.env[key]; + } + }); + + afterEach(() => { + for (const key of envVars) { + if (savedEnv[key] === undefined) { + delete process.env[key]; + } else { + process.env[key] = savedEnv[key]; + } + } + }); + + describe('parse', () => { + it('should default every standard flag', () => { + const cli = new CLI({ name: 'test' }); + const values = cli.parse([]); + + expect(values).toEqual({ + address: '0.0.0.0:9443', + debug: false, + insecure: false, + 'tls-server-certs-dir': '/tls/server', + 'max-recv-message-size': '4', + help: false, + }); + }); + + it('should parse standard flags', () => { + const cli = new CLI({ name: 'test' }); + const values = cli.parse([ + '--address', + 'localhost:1234', + '--debug', + '--insecure', + '--tls-server-certs-dir', + '/certs', + ]); + + expect(values.address).toBe('localhost:1234'); + expect(values.debug).toBe(true); + expect(values.insecure).toBe(true); + expect(values['tls-server-certs-dir']).toBe('/certs'); + }); + + it('should accept short flags', () => { + const cli = new CLI({ name: 'test' }); + expect(cli.parse(['-d']).debug).toBe(true); + expect(new CLI({ name: 'test' }).parse(['-h']).help).toBe(true); + }); + + it('should reject unrecognized flags', () => { + const cli = new CLI({ name: 'test' }); + expect(() => cli.parse(['--nope'])).toThrow(/Unknown option '--nope'/); + }); + + it('should parse custom flags alongside standard ones', () => { + const cli = new CLI({ + name: 'test', + flags: { + 'my-flag': { + type: 'string', + default: 'foo', + env: 'MY_FLAG', + description: 'My custom flag.', + }, + verbose: { + type: 'boolean', + default: false, + description: 'Verbose output.', + }, + }, + }); + + const values = cli.parse(['--my-flag', 'bar', '--verbose', '--debug']); + expect(values['my-flag']).toBe('bar'); + expect(values.verbose).toBe(true); + expect(values.debug).toBe(true); + }); + + it('should reject custom flags that conflict with standard flags', () => { + expect( + () => + new CLI({ + flags: { + debug: { type: 'boolean', description: 'Conflict.' }, + }, + }) + ).toThrow(/flag "debug" conflicts with a standard flag/); + }); + }); + + describe('environment variables', () => { + it('should read string flags from env when not given on CLI', () => { + process.env.ADDRESS = 'env-address:9999'; + const cli = new CLI({ name: 'test' }); + const values = cli.parse([]); + + expect(values.address).toBe('env-address:9999'); + }); + + it('should read boolean flags from env', () => { + process.env.DEBUG = 'true'; + const cli = new CLI({ name: 'test' }); + + expect(cli.parse([]).debug).toBe(true); + }); + + it('should accept "1" as truthy for boolean env vars', () => { + process.env.INSECURE = '1'; + const cli = new CLI({ name: 'test' }); + + expect(cli.parse([]).insecure).toBe(true); + }); + + it('should treat other env values as falsy for booleans', () => { + process.env.DEBUG = 'no'; + const cli = new CLI({ name: 'test' }); + + expect(cli.parse([]).debug).toBe(false); + }); + + it('should prefer CLI argument over env var', () => { + process.env.ADDRESS = 'env-address:9999'; + const cli = new CLI({ name: 'test' }); + const values = cli.parse(['--address', 'cli-address:8888']); + + expect(values.address).toBe('cli-address:8888'); + }); + + it('should read custom flag env vars', () => { + process.env.MY_FLAG = 'from-env'; + const cli = new CLI({ + name: 'test', + flags: { + 'my-flag': { + type: 'string', + default: 'default-val', + env: 'MY_FLAG', + description: 'Test.', + }, + }, + }); + + expect(cli.parse([])['my-flag']).toBe('from-env'); + }); + + it('should prefer env over default but CLI over env', () => { + process.env.MY_FLAG = 'from-env'; + const cli = new CLI({ + name: 'test', + flags: { + 'my-flag': { + type: 'string', + default: 'default-val', + env: 'MY_FLAG', + description: 'Test.', + }, + }, + }); + + expect(cli.parse(['--my-flag', 'from-cli'])['my-flag']).toBe('from-cli'); + }); + }); + + describe('standardOptions', () => { + it('should return ServerOptions from parsed standard flags', () => { + const cli = new CLI({ name: 'test' }); + cli.parse(['--address', 'localhost:5555', '--debug', '--insecure']); + + expect(cli.standardOptions()).toEqual({ + address: 'localhost:5555', + debug: true, + insecure: true, + tlsServerCertsDir: '/tls/server', + maxRecvMessageSize: 4 * 1024 * 1024, + }); + }); + + it('should convert max-recv-message-size from MB to bytes', () => { + const cli = new CLI({ name: 'test' }); + cli.parse(['--max-recv-message-size', '8']); + + expect(cli.standardOptions().maxRecvMessageSize).toBe(8 * 1024 * 1024); + }); + + it('should reflect env vars in standard options', () => { + process.env.ADDRESS = 'env:1111'; + process.env.DEBUG = 'true'; + const cli = new CLI({ name: 'test' }); + cli.parse([]); + + const opts = cli.standardOptions(); + expect(opts.address).toBe('env:1111'); + expect(opts.debug).toBe(true); + }); + }); + + describe('logger', () => { + it('should return info-level logger by default', () => { + const cli = new CLI({ name: 'test' }); + cli.parse([]); + + expect(cli.logger().level).toBe('info'); + }); + + it('should return debug-level logger when --debug is set', () => { + const cli = new CLI({ name: 'test' }); + cli.parse(['--debug']); + + expect(cli.logger().level).toBe('debug'); + }); + }); + + describe('helpText', () => { + it('should include program name and all standard flags', () => { + const cli = new CLI({ name: 'my-fn' }); + const help = cli.helpText(); + + expect(help).toContain('Usage: my-fn'); + for (const flag of ['--address', '--debug', '--insecure', '--tls-server-certs-dir', '--max-recv-message-size', '--help']) { + expect(help).toContain(flag); + } + }); + + it('should include custom flags', () => { + const cli = new CLI({ + name: 'my-fn', + flags: { + 'my-flag': { + type: 'string', + default: 'foo', + env: 'MY_FLAG', + description: 'My custom flag.', + }, + }, + }); + const help = cli.helpText(); + + expect(help).toContain('--my-flag'); + expect(help).toContain('My custom flag.'); + expect(help).toContain('[env: MY_FLAG]'); + }); + + it('should show env var hints for standard flags', () => { + const cli = new CLI({ name: 'test' }); + const help = cli.helpText(); + + for (const env of ['ADDRESS', 'DEBUG', 'INSECURE', 'TLS_SERVER_CERTS_DIR', 'MAX_RECV_MESSAGE_SIZE']) { + expect(help).toContain(`[env: ${env}]`); + } + }); + }); + + describe('name', () => { + it('should return the configured program name', () => { + const cli = new CLI({ name: 'my-function' }); + expect(cli.name).toBe('my-function'); + }); + }); +}); diff --git a/src/cli/cli.ts b/src/cli/cli.ts new file mode 100644 index 0000000..5e08e99 --- /dev/null +++ b/src/cli/cli.ts @@ -0,0 +1,232 @@ +/** + * A shareable CLI for composition functions. + * + * The {@link CLI} class provides the standard flags every composition function + * accepts, reads environment variables, and lets function authors add custom + * flags. + * + * Simple functions that need no custom flags can keep using {@link serve}. + * Functions that need extra flags create a CLI, parse it, then pass the + * results to serve: + * + * @example + * ```typescript + * const cli = new CLI({ + * flags: { + * 'my-flag': { type: 'string', default: 'foo', env: 'MY_FLAG', description: 'My custom flag.' }, + * }, + * }); + * + * const parsed = cli.parse(); + * if (parsed.help) { + * process.stdout.write(cli.helpText() + '\n'); + * process.exit(0); + * } + * + * serve(compose, { argv: [], serverOptions: cli.standardOptions(), logger: cli.logger() }); + * ``` + */ + +import { basename } from 'node:path'; +import { parseArgs as parseNodeArgs } from 'node:util'; +import { pino, type Logger } from 'pino'; +import type { ServerOptions } from '../runtime/runtime.js'; + +const DEFAULT_ADDRESS = '0.0.0.0:9443'; +const DEFAULT_TLS_SERVER_CERTS_DIR = '/tls/server'; +const DEFAULT_MAX_RECV_MESSAGE_SIZE = 4; + +/** Specification for a single CLI flag. */ +export interface FlagSpec { + type: 'string' | 'boolean'; + default?: string | boolean; + short?: string; + env?: string; + description: string; +} + +const standardFlags: Record = { + address: { + type: 'string', + default: DEFAULT_ADDRESS, + env: 'ADDRESS', + description: `Address to listen for gRPC connections. Default ${DEFAULT_ADDRESS}.`, + }, + debug: { + type: 'boolean', + default: false, + short: 'd', + env: 'DEBUG', + description: 'Emit debug logs.', + }, + insecure: { + type: 'boolean', + default: false, + env: 'INSECURE', + description: 'Run without mTLS credentials.', + }, + 'tls-server-certs-dir': { + type: 'string', + default: DEFAULT_TLS_SERVER_CERTS_DIR, + env: 'TLS_SERVER_CERTS_DIR', + description: `Directory holding tls.key, tls.crt and ca.crt. Default ${DEFAULT_TLS_SERVER_CERTS_DIR}.`, + }, + 'max-recv-message-size': { + type: 'string', + default: String(DEFAULT_MAX_RECV_MESSAGE_SIZE), + env: 'MAX_RECV_MESSAGE_SIZE', + description: `Maximum size of received gRPC messages in MB. Default ${DEFAULT_MAX_RECV_MESSAGE_SIZE}.`, + }, + help: { + type: 'boolean', + default: false, + short: 'h', + description: 'Show this help.', + }, +}; + +/** Options accepted by the {@link CLI} constructor. */ +export interface CLIOptions { + /** Program name shown in help text. Defaults to the running script's basename. */ + name?: string; + + /** Custom flags to register alongside the standard ones. */ + flags?: Record; +} + +/** + * A shareable, extensible CLI for Crossplane composition functions. + * + * Provides the standard flags (address, debug, insecure, tls-server-certs-dir, + * max-recv-message-size, help) with environment variable support, and lets + * function authors register additional flags. + * + * Resolution order per flag: CLI argument > environment variable > default. + */ +export class CLI { + private readonly programName: string; + private readonly allFlags: Record; + private values: Record = {}; + + constructor(opts?: CLIOptions) { + this.programName = opts?.name ?? defaultName(); + + const custom = opts?.flags ?? {}; + for (const name of Object.keys(custom)) { + if (name in standardFlags) { + throw new Error(`flag "${name}" conflicts with a standard flag`); + } + } + this.allFlags = { ...standardFlags, ...custom }; + } + + /** + * Parse command-line arguments. + * + * For each flag the resolution order is: CLI argument, then environment + * variable (if configured), then the declared default. + * + * @param argv - Arguments without the node executable or script path. + * Defaults to `process.argv.slice(2)`. + * @returns All parsed values keyed by flag name. + * @throws If a flag is unrecognized, missing its value, or given a value it + * does not accept. + */ + parse(argv?: string[]): Record { + const args = argv ?? process.argv.slice(2); + + const parseOptions: Record = {}; + for (const [name, spec] of Object.entries(this.allFlags)) { + const opt: { type: string; short?: string; default?: boolean } = { type: spec.type }; + if (spec.short) opt.short = spec.short; + if (spec.type === 'boolean') opt.default = false; + parseOptions[name] = opt; + } + + const { values } = parseNodeArgs({ + args, + options: parseOptions as NonNullable[0]>['options'], + allowPositionals: false, + }); + + const parsed = values as Record; + + for (const [name, spec] of Object.entries(this.allFlags)) { + this.values[name] = resolveValue(spec, parsed[name]); + } + + return { ...this.values }; + } + + /** Return {@link ServerOptions} derived from the standard flags. */ + standardOptions(): ServerOptions { + const maxRecvMB = parseInt(String(this.values['max-recv-message-size']), 10); + return { + address: this.values['address'] as string, + debug: this.values['debug'] as boolean, + insecure: this.values['insecure'] as boolean, + tlsServerCertsDir: this.values['tls-server-certs-dir'] as string, + maxRecvMessageSize: + (isNaN(maxRecvMB) ? DEFAULT_MAX_RECV_MESSAGE_SIZE : maxRecvMB) * 1024 * 1024, + }; + } + + /** Return a pino {@link Logger} configured from the --debug flag. */ + logger(): Logger { + return pino({ + level: this.values['debug'] ? 'debug' : 'info', + formatters: { + level: (label: string) => ({ severity: label.toUpperCase() }), + }, + }); + } + + /** Generate help text that includes both standard and custom flags. */ + helpText(): string { + const usage = Object.entries(this.allFlags).map(([flag, spec]) => { + const short = spec.short ? `-${spec.short}, ` : ' '; + const value = spec.type === 'string' ? ' ' : ''; + const env = spec.env ? ` [env: ${spec.env}]` : ''; + return ` ${short}--${flag}${value}`.padEnd(38) + spec.description + env; + }); + return [ + `Usage: ${this.programName} [flags]`, + '', + 'A Crossplane composition function.', + '', + 'Flags:', + ...usage, + ].join('\n'); + } + + /** The program name used in help text. */ + get name(): string { + return this.programName; + } +} + +function resolveValue( + spec: FlagSpec, + cliValue: string | boolean | undefined +): string | boolean | undefined { + const givenOnCli = + spec.type === 'string' ? cliValue !== undefined : (cliValue as boolean) === true; + + if (givenOnCli) return cliValue; + + if (spec.env) { + const envValue = process.env[spec.env]; + if (envValue !== undefined) { + return spec.type === 'boolean' + ? envValue === '1' || envValue.toLowerCase() === 'true' + : envValue; + } + } + + return spec.default; +} + +function defaultName(): string { + const script = process.argv[1]; + return script ? basename(script) : 'function'; +} diff --git a/src/function/function.ts b/src/function/function.ts index 970f6d6..5436cc0 100644 --- a/src/function/function.ts +++ b/src/function/function.ts @@ -147,8 +147,16 @@ export class FunctionRunner { * const server = getServer(runner, logger); * ``` */ -export function getServer(functionRunner: FunctionRunner, logger: Logger): grpc.Server { - const server = new grpc.Server(); +export function getServer( + functionRunner: FunctionRunner, + logger: Logger, + opts?: { maxRecvMessageSize?: number } +): grpc.Server { + const channelOptions: grpc.ServerOptions = {}; + if (opts?.maxRecvMessageSize) { + channelOptions['grpc.max_receive_message_length'] = opts.maxRecvMessageSize; + } + const server = new grpc.Server(channelOptions); // Implement the service using the generated interface const implementation = { diff --git a/src/index.ts b/src/index.ts index 1d14ea7..4a13a96 100644 --- a/src/index.ts +++ b/src/index.ts @@ -61,6 +61,9 @@ export { update as updateResource, } from './resource/resource.js'; +// Shareable CLI +export { CLI, type CLIOptions, type FlagSpec } from './cli/cli.js'; + // Runtime utilities export { getServerCredentials, diff --git a/src/runtime/runtime.ts b/src/runtime/runtime.ts index c185975..3fbbfda 100644 --- a/src/runtime/runtime.ts +++ b/src/runtime/runtime.ts @@ -41,6 +41,12 @@ export interface ServerOptions { * Ignored if insecure is set to true. */ tlsServerCertsDir?: string; + + /** + * Maximum size of received gRPC messages in bytes. + * Default: 4 MB (4 * 1024 * 1024). + */ + maxRecvMessageSize?: number; } /** @@ -112,8 +118,12 @@ export function getServerCredentials(opts?: ServerOptions): grpc.ServerCredentia * startServer(server, { address: ":9443", insecure: false }, logger); * ``` */ -export function newGrpcServer(functionRunner: FunctionRunner, logger: Logger): grpc.Server { - const server = getServer(functionRunner, logger); +export function newGrpcServer( + functionRunner: FunctionRunner, + logger: Logger, + opts?: Pick +): grpc.Server { + const server = getServer(functionRunner, logger, opts); if (logger) { logger.debug('grpc server created'); } diff --git a/src/serve/serve.ts b/src/serve/serve.ts index bf2d3a5..3c14b55 100644 --- a/src/serve/serve.ts +++ b/src/serve/serve.ts @@ -266,7 +266,9 @@ export function serve(fn: ComposeFunction | FunctionHandler, opts: ServeOptions logger.debug({ options: serverOptions }, 'starting function'); const handler: FunctionHandler = typeof fn === 'function' ? fromCompose(fn) : fn; - const server = newGrpcServer(new FunctionRunner(handler, logger), logger); + const server = newGrpcServer(new FunctionRunner(handler, logger), logger, { + maxRecvMessageSize: serverOptions.maxRecvMessageSize, + }); startServer(server, serverOptions, logger); const shutdown = (signal: string): void => { From 352468171fb5163ad9d3dc09bcb5f19ba7e1cf2b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jes=C3=BAs=20Fern=C3=A1ndez?= <7312236+fernandezcuesta@users.noreply.github.com> Date: Mon, 14 Sep 2026 09:43:45 +0200 Subject: [PATCH 2/9] chore: sort MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Jesús Fernández <7312236+fernandezcuesta@users.noreply.github.com> --- src/cli/cli.ts | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/src/cli/cli.ts b/src/cli/cli.ts index 5e08e99..4511244 100644 --- a/src/cli/cli.ts +++ b/src/cli/cli.ts @@ -33,8 +33,8 @@ import { pino, type Logger } from 'pino'; import type { ServerOptions } from '../runtime/runtime.js'; const DEFAULT_ADDRESS = '0.0.0.0:9443'; -const DEFAULT_TLS_SERVER_CERTS_DIR = '/tls/server'; const DEFAULT_MAX_RECV_MESSAGE_SIZE = 4; +const DEFAULT_TLS_SERVER_CERTS_DIR = '/tls/server'; /** Specification for a single CLI flag. */ export interface FlagSpec { @@ -65,18 +65,18 @@ const standardFlags: Record = { env: 'INSECURE', description: 'Run without mTLS credentials.', }, - 'tls-server-certs-dir': { - type: 'string', - default: DEFAULT_TLS_SERVER_CERTS_DIR, - env: 'TLS_SERVER_CERTS_DIR', - description: `Directory holding tls.key, tls.crt and ca.crt. Default ${DEFAULT_TLS_SERVER_CERTS_DIR}.`, - }, 'max-recv-message-size': { type: 'string', default: String(DEFAULT_MAX_RECV_MESSAGE_SIZE), env: 'MAX_RECV_MESSAGE_SIZE', description: `Maximum size of received gRPC messages in MB. Default ${DEFAULT_MAX_RECV_MESSAGE_SIZE}.`, }, + 'tls-server-certs-dir': { + type: 'string', + default: DEFAULT_TLS_SERVER_CERTS_DIR, + env: 'TLS_SERVER_CERTS_DIR', + description: `Directory holding tls.key, tls.crt and ca.crt. Default ${DEFAULT_TLS_SERVER_CERTS_DIR}.`, + }, help: { type: 'boolean', default: false, From 7aa7093f9211e8fb3fa515ed217accc522c074b2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jes=C3=BAs=20Fern=C3=A1ndez?= <7312236+fernandezcuesta@users.noreply.github.com> Date: Wed, 23 Sep 2026 00:23:50 +0200 Subject: [PATCH 3/9] fix: add max send message size server option MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Jesús Fernández <7312236+fernandezcuesta@users.noreply.github.com> --- src/cli/cli.test.ts | 38 ++++++++++++++++++++++++++++++++++---- src/cli/cli.ts | 24 ++++++++++++++++++++---- src/function/function.ts | 6 +++++- src/runtime/runtime.ts | 8 +++++++- src/serve/serve.ts | 1 + 5 files changed, 67 insertions(+), 10 deletions(-) diff --git a/src/cli/cli.test.ts b/src/cli/cli.test.ts index 75f19ce..ea0254e 100644 --- a/src/cli/cli.test.ts +++ b/src/cli/cli.test.ts @@ -3,7 +3,7 @@ import { CLI } from './cli.js'; describe('CLI', () => { const savedEnv: Record = {}; - const envVars = ['ADDRESS', 'DEBUG', 'INSECURE', 'TLS_SERVER_CERTS_DIR', 'MAX_RECV_MESSAGE_SIZE', 'MY_FLAG']; + const envVars = ['ADDRESS', 'DEBUG', 'INSECURE', 'TLS_SERVER_CERTS_DIR', 'MAX_RECV_MESSAGE_SIZE', 'MAX_GRPC_MESSAGE_SIZE', 'MAX_SEND_MESSAGE_SIZE', 'MY_FLAG']; beforeEach(() => { for (const key of envVars) { @@ -31,8 +31,9 @@ describe('CLI', () => { address: '0.0.0.0:9443', debug: false, insecure: false, - 'tls-server-certs-dir': '/tls/server', 'max-recv-message-size': '4', + 'max-send-message-size': undefined, + 'tls-server-certs-dir': '/tls/server', help: false, }); }); @@ -156,6 +157,21 @@ describe('CLI', () => { expect(cli.parse([])['my-flag']).toBe('from-env'); }); + it('should read MAX_GRPC_MESSAGE_SIZE as alias for MAX_RECV_MESSAGE_SIZE', () => { + process.env.MAX_GRPC_MESSAGE_SIZE = '16'; + const cli = new CLI({ name: 'test' }); + + expect(cli.parse([])['max-recv-message-size']).toBe('16'); + }); + + it('should prefer MAX_RECV_MESSAGE_SIZE over MAX_GRPC_MESSAGE_SIZE', () => { + process.env.MAX_RECV_MESSAGE_SIZE = '8'; + process.env.MAX_GRPC_MESSAGE_SIZE = '16'; + const cli = new CLI({ name: 'test' }); + + expect(cli.parse([])['max-recv-message-size']).toBe('8'); + }); + it('should prefer env over default but CLI over env', () => { process.env.MY_FLAG = 'from-env'; const cli = new CLI({ @@ -195,6 +211,20 @@ describe('CLI', () => { expect(cli.standardOptions().maxRecvMessageSize).toBe(8 * 1024 * 1024); }); + it('should default maxSendMessageSize to undefined when not set', () => { + const cli = new CLI({ name: 'test' }); + cli.parse([]); + + expect(cli.standardOptions().maxSendMessageSize).toBeUndefined(); + }); + + it('should convert max-send-message-size from MB to bytes', () => { + const cli = new CLI({ name: 'test' }); + cli.parse(['--max-send-message-size', '16']); + + expect(cli.standardOptions().maxSendMessageSize).toBe(16 * 1024 * 1024); + }); + it('should reflect env vars in standard options', () => { process.env.ADDRESS = 'env:1111'; process.env.DEBUG = 'true'; @@ -229,7 +259,7 @@ describe('CLI', () => { const help = cli.helpText(); expect(help).toContain('Usage: my-fn'); - for (const flag of ['--address', '--debug', '--insecure', '--tls-server-certs-dir', '--max-recv-message-size', '--help']) { + for (const flag of ['--address', '--debug', '--insecure', '--max-recv-message-size', '--max-send-message-size', '--tls-server-certs-dir', '--help']) { expect(help).toContain(flag); } }); @@ -257,7 +287,7 @@ describe('CLI', () => { const cli = new CLI({ name: 'test' }); const help = cli.helpText(); - for (const env of ['ADDRESS', 'DEBUG', 'INSECURE', 'TLS_SERVER_CERTS_DIR', 'MAX_RECV_MESSAGE_SIZE']) { + for (const env of ['ADDRESS', 'DEBUG', 'INSECURE', 'MAX_RECV_MESSAGE_SIZE', 'MAX_SEND_MESSAGE_SIZE', 'TLS_SERVER_CERTS_DIR']) { expect(help).toContain(`[env: ${env}]`); } }); diff --git a/src/cli/cli.ts b/src/cli/cli.ts index 4511244..3bdf81b 100644 --- a/src/cli/cli.ts +++ b/src/cli/cli.ts @@ -41,7 +41,10 @@ export interface FlagSpec { type: 'string' | 'boolean'; default?: string | boolean; short?: string; + /** Primary environment variable. */ env?: string; + /** Fallback environment variables checked when the primary is not set. */ + envAliases?: string[]; description: string; } @@ -69,8 +72,14 @@ const standardFlags: Record = { type: 'string', default: String(DEFAULT_MAX_RECV_MESSAGE_SIZE), env: 'MAX_RECV_MESSAGE_SIZE', + envAliases: ['MAX_GRPC_MESSAGE_SIZE'], description: `Maximum size of received gRPC messages in MB. Default ${DEFAULT_MAX_RECV_MESSAGE_SIZE}.`, }, + 'max-send-message-size': { + type: 'string', + env: 'MAX_SEND_MESSAGE_SIZE', + description: 'Maximum size of sent gRPC messages in MB. Defaults to --max-recv-message-size.', + }, 'tls-server-certs-dir': { type: 'string', default: DEFAULT_TLS_SERVER_CERTS_DIR, @@ -161,13 +170,19 @@ export class CLI { /** Return {@link ServerOptions} derived from the standard flags. */ standardOptions(): ServerOptions { const maxRecvMB = parseInt(String(this.values['max-recv-message-size']), 10); + const recvBytes = (isNaN(maxRecvMB) ? DEFAULT_MAX_RECV_MESSAGE_SIZE : maxRecvMB) * 1024 * 1024; + + const sendRaw = this.values['max-send-message-size']; + const maxSendMB = sendRaw !== undefined ? parseInt(String(sendRaw), 10) : NaN; + const sendBytes = isNaN(maxSendMB) ? undefined : maxSendMB * 1024 * 1024; + return { address: this.values['address'] as string, debug: this.values['debug'] as boolean, insecure: this.values['insecure'] as boolean, tlsServerCertsDir: this.values['tls-server-certs-dir'] as string, - maxRecvMessageSize: - (isNaN(maxRecvMB) ? DEFAULT_MAX_RECV_MESSAGE_SIZE : maxRecvMB) * 1024 * 1024, + maxRecvMessageSize: recvBytes, + maxSendMessageSize: sendBytes, }; } @@ -214,8 +229,9 @@ function resolveValue( if (givenOnCli) return cliValue; - if (spec.env) { - const envValue = process.env[spec.env]; + const envKeys = [spec.env, ...(spec.envAliases ?? [])].filter(Boolean) as string[]; + for (const key of envKeys) { + const envValue = process.env[key]; if (envValue !== undefined) { return spec.type === 'boolean' ? envValue === '1' || envValue.toLowerCase() === 'true' diff --git a/src/function/function.ts b/src/function/function.ts index 5436cc0..4cfc5dd 100644 --- a/src/function/function.ts +++ b/src/function/function.ts @@ -150,12 +150,16 @@ export class FunctionRunner { export function getServer( functionRunner: FunctionRunner, logger: Logger, - opts?: { maxRecvMessageSize?: number } + opts?: { maxRecvMessageSize?: number; maxSendMessageSize?: number } ): grpc.Server { const channelOptions: grpc.ServerOptions = {}; if (opts?.maxRecvMessageSize) { channelOptions['grpc.max_receive_message_length'] = opts.maxRecvMessageSize; } + const sendSize = opts?.maxSendMessageSize ?? opts?.maxRecvMessageSize; + if (sendSize) { + channelOptions['grpc.max_send_message_length'] = sendSize; + } const server = new grpc.Server(channelOptions); // Implement the service using the generated interface diff --git a/src/runtime/runtime.ts b/src/runtime/runtime.ts index 3fbbfda..ddb39e6 100644 --- a/src/runtime/runtime.ts +++ b/src/runtime/runtime.ts @@ -47,6 +47,12 @@ export interface ServerOptions { * Default: 4 MB (4 * 1024 * 1024). */ maxRecvMessageSize?: number; + + /** + * Maximum size of sent gRPC messages in bytes. + * Defaults to maxRecvMessageSize when not set. + */ + maxSendMessageSize?: number; } /** @@ -121,7 +127,7 @@ export function getServerCredentials(opts?: ServerOptions): grpc.ServerCredentia export function newGrpcServer( functionRunner: FunctionRunner, logger: Logger, - opts?: Pick + opts?: Pick ): grpc.Server { const server = getServer(functionRunner, logger, opts); if (logger) { diff --git a/src/serve/serve.ts b/src/serve/serve.ts index 3c14b55..cfb42a7 100644 --- a/src/serve/serve.ts +++ b/src/serve/serve.ts @@ -268,6 +268,7 @@ export function serve(fn: ComposeFunction | FunctionHandler, opts: ServeOptions const handler: FunctionHandler = typeof fn === 'function' ? fromCompose(fn) : fn; const server = newGrpcServer(new FunctionRunner(handler, logger), logger, { maxRecvMessageSize: serverOptions.maxRecvMessageSize, + maxSendMessageSize: serverOptions.maxSendMessageSize, }); startServer(server, serverOptions, logger); From 828412dda21fb143af27d19d02203ef9a70471a6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jes=C3=BAs=20Fern=C3=A1ndez?= <7312236+fernandezcuesta@users.noreply.github.com> Date: Wed, 23 Sep 2026 00:25:22 +0200 Subject: [PATCH 4/9] fix: lint MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Jesús Fernández <7312236+fernandezcuesta@users.noreply.github.com> --- src/cli/cli.test.ts | 30 +++++++++++++++++++++++++++--- 1 file changed, 27 insertions(+), 3 deletions(-) diff --git a/src/cli/cli.test.ts b/src/cli/cli.test.ts index ea0254e..20d81fb 100644 --- a/src/cli/cli.test.ts +++ b/src/cli/cli.test.ts @@ -3,7 +3,16 @@ import { CLI } from './cli.js'; describe('CLI', () => { const savedEnv: Record = {}; - const envVars = ['ADDRESS', 'DEBUG', 'INSECURE', 'TLS_SERVER_CERTS_DIR', 'MAX_RECV_MESSAGE_SIZE', 'MAX_GRPC_MESSAGE_SIZE', 'MAX_SEND_MESSAGE_SIZE', 'MY_FLAG']; + const envVars = [ + 'ADDRESS', + 'DEBUG', + 'INSECURE', + 'TLS_SERVER_CERTS_DIR', + 'MAX_RECV_MESSAGE_SIZE', + 'MAX_GRPC_MESSAGE_SIZE', + 'MAX_SEND_MESSAGE_SIZE', + 'MY_FLAG', + ]; beforeEach(() => { for (const key of envVars) { @@ -259,7 +268,15 @@ describe('CLI', () => { const help = cli.helpText(); expect(help).toContain('Usage: my-fn'); - for (const flag of ['--address', '--debug', '--insecure', '--max-recv-message-size', '--max-send-message-size', '--tls-server-certs-dir', '--help']) { + for (const flag of [ + '--address', + '--debug', + '--insecure', + '--max-recv-message-size', + '--max-send-message-size', + '--tls-server-certs-dir', + '--help', + ]) { expect(help).toContain(flag); } }); @@ -287,7 +304,14 @@ describe('CLI', () => { const cli = new CLI({ name: 'test' }); const help = cli.helpText(); - for (const env of ['ADDRESS', 'DEBUG', 'INSECURE', 'MAX_RECV_MESSAGE_SIZE', 'MAX_SEND_MESSAGE_SIZE', 'TLS_SERVER_CERTS_DIR']) { + for (const env of [ + 'ADDRESS', + 'DEBUG', + 'INSECURE', + 'MAX_RECV_MESSAGE_SIZE', + 'MAX_SEND_MESSAGE_SIZE', + 'TLS_SERVER_CERTS_DIR', + ]) { expect(help).toContain(`[env: ${env}]`); } }); From 7c09383a67f95465cf20b1739db92ffbb370f0be Mon Sep 17 00:00:00 2001 From: Steven Borrelli Date: Mon, 2 Nov 2026 12:27:31 +0000 Subject: [PATCH 5/9] Build serve() on the shareable CLI and validate flag values serve() kept its own flag table and parser beside the new CLI class, so a plain serve(compose) function rejected --max-recv-message-size and ignored the standard environment variables. Tooling configuring every function in a pipeline (#39) needs every function to honour them, so serve() now parses through a CLI, and parseArgs() and helpText() delegate to one. serve() accepts a CLI of the function's own, so custom flags get the same --help and usage error handling rather than needing argv: [] to skip it. Bad values are now reported rather than swallowed: - Message sizes must be positive whole numbers of megabytes. "eight", "16MB", 0 and -1 previously became the default, a truncated value, the grpc-js default, or a negative byte count. - getServer() checks for undefined rather than truthiness. - standardOptions(), logger() and values throw before parse(), rather than returning undefineds that override serve's defaults. - The constructor rejects reused short aliases, and boolean flags defaulting to true, which could never be turned off. Also size the help column to the longest flag, import the default constants rather than redeclaring them, and drop unrelated lockfile churn. Co-Authored-By: Claude Opus 5.5 Signed-off-by: Steven Borrelli --- README.md | 18 ++-- USAGE.md | 68 ++++++------- package-lock.json | 48 +++++++--- src/cli/cli.test.ts | 116 +++++++++++++++++++++++ src/cli/cli.ts | 200 ++++++++++++++++++++++++++++----------- src/function/function.ts | 6 +- src/index.ts | 8 +- src/runtime/runtime.ts | 5 +- src/serve/serve.test.ts | 53 ++++++++++- src/serve/serve.ts | 138 ++++++++------------------- 10 files changed, 446 insertions(+), 214 deletions(-) diff --git a/README.md b/README.md index 45db847..54b4658 100644 --- a/README.md +++ b/README.md @@ -60,13 +60,14 @@ serve(compose); ### Custom Flags with the Shareable CLI -If your function needs its own command-line flags or environment variables, use the -`CLI` class instead of calling `serve()` directly. It provides the same standard -flags that `serve()` uses, plus a way to register your own: +Every function served by `serve()` accepts the same standard flags and environment +variables — `--address`/`ADDRESS`, `--max-recv-message-size`/`MAX_RECV_MESSAGE_SIZE` and +so on. If your function needs flags of its own, declare them with the `CLI` class and +hand it to `serve()`, which parses it, handles `--help` and reports usage errors: ```typescript import { CLI, serve } from "@crossplane-org/function-sdk-typescript"; -import { compose } from "./my-function.js"; +import { compose } from "./my-function.js"; // (req, rsp, cacheSize: number) => rsp const cli = new CLI({ flags: { @@ -74,13 +75,8 @@ const cli = new CLI({ }, }); -const parsed = cli.parse(); -if (parsed.help) { - process.stdout.write(cli.helpText() + "\n"); - process.exit(0); -} - -serve(compose, { argv: [], serverOptions: cli.standardOptions(), logger: cli.logger() }); +// serve() parses the CLI before any request arrives, so compose can read its values. +serve((req, rsp) => compose(req, rsp, Number(cli.values["cache-size"])), { cli }); ``` See [USAGE.md](USAGE.md#custom-flags-with-the-shareable-cli) for the full list of diff --git a/USAGE.md b/USAGE.md index b8fde04..d11e7b2 100644 --- a/USAGE.md +++ b/USAGE.md @@ -151,7 +151,9 @@ That is the whole entry point. `serve()` parses the standard function flags, bui logger from `--debug`, starts the gRPC server, and shuts it down cleanly on `SIGINT` and `SIGTERM`. It accepts either a `ComposeFunction` or a `FunctionHandler`. -Every function served this way accepts the same flags: +Every function served this way accepts the same flags and environment variables, so +tooling can configure every function in a pipeline the same way. A flag given on the +command line wins over its environment variable, which wins over the default: | Flag | Env | Default | Description | |------|-----|---------|-------------| @@ -159,15 +161,20 @@ Every function served this way accepts the same flags: | `--debug` / `-d` | `DEBUG` | `false` | Emit debug logs | | `--insecure` | `INSECURE` | `false` | Run without mTLS | | `--tls-server-certs-dir` | `TLS_SERVER_CERTS_DIR` | `/tls/server` | mTLS certificate directory | -| `--max-recv-message-size` | `MAX_RECV_MESSAGE_SIZE` | `4` | Max gRPC message size in MB | +| `--max-recv-message-size` | `MAX_RECV_MESSAGE_SIZE`, `MAX_GRPC_MESSAGE_SIZE` | `4` | Max received gRPC message size in MB | +| `--max-send-message-size` | `MAX_SEND_MESSAGE_SIZE` | the receive size | Max sent gRPC message size in MB | | `--help` / `-h` | — | `false` | Show help text | +Boolean environment variables are on when set to `true` or `1`. Message sizes must be +positive whole numbers of megabytes; anything else is rejected at startup. + `serve()` takes an options object for the cases where the defaults do not fit: ```typescript serve(compose, { name: "my-function", // Program name shown in --help argv: ["--insecure"], // Defaults to process.argv.slice(2) + cli: myCLI, // A CLI declaring flags of your own (see below) logger: myLogger, // Defaults to a pino logger built from --debug serverOptions: { insecure: true } // Overrides applied on top of the parsed flags }); @@ -190,15 +197,15 @@ node dist/main.js --tls-server-certs-dir /path/to/certs ### Custom Flags with the Shareable CLI -If your function needs its own command-line flags or environment variables, use the -`CLI` class. It provides the same standard flags that `serve()` uses, plus a way to -register your own: +If your function needs its own command-line flags or environment variables, declare +them with the `CLI` class and hand it to `serve()`. `serve()` is built on the same +class, so your function keeps every standard flag, and `--help` lists yours alongside +them: ```typescript #!/usr/bin/env node -import { CLI, serve } from "@crossplane-org/function-sdk-typescript"; -import { compose } from "./my-function.js"; +import { CLI, serve, type ComposeFunction } from "@crossplane-org/function-sdk-typescript"; const cli = new CLI({ flags: { @@ -210,7 +217,6 @@ const cli = new CLI({ }, "verbose": { type: "boolean", - default: false, short: "v", env: "VERBOSE", description: "Enable verbose output.", @@ -218,38 +224,34 @@ const cli = new CLI({ }, }); -try { - const parsed = cli.parse(); - if (parsed.help) { - process.stdout.write(cli.helpText() + "\n"); - process.exit(0); - } - - // Pass the CLI's standard options and logger to serve, skipping its - // internal argument parsing by supplying an empty argv. - serve(compose, { - argv: [], - serverOptions: cli.standardOptions(), - logger: cli.logger(), - }); +const compose: ComposeFunction = (req, rsp) => { + // serve() parses the CLI before the server starts, so its values are + // always available by the time a request arrives. + const cacheSize = Number(cli.values["cache-size"]); + // ... + return rsp; +}; - const cacheSize = Number(parsed["cache-size"]); -} catch (error) { - process.stderr.write(`${cli.name}: ${error instanceof Error ? error.message : error}\n`); - process.exit(2); -} +serve(compose, { cli }); ``` +`serve()` parses the CLI, reports bad flags as usage errors, and handles `--help`. If you +need the values before the server starts, call `cli.parse()` yourself first; `serve()` +then uses those values rather than parsing again, though errors thrown by your own +`parse()` call are yours to report. + Each custom flag supports: - **`type`** — `"string"` or `"boolean"`. -- **`default`** — Value used when neither the CLI argument nor the env var is set. +- **`default`** — Value used when neither the CLI argument nor the env var is set. A + boolean flag can only default to `false`, since it could never be turned off. - **`short`** — Single-character alias (e.g. `-v`). - **`env`** — Environment variable name. Resolution order: CLI argument > env var > default. +- **`envAliases`** — Further environment variables, checked in order when `env` is unset. - **`description`** — Shown in `--help` output. -Custom flag names must not collide with the standard flags; the constructor throws if -they do. +The constructor throws if a custom flag reuses a standard flag's name or any other +flag's short alias, or is a boolean flag defaulting to `true`. ### Building the Server Yourself @@ -428,8 +430,10 @@ normal(rsp, "Function completed successfully"); - `new CLI(opts?)` - Create a CLI with optional custom flags - `cli.parse(argv?)` - Parse arguments (CLI arg > env var > default) -- `cli.standardOptions()` - Get `ServerOptions` from the standard flags -- `cli.logger()` - Get a pino Logger configured from `--debug` +- `cli.values` - The parsed values, keyed by flag name; throws before `parse()` +- `cli.parsed` - Whether `parse()` has been called +- `cli.standardOptions()` - Get `ServerOptions` from the standard flags; throws before `parse()` +- `cli.logger()` - Get a pino Logger configured from `--debug`; throws before `parse()` - `cli.helpText()` - Generate help text including custom flags - `cli.name` - The program name used in help text diff --git a/package-lock.json b/package-lock.json index dc29a46..c7469c8 100644 --- a/package-lock.json +++ b/package-lock.json @@ -479,7 +479,6 @@ "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.20.0.tgz", "integrity": "sha512-Thbli+OlOj+iMPYFBVBfJ3OmCAnaSyNn4M1vz9T6Gka5Jt9ba/HIR56joy65tY6kx/FCF5VXNB819Y7/GUrBGA==", "license": "MIT", - "peer": true, "dependencies": { "fast-deep-equal": "^3.1.3", "fast-uri": "^3.0.1", @@ -512,6 +511,7 @@ "integrity": "sha512-1Duyg48TdJNdyhEB8Xn1L36bT9Pv6GUtlKjHxOys8xkaF/rQq3XJE+bAurSK/AgIz5mGFsb77cn9Pb20+WCScw==", "dev": true, "license": "MIT", + "peer": true, "funding": { "url": "https://github.com/sponsors/oxc-project" } @@ -592,6 +592,7 @@ "os": [ "android" ], + "peer": true, "engines": { "node": "^20.19.0 || >=22.12.0" } @@ -609,6 +610,7 @@ "os": [ "android" ], + "peer": true, "engines": { "node": "^20.19.0 || >=22.12.0" } @@ -626,6 +628,7 @@ "os": [ "darwin" ], + "peer": true, "engines": { "node": "^20.19.0 || >=22.12.0" } @@ -643,6 +646,7 @@ "os": [ "darwin" ], + "peer": true, "engines": { "node": "^20.19.0 || >=22.12.0" } @@ -660,6 +664,7 @@ "os": [ "freebsd" ], + "peer": true, "engines": { "node": "^20.19.0 || >=22.12.0" } @@ -677,6 +682,7 @@ "os": [ "linux" ], + "peer": true, "engines": { "node": "^20.19.0 || >=22.12.0" } @@ -697,6 +703,7 @@ "os": [ "linux" ], + "peer": true, "engines": { "node": "^20.19.0 || >=22.12.0" } @@ -717,6 +724,7 @@ "os": [ "linux" ], + "peer": true, "engines": { "node": "^20.19.0 || >=22.12.0" } @@ -737,6 +745,7 @@ "os": [ "linux" ], + "peer": true, "engines": { "node": "^20.19.0 || >=22.12.0" } @@ -757,6 +766,7 @@ "os": [ "linux" ], + "peer": true, "engines": { "node": "^20.19.0 || >=22.12.0" } @@ -777,6 +787,7 @@ "os": [ "linux" ], + "peer": true, "engines": { "node": "^20.19.0 || >=22.12.0" } @@ -797,6 +808,7 @@ "os": [ "linux" ], + "peer": true, "engines": { "node": "^20.19.0 || >=22.12.0" } @@ -814,6 +826,7 @@ "os": [ "openharmony" ], + "peer": true, "engines": { "node": "^20.19.0 || >=22.12.0" } @@ -831,6 +844,7 @@ "os": [ "win32" ], + "peer": true, "engines": { "node": "^20.19.0 || >=22.12.0" } @@ -848,6 +862,7 @@ "os": [ "win32" ], + "peer": true, "engines": { "node": "^20.19.0 || >=22.12.0" } @@ -857,7 +872,8 @@ "resolved": "https://registry.npmjs.org/@rolldown/pluginutils/-/pluginutils-1.0.1.tgz", "integrity": "sha512-2j9bGt5Jh8hj+vPtgzPtl72j0yRxHAyumoo6TNfAjsLB04UtpSvPbPcDcBMxz7n+9CYB0c1GxQFxYRg2jimqGw==", "dev": true, - "license": "MIT" + "license": "MIT", + "peer": true }, "node_modules/@tsconfig/node10": { "version": "1.0.12", @@ -931,7 +947,6 @@ "resolved": "https://registry.npmjs.org/@types/node/-/node-26.6.6.tgz", "integrity": "sha512-MzQj+8Kx3XI40OmUAE6Qoh58ZMNstNNMwn2nfd3qWsfe7nDNSqJNzes4njhz6AHwrSHOffSLwXU6yb474Q4aog==", "license": "MIT", - "peer": true, "dependencies": { "undici-types": "~8.9.0" } @@ -981,7 +996,6 @@ "integrity": "sha512-ZGwZP4OCfyA0AQTpEAMWz+rtX01DRhQWW5hB0ucKDEIX5U7jdmPSaMx94rQfaPAQzIYz2BimOgKOJtjfpRFQ9g==", "dev": true, "license": "MIT", - "peer": true, "dependencies": { "@typescript-eslint/scope-manager": "8.72.1", "@typescript-eslint/types": "8.72.1", @@ -1564,7 +1578,6 @@ "integrity": "sha512-4KpkGdIrSqBihx/JyP/e+S+IKB98etg1XDQiLAxksLfcShnwi1VReGeOT9NI43hLHbknosKp/1CCLn9Zgcs8mg==", "dev": true, "license": "MIT", - "peer": true, "dependencies": { "@bcoe/v8-coverage": "^1.0.2", "@vitest/istanbul-lib-coverage": "^1.0.2", @@ -1655,7 +1668,6 @@ "integrity": "sha512-UVJyE9MttOsBQIDKw1skb9nAwQuR5wuGD3+82K6JgJlm/Y+KI92oNsMNGZCYdDsVtRHSak0pcV5Dno5+4jh9sw==", "dev": true, "license": "MIT", - "peer": true, "bin": { "acorn": "bin/acorn" }, @@ -1691,7 +1703,6 @@ "resolved": "https://registry.npmjs.org/ajv/-/ajv-6.14.0.tgz", "integrity": "sha512-IWrosm/yrn43eiKqkfkHis7QioDleaXQHdDVPKg0FSwwd/DuvyX79TZnFOnYpB7dcsFAMmtFztZuXPDvSePkFw==", "license": "MIT", - "peer": true, "dependencies": { "fast-deep-equal": "^3.1.1", "fast-json-stable-stringify": "^2.0.0", @@ -2053,7 +2064,6 @@ "integrity": "sha512-T0pNsxkb9IKmtQjhpK3d7nWOpFv+YHuMbTJnSVMoQblF0onvXfErrtp4V1jHtsQPan7dKaGVD0q1WCXnzMF31A==", "dev": true, "license": "MIT", - "peer": true, "workspaces": [ "packages/*" ], @@ -2339,6 +2349,7 @@ "os": [ "darwin" ], + "peer": true, "engines": { "node": "^8.16.0 || ^10.6.0 || >=11.0.0" } @@ -2520,6 +2531,7 @@ "integrity": "sha512-WkUDrojuJs0xkgGf2udWxa3yGBRxPtxUkB79i6aCZLRgc7PM8fZe9TosfPDcvEpQZbuFASnHYmRLBLUbmLOIIA==", "dev": true, "license": "MPL-2.0", + "peer": true, "dependencies": { "detect-libc": "^2.0.3" }, @@ -2557,6 +2569,7 @@ "os": [ "android" ], + "peer": true, "engines": { "node": ">= 12.0.0" }, @@ -2578,6 +2591,7 @@ "os": [ "darwin" ], + "peer": true, "engines": { "node": ">= 12.0.0" }, @@ -2599,6 +2613,7 @@ "os": [ "darwin" ], + "peer": true, "engines": { "node": ">= 12.0.0" }, @@ -2620,6 +2635,7 @@ "os": [ "freebsd" ], + "peer": true, "engines": { "node": ">= 12.0.0" }, @@ -2641,6 +2657,7 @@ "os": [ "linux" ], + "peer": true, "engines": { "node": ">= 12.0.0" }, @@ -2665,6 +2682,7 @@ "os": [ "linux" ], + "peer": true, "engines": { "node": ">= 12.0.0" }, @@ -2689,6 +2707,7 @@ "os": [ "linux" ], + "peer": true, "engines": { "node": ">= 12.0.0" }, @@ -2713,6 +2732,7 @@ "os": [ "linux" ], + "peer": true, "engines": { "node": ">= 12.0.0" }, @@ -2737,6 +2757,7 @@ "os": [ "linux" ], + "peer": true, "engines": { "node": ">= 12.0.0" }, @@ -2758,6 +2779,7 @@ "os": [ "win32" ], + "peer": true, "engines": { "node": ">= 12.0.0" }, @@ -2779,6 +2801,7 @@ "os": [ "win32" ], + "peer": true, "engines": { "node": ">= 12.0.0" }, @@ -2793,6 +2816,7 @@ "integrity": "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==", "dev": true, "license": "Apache-2.0", + "peer": true, "engines": { "node": ">=8" } @@ -2895,6 +2919,7 @@ } ], "license": "MIT", + "peer": true, "bin": { "nanoid": "bin/nanoid.cjs" }, @@ -3029,7 +3054,8 @@ "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz", "integrity": "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==", "dev": true, - "license": "ISC" + "license": "ISC", + "peer": true }, "node_modules/picomatch": { "version": "4.0.7", @@ -3107,6 +3133,7 @@ } ], "license": "MIT", + "peer": true, "dependencies": { "nanoid": "^3.3.20", "picocolors": "^1.1.1", @@ -3287,6 +3314,7 @@ "integrity": "sha512-bWvlMpFKiTfDKfnK7FC2MPgPeWCf/Kpwsq49ApdW+FQaBZb6O6dZ4MAPbPUjp7hYQrw/RobqCzn64BRrQecGHw==", "dev": true, "license": "MIT", + "peer": true, "dependencies": { "@oxc-project/types": "=0.156.0", "@rolldown/pluginutils": "^1.0.0" @@ -3623,7 +3651,6 @@ "integrity": "sha512-mbCddXd+jm7hfx7w2YU64/Av4/NqqeG3GoRZgxPcgoTxYjhrcfJRw9ULch71SS4G+Q3bOXFhRvPqjguN0Hyp5w==", "dev": true, "license": "Apache-2.0", - "peer": true, "dependencies": { "@typescript/old": "npm:typescript@^6" }, @@ -3762,7 +3789,6 @@ "integrity": "sha512-cPODOMF8YnkiiYtDdHo6n4wWmBrOBBbOIYH2d33M4l3CdNn72h+qMmO6uXffUN6A5AZFXNND/d+krS9mgkXRfg==", "dev": true, "license": "MIT", - "peer": true, "dependencies": { "@types/chai": "^5.2.2", "@vitest/mocker": "5.0.5", diff --git a/src/cli/cli.test.ts b/src/cli/cli.test.ts index 20d81fb..43dfe2f 100644 --- a/src/cli/cli.test.ts +++ b/src/cli/cli.test.ts @@ -109,6 +109,99 @@ describe('CLI', () => { }) ).toThrow(/flag "debug" conflicts with a standard flag/); }); + + it('should reject a custom short alias that a standard flag uses', () => { + // Otherwise -d would silently keep meaning --debug, and the custom flag's + // alias would never take effect. + expect( + () => + new CLI({ + flags: { verbose: { type: 'boolean', short: 'd', description: 'Verbose.' } }, + }) + ).toThrow(/flag "verbose" reuses short alias -d of flag "debug"/); + }); + + it('should reject two custom flags sharing a short alias', () => { + expect( + () => + new CLI({ + flags: { + verbose: { type: 'boolean', short: 'v', description: 'Verbose.' }, + version: { type: 'boolean', short: 'v', description: 'Version.' }, + }, + }) + ).toThrow(/flag "version" reuses short alias -v of flag "verbose"/); + }); + + it('should reject a boolean flag that defaults to true', () => { + // A boolean flag on the command line can only turn something on, so one + // that is already on could never be turned off. + expect( + () => + new CLI({ + flags: { feature: { type: 'boolean', default: true, description: 'Feature.' } }, + }) + ).toThrow(/boolean flag "feature" cannot default to true/); + }); + + it('should default a custom boolean flag without a declared default to false', () => { + const cli = new CLI({ + flags: { verbose: { type: 'boolean', description: 'Verbose.' } }, + }); + expect(cli.parse([]).verbose).toBe(false); + }); + + it('should reject a message size that is not a whole number', () => { + const cli = new CLI({ name: 'test' }); + expect(() => cli.parse(['--max-recv-message-size', 'eight'])).toThrow( + /--max-recv-message-size or MAX_RECV_MESSAGE_SIZE or MAX_GRPC_MESSAGE_SIZE must be a positive whole number of megabytes, got "eight"/ + ); + expect(() => cli.parse(['--max-send-message-size', '1.5'])).toThrow( + /--max-send-message-size or MAX_SEND_MESSAGE_SIZE must be a positive whole number/ + ); + }); + + it('should reject a message size that is zero or negative', () => { + const cli = new CLI({ name: 'test' }); + expect(() => cli.parse(['--max-recv-message-size', '0'])).toThrow(/got "0"/); + expect(() => cli.parse(['--max-recv-message-size=-1'])).toThrow(/got "-1"/); + }); + + it('should reject a message size with a unit from the environment', () => { + // parseInt would read this as 16 and drop the unit without a word. + process.env.MAX_RECV_MESSAGE_SIZE = '16MB'; + const cli = new CLI({ name: 'test' }); + expect(() => cli.parse([])).toThrow(/got "16MB"/); + }); + }); + + describe('before parse', () => { + it('should refuse to return values', () => { + expect(() => new CLI({ name: 'test' }).values).toThrow(/parse\(\) must be called/); + }); + + it('should refuse to return standard options', () => { + // Returning undefineds instead would override serve's own defaults and + // reach grpc-js as an undefined listen address. + expect(() => new CLI({ name: 'test' }).standardOptions()).toThrow(/parse\(\) must be called/); + }); + + it('should refuse to build a logger', () => { + expect(() => new CLI({ name: 'test' }).logger()).toThrow(/parse\(\) must be called/); + }); + + it('should report whether it has been parsed', () => { + const cli = new CLI({ name: 'test' }); + expect(cli.parsed).toBe(false); + cli.parse([]); + expect(cli.parsed).toBe(true); + }); + + it('should not record values from a parse that failed', () => { + const cli = new CLI({ name: 'test' }); + expect(() => cli.parse(['--max-recv-message-size', 'eight'])).toThrow(); + expect(cli.parsed).toBe(false); + }); }); describe('environment variables', () => { @@ -234,6 +327,16 @@ describe('CLI', () => { expect(cli.standardOptions().maxSendMessageSize).toBe(16 * 1024 * 1024); }); + it('should read message sizes from the environment', () => { + process.env.MAX_GRPC_MESSAGE_SIZE = '16'; + process.env.MAX_SEND_MESSAGE_SIZE = '32'; + const cli = new CLI({ name: 'test' }); + cli.parse([]); + + expect(cli.standardOptions().maxRecvMessageSize).toBe(16 * 1024 * 1024); + expect(cli.standardOptions().maxSendMessageSize).toBe(32 * 1024 * 1024); + }); + it('should reflect env vars in standard options', () => { process.env.ADDRESS = 'env:1111'; process.env.DEBUG = 'true'; @@ -323,4 +426,17 @@ describe('CLI', () => { expect(cli.name).toBe('my-function'); }); }); + + describe('values', () => { + it('should return the values from the last parse', () => { + const cli = new CLI({ + name: 'test', + flags: { 'my-flag': { type: 'string', default: 'foo', description: 'Test.' } }, + }); + cli.parse(['--my-flag', 'bar']); + + expect(cli.values['my-flag']).toBe('bar'); + expect(cli.values.address).toBe('0.0.0.0:9443'); + }); + }); }); diff --git a/src/cli/cli.ts b/src/cli/cli.ts index 3bdf81b..bf9dd5f 100644 --- a/src/cli/cli.ts +++ b/src/cli/cli.ts @@ -3,11 +3,11 @@ * * The {@link CLI} class provides the standard flags every composition function * accepts, reads environment variables, and lets function authors add custom - * flags. + * flags. {@link serve} is built on it, so every function honours the same + * flags and environment variables whether or not it declares flags of its own. * - * Simple functions that need no custom flags can keep using {@link serve}. - * Functions that need extra flags create a CLI, parse it, then pass the - * results to serve: + * Functions that need extra flags create a CLI and hand it to serve, which + * parses it, handles --help and reports usage errors: * * @example * ```typescript @@ -17,13 +17,10 @@ * }, * }); * - * const parsed = cli.parse(); - * if (parsed.help) { - * process.stdout.write(cli.helpText() + '\n'); - * process.exit(0); - * } + * serve(compose, { cli }); * - * serve(compose, { argv: [], serverOptions: cli.standardOptions(), logger: cli.logger() }); + * // serve has parsed the CLI by the time it returns. + * const myFlag = cli.values['my-flag']; * ``` */ @@ -32,13 +29,25 @@ import { parseArgs as parseNodeArgs } from 'node:util'; import { pino, type Logger } from 'pino'; import type { ServerOptions } from '../runtime/runtime.js'; -const DEFAULT_ADDRESS = '0.0.0.0:9443'; -const DEFAULT_MAX_RECV_MESSAGE_SIZE = 4; -const DEFAULT_TLS_SERVER_CERTS_DIR = '/tls/server'; +/** The address a function listens on unless told otherwise. */ +export const DEFAULT_ADDRESS = '0.0.0.0:9443'; + +/** + * Where the package reconciler mounts the TLS certificates it generates. + */ +export const DEFAULT_TLS_SERVER_CERTS_DIR = '/tls/server'; + +/** The default maximum size of a received gRPC message, in megabytes. */ +export const DEFAULT_MAX_RECV_MESSAGE_SIZE = 4; /** Specification for a single CLI flag. */ export interface FlagSpec { type: 'string' | 'boolean'; + /** + * Value used when neither the flag nor its environment variable is set. + * Boolean flags may only default to false, since a boolean flag set on the + * command line can only turn something on. + */ default?: string | boolean; short?: string; /** Primary environment variable. */ @@ -48,6 +57,9 @@ export interface FlagSpec { description: string; } +/** The value of a parsed flag. */ +export type FlagValue = string | boolean | undefined; + const standardFlags: Record = { address: { type: 'string', @@ -94,6 +106,9 @@ const standardFlags: Record = { }, }; +/** Standard flags whose value is a whole number of megabytes. */ +const megabyteFlags = ['max-recv-message-size', 'max-send-message-size']; + /** Options accepted by the {@link CLI} constructor. */ export interface CLIOptions { /** Program name shown in help text. Defaults to the running script's basename. */ @@ -107,16 +122,20 @@ export interface CLIOptions { * A shareable, extensible CLI for Crossplane composition functions. * * Provides the standard flags (address, debug, insecure, tls-server-certs-dir, - * max-recv-message-size, help) with environment variable support, and lets - * function authors register additional flags. + * max-recv-message-size, max-send-message-size, help) with environment + * variable support, and lets function authors register additional flags. * * Resolution order per flag: CLI argument > environment variable > default. */ export class CLI { private readonly programName: string; private readonly allFlags: Record; - private values: Record = {}; + private parsedValues?: Record; + /** + * @throws If a custom flag reuses a standard flag's name or another flag's + * short alias, or is a boolean flag that defaults to true. + */ constructor(opts?: CLIOptions) { this.programName = opts?.name ?? defaultName(); @@ -127,6 +146,21 @@ export class CLI { } } this.allFlags = { ...standardFlags, ...custom }; + + const shorts = new Map(); + for (const [name, spec] of Object.entries(this.allFlags)) { + if (spec.type === 'boolean' && spec.default === true) { + throw new Error( + `boolean flag "${name}" cannot default to true, since it could not be turned off` + ); + } + if (spec.short === undefined) continue; + const other = shorts.get(spec.short); + if (other !== undefined) { + throw new Error(`flag "${name}" reuses short alias -${spec.short} of flag "${other}"`); + } + shorts.set(spec.short, name); + } } /** @@ -141,14 +175,13 @@ export class CLI { * @throws If a flag is unrecognized, missing its value, or given a value it * does not accept. */ - parse(argv?: string[]): Record { + parse(argv?: string[]): Record { const args = argv ?? process.argv.slice(2); - const parseOptions: Record = {}; + const parseOptions: Record = {}; for (const [name, spec] of Object.entries(this.allFlags)) { - const opt: { type: string; short?: string; default?: boolean } = { type: spec.type }; + const opt: { type: string; short?: string } = { type: spec.type }; if (spec.short) opt.short = spec.short; - if (spec.type === 'boolean') opt.default = false; parseOptions[name] = opt; } @@ -158,52 +191,88 @@ export class CLI { allowPositionals: false, }); - const parsed = values as Record; + const parsed = values as Record; + const resolved: Record = {}; for (const [name, spec] of Object.entries(this.allFlags)) { - this.values[name] = resolveValue(spec, parsed[name]); + resolved[name] = resolveValue(spec, parsed[name]); + } + + // Check the sizes now, so that a bad value is reported as a usage error + // rather than silently replaced by a default once the server starts. + for (const name of megabyteFlags) { + const value = resolved[name]; + if (value !== undefined) toBytes(name, this.allFlags[name], String(value)); } - return { ...this.values }; + this.parsedValues = resolved; + return { ...resolved }; } - /** Return {@link ServerOptions} derived from the standard flags. */ - standardOptions(): ServerOptions { - const maxRecvMB = parseInt(String(this.values['max-recv-message-size']), 10); - const recvBytes = (isNaN(maxRecvMB) ? DEFAULT_MAX_RECV_MESSAGE_SIZE : maxRecvMB) * 1024 * 1024; + /** + * The values from the last call to {@link parse}. + * + * @throws If {@link parse} has not been called. + */ + get values(): Readonly> { + if (this.parsedValues === undefined) { + throw new Error('CLI.parse() must be called before reading its values'); + } + return this.parsedValues; + } - const sendRaw = this.values['max-send-message-size']; - const maxSendMB = sendRaw !== undefined ? parseInt(String(sendRaw), 10) : NaN; - const sendBytes = isNaN(maxSendMB) ? undefined : maxSendMB * 1024 * 1024; + /** Whether {@link parse} has been called. */ + get parsed(): boolean { + return this.parsedValues !== undefined; + } + + /** + * Return {@link ServerOptions} derived from the standard flags. + * + * @throws If {@link parse} has not been called. + */ + standardOptions(): ServerOptions { + const values = this.values; + const send = values['max-send-message-size']; return { - address: this.values['address'] as string, - debug: this.values['debug'] as boolean, - insecure: this.values['insecure'] as boolean, - tlsServerCertsDir: this.values['tls-server-certs-dir'] as string, - maxRecvMessageSize: recvBytes, - maxSendMessageSize: sendBytes, + address: values['address'] as string, + debug: values['debug'] as boolean, + insecure: values['insecure'] as boolean, + tlsServerCertsDir: values['tls-server-certs-dir'] as string, + maxRecvMessageSize: toBytes( + 'max-recv-message-size', + this.allFlags['max-recv-message-size'], + String(values['max-recv-message-size']) + ), + maxSendMessageSize: + send === undefined + ? undefined + : toBytes('max-send-message-size', this.allFlags['max-send-message-size'], String(send)), }; } - /** Return a pino {@link Logger} configured from the --debug flag. */ + /** + * Return a pino {@link Logger} configured from the --debug flag. + * + * @throws If {@link parse} has not been called. + */ logger(): Logger { - return pino({ - level: this.values['debug'] ? 'debug' : 'info', - formatters: { - level: (label: string) => ({ severity: label.toUpperCase() }), - }, - }); + return newLogger(this.values['debug'] === true); } /** Generate help text that includes both standard and custom flags. */ helpText(): string { - const usage = Object.entries(this.allFlags).map(([flag, spec]) => { + const rows = Object.entries(this.allFlags).map(([flag, spec]) => { const short = spec.short ? `-${spec.short}, ` : ' '; const value = spec.type === 'string' ? ' ' : ''; const env = spec.env ? ` [env: ${spec.env}]` : ''; - return ` ${short}--${flag}${value}`.padEnd(38) + spec.description + env; + return { usage: ` ${short}--${flag}${value}`, description: spec.description + env }; }); + // Size the column to the longest flag, so a long custom flag name cannot + // run into its description. + const width = Math.max(...rows.map((r) => r.usage.length)) + 2; + const usage = rows.map((r) => r.usage.padEnd(width) + r.description); return [ `Usage: ${this.programName} [flags]`, '', @@ -220,14 +289,23 @@ export class CLI { } } -function resolveValue( - spec: FlagSpec, - cliValue: string | boolean | undefined -): string | boolean | undefined { - const givenOnCli = - spec.type === 'string' ? cliValue !== undefined : (cliValue as boolean) === true; +/** + * Create the logger a function uses: JSON, with the level reported as + * `severity` so that log collectors pick it up. + */ +export function newLogger(debug: boolean): Logger { + return pino({ + level: debug ? 'debug' : 'info', + formatters: { + level: (label: string) => ({ severity: label.toUpperCase() }), + }, + }); +} - if (givenOnCli) return cliValue; +function resolveValue(spec: FlagSpec, cliValue: FlagValue): FlagValue { + // node:util leaves a flag that was not given undefined, and a boolean flag + // can only be given as true, so undefined means "not on the command line". + if (cliValue !== undefined) return cliValue; const envKeys = [spec.env, ...(spec.envAliases ?? [])].filter(Boolean) as string[]; for (const key of envKeys) { @@ -239,7 +317,23 @@ function resolveValue( } } - return spec.default; + return spec.type === 'boolean' ? (spec.default ?? false) : spec.default; +} + +/** + * Convert a size in megabytes to bytes. + * + * @throws If the value is not a positive whole number. + */ +function toBytes(name: string, spec: FlagSpec | undefined, value: string): number { + if (!/^[1-9][0-9]*$/.test(value)) { + const envKeys = [spec?.env, ...(spec?.envAliases ?? [])].filter(Boolean); + const source = [`--${name}`, ...envKeys].join(' or '); + throw new Error( + `${source} must be a positive whole number of megabytes, got ${JSON.stringify(value)}` + ); + } + return Number(value) * 1024 * 1024; } function defaultName(): string { diff --git a/src/function/function.ts b/src/function/function.ts index 4cfc5dd..2324bb9 100644 --- a/src/function/function.ts +++ b/src/function/function.ts @@ -139,6 +139,8 @@ export class FunctionRunner { * * @param functionRunner - The FunctionRunner instance to handle requests * @param logger - Logger instance for debug logging + * @param opts - Message size limits in bytes. The send limit falls back to the + * receive limit; with neither set, grpc-js's own defaults apply. * @returns A configured gRPC Server with the function service registered * * @example @@ -153,11 +155,11 @@ export function getServer( opts?: { maxRecvMessageSize?: number; maxSendMessageSize?: number } ): grpc.Server { const channelOptions: grpc.ServerOptions = {}; - if (opts?.maxRecvMessageSize) { + if (opts?.maxRecvMessageSize !== undefined) { channelOptions['grpc.max_receive_message_length'] = opts.maxRecvMessageSize; } const sendSize = opts?.maxSendMessageSize ?? opts?.maxRecvMessageSize; - if (sendSize) { + if (sendSize !== undefined) { channelOptions['grpc.max_send_message_length'] = sendSize; } const server = new grpc.Server(channelOptions); diff --git a/src/index.ts b/src/index.ts index 4a13a96..1d7c1d8 100644 --- a/src/index.ts +++ b/src/index.ts @@ -62,7 +62,13 @@ export { } from './resource/resource.js'; // Shareable CLI -export { CLI, type CLIOptions, type FlagSpec } from './cli/cli.js'; +export { + CLI, + type CLIOptions, + DEFAULT_MAX_RECV_MESSAGE_SIZE, + type FlagSpec, + type FlagValue, +} from './cli/cli.js'; // Runtime utilities export { diff --git a/src/runtime/runtime.ts b/src/runtime/runtime.ts index ddb39e6..59ccc0f 100644 --- a/src/runtime/runtime.ts +++ b/src/runtime/runtime.ts @@ -44,13 +44,14 @@ export interface ServerOptions { /** * Maximum size of received gRPC messages in bytes. - * Default: 4 MB (4 * 1024 * 1024). + * Default: grpc-js's own limit of 4 MB (4 * 1024 * 1024). */ maxRecvMessageSize?: number; /** * Maximum size of sent gRPC messages in bytes. - * Defaults to maxRecvMessageSize when not set. + * Defaults to maxRecvMessageSize when not set, and to grpc-js's own + * default (unlimited) when neither is set. */ maxSendMessageSize?: number; } diff --git a/src/serve/serve.test.ts b/src/serve/serve.test.ts index c715852..29e65ad 100644 --- a/src/serve/serve.test.ts +++ b/src/serve/serve.test.ts @@ -1,4 +1,4 @@ -import { describe, it, expect } from 'vitest'; +import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'; import { DEFAULT_ADDRESS, DEFAULT_TLS_SERVER_CERTS_DIR, @@ -12,6 +12,26 @@ import { Resource, RunFunctionRequest } from '../proto/run_function.js'; import { Severity } from '../proto/run_function.js'; import { fatal, to } from '../response/response.js'; +// parseArgs reads the standard environment variables, so clear them to keep +// the tests independent of the environment they run in. +const standardEnv = [ + 'ADDRESS', + 'DEBUG', + 'INSECURE', + 'TLS_SERVER_CERTS_DIR', + 'MAX_RECV_MESSAGE_SIZE', + 'MAX_GRPC_MESSAGE_SIZE', + 'MAX_SEND_MESSAGE_SIZE', +]; + +beforeEach(() => { + for (const key of standardEnv) vi.stubEnv(key, undefined); +}); + +afterEach(() => { + vi.unstubAllEnvs(); +}); + describe('parseArgs', () => { it('should default every flag', () => { expect(parseArgs([])).toEqual({ @@ -19,10 +39,29 @@ describe('parseArgs', () => { debug: false, insecure: false, tlsServerCertsDir: DEFAULT_TLS_SERVER_CERTS_DIR, + maxRecvMessageSize: 4 * 1024 * 1024, + maxSendMessageSize: undefined, help: false, }); }); + it('should read the standard environment variables', () => { + // serve is built on parseArgs' parser, so this is what lets tooling + // configure every function the same way, whether or not it declares flags + // of its own. + vi.stubEnv('ADDRESS', '127.0.0.1:19999'); + vi.stubEnv('MAX_RECV_MESSAGE_SIZE', '16'); + const opts = parseArgs([]); + expect(opts.address).toBe('127.0.0.1:19999'); + expect(opts.maxRecvMessageSize).toBe(16 * 1024 * 1024); + }); + + it('should parse the message size flags', () => { + const opts = parseArgs(['--max-recv-message-size', '16', '--max-send-message-size', '32']); + expect(opts.maxRecvMessageSize).toBe(16 * 1024 * 1024); + expect(opts.maxSendMessageSize).toBe(32 * 1024 * 1024); + }); + it('should parse flags given as separate arguments', () => { const opts = parseArgs([ '--address', @@ -37,6 +76,8 @@ describe('parseArgs', () => { debug: true, insecure: true, tlsServerCertsDir: '/certs', + maxRecvMessageSize: 4 * 1024 * 1024, + maxSendMessageSize: undefined, help: false, }); }); @@ -76,7 +117,15 @@ describe('helpText', () => { it('should name the program and list every flag', () => { const help = helpText('my-function'); expect(help).toContain('Usage: my-function'); - for (const flag of ['--address', '--debug', '--insecure', '--tls-server-certs-dir', '--help']) { + for (const flag of [ + '--address', + '--debug', + '--insecure', + '--max-recv-message-size', + '--max-send-message-size', + '--tls-server-certs-dir', + '--help', + ]) { expect(help).toContain(flag); } }); diff --git a/src/serve/serve.ts b/src/serve/serve.ts index cfb42a7..75ddc77 100644 --- a/src/serve/serve.ts +++ b/src/serve/serve.ts @@ -13,21 +13,14 @@ */ import * as grpc from '@grpc/grpc-js'; -import { basename } from 'node:path'; -import { parseArgs as parseNodeArgs } from 'node:util'; -import { pino, type Logger } from 'pino'; +import type { Logger } from 'pino'; +import { CLI, newLogger } from '../cli/cli.js'; import { FunctionRunner, type FunctionHandler } from '../function/function.js'; import { newGrpcServer, startServer, type ServerOptions } from '../runtime/runtime.js'; import { to } from '../response/response.js'; import type { RunFunctionRequest, RunFunctionResponse, State } from '../proto/run_function.js'; -/** The address a function listens on unless told otherwise. */ -export const DEFAULT_ADDRESS = '0.0.0.0:9443'; - -/** - * Where the package reconciler mounts the TLS certificates it generates. - */ -export const DEFAULT_TLS_SERVER_CERTS_DIR = '/tls/server'; +export { DEFAULT_ADDRESS, DEFAULT_TLS_SERVER_CERTS_DIR } from '../cli/cli.js'; /** * A RunFunctionResponse whose desired state is guaranteed to be present. @@ -38,18 +31,6 @@ export const DEFAULT_TLS_SERVER_CERTS_DIR = '/tls/server'; */ export type ComposeResponse = RunFunctionResponse & { desired: State }; -/** - * The program name to show in --help when the caller does not supply one. - * - * Taken from the script being run, the way most command line tools do it, so - * the help of a function started as `node dist/main.js` says `main.js` rather - * than something generic. - */ -function defaultName(): string { - const script = process.argv[1]; - return script ? basename(script) : 'function'; -} - /** * A composition function. * @@ -108,16 +89,25 @@ export function fromCompose(compose: ComposeFunction): FunctionHandler { export interface ServeOptions { /** * Program name shown in --help. Defaults to the basename of the running - * script. + * script. Ignored when {@link cli} is given, since the CLI has its own name. */ name?: string; /** * Arguments to parse, without the node executable or script path. - * Defaults to process.argv.slice(2). + * Defaults to process.argv.slice(2). Ignored when {@link cli} is given and + * has already been parsed. */ argv?: string[]; + /** + * A {@link CLI} declaring flags of the function's own, alongside the + * standard ones. serve parses it unless it has been parsed already, and its + * help text is what --help prints. Defaults to a CLI with only the standard + * flags. + */ + cli?: CLI; + /** * Logger to use. One is created from the parsed --debug flag if omitted. */ @@ -127,33 +117,6 @@ export interface ServeOptions { serverOptions?: Partial; } -/** - * The flags every composition function accepts. - * - * This is the single source of truth: both the parser and the help text are - * derived from it, so a flag cannot be added to one and forgotten in the - * other. - */ -const flags = { - address: { type: 'string', default: DEFAULT_ADDRESS }, - debug: { type: 'boolean', short: 'd', default: false }, - insecure: { type: 'boolean', default: false }, - 'tls-server-certs-dir': { type: 'string', default: DEFAULT_TLS_SERVER_CERTS_DIR }, - help: { type: 'boolean', short: 'h', default: false }, -} as const; - -/** - * What each flag does. Keyed by {@link flags}, so adding a flag without - * describing it is a compile error. - */ -const descriptions: Record = { - address: `Address to listen for gRPC connections. Default ${DEFAULT_ADDRESS}.`, - debug: 'Emit debug logs.', - insecure: 'Run without mTLS credentials.', - 'tls-server-certs-dir': `Directory holding tls.key, tls.crt and ca.crt. Default ${DEFAULT_TLS_SERVER_CERTS_DIR}.`, - help: 'Show this help.', -}; - /** The result of {@link parseArgs}: server options, plus whether help was asked for. */ export interface ParsedArgs extends ServerOptions { /** Whether --help or -h was given. */ @@ -161,10 +124,10 @@ export interface ParsedArgs extends ServerOptions { } /** - * Parse the standard function command line flags. + * Parse the standard function command line flags and environment variables. * - * Exported so that it can be tested, and so that a function needing extra - * flags of its own can reuse the standard ones. + * A shorthand for parsing a {@link CLI} with no flags of its own. Exported so + * that it can be tested. * * @param argv - Arguments without the node executable or script path. * @returns The parsed options. @@ -172,31 +135,14 @@ export interface ParsedArgs extends ServerOptions { * does not take. */ export function parseArgs(argv: string[]): ParsedArgs { - const { values } = parseNodeArgs({ args: argv, options: flags, allowPositionals: false }); - return { - address: values.address, - debug: values.debug, - insecure: values.insecure, - tlsServerCertsDir: values['tls-server-certs-dir'], - help: values.help, - }; + const cli = new CLI(); + const values = cli.parse(argv); + return { ...cli.standardOptions(), help: values.help === true }; } -/** The --help text, derived from {@link flags} and {@link descriptions}. */ +/** The --help text for a function with only the standard flags. */ export function helpText(name: string): string { - const usage = Object.entries(flags).map(([flag, spec]) => { - const short = 'short' in spec ? `-${spec.short}, ` : ' '; - const value = spec.type === 'string' ? ' ' : ''; - return ` ${short}--${flag}${value}`.padEnd(38) + descriptions[flag as keyof typeof flags]; - }); - return [ - `Usage: ${name} [flags]`, - '', - 'A Crossplane composition function.', - '', - 'Flags:', - ...usage, - ].join('\n'); + return new CLI({ name }).helpText(); } /** @@ -232,36 +178,28 @@ export function usageErrorText(name: string, error: unknown): string { * ``` */ export function serve(fn: ComposeFunction | FunctionHandler, opts: ServeOptions = {}): grpc.Server { - const name = opts.name ?? defaultName(); - const argv = opts.argv ?? process.argv.slice(2); - - let args: ParsedArgs; - try { - args = parseArgs(argv); - } catch (error) { - // node:util throws a TypeError whose message is exactly what the user - // needs to see. Without this it reaches the top level and Node prints it - // under a stack trace through its own internals, which buries it. - process.stderr.write(`${usageErrorText(name, error)}\n`); - process.exit(2); + const cli = opts.cli ?? new CLI({ name: opts.name }); + + if (!cli.parsed) { + try { + cli.parse(opts.argv ?? process.argv.slice(2)); + } catch (error) { + // node:util throws a TypeError whose message is exactly what the user + // needs to see. Without this it reaches the top level and Node prints it + // under a stack trace through its own internals, which buries it. + process.stderr.write(`${usageErrorText(cli.name, error)}\n`); + process.exit(2); + } } - const { help, ...parsed } = args; - if (help) { - process.stdout.write(`${helpText(name)}\n`); + if (cli.values.help === true) { + process.stdout.write(`${cli.helpText()}\n`); process.exit(0); } - const serverOptions: ServerOptions = { ...parsed, ...opts.serverOptions }; + const serverOptions: ServerOptions = { ...cli.standardOptions(), ...opts.serverOptions }; - const logger = - opts.logger ?? - pino({ - level: serverOptions.debug ? 'debug' : 'info', - formatters: { - level: (label: string) => ({ severity: label.toUpperCase() }), - }, - }); + const logger = opts.logger ?? newLogger(serverOptions.debug === true); logger.debug({ options: serverOptions }, 'starting function'); From 4d03aa68f4d436c24cbd3daf5c66f27bf786bc5f Mon Sep 17 00:00:00 2001 From: Steven Borrelli Date: Mon, 2 Nov 2026 12:36:28 +0000 Subject: [PATCH 6/9] Test serve's help with a CLI, and document the message size alias Add a test that serve(compose, { cli }) prints the standard flags exactly as it does without a CLI of its own -- same lines, order and alignment -- followed by the custom flags on the same description column. --help listed only a flag's primary environment variable, so MAX_GRPC_MESSAGE_SIZE appeared nowhere in a function's own help. It now lists aliases too. Give message size limits their own section in USAGE.md: the alias, that it raises the send limit along with the receive one, and how to set it through a DeploymentRuntimeConfig. Add an upgrade note covering the send limit no longer defaulting to unlimited, and serve() now reading the standard environment variables. Co-Authored-By: Claude Opus 5.5 Signed-off-by: Steven Borrelli --- README.md | 10 ++++-- USAGE.md | 49 +++++++++++++++++++++++++++ src/cli/cli.test.ts | 18 +++++++++- src/cli/cli.ts | 3 +- src/serve/serve.test.ts | 75 +++++++++++++++++++++++++++++++++++++++++ 5 files changed, 151 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 54b4658..f46849d 100644 --- a/README.md +++ b/README.md @@ -62,8 +62,14 @@ serve(compose); Every function served by `serve()` accepts the same standard flags and environment variables — `--address`/`ADDRESS`, `--max-recv-message-size`/`MAX_RECV_MESSAGE_SIZE` and -so on. If your function needs flags of its own, declare them with the `CLI` class and -hand it to `serve()`, which parses it, handles `--help` and reports usage errors: +so on. `MAX_GRPC_MESSAGE_SIZE` is an alias that raises both the receive and send limits +(unless the send limit is set separately), so one variable can configure every function +in a pipeline; see +[Message size limits](USAGE.md#message-size-limits), which also covers how the send limit +changed from earlier versions. + +If your function needs flags of its own, declare them with the `CLI` class and hand it +to `serve()`, which parses it, handles `--help` and reports usage errors: ```typescript import { CLI, serve } from "@crossplane-org/function-sdk-typescript"; diff --git a/USAGE.md b/USAGE.md index d11e7b2..5e749e6 100644 --- a/USAGE.md +++ b/USAGE.md @@ -168,6 +168,55 @@ command line wins over its environment variable, which wins over the default: Boolean environment variables are on when set to `true` or `1`. Message sizes must be positive whole numbers of megabytes; anything else is rejected at startup. +#### Message size limits + +A function rejects any request larger than its receive limit, 4 MB by default. A +composite resource with many composed resources can outgrow that, since every request +carries the observed and desired state of all of them. Raise it with any of: + +- `--max-recv-message-size 16` +- `MAX_RECV_MESSAGE_SIZE=16` +- `MAX_GRPC_MESSAGE_SIZE=16` + +`MAX_GRPC_MESSAGE_SIZE` is an alias for `MAX_RECV_MESSAGE_SIZE`, meant for tooling or +platform teams that set one size across every function in a pipeline. Because the send +limit defaults to the receive limit, it raises both. If both variables are set, +`MAX_RECV_MESSAGE_SIZE` wins. + +Functions run in pods that Crossplane manages, so set the variable through a +`DeploymentRuntimeConfig`: + +```yaml +apiVersion: pkg.crossplane.io/v1beta1 +kind: DeploymentRuntimeConfig +metadata: + name: large-messages +spec: + deploymentTemplate: + spec: + selector: {} + template: + spec: + containers: + - name: package-runtime + env: + - name: MAX_GRPC_MESSAGE_SIZE + value: "16" +``` + +#### Upgrading from earlier versions + +Two behaviour changes affect functions that call `serve()` without changing any code: + +- **Sent messages are now limited.** Earlier versions left the send limit at the + grpc-js default, which is unlimited. It now defaults to the receive limit, 4 MB + unless raised. A function that returns responses larger than that must raise + `--max-send-message-size` / `MAX_SEND_MESSAGE_SIZE`, or the receive limit. +- **The standard environment variables are read.** Earlier versions of `serve()` only + read flags. A pod that already sets `ADDRESS`, `DEBUG`, `INSECURE`, + `TLS_SERVER_CERTS_DIR` or one of the message size variables for some other reason + will now pick it up. + `serve()` takes an options object for the cases where the defaults do not fit: ```typescript diff --git a/src/cli/cli.test.ts b/src/cli/cli.test.ts index 43dfe2f..fb8cbce 100644 --- a/src/cli/cli.test.ts +++ b/src/cli/cli.test.ts @@ -411,13 +411,29 @@ describe('CLI', () => { 'ADDRESS', 'DEBUG', 'INSECURE', - 'MAX_RECV_MESSAGE_SIZE', + 'MAX_RECV_MESSAGE_SIZE, MAX_GRPC_MESSAGE_SIZE', 'MAX_SEND_MESSAGE_SIZE', 'TLS_SERVER_CERTS_DIR', ]) { expect(help).toContain(`[env: ${env}]`); } }); + + it('should list a flag’s environment variable aliases', () => { + const cli = new CLI({ + name: 'test', + flags: { + 'my-flag': { + type: 'string', + env: 'MY_FLAG', + envAliases: ['OLD_MY_FLAG'], + description: 'Test.', + }, + }, + }); + + expect(cli.helpText()).toContain('[env: MY_FLAG, OLD_MY_FLAG]'); + }); }); describe('name', () => { diff --git a/src/cli/cli.ts b/src/cli/cli.ts index bf9dd5f..644f554 100644 --- a/src/cli/cli.ts +++ b/src/cli/cli.ts @@ -266,7 +266,8 @@ export class CLI { const rows = Object.entries(this.allFlags).map(([flag, spec]) => { const short = spec.short ? `-${spec.short}, ` : ' '; const value = spec.type === 'string' ? ' ' : ''; - const env = spec.env ? ` [env: ${spec.env}]` : ''; + const envKeys = [spec.env, ...(spec.envAliases ?? [])].filter(Boolean); + const env = envKeys.length > 0 ? ` [env: ${envKeys.join(', ')}]` : ''; return { usage: ` ${short}--${flag}${value}`, description: spec.description + env }; }); // Size the column to the longest flag, so a long custom flag name cannot diff --git a/src/serve/serve.test.ts b/src/serve/serve.test.ts index 29e65ad..2854eb9 100644 --- a/src/serve/serve.test.ts +++ b/src/serve/serve.test.ts @@ -1,10 +1,12 @@ import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'; +import { CLI } from '../cli/cli.js'; import { DEFAULT_ADDRESS, DEFAULT_TLS_SERVER_CERTS_DIR, fromCompose, helpText, parseArgs, + serve, usageErrorText, type ComposeFunction, } from './serve.js'; @@ -142,6 +144,79 @@ describe('helpText', () => { }); }); +describe('serve', () => { + /** Thrown by the stubbed process.exit, so serve stops where the process would. */ + class Exit extends Error { + constructor(readonly code: number | string | null | undefined) { + super(`process.exit(${code})`); + } + } + + afterEach(() => { + vi.restoreAllMocks(); + }); + + /** Run serve with argv, returning its exit code and what it wrote to stdout. */ + function run(opts: Parameters[1]): { code: unknown; stdout: string } { + vi.spyOn(process, 'exit').mockImplementation((code) => { + throw new Exit(code); + }); + let stdout = ''; + vi.spyOn(process.stdout, 'write').mockImplementation((chunk) => { + stdout += String(chunk); + return true; + }); + + try { + serve((_req, rsp) => rsp, opts); + } catch (error) { + if (error instanceof Exit) return { code: error.code, stdout }; + throw error; + } + throw new Error('serve did not exit'); + } + + it('should print custom flags after the standard ones, leaving those untouched', () => { + const cli = new CLI({ + name: 'my-fn', + flags: { + 'cache-size': { + type: 'string', + default: '100', + env: 'CACHE_SIZE', + description: 'Number of entries to cache.', + }, + verbose: { type: 'boolean', short: 'v', description: 'Enable verbose output.' }, + }, + }); + + const { code, stdout } = run({ cli, argv: ['--help'] }); + + expect(code).toBe(0); + + // The standard flags print exactly as they do for a function with no + // flags of its own: same lines, same order, same alignment. + const standard = helpText('my-fn').split('\n'); + const printed = stdout.trimEnd().split('\n'); + expect(printed.slice(0, standard.length)).toEqual(standard); + + // The custom flags follow, in declaration order, aligned to the same + // description column as the standard ones. + const column = standard.find((l) => l.includes('--address'))!.indexOf('Address'); + expect(printed.slice(standard.length)).toEqual([ + ' --cache-size '.padEnd(column) + 'Number of entries to cache. [env: CACHE_SIZE]', + ' -v, --verbose'.padEnd(column) + 'Enable verbose output.', + ]); + }); + + it('should print only the standard flags without a CLI of its own', () => { + const { code, stdout } = run({ name: 'my-fn', argv: ['--help'] }); + + expect(code).toBe(0); + expect(stdout).toBe(`${helpText('my-fn')}\n`); + }); +}); + describe('usageErrorText', () => { it('should surface the parser message and point at --help', () => { let thrown: unknown; From eead1481abef5f6f449ef2e448caea4eebd22381 Mon Sep 17 00:00:00 2001 From: Steven Borrelli Date: Mon, 2 Nov 2026 17:18:17 +0000 Subject: [PATCH 7/9] Treat empty flag values as unset and bound the message size Reviewing this branch turned up four problems, each of them things an operator can hit from the environment the PR starts reading: An empty string reached the server. ADDRESS="" produced a raw stack trace from grpc-js's normalizePort, outside the usage-error format, and TLS_SERVER_CERTS_DIR="" silently started the server in plaintext, since getServerCredentials treats "" as "unset". resolveValue now falls through an empty value from either the command line or the environment to the default. This was a regression: main does not read the environment at all, so an empty variable was previously impossible. An unparseable address killed the process with a stack trace, and any other bind failure exited 0 with nothing listening behind it. serve() now reports a synchronous grpc-js throw as a usage error (exit 2), and startServer exits 1 on a bind failure rather than logging and returning. The message size was accepted unbounded. 99999999999999 became a byte count past what int32 channel arguments can hold, while 0007 was rejected for a leading zero. Sizes are now whole numbers between 1 and 2047 MB. No test covered any of it. Added tests for empty values on every standard variable, the size bounds, and both bind error paths, and mutation-checked each so they fail without their fix. Co-Authored-By: Claude Code Signed-off-by: Steven Borrelli --- USAGE.md | 17 +++++++++-- src/cli/cli.test.ts | 66 ++++++++++++++++++++++++++++++++++++++++- src/cli/cli.ts | 37 ++++++++++++++++++----- src/runtime/runtime.ts | 6 ++-- src/serve/serve.test.ts | 44 +++++++++++++++++++++++++-- src/serve/serve.ts | 10 ++++++- 6 files changed, 164 insertions(+), 16 deletions(-) diff --git a/USAGE.md b/USAGE.md index 5e749e6..f791a47 100644 --- a/USAGE.md +++ b/USAGE.md @@ -165,8 +165,10 @@ command line wins over its environment variable, which wins over the default: | `--max-send-message-size` | `MAX_SEND_MESSAGE_SIZE` | the receive size | Max sent gRPC message size in MB | | `--help` / `-h` | — | `false` | Show help text | -Boolean environment variables are on when set to `true` or `1`. Message sizes must be -positive whole numbers of megabytes; anything else is rejected at startup. +Boolean environment variables are on when set to `true` or `1`. An empty value — a +variable set to `""`, or an empty argument — is treated as unset, so it falls through to +the default rather than reaching the server. Message sizes must be whole numbers of +megabytes between 1 and 2047; anything else is rejected at startup. #### Message size limits @@ -183,6 +185,10 @@ platform teams that set one size across every function in a pipeline. Because th limit defaults to the receive limit, it raises both. If both variables are set, `MAX_RECV_MESSAGE_SIZE` wins. +A size must be a whole number of megabytes between 1 and 2047, the most gRPC's message +size channel arguments can hold; `8`, `0008` and `2047` are accepted, `0`, `8.5`, `8MB` +and `4096` are rejected at startup. + Functions run in pods that Crossplane manages, so set the variable through a `DeploymentRuntimeConfig`: @@ -215,7 +221,12 @@ Two behaviour changes affect functions that call `serve()` without changing any - **The standard environment variables are read.** Earlier versions of `serve()` only read flags. A pod that already sets `ADDRESS`, `DEBUG`, `INSECURE`, `TLS_SERVER_CERTS_DIR` or one of the message size variables for some other reason - will now pick it up. + will now pick it up. An empty value is treated as unset, so `value: ""` in a pod + spec falls back to the default rather than replacing it. +- **A function that cannot bind exits non-zero.** Earlier versions logged a bind error + and exited 0, leaving a container running with nothing listening behind it. The + process now exits 1 when the address cannot be bound, and 2 when the address itself + is unparsable, so a supervisor or readiness probe can see the failure. `serve()` takes an options object for the cases where the defaults do not fit: diff --git a/src/cli/cli.test.ts b/src/cli/cli.test.ts index fb8cbce..6e5c73d 100644 --- a/src/cli/cli.test.ts +++ b/src/cli/cli.test.ts @@ -1,5 +1,5 @@ import { describe, it, expect, beforeEach, afterEach } from 'vitest'; -import { CLI } from './cli.js'; +import { CLI, DEFAULT_ADDRESS, DEFAULT_TLS_SERVER_CERTS_DIR } from './cli.js'; describe('CLI', () => { const savedEnv: Record = {}; @@ -173,6 +173,70 @@ describe('CLI', () => { const cli = new CLI({ name: 'test' }); expect(() => cli.parse([])).toThrow(/got "16MB"/); }); + + it('should accept a message size written with leading zeros', () => { + const cli = new CLI({ name: 'test' }); + cli.parse(['--max-recv-message-size', '0007']); + + expect(cli.standardOptions().maxRecvMessageSize).toBe(7 * 1024 * 1024); + }); + + it('should reject a message size larger than grpc-js accepts', () => { + // The channel arguments are int32, so anything past this would overflow + // into a different limit rather than being honoured. + const cli = new CLI({ name: 'test' }); + expect(() => cli.parse(['--max-recv-message-size', '2048'])).toThrow( + /must be at most 2047 MB, got "2048"/ + ); + expect(() => cli.parse(['--max-recv-message-size', '99999999999999'])).toThrow( + /must be at most 2047 MB/ + ); + + const atLimit = new CLI({ name: 'test' }); + atLimit.parse(['--max-recv-message-size', '2047']); + expect(atLimit.standardOptions().maxRecvMessageSize).toBe(2047 * 1024 * 1024); + }); + + it('should treat an empty environment variable as unset', () => { + // A pod spec with value: "" says nothing about the value, and letting it + // through reaches the server as an empty address, or as an empty + // certificate directory that silently downgrades TLS to plaintext. + process.env.ADDRESS = ''; + process.env.TLS_SERVER_CERTS_DIR = ''; + process.env.INSECURE = ''; + + const cli = new CLI({ name: 'test' }); + cli.parse([]); + const opts = cli.standardOptions(); + + expect(opts.address).toBe(DEFAULT_ADDRESS); + expect(opts.tlsServerCertsDir).toBe(DEFAULT_TLS_SERVER_CERTS_DIR); + expect(opts.insecure).toBe(false); + }); + + it('should fall through to the next source when an alias is empty', () => { + process.env.MAX_RECV_MESSAGE_SIZE = ''; + process.env.MAX_GRPC_MESSAGE_SIZE = '16'; + + const cli = new CLI({ name: 'test' }); + cli.parse([]); + + expect(cli.standardOptions().maxRecvMessageSize).toBe(16 * 1024 * 1024); + }); + + it('should treat an empty message size as unset rather than rejecting it', () => { + process.env.MAX_RECV_MESSAGE_SIZE = ''; + + const cli = new CLI({ name: 'test' }); + cli.parse([]); + + expect(cli.standardOptions().maxRecvMessageSize).toBe(4 * 1024 * 1024); + }); + + it('should treat an empty argument as unset', () => { + const cli = new CLI({ name: 'test' }); + expect(cli.parse(['--address', '']).address).toBe(DEFAULT_ADDRESS); + }); }); describe('before parse', () => { diff --git a/src/cli/cli.ts b/src/cli/cli.ts index 644f554..a47103a 100644 --- a/src/cli/cli.ts +++ b/src/cli/cli.ts @@ -109,6 +109,12 @@ const standardFlags: Record = { /** Standard flags whose value is a whole number of megabytes. */ const megabyteFlags = ['max-recv-message-size', 'max-send-message-size']; +/** + * The largest value the gRPC message size channel arguments take: they are + * passed to grpc-js as int32. + */ +const MAX_MESSAGE_SIZE_BYTES = 2147483647; + /** Options accepted by the {@link CLI} constructor. */ export interface CLIOptions { /** Program name shown in help text. Defaults to the running script's basename. */ @@ -126,6 +132,7 @@ export interface CLIOptions { * variable support, and lets function authors register additional flags. * * Resolution order per flag: CLI argument > environment variable > default. + * An empty string from either source is treated as unset. */ export class CLI { private readonly programName: string; @@ -306,12 +313,17 @@ export function newLogger(debug: boolean): Logger { function resolveValue(spec: FlagSpec, cliValue: FlagValue): FlagValue { // node:util leaves a flag that was not given undefined, and a boolean flag // can only be given as true, so undefined means "not on the command line". - if (cliValue !== undefined) return cliValue; + // + // An empty string means the same thing. A pod spec with `value: ""` and an + // empty argument both say nothing about the value itself, and letting one + // through would reach the server as an empty listen address or, for + // tls-server-certs-dir, silently downgrade TLS to plaintext. + if (cliValue !== undefined && cliValue !== '') return cliValue; const envKeys = [spec.env, ...(spec.envAliases ?? [])].filter(Boolean) as string[]; for (const key of envKeys) { const envValue = process.env[key]; - if (envValue !== undefined) { + if (envValue !== undefined && envValue !== '') { return spec.type === 'boolean' ? envValue === '1' || envValue.toLowerCase() === 'true' : envValue; @@ -324,17 +336,28 @@ function resolveValue(spec: FlagSpec, cliValue: FlagValue): FlagValue { /** * Convert a size in megabytes to bytes. * - * @throws If the value is not a positive whole number. + * @throws If the value is not a positive whole number, or is larger than the + * 32-bit limit grpc-js imposes on the message size channel arguments. */ function toBytes(name: string, spec: FlagSpec | undefined, value: string): number { - if (!/^[1-9][0-9]*$/.test(value)) { - const envKeys = [spec?.env, ...(spec?.envAliases ?? [])].filter(Boolean); - const source = [`--${name}`, ...envKeys].join(' or '); + const envKeys = [spec?.env, ...(spec?.envAliases ?? [])].filter(Boolean); + const source = [`--${name}`, ...envKeys].join(' or '); + + // Leading zeros are allowed: 0007 and 7 mean the same thing. + if (!/^[0-9]+$/.test(value) || Number(value) === 0) { throw new Error( `${source} must be a positive whole number of megabytes, got ${JSON.stringify(value)}` ); } - return Number(value) * 1024 * 1024; + + const bytes = Number(value) * 1024 * 1024; + // grpc-js passes these to its channel as int32, so a larger number would + // silently overflow into a different limit rather than being honoured. + if (bytes > MAX_MESSAGE_SIZE_BYTES) { + const maxMegabytes = Math.floor(MAX_MESSAGE_SIZE_BYTES / 1024 / 1024); + throw new Error(`${source} must be at most ${maxMegabytes} MB, got ${JSON.stringify(value)}`); + } + return bytes; } function defaultName(): string { diff --git a/src/runtime/runtime.ts b/src/runtime/runtime.ts index 59ccc0f..54fd286 100644 --- a/src/runtime/runtime.ts +++ b/src/runtime/runtime.ts @@ -145,7 +145,9 @@ export function newGrpcServer( * based on the provided options. The binding happens asynchronously. * * The server will log when it successfully starts listening or if an error occurs - * during binding. + * during binding. If binding fails the process exits non-zero: a function that + * cannot listen is not serving, and reporting success would leave a container + * running with nothing behind it. * * @param server - The gRPC Server instance to start * @param opts - Server options including address and TLS configuration @@ -175,7 +177,7 @@ export function startServer(server: grpc.Server, opts: ServerOptions, logger: Lo server.bindAsync(opts.address, creds, (err) => { if (err) { logger.error(`server bind error: ${err.message}`); - return; + process.exit(1); } logger.info(`server started and listening on ${opts.address}`); }); diff --git a/src/serve/serve.test.ts b/src/serve/serve.test.ts index 2854eb9..57cd1ec 100644 --- a/src/serve/serve.test.ts +++ b/src/serve/serve.test.ts @@ -64,6 +64,22 @@ describe('parseArgs', () => { expect(opts.maxSendMessageSize).toBe(32 * 1024 * 1024); }); + it('should treat an empty environment variable as unset', () => { + // A container that sets value: "" for one of these variables would + // otherwise take the default away and hand the server an empty address. + for (const key of standardEnv) vi.stubEnv(key, ''); + + expect(parseArgs([])).toEqual({ + address: DEFAULT_ADDRESS, + debug: false, + insecure: false, + tlsServerCertsDir: DEFAULT_TLS_SERVER_CERTS_DIR, + maxRecvMessageSize: 4 * 1024 * 1024, + maxSendMessageSize: undefined, + help: false, + }); + }); + it('should parse flags given as separate arguments', () => { const opts = parseArgs([ '--address', @@ -157,7 +173,11 @@ describe('serve', () => { }); /** Run serve with argv, returning its exit code and what it wrote to stdout. */ - function run(opts: Parameters[1]): { code: unknown; stdout: string } { + function run(opts: Parameters[1]): { + code: unknown; + stdout: string; + stderr: string; + } { vi.spyOn(process, 'exit').mockImplementation((code) => { throw new Exit(code); }); @@ -166,11 +186,16 @@ describe('serve', () => { stdout += String(chunk); return true; }); + let stderr = ''; + vi.spyOn(process.stderr, 'write').mockImplementation((chunk) => { + stderr += String(chunk); + return true; + }); try { serve((_req, rsp) => rsp, opts); } catch (error) { - if (error instanceof Exit) return { code: error.code, stdout }; + if (error instanceof Exit) return { code: error.code, stdout, stderr }; throw error; } throw new Error('serve did not exit'); @@ -215,6 +240,21 @@ describe('serve', () => { expect(code).toBe(0); expect(stdout).toBe(`${helpText('my-fn')}\n`); }); + + it('should report an address grpc-js cannot parse as a usage error', () => { + // grpc-js throws this synchronously from bindAsync, so without catching + // it the process dies with a stack trace through grpc-js's internals. + const { code, stderr } = run({ + name: 'my-fn', + argv: [], + // insecure, so we reach bindAsync instead of reading TLS certs. + serverOptions: { address: '', insecure: true }, + }); + + expect(code).toBe(2); + expect(stderr).toContain('my-fn: Could not parse port ""'); + expect(stderr).toContain("Try 'my-fn --help' for the available flags."); + }); }); describe('usageErrorText', () => { diff --git a/src/serve/serve.ts b/src/serve/serve.ts index 75ddc77..fb5ecfa 100644 --- a/src/serve/serve.ts +++ b/src/serve/serve.ts @@ -208,7 +208,15 @@ export function serve(fn: ComposeFunction | FunctionHandler, opts: ServeOptions maxRecvMessageSize: serverOptions.maxRecvMessageSize, maxSendMessageSize: serverOptions.maxSendMessageSize, }); - startServer(server, serverOptions, logger); + try { + startServer(server, serverOptions, logger); + } catch (error) { + // grpc-js throws synchronously for an address it cannot parse at all. Let + // it out and it reaches the top level as a stack trace through grpc-js's + // own internals; this is a bad value for a flag, so report it as one. + process.stderr.write(`${usageErrorText(cli.name, error)}\n`); + process.exit(2); + } const shutdown = (signal: string): void => { logger.info(`received ${signal}, shutting down`); From b2517d90fc4cedace108494885891cd344fe4f46 Mon Sep 17 00:00:00 2001 From: Steven Borrelli Date: Sun, 15 Nov 2026 08:26:03 +0000 Subject: [PATCH 8/9] Address review of the CLI rework Fixes from a review of this branch: - Remove the try/catch around startServer() in serve(). It was meant to report an unparsable address as a usage error, but it also caught a missing TLS certificate and reported that as a bad flag with exit 2. Empty values already fall back to the default, so the only remaining way to reach grpc-js's synchronous throw is an empty address passed through serverOptions, which is a programming error. - Revert startServer() to logging a bind failure rather than exiting the process. It is exported for functions that build their own server, and those should get to decide what a bind failure means. - Skip message size validation when --help is given, so a bad size in the environment no longer stops --help printing the help that would explain it. standardOptions() still rejects the size. - Check custom flags against the standard ones with Object.hasOwn, so a flag named after an Object.prototype property such as "constructor" is not reported as a conflict. - Reject a flag default whose type does not match the flag. A boolean flag defaulting to the string 'false' resolved to that string, which is truthy. - Build a flag's list of environment variables in one place. - Drop the upgrade note about bind failures exiting, which no longer applies. Co-Authored-By: Claude Opus 5.5 Signed-off-by: Steven Borrelli --- USAGE.md | 4 ---- src/cli/cli.test.ts | 37 ++++++++++++++++++++++++++++++++++++ src/cli/cli.ts | 42 ++++++++++++++++++++++++++++++----------- src/runtime/runtime.ts | 6 ++---- src/serve/serve.test.ts | 28 ++++++++++++++++----------- src/serve/serve.ts | 10 +--------- 6 files changed, 88 insertions(+), 39 deletions(-) diff --git a/USAGE.md b/USAGE.md index f791a47..e1b6a07 100644 --- a/USAGE.md +++ b/USAGE.md @@ -223,10 +223,6 @@ Two behaviour changes affect functions that call `serve()` without changing any `TLS_SERVER_CERTS_DIR` or one of the message size variables for some other reason will now pick it up. An empty value is treated as unset, so `value: ""` in a pod spec falls back to the default rather than replacing it. -- **A function that cannot bind exits non-zero.** Earlier versions logged a bind error - and exited 0, leaving a container running with nothing listening behind it. The - process now exits 1 when the address cannot be bound, and 2 when the address itself - is unparsable, so a supervisor or readiness probe can see the failure. `serve()` takes an options object for the cases where the defaults do not fit: diff --git a/src/cli/cli.test.ts b/src/cli/cli.test.ts index 6e5c73d..c8e5331 100644 --- a/src/cli/cli.test.ts +++ b/src/cli/cli.test.ts @@ -144,6 +144,34 @@ describe('CLI', () => { ).toThrow(/boolean flag "feature" cannot default to true/); }); + it('should reject a default whose type does not match the flag', () => { + // The string 'false' is truthy, so a boolean flag defaulting to it would + // read as on. + expect( + () => + new CLI({ + flags: { verbose: { type: 'boolean', default: 'false', description: 'Verbose.' } }, + }) + ).toThrow(/boolean flag "verbose" has a string default; it must be a boolean/); + expect( + () => + new CLI({ + flags: { size: { type: 'string', default: false, description: 'Size.' } }, + }) + ).toThrow(/string flag "size" has a boolean default; it must be a string/); + }); + + it('should accept a custom flag named after an Object.prototype property', () => { + // `name in standardFlags` would match inherited properties and report a + // conflict with a standard flag that does not exist. + const cli = new CLI({ + name: 'test', + flags: { constructor: { type: 'string', default: 'x', description: 'Test.' } }, + }); + + expect(cli.parse([]).constructor).toBe('x'); + }); + it('should default a custom boolean flag without a declared default to false', () => { const cli = new CLI({ flags: { verbose: { type: 'boolean', description: 'Verbose.' } }, @@ -266,6 +294,15 @@ describe('CLI', () => { expect(() => cli.parse(['--max-recv-message-size', 'eight'])).toThrow(); expect(cli.parsed).toBe(false); }); + + it('should not check message sizes when help is asked for', () => { + process.env.MAX_GRPC_MESSAGE_SIZE = '16MB'; + const cli = new CLI({ name: 'test' }); + + expect(cli.parse(['--help']).help).toBe(true); + // The size is still invalid, and standardOptions still says so. + expect(() => cli.standardOptions()).toThrow(/got "16MB"/); + }); }); describe('environment variables', () => { diff --git a/src/cli/cli.ts b/src/cli/cli.ts index a47103a..c119cc9 100644 --- a/src/cli/cli.ts +++ b/src/cli/cli.ts @@ -141,14 +141,17 @@ export class CLI { /** * @throws If a custom flag reuses a standard flag's name or another flag's - * short alias, or is a boolean flag that defaults to true. + * short alias, has a default of the wrong type, or is a boolean flag that + * defaults to true. */ constructor(opts?: CLIOptions) { this.programName = opts?.name ?? defaultName(); const custom = opts?.flags ?? {}; for (const name of Object.keys(custom)) { - if (name in standardFlags) { + // Object.hasOwn rather than `in`, which would also match properties + // inherited from Object.prototype, such as a flag named "constructor". + if (Object.hasOwn(standardFlags, name)) { throw new Error(`flag "${name}" conflicts with a standard flag`); } } @@ -156,6 +159,13 @@ export class CLI { const shorts = new Map(); for (const [name, spec] of Object.entries(this.allFlags)) { + // A boolean flag defaulting to the string 'false' would otherwise + // resolve to that string, which is truthy. + if (spec.default !== undefined && typeof spec.default !== spec.type) { + throw new Error( + `${spec.type} flag "${name}" has a ${typeof spec.default} default; it must be a ${spec.type}` + ); + } if (spec.type === 'boolean' && spec.default === true) { throw new Error( `boolean flag "${name}" cannot default to true, since it could not be turned off` @@ -207,9 +217,14 @@ export class CLI { // Check the sizes now, so that a bad value is reported as a usage error // rather than silently replaced by a default once the server starts. - for (const name of megabyteFlags) { - const value = resolved[name]; - if (value !== undefined) toBytes(name, this.allFlags[name], String(value)); + // Skip it when help is asked for: someone running --help may well be + // trying to find out what a valid size looks like, and the error would + // only point them back at --help. + if (resolved.help !== true) { + for (const name of megabyteFlags) { + const value = resolved[name]; + if (value !== undefined) toBytes(name, this.allFlags[name], String(value)); + } } this.parsedValues = resolved; @@ -236,7 +251,9 @@ export class CLI { /** * Return {@link ServerOptions} derived from the standard flags. * - * @throws If {@link parse} has not been called. + * @throws If {@link parse} has not been called, or if a message size is + * invalid. {@link parse} reports an invalid size itself, except when + * --help was given. */ standardOptions(): ServerOptions { const values = this.values; @@ -273,7 +290,7 @@ export class CLI { const rows = Object.entries(this.allFlags).map(([flag, spec]) => { const short = spec.short ? `-${spec.short}, ` : ' '; const value = spec.type === 'string' ? ' ' : ''; - const envKeys = [spec.env, ...(spec.envAliases ?? [])].filter(Boolean); + const envKeys = envKeysOf(spec); const env = envKeys.length > 0 ? ` [env: ${envKeys.join(', ')}]` : ''; return { usage: ` ${short}--${flag}${value}`, description: spec.description + env }; }); @@ -310,6 +327,11 @@ export function newLogger(debug: boolean): Logger { }); } +/** The environment variables a flag reads, in the order they are checked. */ +function envKeysOf(spec: FlagSpec | undefined): string[] { + return [spec?.env, ...(spec?.envAliases ?? [])].filter((key): key is string => !!key); +} + function resolveValue(spec: FlagSpec, cliValue: FlagValue): FlagValue { // node:util leaves a flag that was not given undefined, and a boolean flag // can only be given as true, so undefined means "not on the command line". @@ -320,8 +342,7 @@ function resolveValue(spec: FlagSpec, cliValue: FlagValue): FlagValue { // tls-server-certs-dir, silently downgrade TLS to plaintext. if (cliValue !== undefined && cliValue !== '') return cliValue; - const envKeys = [spec.env, ...(spec.envAliases ?? [])].filter(Boolean) as string[]; - for (const key of envKeys) { + for (const key of envKeysOf(spec)) { const envValue = process.env[key]; if (envValue !== undefined && envValue !== '') { return spec.type === 'boolean' @@ -340,8 +361,7 @@ function resolveValue(spec: FlagSpec, cliValue: FlagValue): FlagValue { * 32-bit limit grpc-js imposes on the message size channel arguments. */ function toBytes(name: string, spec: FlagSpec | undefined, value: string): number { - const envKeys = [spec?.env, ...(spec?.envAliases ?? [])].filter(Boolean); - const source = [`--${name}`, ...envKeys].join(' or '); + const source = [`--${name}`, ...envKeysOf(spec)].join(' or '); // Leading zeros are allowed: 0007 and 7 mean the same thing. if (!/^[0-9]+$/.test(value) || Number(value) === 0) { diff --git a/src/runtime/runtime.ts b/src/runtime/runtime.ts index 54fd286..59ccc0f 100644 --- a/src/runtime/runtime.ts +++ b/src/runtime/runtime.ts @@ -145,9 +145,7 @@ export function newGrpcServer( * based on the provided options. The binding happens asynchronously. * * The server will log when it successfully starts listening or if an error occurs - * during binding. If binding fails the process exits non-zero: a function that - * cannot listen is not serving, and reporting success would leave a container - * running with nothing behind it. + * during binding. * * @param server - The gRPC Server instance to start * @param opts - Server options including address and TLS configuration @@ -177,7 +175,7 @@ export function startServer(server: grpc.Server, opts: ServerOptions, logger: Lo server.bindAsync(opts.address, creds, (err) => { if (err) { logger.error(`server bind error: ${err.message}`); - process.exit(1); + return; } logger.info(`server started and listening on ${opts.address}`); }); diff --git a/src/serve/serve.test.ts b/src/serve/serve.test.ts index 57cd1ec..610394b 100644 --- a/src/serve/serve.test.ts +++ b/src/serve/serve.test.ts @@ -241,19 +241,25 @@ describe('serve', () => { expect(stdout).toBe(`${helpText('my-fn')}\n`); }); - it('should report an address grpc-js cannot parse as a usage error', () => { - // grpc-js throws this synchronously from bindAsync, so without catching - // it the process dies with a stack trace through grpc-js's internals. - const { code, stderr } = run({ - name: 'my-fn', - argv: [], - // insecure, so we reach bindAsync instead of reading TLS certs. - serverOptions: { address: '', insecure: true }, - }); + it('should print help even when a message size in the environment is invalid', () => { + // Someone running --help may be trying to find out what a valid size looks + // like. Rejecting the size would only send them back to --help. + vi.stubEnv('MAX_GRPC_MESSAGE_SIZE', '16MB'); + + const { code, stdout, stderr } = run({ name: 'my-fn', argv: ['--help'] }); + + expect(code).toBe(0); + expect(stdout).toBe(`${helpText('my-fn')}\n`); + expect(stderr).toBe(''); + }); + + it('should still reject an invalid message size without --help', () => { + vi.stubEnv('MAX_GRPC_MESSAGE_SIZE', '16MB'); + + const { code, stderr } = run({ name: 'my-fn', argv: [] }); expect(code).toBe(2); - expect(stderr).toContain('my-fn: Could not parse port ""'); - expect(stderr).toContain("Try 'my-fn --help' for the available flags."); + expect(stderr).toContain('got "16MB"'); }); }); diff --git a/src/serve/serve.ts b/src/serve/serve.ts index fb5ecfa..75ddc77 100644 --- a/src/serve/serve.ts +++ b/src/serve/serve.ts @@ -208,15 +208,7 @@ export function serve(fn: ComposeFunction | FunctionHandler, opts: ServeOptions maxRecvMessageSize: serverOptions.maxRecvMessageSize, maxSendMessageSize: serverOptions.maxSendMessageSize, }); - try { - startServer(server, serverOptions, logger); - } catch (error) { - // grpc-js throws synchronously for an address it cannot parse at all. Let - // it out and it reaches the top level as a stack trace through grpc-js's - // own internals; this is a bad value for a flag, so report it as one. - process.stderr.write(`${usageErrorText(cli.name, error)}\n`); - process.exit(2); - } + startServer(server, serverOptions, logger); const shutdown = (signal: string): void => { logger.info(`received ${signal}, shutting down`); From 31b49738b55db6eb085987d85c6f538006a765b3 Mon Sep 17 00:00:00 2001 From: Steven Borrelli Date: Sun, 15 Nov 2026 08:34:17 +0000 Subject: [PATCH 9/9] Exit serve() when the server cannot bind serve() logged a bind failure and carried on with nothing listening, so a function whose port was taken looked healthy to Kubernetes while serving nothing. It now exits 1. Binding finishes after startServer() returns, so it cannot throw a bind failure. startServer() takes an optional onBindError callback, called after the error is logged, and serve() passes one that exits. The callback is optional and startServer() still only logs without it, so existing callers, including functions that build their own server, see no change. Co-Authored-By: Claude Opus 5.5 Signed-off-by: Steven Borrelli --- README.md | 2 +- USAGE.md | 12 ++++-- src/runtime/runtime.test.ts | 73 +++++++++++++++++++++++++++++++++++++ src/runtime/runtime.ts | 22 +++++++++-- src/serve/serve.test.ts | 42 +++++++++++++++++++++ src/serve/serve.ts | 8 +++- 6 files changed, 150 insertions(+), 9 deletions(-) create mode 100644 src/runtime/runtime.test.ts diff --git a/README.md b/README.md index f46849d..0665ea3 100644 --- a/README.md +++ b/README.md @@ -720,7 +720,7 @@ import { - **`parseArgs(argv)`** - Parse the standard function flags - **`helpText(name)`** - The `--help` text for the standard flags - **`newGrpcServer(runner, logger)`** - Create a gRPC server instance -- **`startServer(server, opts, logger)`** - Bind and start the server +- **`startServer(server, opts, logger, onBindError?)`** - Bind and start the server; `onBindError` is called if binding fails #### Response Functions diff --git a/USAGE.md b/USAGE.md index e1b6a07..915ac69 100644 --- a/USAGE.md +++ b/USAGE.md @@ -212,7 +212,7 @@ spec: #### Upgrading from earlier versions -Two behaviour changes affect functions that call `serve()` without changing any code: +Three behaviour changes affect functions that call `serve()` without changing any code: - **Sent messages are now limited.** Earlier versions left the send limit at the grpc-js default, which is unlimited. It now defaults to the receive limit, 4 MB @@ -223,6 +223,9 @@ Two behaviour changes affect functions that call `serve()` without changing any `TLS_SERVER_CERTS_DIR` or one of the message size variables for some other reason will now pick it up. An empty value is treated as unset, so `value: ""` in a pod spec falls back to the default rather than replacing it. +- **A function that cannot bind its address exits 1.** Earlier versions logged the + bind error and carried on with nothing listening. The container now crashes + instead, so the failure is visible to Kubernetes. `serve()` takes an options object for the cases where the defaults do not fit: @@ -339,7 +342,10 @@ const logger = pino({ }); const server = newGrpcServer(new FunctionRunner(new MyFunction(), logger), logger); -startServer(server, opts as ServerOptions, logger); +// Binding finishes after startServer returns, so a failure such as the port +// being in use arrives through the optional callback. Without one it is only +// logged. +startServer(server, opts as ServerOptions, logger, () => process.exit(1)); process.on("SIGTERM", () => { server.tryShutdown(() => process.exit(0)); @@ -502,7 +508,7 @@ normal(rsp, "Function completed successfully"); - `DEFAULT_ADDRESS` - `0.0.0.0:9443` - `DEFAULT_TLS_SERVER_CERTS_DIR` - `/tls/server` - `newGrpcServer(runner, logger)` - Create gRPC server instance -- `startServer(server, opts, logger)` - Bind and start the server on specified address +- `startServer(server, opts, logger, onBindError?)` - Bind and start the server on specified address; `onBindError` is called if binding fails - `getServerCredentials(opts)` - Create server credentials (TLS or insecure mode) ### Resource Helpers diff --git a/src/runtime/runtime.test.ts b/src/runtime/runtime.test.ts new file mode 100644 index 0000000..b9e445e --- /dev/null +++ b/src/runtime/runtime.test.ts @@ -0,0 +1,73 @@ +import { describe, it, expect, afterEach, vi } from 'vitest'; +import * as grpc from '@grpc/grpc-js'; +import type { Logger } from 'pino'; +import { startServer } from './runtime.js'; + +/** A logger whose calls can be inspected. */ +function stubLogger(): Logger { + return { debug: vi.fn(), info: vi.fn(), error: vi.fn() } as unknown as Logger; +} + +describe('startServer', () => { + const servers: grpc.Server[] = []; + + afterEach(() => { + for (const server of servers.splice(0)) server.forceShutdown(); + }); + + function newServer(): grpc.Server { + const server = new grpc.Server(); + servers.push(server); + return server; + } + + /** Bind a server to a free port and return the port, so it can be collided with. */ + function occupyPort(): Promise { + return new Promise((resolve, reject) => { + newServer().bindAsync('127.0.0.1:0', grpc.ServerCredentials.createInsecure(), (err, port) => + err ? reject(err) : resolve(port) + ); + }); + } + + it('should report a bind failure to onBindError after logging it', async () => { + const port = await occupyPort(); + const logger = stubLogger(); + + const err = await new Promise((resolve) => { + startServer(newServer(), { address: `127.0.0.1:${port}`, insecure: true }, logger, resolve); + }); + + expect(err.message).toMatch(/EADDRINUSE/); + expect(logger.error).toHaveBeenCalledWith(expect.stringContaining('server bind error')); + }); + + it('should only log a bind failure when there is no onBindError', async () => { + const port = await occupyPort(); + const logger = stubLogger(); + const logged = new Promise((resolve) => { + vi.mocked(logger.error).mockImplementation(() => resolve()); + }); + + // Callers written before onBindError existed keep working: no throw, no + // exit, just the log line. + expect(() => + startServer(newServer(), { address: `127.0.0.1:${port}`, insecure: true }, logger) + ).not.toThrow(); + await logged; + }); + + it('should not call onBindError when the server binds', async () => { + const logger = stubLogger(); + const onBindError = vi.fn(); + const started = new Promise((resolve) => { + vi.mocked(logger.info).mockImplementation(() => resolve()); + }); + + startServer(newServer(), { address: '127.0.0.1:0', insecure: true }, logger, onBindError); + await started; + + expect(logger.info).toHaveBeenCalledWith(expect.stringContaining('server started')); + expect(onBindError).not.toHaveBeenCalled(); + }); +}); diff --git a/src/runtime/runtime.ts b/src/runtime/runtime.ts index 59ccc0f..2f456dc 100644 --- a/src/runtime/runtime.ts +++ b/src/runtime/runtime.ts @@ -145,12 +145,19 @@ export function newGrpcServer( * based on the provided options. The binding happens asynchronously. * * The server will log when it successfully starts listening or if an error occurs - * during binding. + * during binding. Binding finishes after this function returns, so a failure to + * bind — the port is in use, say — is reported through `onBindError` rather + * than thrown. Without one, the error is only logged, and the server is left + * not listening. * * @param server - The gRPC Server instance to start * @param opts - Server options including address and TLS configuration * @param logger - Logger instance for info and error logging - * @returns The same server instance (now bound and listening) + * @param onBindError - Called if the server fails to bind, after the error has + * been logged. + * @returns The same server instance, bound and listening once binding finishes + * @throws If the TLS certificates cannot be read, or the address cannot be + * parsed at all. * * @example * ```typescript @@ -166,15 +173,24 @@ export function newGrpcServer( * address: "localhost:9443", * insecure: true * }, logger); + * + * // Exit if the server cannot bind, rather than running with nothing listening + * startServer(server, opts, logger, () => process.exit(1)); * ``` */ -export function startServer(server: grpc.Server, opts: ServerOptions, logger: Logger): grpc.Server { +export function startServer( + server: grpc.Server, + opts: ServerOptions, + logger: Logger, + onBindError?: (err: Error) => void +): grpc.Server { const creds = getServerCredentials(opts); logger.debug(`serverCredentials type: ${creds.constructor.name}`); server.bindAsync(opts.address, creds, (err) => { if (err) { logger.error(`server bind error: ${err.message}`); + onBindError?.(err); return; } logger.info(`server started and listening on ${opts.address}`); diff --git a/src/serve/serve.test.ts b/src/serve/serve.test.ts index 610394b..565fc90 100644 --- a/src/serve/serve.test.ts +++ b/src/serve/serve.test.ts @@ -1,4 +1,6 @@ import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'; +import * as grpc from '@grpc/grpc-js'; +import { pino } from 'pino'; import { CLI } from '../cli/cli.js'; import { DEFAULT_ADDRESS, @@ -261,6 +263,46 @@ describe('serve', () => { expect(code).toBe(2); expect(stderr).toContain('got "16MB"'); }); + + it('should exit 1 when the server cannot bind its address', async () => { + // Occupy a port, then ask serve to listen on it. + const blocker = new grpc.Server(); + const port = await new Promise((resolve, reject) => { + blocker.bindAsync('127.0.0.1:0', grpc.ServerCredentials.createInsecure(), (err, p) => + err ? reject(err) : resolve(p) + ); + }); + + // The bind fails after serve returns, so wait for the exit rather than + // throwing from it as run() does. + const exited = new Promise((resolve) => { + vi.spyOn(process, 'exit').mockImplementation((code) => { + resolve(code); + return undefined as never; + }); + }); + + // serve installs signal handlers; remove them again afterwards. + const signals = ['SIGINT', 'SIGTERM'] as const; + const before = signals.map((s) => process.listeners(s)); + + const server = serve((_req, rsp) => rsp, { + argv: ['--insecure', '--address', `127.0.0.1:${port}`], + logger: pino({ level: 'silent' }), + }); + + try { + expect(await exited).toBe(1); + } finally { + server.forceShutdown(); + blocker.forceShutdown(); + signals.forEach((s, i) => { + for (const l of process.listeners(s)) { + if (!before[i].includes(l)) process.off(s, l); + } + }); + } + }); }); describe('usageErrorText', () => { diff --git a/src/serve/serve.ts b/src/serve/serve.ts index 75ddc77..0220202 100644 --- a/src/serve/serve.ts +++ b/src/serve/serve.ts @@ -160,7 +160,8 @@ export function usageErrorText(name: string, error: unknown): string { * Run a composition function as a gRPC server. * * Parses the standard flags, creates a logger, starts the server, and shuts it - * down cleanly on SIGINT and SIGTERM. This is everything a function's + * down cleanly on SIGINT and SIGTERM. If the server cannot bind its address, + * the process exits with status 1. This is everything a function's * entrypoint needs to do. * * @param fn - A {@link ComposeFunction}, or a {@link FunctionHandler} for @@ -208,7 +209,10 @@ export function serve(fn: ComposeFunction | FunctionHandler, opts: ServeOptions maxRecvMessageSize: serverOptions.maxRecvMessageSize, maxSendMessageSize: serverOptions.maxSendMessageSize, }); - startServer(server, serverOptions, logger); + // A function that cannot listen is not serving. Exit, so the failure shows up + // as a crashed container rather than one that looks healthy with nothing + // behind it. startServer has already logged why. + startServer(server, serverOptions, logger, () => process.exit(1)); const shutdown = (signal: string): void => { logger.info(`received ${signal}, shutting down`);