diff --git a/README.md b/README.md index 84822f3..0665ea3 100644 --- a/README.md +++ b/README.md @@ -58,6 +58,38 @@ import { compose } from "./my-function.js"; serve(compose); ``` +### Custom Flags with the Shareable CLI + +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. `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"; +import { compose } from "./my-function.js"; // (req, rsp, cacheSize: number) => rsp + +const cli = new CLI({ + flags: { + "cache-size": { type: "string", default: "100", env: "CACHE_SIZE", description: "Number of entries to cache." }, + }, +}); + +// 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 +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 +699,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 @@ -679,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 3adc4e2..915ac69 100644 --- a/USAGE.md +++ b/USAGE.md @@ -151,20 +151,81 @@ 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 | +|------|-----|---------|-------------| +| `--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`, `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`. 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 + +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. + +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`: + +```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" ``` -Usage: main.js [flags] -A Crossplane composition function. +#### Upgrading from earlier versions -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. -``` +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 + 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. 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: @@ -172,6 +233,7 @@ Flags: 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 }); @@ -192,6 +254,64 @@ 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, 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, type ComposeFunction } from "@crossplane-org/function-sdk-typescript"; + +const cli = new CLI({ + flags: { + "cache-size": { + type: "string", + default: "100", + env: "CACHE_SIZE", + description: "Number of entries to cache.", + }, + "verbose": { + type: "boolean", + short: "v", + env: "VERBOSE", + description: "Enable verbose output.", + }, + }, +}); + +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; +}; + +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. 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. + +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 `serve()` is the recommended entry point, but the pieces it uses are exported, so a @@ -222,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)); @@ -365,6 +488,17 @@ 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.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 + ### Runtime - `serve(fn, opts?)` - Run a `ComposeFunction` or `FunctionHandler` as a gRPC server: parses flags, builds a logger, starts the server, handles shutdown @@ -374,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/cli/cli.test.ts b/src/cli/cli.test.ts new file mode 100644 index 0000000..c8e5331 --- /dev/null +++ b/src/cli/cli.test.ts @@ -0,0 +1,559 @@ +import { describe, it, expect, beforeEach, afterEach } from 'vitest'; +import { CLI, DEFAULT_ADDRESS, DEFAULT_TLS_SERVER_CERTS_DIR } 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', + ]; + + 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, + 'max-recv-message-size': '4', + 'max-send-message-size': undefined, + 'tls-server-certs-dir': '/tls/server', + 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/); + }); + + 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 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.' } }, + }); + 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"/); + }); + + 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', () => { + 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); + }); + + 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', () => { + 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 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({ + 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 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 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'; + 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', + '--max-recv-message-size', + '--max-send-message-size', + '--tls-server-certs-dir', + '--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', + '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', () => { + it('should return the configured program name', () => { + const cli = new CLI({ name: 'my-function' }); + 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 new file mode 100644 index 0000000..c119cc9 --- /dev/null +++ b/src/cli/cli.ts @@ -0,0 +1,386 @@ +/** + * 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. {@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. + * + * Functions that need extra flags create a CLI and hand it to serve, which + * parses it, handles --help and reports usage errors: + * + * @example + * ```typescript + * const cli = new CLI({ + * flags: { + * 'my-flag': { type: 'string', default: 'foo', env: 'MY_FLAG', description: 'My custom flag.' }, + * }, + * }); + * + * serve(compose, { cli }); + * + * // serve has parsed the CLI by the time it returns. + * const myFlag = cli.values['my-flag']; + * ``` + */ + +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'; + +/** 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. */ + env?: string; + /** Fallback environment variables checked when the primary is not set. */ + envAliases?: string[]; + description: string; +} + +/** The value of a parsed flag. */ +export type FlagValue = string | boolean | undefined; + +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.', + }, + 'max-recv-message-size': { + 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, + 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, + short: 'h', + description: 'Show this help.', + }, +}; + +/** 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. */ + 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, 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. + * An empty string from either source is treated as unset. + */ +export class CLI { + private readonly programName: string; + private readonly allFlags: Record; + private parsedValues?: Record; + + /** + * @throws If a custom flag reuses a standard flag's name or another flag's + * 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)) { + // 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`); + } + } + this.allFlags = { ...standardFlags, ...custom }; + + 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` + ); + } + 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); + } + } + + /** + * 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 } = { type: spec.type }; + if (spec.short) opt.short = spec.short; + parseOptions[name] = opt; + } + + const { values } = parseNodeArgs({ + args, + options: parseOptions as NonNullable[0]>['options'], + allowPositionals: false, + }); + + const parsed = values as Record; + + const resolved: Record = {}; + for (const [name, spec] of Object.entries(this.allFlags)) { + 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. + // 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; + return { ...resolved }; + } + + /** + * 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; + } + + /** 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, 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; + const send = values['max-send-message-size']; + + return { + 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. + * + * @throws If {@link parse} has not been called. + */ + logger(): Logger { + return newLogger(this.values['debug'] === true); + } + + /** Generate help text that includes both standard and custom flags. */ + helpText(): string { + const rows = Object.entries(this.allFlags).map(([flag, spec]) => { + const short = spec.short ? `-${spec.short}, ` : ' '; + const value = spec.type === 'string' ? ' ' : ''; + const envKeys = envKeysOf(spec); + 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 + // 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]`, + '', + 'A Crossplane composition function.', + '', + 'Flags:', + ...usage, + ].join('\n'); + } + + /** The program name used in help text. */ + get name(): string { + return this.programName; + } +} + +/** + * 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() }), + }, + }); +} + +/** 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". + // + // 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; + + for (const key of envKeysOf(spec)) { + const envValue = process.env[key]; + if (envValue !== undefined && envValue !== '') { + return spec.type === 'boolean' + ? envValue === '1' || envValue.toLowerCase() === 'true' + : envValue; + } + } + + 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, 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 { + 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) { + throw new Error( + `${source} must be a positive whole number of megabytes, got ${JSON.stringify(value)}` + ); + } + + 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 { + const script = process.argv[1]; + return script ? basename(script) : 'function'; +} diff --git a/src/function/function.ts b/src/function/function.ts index 970f6d6..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 @@ -147,8 +149,20 @@ 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; maxSendMessageSize?: number } +): grpc.Server { + const channelOptions: grpc.ServerOptions = {}; + if (opts?.maxRecvMessageSize !== undefined) { + channelOptions['grpc.max_receive_message_length'] = opts.maxRecvMessageSize; + } + const sendSize = opts?.maxSendMessageSize ?? opts?.maxRecvMessageSize; + if (sendSize !== undefined) { + channelOptions['grpc.max_send_message_length'] = sendSize; + } + 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..1d7c1d8 100644 --- a/src/index.ts +++ b/src/index.ts @@ -61,6 +61,15 @@ export { update as updateResource, } from './resource/resource.js'; +// Shareable CLI +export { + CLI, + type CLIOptions, + DEFAULT_MAX_RECV_MESSAGE_SIZE, + type FlagSpec, + type FlagValue, +} from './cli/cli.js'; + // Runtime utilities export { getServerCredentials, 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 c185975..2f456dc 100644 --- a/src/runtime/runtime.ts +++ b/src/runtime/runtime.ts @@ -41,6 +41,19 @@ export interface ServerOptions { * Ignored if insecure is set to true. */ tlsServerCertsDir?: string; + + /** + * Maximum size of received gRPC messages in bytes. + * 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, and to grpc-js's own + * default (unlimited) when neither is set. + */ + maxSendMessageSize?: number; } /** @@ -112,8 +125,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'); } @@ -128,12 +145,19 @@ export function newGrpcServer(functionRunner: FunctionRunner, logger: Logger): g * 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 @@ -149,15 +173,24 @@ export function newGrpcServer(functionRunner: FunctionRunner, logger: Logger): g * 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 c715852..565fc90 100644 --- a/src/serve/serve.test.ts +++ b/src/serve/serve.test.ts @@ -1,10 +1,14 @@ -import { describe, it, expect } from 'vitest'; +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, DEFAULT_TLS_SERVER_CERTS_DIR, fromCompose, helpText, parseArgs, + serve, usageErrorText, type ComposeFunction, } from './serve.js'; @@ -12,6 +16,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,6 +43,41 @@ 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 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, }); }); @@ -37,6 +96,8 @@ describe('parseArgs', () => { debug: true, insecure: true, tlsServerCertsDir: '/certs', + maxRecvMessageSize: 4 * 1024 * 1024, + maxSendMessageSize: undefined, help: false, }); }); @@ -76,7 +137,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); } }); @@ -93,6 +162,149 @@ 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; + stderr: 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; + }); + 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, stderr }; + 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`); + }); + + 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('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', () => { it('should surface the parser message and point at --help', () => { let thrown: unknown; diff --git a/src/serve/serve.ts b/src/serve/serve.ts index bf2d3a5..0220202 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(); } /** @@ -214,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 @@ -232,42 +179,40 @@ 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'); const handler: FunctionHandler = typeof fn === 'function' ? fromCompose(fn) : fn; - const server = newGrpcServer(new FunctionRunner(handler, logger), logger); - startServer(server, serverOptions, logger); + const server = newGrpcServer(new FunctionRunner(handler, logger), logger, { + maxRecvMessageSize: serverOptions.maxRecvMessageSize, + maxSendMessageSize: serverOptions.maxSendMessageSize, + }); + // 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`);