@crossplane-org/function-sdk-typescript 0.6.0 → 0.7.0-20260829081314-5f2a0f216756

package/README.md

@@ -20,7 +20,46 @@ npm install @crossplane-org/function-sdk-typescript
 
 ### Creating Your Function
 
-Implement the `FunctionHandler` interface:
+A function is a plain function given the request and a response to fill in:
+
+```typescript
+import {
+    Resource,
+    normal,
+    type ComposeFunction,
+} from "@crossplane-org/function-sdk-typescript";
+
+export const compose: ComposeFunction = (req, rsp, logger) => {
+    logger?.info("Processing function request");
+
+    rsp.desired.resources["my-config"] = Resource.fromJSON({
+        resource: {
+            apiVersion: "v1",
+            kind: "ConfigMap",
+            metadata: { name: "my-config" },
+            data: { key: "value" },
+        },
+    });
+
+    normal(rsp, "Function completed successfully");
+    return rsp;
+};
+```
+
+Your entry point hands it to `serve()`, which parses the standard function flags,
+builds a logger, starts the gRPC server and handles shutdown:
+
+```typescript
+#!/usr/bin/env node
+
+import { serve } from "@crossplane-org/function-sdk-typescript";
+import { compose } from "./my-function.js";
+
+serve(compose);
+```
+
+If your function needs the full interface, implement `FunctionHandler` — `serve()`
+accepts either:
 
 ```typescript
 import type {
@@ -625,11 +664,23 @@ import {
 
     // Runtime types
     ServerOptions,
+    ComposeFunction,
+    ComposeResponse,
+    ServeOptions,
 } from "@crossplane-org/function-sdk-typescript";
 ```
 
 ### Core Functions
 
+#### Server Functions
+
+- **`serve(fn, opts?)`** - Run a `ComposeFunction` or `FunctionHandler` as a gRPC server
+- **`fromCompose(compose)`** - Adapt a `ComposeFunction` to the `FunctionHandler` interface
+- **`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
+
 #### Response Functions
 
 - **`to(req, ttl?)`** - Initialize a response from a request

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export { advertiseCapabilities, getContextKey, getCredentials, getDesiredCompose
 export { DEFAULT_TTL, fatal, normal, requireResource, requireSchema, setContextKey, setDesiredComposedResources, setDesiredCompositeResource, setDesiredCompositeStatus, setDesiredResources, setOutput, to, update, updateDesiredComposedResources, warning, } from './response/response.js';
 export { asObject, asStruct, type Composite, type Condition as ResourceCondition, type ConnectionDetails, type DesiredComposed, fromModel, fromObject, getCondition, type MergeOptions, mustStructJSON, mustStructObject, newDesiredComposed, type ObservedComposed, toObject, update as updateResource, } from './resource/resource.js';
 export { getServerCredentials, newGrpcServer, type ServerOptions, startServer, } from './runtime/runtime.js';
+export { type ComposeFunction, type ComposeResponse, DEFAULT_ADDRESS, DEFAULT_TLS_SERVER_CERTS_DIR, fromCompose, helpText, parseArgs, serve, type ServeOptions, } from './serve/serve.js';
 export { Capability, Condition, CredentialData, Credentials, FunctionRunnerServiceService, Ready, Requirements, Resource, Resources, ResourceSelector, Result, RunFunctionRequest, RunFunctionResponse, Schema, SchemaSelector, Severity, State, Status, Target, } from './proto/run_function.js';
 export type { Logger } from 'pino';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,YAAY,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAGnE,OAAO,EACL,qBAAqB,EACrB,aAAa,EACb,cAAc,EACd,2BAA2B,EAC3B,2BAA2B,EAC3B,QAAQ,EACR,4BAA4B,EAC5B,4BAA4B,EAC5B,mBAAmB,EACnB,oBAAoB,EACpB,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,aAAa,GACd,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACL,WAAW,EACX,KAAK,EACL,MAAM,EACN,eAAe,EACf,aAAa,EACb,aAAa,EACb,2BAA2B,EAC3B,2BAA2B,EAC3B,yBAAyB,EACzB,mBAAmB,EACnB,SAAS,EACT,EAAE,EACF,MAAM,EACN,8BAA8B,EAC9B,OAAO,GACR,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,KAAK,SAAS,EACd,KAAK,SAAS,IAAI,iBAAiB,EACnC,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,SAAS,EACT,UAAU,EACV,YAAY,EACZ,KAAK,YAAY,EACjB,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,KAAK,gBAAgB,EACrB,QAAQ,EACR,MAAM,IAAI,cAAc,GACzB,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EACL,oBAAoB,EACpB,aAAa,EACb,KAAK,aAAa,EAClB,WAAW,GACZ,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACL,UAAU,EACV,SAAS,EACT,cAAc,EACd,WAAW,EACX,4BAA4B,EAC5B,KAAK,EACL,YAAY,EACZ,QAAQ,EACR,SAAS,EACT,gBAAgB,EAChB,MAAM,EACN,kBAAkB,EAClB,mBAAmB,EACnB,MAAM,EACN,cAAc,EACd,QAAQ,EACR,KAAK,EACL,MAAM,EACN,MAAM,GACP,MAAM,yBAAyB,CAAC;AAEjC,YAAY,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,YAAY,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAGnE,OAAO,EACL,qBAAqB,EACrB,aAAa,EACb,cAAc,EACd,2BAA2B,EAC3B,2BAA2B,EAC3B,QAAQ,EACR,4BAA4B,EAC5B,4BAA4B,EAC5B,mBAAmB,EACnB,oBAAoB,EACpB,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,aAAa,GACd,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACL,WAAW,EACX,KAAK,EACL,MAAM,EACN,eAAe,EACf,aAAa,EACb,aAAa,EACb,2BAA2B,EAC3B,2BAA2B,EAC3B,yBAAyB,EACzB,mBAAmB,EACnB,SAAS,EACT,EAAE,EACF,MAAM,EACN,8BAA8B,EAC9B,OAAO,GACR,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,KAAK,SAAS,EACd,KAAK,SAAS,IAAI,iBAAiB,EACnC,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,SAAS,EACT,UAAU,EACV,YAAY,EACZ,KAAK,YAAY,EACjB,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,KAAK,gBAAgB,EACrB,QAAQ,EACR,MAAM,IAAI,cAAc,GACzB,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EACL,oBAAoB,EACpB,aAAa,EACb,KAAK,aAAa,EAClB,WAAW,GACZ,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,eAAe,EACf,4BAA4B,EAC5B,WAAW,EACX,QAAQ,EACR,SAAS,EACT,KAAK,EACL,KAAK,YAAY,GAClB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,UAAU,EACV,SAAS,EACT,cAAc,EACd,WAAW,EACX,4BAA4B,EAC5B,KAAK,EACL,YAAY,EACZ,QAAQ,EACR,SAAS,EACT,gBAAgB,EAChB,MAAM,EACN,kBAAkB,EAClB,mBAAmB,EACnB,MAAM,EACN,cAAc,EACd,QAAQ,EACR,KAAK,EACL,MAAM,EACN,MAAM,GACP,MAAM,yBAAyB,CAAC;AAEjC,YAAY,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC"}

package/dist/index.js

@@ -8,6 +8,8 @@ export { DEFAULT_TTL, fatal, normal, requireResource, requireSchema, setContextK
 export { asObject, asStruct, fromModel, fromObject, getCondition, mustStructJSON, mustStructObject, newDesiredComposed, toObject, update as updateResource, } from './resource/resource.js';
 // Runtime utilities
 export { getServerCredentials, newGrpcServer, startServer, } from './runtime/runtime.js';
+// Entrypoint helpers
+export { DEFAULT_ADDRESS, DEFAULT_TLS_SERVER_CERTS_DIR, fromCompose, helpText, parseArgs, serve, } from './serve/serve.js';
 // Protocol buffer types
 export { Capability, Condition, CredentialData, Credentials, FunctionRunnerServiceService, Ready, Requirements, Resource, Resources, ResourceSelector, Result, RunFunctionRequest, RunFunctionResponse, Schema, SchemaSelector, Severity, State, Status, Target, } from './proto/run_function.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mDAAmD;AAInD,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAEnE,kBAAkB;AAClB,OAAO,EACL,qBAAqB,EACrB,aAAa,EACb,cAAc,EACd,2BAA2B,EAC3B,2BAA2B,EAC3B,QAAQ,EACR,4BAA4B,EAC5B,4BAA4B,EAC5B,mBAAmB,EACnB,oBAAoB,EACpB,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,aAAa,GACd,MAAM,sBAAsB,CAAC;AAE9B,mBAAmB;AACnB,OAAO,EACL,WAAW,EACX,KAAK,EACL,MAAM,EACN,eAAe,EACf,aAAa,EACb,aAAa,EACb,2BAA2B,EAC3B,2BAA2B,EAC3B,yBAAyB,EACzB,mBAAmB,EACnB,SAAS,EACT,EAAE,EACF,MAAM,EACN,8BAA8B,EAC9B,OAAO,GACR,MAAM,wBAAwB,CAAC;AAEhC,qBAAqB;AACrB,OAAO,EACL,QAAQ,EACR,QAAQ,EAKR,SAAS,EACT,UAAU,EACV,YAAY,EAEZ,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAElB,QAAQ,EACR,MAAM,IAAI,cAAc,GACzB,MAAM,wBAAwB,CAAC;AAEhC,oBAAoB;AACpB,OAAO,EACL,oBAAoB,EACpB,aAAa,EAEb,WAAW,GACZ,MAAM,sBAAsB,CAAC;AAE9B,wBAAwB;AACxB,OAAO,EACL,UAAU,EACV,SAAS,EACT,cAAc,EACd,WAAW,EACX,4BAA4B,EAC5B,KAAK,EACL,YAAY,EACZ,QAAQ,EACR,SAAS,EACT,gBAAgB,EAChB,MAAM,EACN,kBAAkB,EAClB,mBAAmB,EACnB,MAAM,EACN,cAAc,EACd,QAAQ,EACR,KAAK,EACL,MAAM,EACN,MAAM,GACP,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mDAAmD;AAInD,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAEnE,kBAAkB;AAClB,OAAO,EACL,qBAAqB,EACrB,aAAa,EACb,cAAc,EACd,2BAA2B,EAC3B,2BAA2B,EAC3B,QAAQ,EACR,4BAA4B,EAC5B,4BAA4B,EAC5B,mBAAmB,EACnB,oBAAoB,EACpB,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,aAAa,GACd,MAAM,sBAAsB,CAAC;AAE9B,mBAAmB;AACnB,OAAO,EACL,WAAW,EACX,KAAK,EACL,MAAM,EACN,eAAe,EACf,aAAa,EACb,aAAa,EACb,2BAA2B,EAC3B,2BAA2B,EAC3B,yBAAyB,EACzB,mBAAmB,EACnB,SAAS,EACT,EAAE,EACF,MAAM,EACN,8BAA8B,EAC9B,OAAO,GACR,MAAM,wBAAwB,CAAC;AAEhC,qBAAqB;AACrB,OAAO,EACL,QAAQ,EACR,QAAQ,EAKR,SAAS,EACT,UAAU,EACV,YAAY,EAEZ,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAElB,QAAQ,EACR,MAAM,IAAI,cAAc,GACzB,MAAM,wBAAwB,CAAC;AAEhC,oBAAoB;AACpB,OAAO,EACL,oBAAoB,EACpB,aAAa,EAEb,WAAW,GACZ,MAAM,sBAAsB,CAAC;AAE9B,qBAAqB;AACrB,OAAO,EAGL,eAAe,EACf,4BAA4B,EAC5B,WAAW,EACX,QAAQ,EACR,SAAS,EACT,KAAK,GAEN,MAAM,kBAAkB,CAAC;AAE1B,wBAAwB;AACxB,OAAO,EACL,UAAU,EACV,SAAS,EACT,cAAc,EACd,WAAW,EACX,4BAA4B,EAC5B,KAAK,EACL,YAAY,EACZ,QAAQ,EACR,SAAS,EACT,gBAAgB,EAChB,MAAM,EACN,kBAAkB,EAClB,mBAAmB,EACnB,MAAM,EACN,cAAc,EACd,QAAQ,EACR,KAAK,EACL,MAAM,EACN,MAAM,GACP,MAAM,yBAAyB,CAAC"}

package/dist/serve/serve.d.ts

@@ -0,0 +1,142 @@
+/**
+ * A batteries-included entrypoint for composition functions.
+ *
+ * Writing a function should not require assembling a gRPC server. This module
+ * provides {@link serve}, which parses the standard function flags, builds a
+ * logger, starts the server and handles shutdown — so a function's entrypoint
+ * is a single call, and its author only writes composition logic.
+ *
+ * It also provides the {@link ComposeFunction} shape: a plain function handed
+ * a request and a response to populate, rather than a class implementing
+ * {@link FunctionHandler}. Both are accepted, so existing handlers keep
+ * working.
+ */
+import * as grpc from '@grpc/grpc-js';
+import { type Logger } from 'pino';
+import { type FunctionHandler } from '../function/function.js';
+import { type ServerOptions } from '../runtime/runtime.js';
+import type { RunFunctionRequest, RunFunctionResponse, State } from '../proto/run_function.js';
+/** The address a function listens on unless told otherwise. */
+export declare const DEFAULT_ADDRESS = "0.0.0.0:9443";
+/**
+ * Where the package reconciler mounts the TLS certificates it generates.
+ */
+export declare const DEFAULT_TLS_SERVER_CERTS_DIR = "/tls/server";
+/**
+ * A RunFunctionResponse whose desired state is guaranteed to be present.
+ *
+ * `RunFunctionResponse.desired` is optional in the protobuf schema, but a
+ * response built by {@link to} always has it, so a compose function can write
+ * `rsp.desired.resources[name]` without a non-null assertion.
+ */
+export type ComposeResponse = RunFunctionResponse & {
+    desired: State;
+};
+/**
+ * A composition function.
+ *
+ * Receives the request along with a response already initialised from it, so
+ * there is no need to call {@link to}, and returns the response to send.
+ *
+ * The response is passed in as a convenience, not as an out parameter: it is
+ * yours to fill in and return, or to ignore in favour of one you build
+ * yourself. Returning it is required, so forgetting is a compile error rather
+ * than an empty response at runtime.
+ *
+ * Note that when the request already carries desired state — as it does for
+ * every function after the first in a pipeline — `rsp.desired` is the same
+ * object as `req.desired`, not a copy. Writing to `rsp.desired.resources`
+ * therefore also changes `req.desired.resources`. That is inherited from
+ * {@link to} and is usually harmless, since a function reads observed state
+ * and writes desired state, but do not rely on `req.desired` still holding
+ * what the previous function left once you have started writing.
+ *
+ * @example
+ * ```typescript
+ * import { Resource, type ComposeFunction } from '@crossplane-org/function-sdk-typescript';
+ * import { VPC } from 'crossplane-models/ec2.aws.m.upbound.io/v1beta1';
+ *
+ * export const compose: ComposeFunction = (req, rsp) => {
+ *   const vpc = new VPC({ spec: { forProvider: { region: 'us-west-2' } } });
+ *   vpc.validate();
+ *   rsp.desired.resources['vpc'] = Resource.fromJSON({ resource: vpc.toJSON() });
+ *   return rsp;
+ * };
+ * ```
+ */
+export type ComposeFunction = (req: RunFunctionRequest, rsp: ComposeResponse, logger?: Logger) => RunFunctionResponse | Promise<RunFunctionResponse>;
+/**
+ * Adapt a {@link ComposeFunction} to the {@link FunctionHandler} interface.
+ *
+ * Builds the response from the request, hands it to the compose function, and
+ * returns whatever that function returns.
+ */
+export declare function fromCompose(compose: ComposeFunction): FunctionHandler;
+/** Options for {@link serve}. */
+export interface ServeOptions {
+    /**
+     * Program name shown in --help. Defaults to the basename of the running
+     * script.
+     */
+    name?: string;
+    /**
+     * Arguments to parse, without the node executable or script path.
+     * Defaults to process.argv.slice(2).
+     */
+    argv?: string[];
+    /**
+     * Logger to use. One is created from the parsed --debug flag if omitted.
+     */
+    logger?: Logger;
+    /** Overrides applied on top of the parsed flags. */
+    serverOptions?: Partial<ServerOptions>;
+}
+/** The result of {@link parseArgs}: server options, plus whether help was asked for. */
+export interface ParsedArgs extends ServerOptions {
+    /** Whether --help or -h was given. */
+    help: boolean;
+}
+/**
+ * Parse the standard function command line flags.
+ *
+ * Exported so that it can be tested, and so that a function needing extra
+ * flags of its own can reuse the standard ones.
+ *
+ * @param argv - Arguments without the node executable or script path.
+ * @returns The parsed options.
+ * @throws If a flag is unrecognised, missing its value, or given a value it
+ *   does not take.
+ */
+export declare function parseArgs(argv: string[]): ParsedArgs;
+/** The --help text, derived from {@link flags} and {@link descriptions}. */
+export declare function helpText(name: string): string;
+/**
+ * The message shown when the command line cannot be parsed.
+ *
+ * Kept separate from {@link serve} so that it can be tested without spawning a
+ * process, since serve's own handling ends in process.exit.
+ */
+export declare 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
+ * entrypoint needs to do.
+ *
+ * @param fn - A {@link ComposeFunction}, or a {@link FunctionHandler} for
+ *   functions that need the full interface.
+ * @param opts - Overrides, mostly useful in tests.
+ * @returns The running gRPC server.
+ *
+ * @example
+ * ```typescript
+ * #!/usr/bin/env node
+ * import { serve } from '@crossplane-org/function-sdk-typescript';
+ * import { compose } from './function.js';
+ *
+ * serve(compose);
+ * ```
+ */
+export declare function serve(fn: ComposeFunction | FunctionHandler, opts?: ServeOptions): grpc.Server;
+//# sourceMappingURL=serve.d.ts.map

package/dist/serve/serve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../src/serve/serve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,IAAI,MAAM,eAAe,CAAC;AAGtC,OAAO,EAAQ,KAAK,MAAM,EAAE,MAAM,MAAM,CAAC;AACzC,OAAO,EAAkB,KAAK,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC/E,OAAO,EAA8B,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAEvF,OAAO,KAAK,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AAE/F,+DAA+D;AAC/D,eAAO,MAAM,eAAe,iBAAiB,CAAC;AAE9C;;GAEG;AACH,eAAO,MAAM,4BAA4B,gBAAgB,CAAC;AAE1D;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,mBAAmB,GAAG;IAAE,OAAO,EAAE,KAAK,CAAA;CAAE,CAAC;AAcvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,MAAM,eAAe,GAAG,CAC5B,GAAG,EAAE,kBAAkB,EACvB,GAAG,EAAE,eAAe,EACpB,MAAM,CAAC,EAAE,MAAM,KACZ,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;AAExD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,eAAe,GAAG,eAAe,CAQrE;AAED,iCAAiC;AACjC,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAEhB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,oDAAoD;IACpD,aAAa,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;CACxC;AA6BD,wFAAwF;AACxF,MAAM,WAAW,UAAW,SAAQ,aAAa;IAC/C,sCAAsC;IACtC,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CASpD;AAED,4EAA4E;AAC5E,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAc7C;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,CAGnE;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,eAAe,GAAG,eAAe,EAAE,IAAI,GAAE,YAAiB,GAAG,IAAI,CAAC,MAAM,CAqDjG"}

package/dist/serve/serve.js

@@ -0,0 +1,192 @@
+/**
+ * A batteries-included entrypoint for composition functions.
+ *
+ * Writing a function should not require assembling a gRPC server. This module
+ * provides {@link serve}, which parses the standard function flags, builds a
+ * logger, starts the server and handles shutdown — so a function's entrypoint
+ * is a single call, and its author only writes composition logic.
+ *
+ * It also provides the {@link ComposeFunction} shape: a plain function handed
+ * a request and a response to populate, rather than a class implementing
+ * {@link FunctionHandler}. Both are accepted, so existing handlers keep
+ * working.
+ */
+import * as grpc from '@grpc/grpc-js';
+import { basename } from 'node:path';
+import { parseArgs as parseNodeArgs } from 'node:util';
+import { pino } from 'pino';
+import { FunctionRunner } from '../function/function.js';
+import { newGrpcServer, startServer } from '../runtime/runtime.js';
+import { to } from '../response/response.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 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() {
+    const script = process.argv[1];
+    return script ? basename(script) : 'function';
+}
+/**
+ * Adapt a {@link ComposeFunction} to the {@link FunctionHandler} interface.
+ *
+ * Builds the response from the request, hands it to the compose function, and
+ * returns whatever that function returns.
+ */
+export function fromCompose(compose) {
+    return {
+        async RunFunction(req, logger) {
+            // to() always populates desired, so the cast holds.
+            const rsp = to(req);
+            return await compose(req, rsp, logger);
+        },
+    };
+}
+/**
+ * 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 },
+};
+/**
+ * What each flag does. Keyed by {@link flags}, so adding a flag without
+ * describing it is a compile error.
+ */
+const descriptions = {
+    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.',
+};
+/**
+ * Parse the standard function command line flags.
+ *
+ * Exported so that it can be tested, and so that a function needing extra
+ * flags of its own can reuse the standard ones.
+ *
+ * @param argv - Arguments without the node executable or script path.
+ * @returns The parsed options.
+ * @throws If a flag is unrecognised, missing its value, or given a value it
+ *   does not take.
+ */
+export function parseArgs(argv) {
+    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,
+    };
+}
+/** The --help text, derived from {@link flags} and {@link descriptions}. */
+export function helpText(name) {
+    const usage = Object.entries(flags).map(([flag, spec]) => {
+        const short = 'short' in spec ? `-${spec.short}, ` : '    ';
+        const value = spec.type === 'string' ? ' <value>' : '';
+        return `  ${short}--${flag}${value}`.padEnd(38) + descriptions[flag];
+    });
+    return [
+        `Usage: ${name} [flags]`,
+        '',
+        'A Crossplane composition function.',
+        '',
+        'Flags:',
+        ...usage,
+    ].join('\n');
+}
+/**
+ * The message shown when the command line cannot be parsed.
+ *
+ * Kept separate from {@link serve} so that it can be tested without spawning a
+ * process, since serve's own handling ends in process.exit.
+ */
+export function usageErrorText(name, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return `${name}: ${message}\nTry '${name} --help' for the available flags.`;
+}
+/**
+ * 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
+ * entrypoint needs to do.
+ *
+ * @param fn - A {@link ComposeFunction}, or a {@link FunctionHandler} for
+ *   functions that need the full interface.
+ * @param opts - Overrides, mostly useful in tests.
+ * @returns The running gRPC server.
+ *
+ * @example
+ * ```typescript
+ * #!/usr/bin/env node
+ * import { serve } from '@crossplane-org/function-sdk-typescript';
+ * import { compose } from './function.js';
+ *
+ * serve(compose);
+ * ```
+ */
+export function serve(fn, opts = {}) {
+    const name = opts.name ?? defaultName();
+    const argv = opts.argv ?? process.argv.slice(2);
+    let args;
+    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 { help, ...parsed } = args;
+    if (help) {
+        process.stdout.write(`${helpText(name)}\n`);
+        process.exit(0);
+    }
+    const serverOptions = { ...parsed, ...opts.serverOptions };
+    const logger = opts.logger ??
+        pino({
+            level: serverOptions.debug ? 'debug' : 'info',
+            formatters: {
+                level: (label) => ({ severity: label.toUpperCase() }),
+            },
+        });
+    logger.debug({ options: serverOptions }, 'starting function');
+    const handler = typeof fn === 'function' ? fromCompose(fn) : fn;
+    const server = newGrpcServer(new FunctionRunner(handler, logger), logger);
+    startServer(server, serverOptions, logger);
+    const shutdown = (signal) => {
+        logger.info(`received ${signal}, shutting down`);
+        server.tryShutdown((err) => {
+            if (err) {
+                logger.error(err, 'error during shutdown');
+                process.exit(1);
+            }
+            logger.info('server shut down');
+            process.exit(0);
+        });
+    };
+    process.on('SIGINT', () => shutdown('SIGINT'));
+    process.on('SIGTERM', () => shutdown('SIGTERM'));
+    return server;
+}
+//# sourceMappingURL=serve.js.map

package/dist/serve/serve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve.js","sourceRoot":"","sources":["../../src/serve/serve.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crossplane-org/function-sdk-typescript",
-  "version": "0.6.0",
+  "version": "0.7.0-20260829081314-5f2a0f216756",
   "description": "A Crossplane Function SDK for Typescript",
   "keywords": [
     "crossplane",