keryx 0.4.0 → 0.6.0

package/api.ts

@@ -40,6 +40,9 @@ if (!globalThis.api) {
   globalThis.config = Config;
 }
 
+/** The global API singleton. All framework state (actions, db, redis, etc.) is accessed through this object. */
 export const api = globalThis.api;
+/** Convenience re-export of `api.logger`. */
 export const logger = globalThis.logger;
+/** The merged configuration object (framework defaults + user overrides + env vars). */
 export const config = globalThis.config;

package/classes/API.ts

@@ -8,6 +8,7 @@ import type { Initializer, InitializerSortKeys } from "./Initializer";
 import { Logger } from "./Logger";
 import { ErrorType, TypedError } from "./TypedError";
 
+/** The mode the API process is running in, which determines which initializers start. */
 export enum RUN_MODE {
   CLI = "cli",
   SERVER = "server",
@@ -15,15 +16,29 @@ export enum RUN_MODE {
 
 let flapPreventer = false;
 
+/**
+ * The global singleton that manages the full framework lifecycle: initialize → start → stop.
+ * All initializers attach their namespaces to this object (e.g., `api.db`, `api.actions`, `api.redis`).
+ * Stored on `globalThis` so every module shares the same instance.
+ */
 export class API {
+  /** The root directory of the user's application. Set this before calling `initialize()`. */
   rootDir: string;
+  /** The root directory of the keryx package itself (auto-resolved from `import.meta.path`). */
   packageDir: string;
+  /** Whether `initialize()` has completed successfully. */
   initialized: boolean;
+  /** Whether `start()` has completed successfully. */
   started: boolean;
+  /** Whether `stop()` has completed successfully. */
   stopped: boolean;
+  /** Epoch timestamp (ms) when the API instance was created. */
   bootTime: number;
+  /** The framework logger instance, configured from `config.logger`. */
   logger: Logger;
+  /** The current run mode (SERVER or CLI), set during `start()`. */
   runMode!: RUN_MODE;
+  /** All discovered initializer instances, sorted by the most-recently-used priority key. */
   initializers: Initializer[];
 
   // allow arbitrary properties to be set on the API, to be added and typed later
@@ -42,6 +57,13 @@ export class API {
     this.initializers = [];
   }
 
+  /**
+   * Load configuration overrides and discover + run all initializers.
+   * Calls each initializer's `initialize()` method in `loadPriority` order.
+   * The return value of each initializer is attached to `api[initializer.name]`.
+   *
+   * @throws {TypedError} With `ErrorType.SERVER_INITIALIZATION` if any initializer fails.
+   */
   async initialize() {
     this.logger.warn("--- 🔄  Initializing process ---");
     this.initialized = false;
@@ -69,6 +91,17 @@ export class API {
     this.logger.warn("--- 🔄  Initializing complete ---");
   }
 
+  /**
+   * Start the framework: connect to external services, bind server ports, start workers.
+   * Calls `initialize()` first if it hasn't been run yet, then calls each initializer's
+   * `start()` method in `startPriority` order. Initializers whose `runModes` do not include
+   * the current `runMode` are skipped.
+   *
+   * @param runMode - Whether to start in SERVER mode (HTTP/WebSocket) or CLI mode.
+   *   Defaults to `RUN_MODE.SERVER`. Initializers can opt out of specific modes via their
+   *   `runModes` property.
+   * @throws {TypedError} With `ErrorType.SERVER_START` if any initializer fails to start.
+   */
   async start(runMode: RUN_MODE = RUN_MODE.SERVER) {
     this.stopped = false;
     this.started = false;
@@ -104,6 +137,12 @@ export class API {
     this.logger.warn("--- 🔼  Starting complete ---");
   }
 
+  /**
+   * Gracefully shut down the framework: disconnect from services, close server ports, stop workers.
+   * Calls each initializer's `stop()` method in `stopPriority` order. No-ops if already stopped.
+   *
+   * @throws {TypedError} With `ErrorType.SERVER_STOP` if any initializer fails to stop.
+   */
   async stop() {
     if (this.stopped) {
       this.logger.warn("API is already stopped");
@@ -133,6 +172,10 @@ export class API {
     this.logger.warn("--- 🔽  Stopping complete ---");
   }
 
+  /**
+   * Stop and then re-start the framework. Includes a flap preventer that ignores
+   * concurrent restart calls to avoid rapid stop/start cycles.
+   */
   async restart() {
     if (flapPreventer) return;
 

package/classes/Action.ts

@@ -50,6 +50,9 @@ export type ActionConstructorInputs = {
     method?: HTTP_METHOD;
   };
 
+  /** Per-action timeout in ms (overrides global `config.server.web.actionTimeout`; 0 disables) */
+  timeout?: number;
+
   /** Configure this action as a background task/job */
   task?: {
     /** Optional recurring frequency in milliseconds */
@@ -64,17 +67,33 @@ export type ActionMiddlewareResponse = {
   updatedResponse?: any;
 };
 
+/**
+ * Middleware hooks that run before and/or after an action's `run()` method.
+ * Middleware can mutate params (via `updatedParams`) or replace the response (via `updatedResponse`).
+ */
 export type ActionMiddleware = {
+  /**
+   * Runs before the action's `run()` method. Can modify params by returning `{ updatedParams }`.
+   * Throw a `TypedError` to abort the action (e.g., for auth checks).
+   */
   runBefore?: (
     params: ActionParams<Action>,
     connection: Connection,
   ) => Promise<ActionMiddlewareResponse | void>;
+  /**
+   * Runs after the action's `run()` method. Can replace the response by returning `{ updatedResponse }`.
+   */
   runAfter?: (
     params: ActionParams<Action>,
     connection: Connection,
   ) => Promise<ActionMiddlewareResponse | void>;
 };
 
+/**
+ * Abstract base class for transport-agnostic controllers. Actions serve simultaneously as
+ * HTTP endpoints, WebSocket handlers, CLI commands, background tasks, and MCP tools.
+ * Subclasses must implement the `run()` method.
+ */
 export abstract class Action {
   name: string;
   description?: string;
@@ -85,6 +104,7 @@ export abstract class Action {
     route: RegExp | string;
     method: HTTP_METHOD;
   };
+  timeout?: number;
   task?: {
     frequency?: number;
     queue: string;
@@ -95,6 +115,7 @@ export abstract class Action {
     this.description = args.description ?? `An Action: ${this.name}`;
     this.inputs = args.inputs;
     this.middleware = args.middleware ?? [];
+    this.timeout = args.timeout;
     this.mcp = { enabled: true, ...args.mcp };
     this.web = {
       route: args.web?.route ?? `/${this.name}`,
@@ -111,18 +132,41 @@ export abstract class Action {
    * It can be `async`.
    * Usually the goal of this run method is to return the data that you want to be sent to API consumers.
    * If error is thrown in this method, it will be logged, caught, and returned to the client as `error`
+   *
+   * @param params - The validated and coerced action inputs. The type is inferred from the
+   *   action's `inputs` Zod schema (falls back to `Record<string, unknown>` when no schema is
+   *   defined). By the time `run` is called, all middleware `runBefore` hooks have already
+   *   executed and may have mutated the params.
+   * @param connection - The connection that initiated this action. Provides access to the
+   *   caller's session (`connection.session`), subscription state, and raw transport handle.
+   *   It is `undefined` when the action is invoked outside an HTTP/WebSocket request context
+   *   (e.g., as a background task via the Resque worker or via `api.actions.run()`).
+   * @param abortSignal - An `AbortSignal` tied to the action's timeout. The signal is aborted
+   *   when the per-action `timeout` (or the global `config.actions.timeout`, default 300 000 ms)
+   *   elapses. Long-running actions should check `abortSignal.aborted` or pass the signal to
+   *   cancellable APIs (e.g., `fetch`) to exit promptly. Not provided when timeouts are
+   *   disabled (`timeout: 0`).
    * @throws {TypedError} All errors thrown should be TypedError instances
    */
   abstract run(
     params: ActionParams<Action>,
     connection?: Connection,
+    abortSignal?: AbortSignal,
   ): Promise<any>;
 }
 
+/**
+ * Infers the validated input type for an action from its `inputs` Zod schema.
+ * Falls back to `Record<string, unknown>` when no schema is defined.
+ */
 export type ActionParams<A extends Action> =
   A["inputs"] extends z.ZodType<any>
     ? z.infer<A["inputs"]>
     : Record<string, unknown>;
 
+/**
+ * Infers the return type of an action's `run()` method, merged with an optional `error` field.
+ * Useful for typing API responses on the client side.
+ */
 export type ActionResponse<A extends Action> = Awaited<ReturnType<A["run"]>> &
   Partial<{ error?: TypedError }>;

package/classes/Channel.ts

@@ -37,6 +37,11 @@ export type ChannelConstructorInputs = {
   middleware?: ChannelMiddleware[];
 };
 
+/**
+ * Abstract base class for PubSub channels. Channels define a `name` (exact string or RegExp)
+ * and optional middleware for authorization on subscribe and cleanup on unsubscribe.
+ * Subclasses can override `authorize()` and `presenceKey()` for custom behavior.
+ */
 export abstract class Channel {
   name: string | RegExp;
   description?: string;

package/classes/Connection.ts

@@ -9,16 +9,39 @@ import { isSecret } from "../util/zodMixins";
 import type { Action, ActionParams } from "./Action";
 import { ErrorType, TypedError } from "./TypedError";
 
+/**
+ * Represents a client connection to the server — HTTP request, WebSocket, or internal caller.
+ * Each connection tracks its own session, channel subscriptions, and rate-limit state.
+ * The generic `T` allows typing the session data shape for your application.
+ */
 export class Connection<T extends Record<string, any> = Record<string, any>> {
+  /** Transport type identifier (e.g., `"web"`, `"websocket"`). */
   type: string;
+  /** A human-readable identifier for the connection, typically the remote IP or a session key. */
   identifier: string;
+  /** Unique connection ID (UUID by default). Used as the key in `api.connections`. */
   id: string;
+  /** The connection's session data, lazily loaded on first action invocation. */
   session?: SessionData<T>;
+  /** Set of channel names this connection is currently subscribed to. */
   subscriptions: Set<string>;
+  /** Whether the session has been loaded from Redis at least once. */
   sessionLoaded: boolean;
+  /** The underlying transport handle (e.g., Bun `ServerWebSocket`). */
   rawConnection?: any;
+  /** Rate-limit metadata populated by the rate-limit middleware. */
   rateLimitInfo?: RateLimitInfo;
+  /** Request correlation ID for distributed tracing. Propagated from the incoming `X-Request-Id` header when `config.server.web.correlationId.trustProxy` is enabled. */
+  correlationId?: string;
 
+  /**
+   * Create a new connection and register it in `api.connections`.
+   *
+   * @param type - Transport type (e.g., `"web"`, `"websocket"`).
+   * @param identifier - Human-readable identifier, typically the remote IP address.
+   * @param id - Unique connection ID. Defaults to a random UUID.
+   * @param rawConnection - The underlying transport handle (e.g., Bun `ServerWebSocket`).
+   */
   constructor(
     type: string,
     identifier: string,
@@ -36,8 +59,18 @@ export class Connection<T extends Record<string, any> = Record<string, any>> {
   }
 
   /**
-   * Runs an action for this connection, given FormData params.
-   *  Throws errors.
+   * Execute an action in the context of this connection. Handles the full lifecycle:
+   * session loading, param validation via the action's Zod schema, middleware execution
+   * (before/after), timeout enforcement, and structured logging.
+   *
+   * @param actionName - The name of the action to run. If not found, throws
+   *   `ErrorType.CONNECTION_ACTION_NOT_FOUND`.
+   * @param params - Raw `FormData` from the HTTP request or WebSocket message.
+   *   Validated and coerced against the action's `inputs` Zod schema.
+   * @param method - The HTTP method of the incoming request (used for logging).
+   * @param url - The request URL (used for logging).
+   * @returns The action response and optional error.
+   * @throws {TypedError} With the appropriate `ErrorType` for validation, timeout, or runtime failures.
    */
   async act(
     actionName: string | undefined,
@@ -76,7 +109,26 @@ export class Connection<T extends Record<string, any> = Record<string, any>> {
         }
       }
 
-      response = await action.run(formattedParams, this);
+      const timeoutMs = action.timeout ?? config.actions.timeout;
+      if (timeoutMs > 0) {
+        const controller = new AbortController();
+        const timeoutError = new TypedError({
+          message: `Action '${action.name}' timed out after ${timeoutMs}ms`,
+          type: ErrorType.CONNECTION_ACTION_TIMEOUT,
+        });
+        const timeoutPromise = new Promise<never>((_, reject) => {
+          setTimeout(() => {
+            controller.abort();
+            reject(timeoutError);
+          }, timeoutMs);
+        });
+        response = await Promise.race([
+          action.run(formattedParams, this, controller.signal),
+          timeoutPromise,
+        ]);
+      } else {
+        response = await action.run(formattedParams, this);
+      }
 
       for (const middleware of action.middleware ?? []) {
         if (middleware.runAfter) {
@@ -122,13 +174,23 @@ export class Connection<T extends Record<string, any> = Record<string, any>> {
           : "\r\n" + error.stack
         : "";
 
+    const correlationIdTag = this.correlationId
+      ? ` [cor:${this.correlationId}]`
+      : "";
+
     logger.info(
-      `${messagePrefix} ${actionName} (${duration}ms) ${method.length > 0 ? `[${method}]` : ""} ${this.identifier}${url.length > 0 ? `(${url})` : ""} ${error ? error : ""} ${loggingParams} ${errorStack}`,
+      `${messagePrefix} ${actionName} (${duration}ms) ${method.length > 0 ? `[${method}]` : ""} ${this.identifier}${url.length > 0 ? `(${url})` : ""}${correlationIdTag} ${error ? error : ""} ${loggingParams} ${errorStack}`,
     );
 
     return { response, error };
   }
 
+  /**
+   * Merge new data into the connection's session. Loads the session first if not yet loaded.
+   *
+   * @param data - Partial session data to merge into the existing session.
+   * @throws {TypedError} With `ErrorType.CONNECTION_SESSION_NOT_FOUND` if no session exists.
+   */
   async updateSession(data: Partial<T>) {
     await this.loadSession();
 
@@ -142,14 +204,23 @@ export class Connection<T extends Record<string, any> = Record<string, any>> {
     return api.session.update(this.session, data);
   }
 
+  /** Add a channel to this connection's subscription set. */
   subscribe(channel: string) {
     this.subscriptions.add(channel);
   }
 
+  /** Remove a channel from this connection's subscription set. */
   unsubscribe(channel: string) {
     this.subscriptions.delete(channel);
   }
 
+  /**
+   * Publish a message to a PubSub channel. The connection must already be subscribed.
+   *
+   * @param channel - The channel name to broadcast to.
+   * @param message - The message payload to send.
+   * @throws {TypedError} With `ErrorType.CONNECTION_NOT_SUBSCRIBED` if not subscribed.
+   */
   async broadcast(channel: string, message: string) {
     if (!this.subscriptions.has(channel)) {
       throw new TypedError({
@@ -161,16 +232,28 @@ export class Connection<T extends Record<string, any> = Record<string, any>> {
     return api.pubsub.broadcast(channel, message, this.id);
   }
 
+  /**
+   * Called when a PubSub message arrives for a channel this connection is subscribed to.
+   * Must be overridden by transport-specific subclasses (e.g., WebSocket connections).
+   *
+   * @param _payload - The incoming PubSub message.
+   * @throws {Error} Always throws in the base class — subclasses must override.
+   */
   onBroadcastMessageReceived(_payload: PubSubMessage) {
     throw new Error(
       "unimplemented - this should be overwritten by connections that support it",
     );
   }
 
+  /** Remove this connection from the global connections map and clean up resources. */
   destroy() {
     return api.connections.destroy(this.type, this.identifier, this.id);
   }
 
+  /**
+   * Load the session from Redis (or create a new one if none exists).
+   * No-ops if the session is already loaded. Sets `sessionLoaded` to `true`.
+   */
   async loadSession() {
     if (this.session) return;
 

package/classes/ExitCode.ts

@@ -1,3 +1,4 @@
+/** Process exit codes used by the CLI runner and signal handlers. */
 export enum ExitCode {
   success = 0,
   error = 1,

package/classes/Initializer.ts

@@ -1,18 +1,21 @@
 import { RUN_MODE } from "./../api";
 
 /**
- * Create a new Initializer. The required properties of an initializer. These can be defined statically (this.name) or as methods which return a value.
+ * Abstract base class for lifecycle components. Initializers are discovered automatically
+ * and run in priority order during the framework's initialize → start → stop phases.
+ * Each initializer typically extends the `API` interface via module augmentation and
+ * returns its namespace object from `initialize()`.
  */
 export abstract class Initializer {
-  /**The name of the Initializer. */
+  /** The unique name of this initializer (also used as the key on the `api` object). */
   name: string;
-  /**What order should this Initializer load at (Default: 1000, core methods are < 1000) */
+  /** Priority order for `initialize()`. Lower values run first. Default: 1000; core initializers use < 1000. */
   loadPriority: number;
-  /**What order should this Initializer start at (Default: 1000, core methods are < 1000) */
+  /** Priority order for `start()`. Lower values run first. Default: 1000; core initializers use < 1000. */
   startPriority: number;
-  /**What order should this Initializer stop at (Default: 1000, core methods are < 1000) */
+  /** Priority order for `stop()`. Lower values run first. Default: 1000; core initializers use < 1000. */
   stopPriority: number;
-  /** which run modes does this sever start in*/
+  /** Which run modes this initializer participates in. Defaults to both SERVER and CLI. */
   runModes: RUN_MODE[];
 
   constructor(name: string) {
@@ -24,17 +27,18 @@ export abstract class Initializer {
   }
 
   /**
-   * Method run as part of the `initialize` lifecycle of your process.  Usually sets api['YourNamespace']
+   * Called during the `initialize` phase. Return a namespace object to attach to `api[this.name]`.
+   * @returns The namespace object (e.g., `{ actions, enqueue, ... }`) that gets set on `api`.
    */
   async initialize?(): Promise<any>;
 
   /**
-   * Method run as part of the `start` lifecycle of your process.  Usually connects to remote servers or processes.
+   * Called during the `start` phase. Connect to external services, bind ports, start workers.
    */
   async start?(): Promise<any>;
 
   /**
-   * Method run as part of the `initialize` lifecycle of your process.  Usually disconnects from remote servers or processes.
+   * Called during the `stop` phase. Disconnect from services, release resources, stop workers.
    */
   async stop?(): Promise<any>;
 }

package/classes/Logger.ts

@@ -15,11 +15,17 @@ export enum LogLevel {
  * The Logger Class.  I write to stdout or stderr, and can be colorized.
  */
 export class Logger {
+  /** Minimum log level to output. Messages below this level are silently dropped. */
   level: LogLevel;
+  /** Whether to apply ANSI color codes to the output. */
   colorize: boolean;
+  /** Whether to prepend an ISO-8601 timestamp to each log line. */
   includeTimestamps: boolean;
+  /** Indentation spaces used when JSON-stringifying the optional object argument. */
   jSONObjectParsePadding: number;
-  quiet: boolean; // an override to disable all logging (used by CLI)
+  /** When `true`, all logging is suppressed (used by CLI mode). */
+  quiet: boolean;
+  /** The output function — defaults to `console.log`. Override for custom transports. */
   outputStream: typeof console.log;
 
   constructor(config: typeof configLogger) {
@@ -31,6 +37,14 @@ export class Logger {
     this.outputStream = console.log;
   }
 
+  /**
+   * Core logging method. Formats and writes a log line to `outputStream` if the given
+   * level meets the minimum threshold. Optionally includes a timestamp and pretty-printed object.
+   *
+   * @param level - The severity level of this log entry.
+   * @param message - The log message string.
+   * @param object - An optional object to JSON-stringify and append to the log line.
+   */
   log(level: LogLevel, message: string, object?: any) {
     if (this.quiet) return;
 
@@ -82,6 +96,11 @@ export class Logger {
     this.log(LogLevel.debug, message, object);
   }
 
+  /**
+   * Log an info message.
+   * @param message - The message to log.
+   * @param object - The object to log.
+   */
   info(message: string, object?: any) {
     this.log(LogLevel.info, message, object);
   }

package/classes/Server.ts

@@ -1,16 +1,24 @@
+/**
+ * Abstract base class for transport servers (e.g., HTTP, WebSocket).
+ * The generic `T` is the type of the underlying server object (e.g., `Bun.Server`).
+ * Subclasses must implement `initialize()`, `start()`, and `stop()`.
+ */
 export abstract class Server<T> {
   name: string;
 
-  /**A place to store the actually server object you create */
+  /** The underlying server instance created by the subclass (e.g., `Bun.Server`). */
   server?: T;
 
   constructor(name: string) {
     this.name = name;
   }
 
+  /** Set up routes, handlers, and configuration. Called during the framework's initialize phase. */
   abstract initialize(): Promise<void>;
 
+  /** Bind to a port and begin accepting connections. Called during the framework's start phase. */
   abstract start(): Promise<void>;
 
+  /** Close the server and release its port. Called during the framework's stop phase. */
   abstract stop(): Promise<void>;
 }

package/classes/TypedError.ts

@@ -1,3 +1,7 @@
+/**
+ * Categorizes all framework errors. Each type maps to an HTTP status code via `ErrorStatusCodes`.
+ * Actions should always throw `TypedError` with one of these types.
+ */
 export enum ErrorType {
   // general
   "SERVER_INITIALIZATION" = "SERVER_INITIALIZATION",
@@ -27,11 +31,13 @@ export enum ErrorType {
   "CONNECTION_CHANNEL_AUTHORIZATION" = "CONNECTION_CHANNEL_AUTHORIZATION",
   "CONNECTION_CHANNEL_VALIDATION" = "CONNECTION_CHANNEL_VALIDATION",
 
+  "CONNECTION_ACTION_TIMEOUT" = "CONNECTION_ACTION_TIMEOUT",
   "CONNECTION_RATE_LIMITED" = "CONNECTION_RATE_LIMITED",
 
   "CONNECTION_TASK_DEFINITION" = "CONNECTION_TASK_DEFINITION",
 }
 
+/** Maps each `ErrorType` to the HTTP status code returned to the client. */
 export const ErrorStatusCodes: Record<ErrorType, number> = {
   [ErrorType.SERVER_INITIALIZATION]: 500,
   [ErrorType.SERVER_START]: 500,
@@ -56,22 +62,36 @@ export const ErrorStatusCodes: Record<ErrorType, number> = {
   [ErrorType.CONNECTION_NOT_SUBSCRIBED]: 406,
   [ErrorType.CONNECTION_CHANNEL_AUTHORIZATION]: 403,
   [ErrorType.CONNECTION_CHANNEL_VALIDATION]: 400,
+  [ErrorType.CONNECTION_ACTION_TIMEOUT]: 408,
   [ErrorType.CONNECTION_RATE_LIMITED]: 429,
 
   [ErrorType.CONNECTION_TASK_DEFINITION]: 500,
 };
 
 export type TypedErrorArgs = {
+  /** Human-readable error message returned to the client. */
   message: string;
+  /** The error category, which determines the HTTP status code. */
   type: ErrorType;
+  /** The original caught error, if wrapping. Its stack trace is preserved on the `TypedError`. */
   originalError?: unknown;
+  /** The param key that caused the error (for validation errors). */
   key?: string;
+  /** The param value that caused the error (for validation errors). */
   value?: any;
 };
 
+/**
+ * Structured error class for action and framework failures. Extends `Error` with an
+ * `ErrorType` that maps to an HTTP status code, and optional `key`/`value` fields for
+ * param validation errors. If `originalError` is provided, its stack trace is preserved.
+ */
 export class TypedError extends Error {
+  /** The error category, used to determine the HTTP status code via `ErrorStatusCodes`. */
   type: ErrorType;
+  /** The param key that caused the error (for validation errors). */
   key?: string;
+  /** The param value that caused the error (for validation errors). */
   value?: any;
 
   constructor(args: TypedErrorArgs) {

package/config/actions.ts

@@ -0,0 +1,7 @@
+import { loadFromEnvIfSet } from "../util/config";
+
+export const configActions = {
+  timeout: await loadFromEnvIfSet("ACTION_TIMEOUT", 300_000),
+  fanOutBatchSize: await loadFromEnvIfSet("ACTION_FAN_OUT_BATCH_SIZE", 100),
+  fanOutResultTtl: await loadFromEnvIfSet("ACTION_FAN_OUT_RESULT_TTL", 600),
+};

package/config/index.ts

@@ -1,3 +1,4 @@
+import { configActions } from "./actions";
 import { configChannels } from "./channels";
 import { configDatabase } from "./database";
 import { configLogger } from "./logger";
@@ -11,6 +12,7 @@ import { configSession } from "./session";
 import { configTasks } from "./tasks";
 
 export const config = {
+  actions: configActions,
   channels: configChannels,
   process: configProcess,
   logger: configLogger,

package/config/server/web.ts

@@ -70,4 +70,8 @@ export const configServerWeb = {
       "strict-origin-when-cross-origin",
     ),
   } as Record<string, string>,
+  correlationId: {
+    header: await loadFromEnvIfSet("WEB_CORRELATION_ID_HEADER", "X-Request-Id"),
+    trustProxy: await loadFromEnvIfSet("WEB_CORRELATION_ID_TRUST_PROXY", false),
+  },
 };

package/initializers/actionts.ts

@@ -5,37 +5,56 @@ import { api, logger } from "../api";
 import { DEFAULT_QUEUE, type Action } from "../classes/Action";
 import { Initializer } from "../classes/Initializer";
 import { ErrorType, TypedError } from "../classes/TypedError";
+import { config } from "../config";
 import { globLoader } from "../util/glob";
 
 const namespace = "actions";
 
-const DEFAULT_FAN_OUT_BATCH_SIZE = 100;
-const DEFAULT_FAN_OUT_RESULT_TTL = 600; // 10 minutes in seconds
-
+/** A single job descriptor for multi-action fan-out. */
 export type FanOutJob = {
+  /** The action name to enqueue. */
   action: string;
+  /** Inputs to pass to the action. Defaults to `{}`. */
   inputs?: TaskInputs;
+  /** Override the queue for this specific job. Falls back to the action's configured queue. */
   queue?: string;
 };
 
+/** Options for controlling fan-out behavior. */
 export type FanOutOptions = {
+  /** Max jobs to enqueue per Redis batch. Defaults to `config.actions.fanOutBatchSize`. */
   batchSize?: number;
+  /** TTL in seconds for the fan-out metadata and result keys in Redis. Defaults to `config.actions.fanOutResultTtl`. */
   resultTtl?: number;
+  /** Correlation ID to propagate to all child jobs for distributed tracing. Injected as `_correlationId` in each job's inputs. */
+  correlationId?: string;
 };
 
+/** Returned immediately from `fanOut()` with metadata about the enqueue operation. */
 export type FanOutResult = {
+  /** Unique ID for querying status later via `fanOutStatus()`. */
   fanOutId: string;
+  /** The action name(s) that were fanned out. */
   actionName: string | string[];
+  /** The queue(s) jobs were enqueued to. */
   queue: string | string[];
+  /** Number of jobs successfully enqueued. */
   enqueued: number;
+  /** Any enqueue-time failures, with the index of the failed job. */
   errors: Array<{ index: number; error: string }>;
 };
 
+/** Status of a fan-out operation, as returned by `fanOutStatus()`. */
 export type FanOutStatus = {
+  /** Total number of jobs in this fan-out batch. */
   total: number;
+  /** Number of jobs that have completed successfully. */
   completed: number;
+  /** Number of jobs that have failed. */
   failed: number;
+  /** Collected results from completed child jobs. */
   results: Array<{ params: Record<string, any>; result: any }>;
+  /** Collected errors from failed child jobs. */
   errors: Array<{ params: Record<string, any>; error: string }>;
 };
 
@@ -55,7 +74,11 @@ export class Actions extends Initializer {
 
   /**
    * Enqueue an action to be performed in the background.
-   * Will throw an error if redis cannot be reached.
+   *
+   * @param actionName - The name of the action to enqueue.
+   * @param inputs - Inputs to pass to the action. Defaults to `{}`.
+   * @param queue - Which queue to enqueue on. Falls back to the action's configured queue, then `"default"`.
+   * @throws {TypedError} With `ErrorType.CONNECTION_TASK_DEFINITION` if the action is not found.
    */
   enqueue = async (
     actionName: string,
@@ -130,8 +153,10 @@ export class Actions extends Initializer {
       return { ...job, queue: resolvedQueue, inputs: job.inputs ?? {} };
     });
 
-    const batchSize = resolvedOptions.batchSize ?? DEFAULT_FAN_OUT_BATCH_SIZE;
-    const resultTtl = resolvedOptions.resultTtl ?? DEFAULT_FAN_OUT_RESULT_TTL;
+    const batchSize =
+      resolvedOptions.batchSize ?? config.actions.fanOutBatchSize;
+    const resultTtl =
+      resolvedOptions.resultTtl ?? config.actions.fanOutResultTtl;
     const fanOutId = randomUUID();
     const metaKey = `fanout:${fanOutId}`;
 
@@ -166,6 +191,9 @@ export class Actions extends Initializer {
           const enrichedInputs = {
             ...job.inputs,
             _fanOutId: fanOutId,
+            ...(resolvedOptions.correlationId
+              ? { _correlationId: resolvedOptions.correlationId }
+              : {}),
           };
           return this.enqueue(job.action, enrichedInputs, job.queue);
         }),
@@ -224,14 +252,15 @@ export class Actions extends Initializer {
   };
 
   /**
-   * Enqueue a task to be performed in the background, at a certain time in the future.
-   * Will throw an error if redis cannot be reached.
+   * Enqueue an action to run at a specific time in the future.
    *
-   * Inputs:
-   * * actionName: The name of the task.
-   * * inputs: inputs to pass to the task.
-   * * queue: (Optional) Which queue/priority to run this instance of the task on.
-   * * suppressDuplicateTaskError: (optional) Suppress errors when the same task with the same arguments are double-enqueued for the same time
+   * @param timestamp - Epoch timestamp (ms) when the task becomes eligible to run.
+   *   Does not guarantee the task will run at exactly this time.
+   * @param actionName - The name of the action to enqueue.
+   * @param inputs - Inputs to pass to the action.
+   * @param queue - Which queue to enqueue on. Defaults to `"default"`.
+   * @param suppressDuplicateTaskError - If `true`, silently ignore errors when the same
+   *   task with the same arguments is already enqueued for the same time.
    */
   enqueueAt = async (
     timestamp: number,
@@ -250,15 +279,14 @@ export class Actions extends Initializer {
   };
 
   /**
-   * Enqueue a task to be performed in the background, at a certain number of ms from now.
-   * Will throw an error if redis cannot be reached.
+   * Enqueue an action to run after a delay (in milliseconds from now).
    *
-   * Inputs:
-   * * timestamp: At what time the task is able to be run.  Does not guarantee that the task will be run at this time. (in ms)
-   * * actionName: The name of the task.
-   * * inputs: inputs to pass to the task.
-   * * queue: (Optional) Which queue/priority to run this instance of the task on.
-   * * suppressDuplicateTaskError: (optional) Suppress errors when the same task with the same arguments are double-enqueued for the same time
+   * @param time - Delay in milliseconds before the task becomes eligible to run.
+   * @param actionName - The name of the action to enqueue.
+   * @param inputs - Inputs to pass to the action.
+   * @param queue - Which queue to enqueue on. Defaults to `"default"`.
+   * @param suppressDuplicateTaskError - If `true`, silently ignore errors when the same
+   *   task with the same arguments is already enqueued for the same time.
    */
   enqueueIn = async (
     time: number,
@@ -277,14 +305,13 @@ export class Actions extends Initializer {
   };
 
   /**
-   * Delete a previously enqueued task, which hasn't been run yet, from a queue.
-   * Will throw an error if redis cannot be reached.
+   * Delete a previously enqueued task that hasn't been run yet.
    *
-   * Inputs:
-   * * q: Which queue/priority is the task stored on?
-   * * actionName: The name of the job, likely to be the same name as a tak.
-   * * args: The arguments of the job.  Note, arguments passed to a Task initially may be modified when enqueuing.  It is best to read job properties first via `api.tasks.queued` or similar method.
-   * * count: Of the jobs that match q, actionName, and args, up to what position should we delete? (Default 0; this command is 0-indexed)
+   * @param queue - The queue the task is stored on.
+   * @param actionName - The name of the job to delete.
+   * @param args - The arguments of the job to match. Note: arguments may have been modified
+   *   during enqueuing — read job properties via `api.actions.queued` first.
+   * @param count - Up to how many matching jobs to delete (0-indexed). Default: 0.
    */
   del = async (
     queue: string,
@@ -296,15 +323,13 @@ export class Actions extends Initializer {
   };
 
   /**
-   * * will delete all jobs in the given queue of the named function/class
-   * * will not prevent new jobs from being added as this method is running
-   * * will not delete jobs in the delayed queues
+   * Delete all jobs of a given action name from a queue. Does not affect delayed queues,
+   * and will not prevent new jobs from being added while running.
    *
-   * Inputs:
-   * * q: Which queue/priority is to run on?
-   * * actionName: The name of the job, likely to be the same name as a tak.
-   * * start? - starting position of task count to remove
-   * * stop? - stop position of task count to remove
+   * @param queue - The queue to delete from.
+   * @param actionName - The action name whose jobs to remove.
+   * @param start - Starting position (0-indexed) of the range to remove.
+   * @param stop - Stop position (0-indexed) of the range to remove.
    */
   delByFunction = async (
     queue: string,
@@ -316,13 +341,12 @@ export class Actions extends Initializer {
   };
 
   /**
-   * Delete all previously enqueued tasks, which haven't been run yet, from all possible delayed timestamps.
-   * Will throw an error if redis cannot be reached.
+   * Delete all delayed instances of a task across all future timestamps.
    *
-   * Inputs:
-   * * q: Which queue/priority is to run on?
-   * * actionName: The name of the job, likely to be the same name as a tak.
-   * * inputs  The arguments of the job.  Note, arguments passed to a Task initially may be modified when enqueuing. It is best to read job properties first via `api.tasks.delayedAt` or similar method.
+   * @param queue - The queue the task is stored on.
+   * @param actionName - The action name to delete.
+   * @param inputs - The job arguments to match. Arguments may have been modified during
+   *   enqueuing — read properties via `api.actions.delayedAt` first.
    */
   delDelayed = async (
     queue: string,
@@ -333,13 +357,12 @@ export class Actions extends Initializer {
   };
 
   /**
-   * Return the timestamps a task is scheduled for.
-   * Will throw an error if redis cannot be reached.
+   * Return the timestamps at which a task is scheduled to run.
    *
-   * Inputs:
-   * * q: Which queue/priority is to run on?
-   * * actionName: The name of the job, likely to be the same name as a tak.
-   * * inputs: The arguments of the job.  Note, arguments passed to a Task initially may be modified when enqueuing.  It is best to read job properties first via `api.tasks.delayedAt` or similar method.
+   * @param queue - The queue the task is stored on.
+   * @param actionName - The action name to look up.
+   * @param inputs - The job arguments to match.
+   * @returns Array of epoch timestamps (ms) when the job is scheduled.
    */
   scheduledAt = async (
     queue: string,
@@ -358,13 +381,12 @@ export class Actions extends Initializer {
   };
 
   /**
-   * Retrieve the details of jobs enqueued on a certain queue between start and stop (0-indexed)
-   * Will throw an error if redis cannot be reached.
+   * Retrieve details of jobs enqueued on a queue (0-indexed range).
    *
-   * Inputs:
-   * * q      The name of the queue.
-   * * start  The index of the first job to return.
-   * * stop   The index of the last job to return.
+   * @param queue - The queue name. Defaults to `"default"`.
+   * @param start - Starting index. Defaults to 0.
+   * @param stop - Ending index. Defaults to 100.
+   * @returns Array of job input objects.
    */
   queued = (
     queue: string = DEFAULT_QUEUE,
@@ -592,6 +614,10 @@ export class Actions extends Initializer {
     return details;
   };
 
+  /**
+   * Swallow "already enqueued" errors for recurring tasks (expected during multi-process boot).
+   * Re-throws any other error.
+   */
   checkForRepeatRecurringTaskEnqueue = (actionName: string, error: any) => {
     if (error.toString().match(/already enqueued at this time/)) {
       // this is OK, the job was enqueued by another process as this method was running

package/initializers/mcp.ts

@@ -2,7 +2,6 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 import colors from "colors";
 import { randomUUID } from "crypto";
-import { z } from "zod";
 import * as z4mini from "zod/v4-mini";
 import { api, logger } from "../api";
 import { Connection } from "../classes/Connection";
@@ -462,16 +461,16 @@ function sanitizeSchemaForMcp(schema: any): any {
     schema.shape as Record<string, any>,
   )) {
     try {
-      z4mini.toJSONSchema(z.object({ [key]: fieldSchema }), {
+      z4mini.toJSONSchema(z4mini.object({ [key]: fieldSchema }), {
         target: "draft-7",
         io: "input",
       });
       newShape[key] = fieldSchema;
     } catch {
       needsSanitization = true;
-      newShape[key] = z.string().describe(`${key}`);
+      newShape[key] = z4mini.string();
     }
   }
 
-  return needsSanitization ? z.object(newShape) : schema;
+  return needsSanitization ? z4mini.object(newShape) : schema;
 }

package/initializers/pubsub.ts

@@ -38,6 +38,13 @@ export class PubSub extends Initializer {
   }
 
   async initialize() {
+    /**
+     * Publish a message to all subscribers of a channel across the cluster via Redis PubSub.
+     *
+     * @param channel - The application-level channel name.
+     * @param message - The message payload (will be JSON-serialized).
+     * @param sender - Identifier of the sending connection. Defaults to `"unknown-sender"`.
+     */
     async function broadcast(
       channel: string,
       message: any,
@@ -67,6 +74,10 @@ export class PubSub extends Initializer {
     }
   }
 
+  /**
+   * Redis subscription callback. Delivers the incoming PubSub message to all local
+   * connections subscribed to the target channel, and forwards to MCP if enabled.
+   */
   async handleMessage(
     _pubSubChannel: string,
     incomingMessage: string | Buffer,

package/initializers/redis.ts

@@ -14,6 +14,11 @@ declare module "../classes/API" {
   }
 }
 
+/**
+ * Initializer that manages two Redis connections: `redis` for general commands and
+ * `subscription` for PubSub. Both are created during `start()` and closed during `stop()`.
+ * Exposes `api.redis.redis` and `api.redis.subscription` as ioredis `RedisClient` instances.
+ */
 export class Redis extends Initializer {
   constructor() {
     super(namespace);

package/initializers/resque.ts

@@ -27,6 +27,11 @@ declare module "../classes/API" {
 
 let SERVER_JOB_COUNTER = 1;
 
+/**
+ * Initializer for the node-resque background job system. Manages the queue, scheduler,
+ * and worker pool. All actions are automatically registered as resque jobs.
+ * Exposes `api.resque.queue`, `api.resque.scheduler`, and `api.resque.workers`.
+ */
 export class Resque extends Initializer {
   constructor() {
     super(namespace);
@@ -36,6 +41,7 @@ export class Resque extends Initializer {
     this.stopPriority = 900;
   }
 
+  /** Create and connect the resque `Queue` instance (used for enqueuing jobs). */
   startQueue = async () => {
     api.resque.queue = new Queue(
       { connection: { redis: api.redis.redis } },
@@ -49,12 +55,14 @@ export class Resque extends Initializer {
     await api.resque.queue.connect();
   };
 
+  /** Disconnect the resque `Queue`. */
   stopQueue = async () => {
     if (api.resque.queue) {
       return api.resque.queue.end();
     }
   };
 
+  /** Create and start the resque `Scheduler` (leader election, delayed job promotion, stuck worker cleanup). */
   startScheduler = async () => {
     if (config.tasks.enabled === true) {
       api.resque.scheduler = new Scheduler({
@@ -96,12 +104,14 @@ export class Resque extends Initializer {
     }
   };
 
+  /** Stop the resque `Scheduler` and disconnect. */
   stopScheduler = async () => {
     if (api.resque.scheduler && api.resque.scheduler.connection.connected) {
       await api.resque.scheduler.end();
     }
   };
 
+  /** Spin up `config.tasks.taskProcessors` worker instances and connect them to Redis. */
   startWorkers = async () => {
     let id = 0;
 
@@ -177,6 +187,7 @@ export class Resque extends Initializer {
     }
   };
 
+  /** Gracefully stop all workers: signal them to stop polling, drain in-flight operations, then disconnect. */
   stopWorkers = async () => {
     // Signal all workers to stop polling/pinging before closing connections.
     // worker.end() clears timers and closes the Redis connection, but if a
@@ -208,6 +219,11 @@ export class Resque extends Initializer {
     return jobs;
   };
 
+  /**
+   * Wrap an action as a node-resque job. Creates a temporary `Connection` with type `"resque"`,
+   * converts inputs to `FormData`, and runs the action via `connection.act()`. Handles
+   * fan-out result/error collection and recurring task re-enqueue.
+   */
   wrapActionAsJob = (
     action: Action,
   ): Job<Awaited<ReturnType<(typeof action)["run"]>>> => {
@@ -220,6 +236,14 @@ export class Resque extends Initializer {
           "resque",
           `job:${api.process.name}:${SERVER_JOB_COUNTER++}}`,
         );
+
+        const propagatedCorrelationId = params._correlationId as
+          | string
+          | undefined;
+        if (propagatedCorrelationId) {
+          connection.correlationId = propagatedCorrelationId;
+        }
+
         const paramsAsFormData = new FormData();
 
         if (typeof params.entries === "function") {

package/initializers/session.ts

@@ -18,6 +18,12 @@ function getKey(connectionId: Connection["id"]) {
   return `${prefix}:${connectionId}`;
 }
 
+/**
+ * Load a session from Redis by connection ID. Refreshes the TTL on access.
+ *
+ * @param connection - The connection whose session to load.
+ * @returns The parsed session data, or `null` if no session exists.
+ */
 async function load<T extends Record<string, any>>(connection: Connection) {
   const key = getKey(connection.id);
   const data = await api.redis.redis.get(key);
@@ -26,6 +32,13 @@ async function load<T extends Record<string, any>>(connection: Connection) {
   return JSON.parse(data) as SessionData<T>;
 }
 
+/**
+ * Create a new session in Redis for the given connection.
+ *
+ * @param connection - The connection to create a session for.
+ * @param data - Initial session data. Defaults to `{}`.
+ * @returns The newly created `SessionData` object.
+ */
 async function create<T extends Record<string, any>>(
   connection: Connection,
   data = {} as T,
@@ -44,6 +57,13 @@ async function create<T extends Record<string, any>>(
   return sessionData;
 }
 
+/**
+ * Merge new data into an existing session and persist to Redis. Refreshes the TTL.
+ *
+ * @param session - The existing session object to update.
+ * @param data - Partial data to shallow-merge into `session.data`.
+ * @returns The updated `session.data`.
+ */
 async function update<T extends Record<string, any>>(
   session: SessionData<T>,
   data: Record<string, any>,
@@ -55,6 +75,12 @@ async function update<T extends Record<string, any>>(
   return session.data;
 }
 
+/**
+ * Delete a session from Redis.
+ *
+ * @param connection - The connection whose session to destroy.
+ * @returns `true` if a session was deleted, `false` if none existed.
+ */
 async function destroy(connection: Connection) {
   const key = getKey(connection.id);
   const response = await api.redis.redis.del(key);

package/middleware/rateLimit.ts

@@ -4,23 +4,37 @@ import type { Connection } from "../classes/Connection";
 import { ErrorType, TypedError } from "../classes/TypedError";
 import { config } from "../config";
 
+/** Rate-limit metadata attached to `connection.rateLimitInfo` and used to set response headers. */
 export type RateLimitInfo = {
+  /** The max number of requests allowed in the current window. */
   limit: number;
+  /** Requests remaining before the limit is hit. */
   remaining: number;
-  resetAt: number; // unix timestamp in seconds
-  retryAfter?: number; // seconds until window resets (only when limited)
+  /** Unix timestamp (seconds) when the current window resets. */
+  resetAt: number;
+  /** Seconds until the window resets. Only present when the limit has been exceeded. */
+  retryAfter?: number;
 };
 
+/** Optional overrides for `checkRateLimit()` to use a custom limit/window instead of the global config. */
 export type RateLimitOverrides = {
+  /** Max requests per window. Defaults to the authenticated or unauthenticated config limit. */
   limit?: number;
+  /** Window duration in milliseconds. Defaults to `config.rateLimit.windowMs`. */
   windowMs?: number;
+  /** Redis key prefix. Defaults to `config.rateLimit.keyPrefix`. */
   keyPrefix?: string;
 };
 
 /**
- * Sliding window rate-limit check using Redis.
- * Exported so OAuth and other non-action handlers can reuse it.
- * Pass `overrides` to use a custom limit/window instead of the global config.
+ * Sliding-window rate-limit check using Redis. Exported so OAuth and other
+ * non-action handlers can reuse it.
+ *
+ * @param identifier - A unique key for the client (e.g., `"ip:1.2.3.4"` or `"user:42"`).
+ * @param isAuthenticated - Whether the caller is authenticated. Determines which
+ *   config limit to use (authenticated vs unauthenticated).
+ * @param overrides - Optional overrides for limit, window duration, or key prefix.
+ * @returns Rate-limit metadata including remaining requests and retry-after (if limited).
  */
 export async function checkRateLimit(
   identifier: string,
@@ -68,6 +82,10 @@ export async function checkRateLimit(
   return { limit, remaining, resetAt };
 }
 
+/**
+ * Action middleware that enforces per-connection rate limiting. Add to an action's
+ * `middleware` array to apply. Throws `ErrorType.CONNECTION_RATE_LIMITED` when exceeded.
+ */
 export const RateLimitMiddleware: ActionMiddleware = {
   runBefore: async (_params, connection: Connection) => {
     if (!config.rateLimit.enabled) return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keryx",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "module": "index.ts",
   "type": "module",
   "license": "MIT",

package/servers/web.ts

@@ -27,6 +27,11 @@ function validateChannelName(channel: string) {
   }
 }
 
+/**
+ * HTTP + WebSocket server built on `Bun.serve`. Handles REST action routing (with path params),
+ * static file serving (with ETag/304 caching), WebSocket connections (actions, PubSub subscribe/unsubscribe),
+ * OAuth endpoints, and MCP SSE streams. Exposes `api.servers.web`.
+ */
 export class WebServer extends Server<ReturnType<typeof Bun.serve>> {
   /** The actual port the server bound to (resolved after start, e.g. when config port is 0). */
   port: number = 0;
@@ -77,6 +82,10 @@ export class WebServer extends Server<ReturnType<typeof Bun.serve>> {
     }
   }
 
+  /**
+   * Main request handler passed to `Bun.serve({ fetch })`. Dispatches to WebSocket upgrade,
+   * static files, OAuth, MCP, or REST action handling in that order.
+   */
   async handleIncomingConnection(
     req: Request,
     server: ReturnType<typeof Bun.serve>,
@@ -129,6 +138,7 @@ export class WebServer extends Server<ReturnType<typeof Bun.serve>> {
     return this.handleWebAction(req, parsedUrl, ip, id);
   }
 
+  /** Called when a new WebSocket connection opens. Creates a `Connection` and wires up broadcast delivery. */
   handleWebSocketConnectionOpen(ws: ServerWebSocket) {
     //@ts-expect-error (ws.data is not defined in the bun types)
     const connection = new Connection("websocket", ws.data.ip, ws.data.id, ws);
@@ -140,6 +150,10 @@ export class WebServer extends Server<ReturnType<typeof Bun.serve>> {
     );
   }
 
+  /**
+   * Called when a WebSocket message arrives. Parses JSON, enforces per-connection rate limiting,
+   * and dispatches to action, subscribe, or unsubscribe handlers based on `messageType`.
+   */
   async handleWebSocketConnectionMessage(
     ws: ServerWebSocket,
     message: string | Buffer,
@@ -212,6 +226,7 @@ export class WebServer extends Server<ReturnType<typeof Bun.serve>> {
     }
   }
 
+  /** Called when a WebSocket connection closes. Removes presence from all channels and destroys the connection. */
   async handleWebSocketConnectionClose(ws: ServerWebSocket) {
     const { connection } = api.connections.find(
       "websocket",
@@ -399,6 +414,17 @@ export class WebServer extends Server<ReturnType<typeof Bun.serve>> {
     const httpMethod = req.method?.toUpperCase() as HTTP_METHOD;
 
     const connection = new Connection("web", ip, id);
+
+    if (
+      config.server.web.correlationId.header &&
+      config.server.web.correlationId.trustProxy
+    ) {
+      const incomingId = req.headers.get(
+        config.server.web.correlationId.header,
+      );
+      if (incomingId) connection.correlationId = incomingId;
+    }
+
     const requestOrigin = req.headers.get("origin") ?? undefined;
 
     // Handle OPTIONS requests.
@@ -720,6 +746,11 @@ const buildHeaders = (connection?: Connection, requestOrigin?: string) => {
         headers["Retry-After"] = String(rateLimitInfo.retryAfter);
       }
     }
+
+    if (config.server.web.correlationId.header && connection.correlationId) {
+      headers[config.server.web.correlationId.header] =
+        connection.correlationId;
+    }
   }
 
   return headers;

package/util/connectionString.ts

@@ -1,3 +1,4 @@
+/** Strip the password from a connection string for safe logging. Preserves protocol, user, host, port, and path. */
 export function formatConnectionStringForLogging(connectionString: string) {
   const connectionStringParsed = new URL(connectionString);
   const connectionStringInfo = `${connectionStringParsed.protocol ? `${connectionStringParsed.protocol}//` : ""}${connectionStringParsed.username ? `${connectionStringParsed.username}@` : ""}${connectionStringParsed.hostname}:${connectionStringParsed.port}${connectionStringParsed.pathname}`;

package/util/glob.ts

@@ -4,8 +4,12 @@ import { api } from "../api";
 import { ErrorType, TypedError } from "../classes/TypedError";
 
 /**
+ * Auto-discover and instantiate all exported classes from `.ts`/`.tsx` files in a directory.
+ * Files prefixed with `.` are skipped. Used to load actions, initializers, and servers.
  *
- * @param searchDir Absolute path or relative path (resolved from api.rootDir) to search for files
+ * @param searchDir - Absolute path or relative path (resolved from `api.rootDir`) to scan.
+ * @returns Array of instantiated class instances of type `T`.
+ * @throws {TypedError} With `ErrorType.SERVER_INITIALIZATION` if any class fails to instantiate.
  */
 export async function globLoader<T>(searchDir: string) {
   const results: T[] = [];

package/util/oauth.ts

@@ -1,3 +1,10 @@
+/**
+ * Validate an OAuth redirect URI per RFC 6749 / OAuth 2.1 rules:
+ * no fragments, no userinfo, and HTTPS required for non-localhost URIs.
+ *
+ * @param uri - The redirect URI to validate.
+ * @returns `{ valid: true }` or `{ valid: false, error: string }`.
+ */
 export function validateRedirectUri(uri: string): {
   valid: boolean;
   error?: string;
@@ -32,6 +39,10 @@ export function validateRedirectUri(uri: string): {
   return { valid: true };
 }
 
+/**
+ * Compare two redirect URIs by origin and pathname (ignoring query params).
+ * Returns `false` if either URI is malformed.
+ */
 export function redirectUrisMatch(
   registeredUri: string,
   requestedUri: string,
@@ -48,6 +59,7 @@ export function redirectUrisMatch(
   }
 }
 
+/** Encode a byte array as a URL-safe base64 string (no padding). Used for PKCE code challenges. */
 export function base64UrlEncode(buffer: Uint8Array): string {
   let binary = "";
   for (const byte of buffer) {
@@ -59,6 +71,7 @@ export function base64UrlEncode(buffer: Uint8Array): string {
     .replace(/=+$/, "");
 }
 
+/** Escape a string for safe inclusion in HTML output (prevents XSS). */
 export function escapeHtml(str: string): string {
   return str
     .replace(/&/g, "&")

package/util/zodMixins.ts

@@ -1,11 +1,11 @@
 import { eq } from "drizzle-orm";
-import { z } from "zod";
+import { z } from "zod/v4";
 import { api } from "../api";
 import { ErrorType, TypedError } from "../classes/TypedError";
 
 // Zod v4: Extend GlobalMeta to support custom 'isSecret' metadata
 // This allows using .meta({ isSecret: true }) on any zod schema
-declare module "zod" {
+declare module "zod/v4" {
   interface GlobalMeta {
     isSecret?: boolean;
   }