defuss-express 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,289 @@
+import ultimateExpress from 'ultimate-express';
+import { Socket } from 'node:net';
+import { TelemetrySink } from 'defuss-open-telemetry';
+
+declare const express: typeof ultimateExpress;
+
+/**
+ * Duck-typed Express-compatible application.
+ *
+ * Accepts any object whose `.listen()` method binds to a port.
+ * HTTP verb helpers (`get`, `post`, …) are optional so that
+ * lightweight frameworks like `ultimate-express` satisfy the contract.
+ */
+type ExpressLike = {
+    listen: (...args: any[]) => any;
+    disable?: (name: string) => void;
+    use?: (...args: any[]) => any;
+    get?: (...args: any[]) => any;
+    post?: (...args: any[]) => any;
+    put?: (...args: any[]) => any;
+    patch?: (...args: any[]) => any;
+    delete?: (...args: any[]) => any;
+    options?: (...args: any[]) => any;
+    head?: (...args: any[]) => any;
+    all?: (...args: any[]) => any;
+} & Record<string, unknown>;
+/** Minimal structured logger accepted by defuss-express. */
+type LoggerLike = {
+    debug: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+};
+/**
+ * Result of parsing the HTTP/1.x request-line and headers from a
+ * raw TCP buffer.  Produced by {@link parseRequestHead} and fed to
+ * load-balancer functions for request-aware routing decisions.
+ */
+type ParsedRequest = {
+    /** HTTP method (`GET`, `POST`, …) – `undefined` if the buffer was unparseable. */
+    method?: string;
+    /** Request path including query string. */
+    path?: string;
+    /** HTTP version string, e.g. `"1.1"`. */
+    httpVersion?: string;
+    /** Value of the `Host` header, if present. */
+    host?: string;
+    /** Lowercase header name → trimmed value map. */
+    headers: Record<string, string>;
+    /** Remote IP of the connecting client. */
+    remoteAddress?: string;
+    /** Remote port of the connecting client. */
+    remotePort?: number;
+    /** `"http1"` when the request-line was successfully parsed, otherwise `"unknown"`. */
+    protocol: "http1" | "unknown";
+    /** The raw header bytes decoded as `latin1`. */
+    rawHead: string;
+};
+/**
+ * Point-in-time resource snapshot reported by a worker process via
+ * IPC heartbeat messages.  Used by the resource-aware load balancer
+ * to steer traffic away from saturated workers.
+ */
+type WorkerRuntimeStats = {
+    /** OS-level process id. */
+    pid: number;
+    /** Sampled CPU usage as a percentage of one core (0–100+). */
+    cpuPercent: number;
+    /** Resident set size in bytes. */
+    rssBytes: number;
+    /** V8 heap used in bytes. */
+    heapUsedBytes: number;
+    /** V8 total heap in bytes. */
+    heapTotalBytes: number;
+    /** V8 external memory in bytes. */
+    externalBytes: number;
+    /** V8 ArrayBuffer memory in bytes. */
+    arrayBuffersBytes: number;
+    /** Process uptime in milliseconds. */
+    uptimeMs: number;
+    /** Number of currently tracked application-level connections. */
+    activeConnections: number;
+    /** `Date.now()` when the snapshot was taken. */
+    sampledAt: number;
+};
+/**
+ * Describes a single worker backend as seen by the primary-process
+ * load balancer.
+ */
+type BackendCandidate = {
+    /** Stable identifier, e.g. `"worker-0"`. */
+    id: string;
+    /** Zero-based index in the worker pool. */
+    workerIndex: number;
+    /** Hostname/IP the worker listens on. */
+    host: string;
+    /** TCP port the worker listens on. */
+    port: number;
+    /** OS pid of the worker process, set once the worker reports in. */
+    pid?: number;
+    /** `true` when the worker is considered able to serve traffic. */
+    healthy: boolean;
+    /** `true` after the worker has sent its `"defuss:worker-ready"` message. */
+    ready: boolean;
+    /** `Date.now()` of the last heartbeat received from this worker. */
+    lastHeartbeatAt?: number;
+    /** Number of TCP proxy connections the primary is currently forwarding to this worker. */
+    activeProxyConnections: number;
+    /** Most recent resource snapshot from the worker. */
+    stats?: WorkerRuntimeStats;
+};
+/**
+ * Context object passed to a {@link LoadBalancerFunction} on every
+ * inbound connection so it can make a routing decision.
+ */
+type LoadBalancerContext = {
+    /** Healthy, ready backend candidates to choose from. */
+    candidates: BackendCandidate[];
+    /** Parsed HTTP request head (method, path, host, headers). */
+    request: ParsedRequest;
+    /** Raw client TCP socket (for advanced inspection). */
+    socket: Socket;
+    /** Monotonically incrementing counter for round-robin tracking. */
+    previousIndex: number;
+};
+/**
+ * Signature for a pluggable load-balancer strategy.
+ *
+ * Receives a {@link LoadBalancerContext} and must return (or resolve)
+ * the {@link BackendCandidate} that should receive the connection.
+ */
+type LoadBalancerFunction = (context: LoadBalancerContext) => BackendCandidate | Promise<BackendCandidate>;
+/**
+ * User-facing configuration object passed to {@link startServer} or
+ * {@link setServerConfig}.  Every field is optional; omitted values
+ * fall back to sensible defaults (see {@link ResolvedServerConfig}).
+ */
+type ServerConfigInput = {
+    /** Bind address for the public-facing load balancer (default `"0.0.0.0"`). */
+    host?: string;
+    /** Public-facing TCP port (default `3000`). */
+    port?: number;
+    /** Bind address for per-worker listeners (default `"127.0.0.1"`). */
+    workerHost?: string;
+    /** First port in the worker port range (default `3001`). */
+    baseWorkerPort?: number;
+    /** Number of worker processes, or `"auto"` for one per available core. */
+    workers?: number | "auto";
+    /** Max time (ms) the load balancer waits for a request head before blind-forwarding (default `10`). */
+    requestInspectionTimeoutMs?: number;
+    /** Max bytes buffered while sniffing the request head (default `16384`). */
+    maxHeaderBytes?: number;
+    /** Enable TCP half-open on proxy sockets (default `true`). */
+    allowHalfOpen?: boolean;
+    /** Interval (ms) at which workers send heartbeat stats (default `60000`). */
+    workerHeartbeatIntervalMs?: number;
+    /** A worker is considered stale after this many ms without a heartbeat (default `150000`). */
+    workerHeartbeatStaleAfterMs?: number;
+    /** Max time (ms) to wait for graceful shutdown before force-killing (default `10000`). */
+    gracefulShutdownTimeoutMs?: number;
+    /** Re-fork workers that exit unexpectedly (default `true`). */
+    respawnWorkers?: boolean;
+    /** Custom load-balancer function. */
+    loadBalancer?: LoadBalancerFunction;
+    /** Structured logger override (defaults to `console`). */
+    logger?: Partial<LoggerLike>;
+    /** Extra environment variables forwarded to forked workers. */
+    workerEnv?: Record<string, string>;
+    /** Install `SIGINT`/`SIGTERM` handlers automatically (default `true`). */
+    installSignalHandlers?: boolean;
+    /**
+     * Optional telemetry sink for emitting counters, histograms, and
+     * gauges.  Defaults to a silent no-op when omitted.
+     *
+     * @example
+     * ```ts
+     * import { createOpenTelemetrySink, OtelMeterAdapter } from "defuss-open-telemetry";
+     * import { metrics } from "@opentelemetry/api";
+     *
+     * setServerConfig({
+     *   telemetry: createOpenTelemetrySink({
+     *     meter: new OtelMeterAdapter(metrics.getMeter("my-app")),
+     *     prefix: "defuss.express.",
+     *   }),
+     * });
+     * ```
+     */
+    telemetry?: TelemetrySink;
+};
+/**
+ * Fully resolved server configuration with all defaults applied.
+ * Produced by {@link resolveServerConfig}.
+ */
+type ResolvedServerConfig = {
+    host: string;
+    port: number;
+    workerHost: string;
+    baseWorkerPort: number;
+    workers: number;
+    requestInspectionTimeoutMs: number;
+    maxHeaderBytes: number;
+    allowHalfOpen: boolean;
+    workerHeartbeatIntervalMs: number;
+    workerHeartbeatStaleAfterMs: number;
+    gracefulShutdownTimeoutMs: number;
+    respawnWorkers: boolean;
+    loadBalancer?: LoadBalancerFunction;
+    logger: LoggerLike;
+    workerEnv: Record<string, string>;
+    installSignalHandlers: boolean;
+    /** Active telemetry sink (defaults to {@link noopTelemetrySink}). */
+    telemetry: TelemetrySink;
+};
+/** Value returned by {@link startServer} describing the running process. */
+type StartServerResult = {
+    /** Whether this process is the `"primary"` load balancer or a `"worker"`. */
+    mode: "primary" | "worker";
+    /** OS-level process id. */
+    pid: number;
+    /** Host the process is listening on. */
+    host: string;
+    /** Port the process is listening on. */
+    port: number;
+    /** Worker index (only set in worker mode). */
+    workerIndex?: number;
+    /** Worker port (only set in worker mode). */
+    workerPort?: number;
+    /** Total number of workers (only set in primary mode). */
+    workers?: number;
+};
+
+/**
+ * Apply partial configuration and store it as the current config.
+ * Returns the fully resolved result.
+ */
+declare const setServerConfig: (next: ServerConfigInput) => ResolvedServerConfig;
+/** Return the current resolved server configuration. */
+declare const getServerConfig: () => ResolvedServerConfig;
+
+/**
+ * Cycle through candidates sequentially.  `previousIndex` is
+ * incremented per connection so each worker gets an equal share.
+ */
+declare const roundRobinLoadBalancer: LoadBalancerFunction;
+/**
+ * Pick the candidate with the fewest active proxy connections.
+ * Useful under heterogeneous request durations.
+ */
+declare const leastConnectionsLoadBalancer: LoadBalancerFunction;
+/**
+ * Composite scoring balancer that accounts for active connections,
+ * CPU pressure, and heap utilisation.  Formula:
+ *
+ * ```
+ * score = connections × 10 + cpuPercent × 2 + (heapUsed / heapTotal) × 100
+ * ```
+ *
+ * The candidate with the **lowest** score wins.
+ */
+declare const resourceAwareLoadBalancer: LoadBalancerFunction;
+/** Default balancer — currently {@link roundRobinLoadBalancer}. */
+declare const defaultLoadBalancer: LoadBalancerFunction;
+
+/**
+ * Start the defuss-express server.
+ *
+ * In the **primary** process this forks worker children, waits for at
+ * least one to become ready, and opens a TCP load-balancer on the
+ * configured public port.
+ *
+ * In a **worker** process this binds the Express-like app to its
+ * assigned worker port and begins IPC heartbeat reporting.
+ *
+ * @param app        - An Express-compatible application instance.
+ * @param nextConfig - Optional partial config (merged with defaults).
+ * @returns Metadata about the started process.
+ */
+declare const startServer: (app: ExpressLike, nextConfig?: ServerConfigInput) => Promise<StartServerResult>;
+/**
+ * Stop the defuss-express server gracefully.
+ *
+ * In the primary process this closes the listening socket, sends
+ * `SIGTERM` to all workers, and waits for shutdown.  In a worker it
+ * destroys active connections and closes the app server.
+ */
+declare const stopServer: () => Promise<void>;
+
+export { express as default, defaultLoadBalancer, express, express as expressDefault, getServerConfig, leastConnectionsLoadBalancer, resourceAwareLoadBalancer, roundRobinLoadBalancer, setServerConfig, startServer, stopServer };
+export type { BackendCandidate, ExpressLike, LoadBalancerContext, LoadBalancerFunction, ParsedRequest, ResolvedServerConfig, ServerConfigInput, StartServerResult, WorkerRuntimeStats };

package/dist/index.d.mts

@@ -0,0 +1,289 @@
+import ultimateExpress from 'ultimate-express';
+import { Socket } from 'node:net';
+import { TelemetrySink } from 'defuss-open-telemetry';
+
+declare const express: typeof ultimateExpress;
+
+/**
+ * Duck-typed Express-compatible application.
+ *
+ * Accepts any object whose `.listen()` method binds to a port.
+ * HTTP verb helpers (`get`, `post`, …) are optional so that
+ * lightweight frameworks like `ultimate-express` satisfy the contract.
+ */
+type ExpressLike = {
+    listen: (...args: any[]) => any;
+    disable?: (name: string) => void;
+    use?: (...args: any[]) => any;
+    get?: (...args: any[]) => any;
+    post?: (...args: any[]) => any;
+    put?: (...args: any[]) => any;
+    patch?: (...args: any[]) => any;
+    delete?: (...args: any[]) => any;
+    options?: (...args: any[]) => any;
+    head?: (...args: any[]) => any;
+    all?: (...args: any[]) => any;
+} & Record<string, unknown>;
+/** Minimal structured logger accepted by defuss-express. */
+type LoggerLike = {
+    debug: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+};
+/**
+ * Result of parsing the HTTP/1.x request-line and headers from a
+ * raw TCP buffer.  Produced by {@link parseRequestHead} and fed to
+ * load-balancer functions for request-aware routing decisions.
+ */
+type ParsedRequest = {
+    /** HTTP method (`GET`, `POST`, …) – `undefined` if the buffer was unparseable. */
+    method?: string;
+    /** Request path including query string. */
+    path?: string;
+    /** HTTP version string, e.g. `"1.1"`. */
+    httpVersion?: string;
+    /** Value of the `Host` header, if present. */
+    host?: string;
+    /** Lowercase header name → trimmed value map. */
+    headers: Record<string, string>;
+    /** Remote IP of the connecting client. */
+    remoteAddress?: string;
+    /** Remote port of the connecting client. */
+    remotePort?: number;
+    /** `"http1"` when the request-line was successfully parsed, otherwise `"unknown"`. */
+    protocol: "http1" | "unknown";
+    /** The raw header bytes decoded as `latin1`. */
+    rawHead: string;
+};
+/**
+ * Point-in-time resource snapshot reported by a worker process via
+ * IPC heartbeat messages.  Used by the resource-aware load balancer
+ * to steer traffic away from saturated workers.
+ */
+type WorkerRuntimeStats = {
+    /** OS-level process id. */
+    pid: number;
+    /** Sampled CPU usage as a percentage of one core (0–100+). */
+    cpuPercent: number;
+    /** Resident set size in bytes. */
+    rssBytes: number;
+    /** V8 heap used in bytes. */
+    heapUsedBytes: number;
+    /** V8 total heap in bytes. */
+    heapTotalBytes: number;
+    /** V8 external memory in bytes. */
+    externalBytes: number;
+    /** V8 ArrayBuffer memory in bytes. */
+    arrayBuffersBytes: number;
+    /** Process uptime in milliseconds. */
+    uptimeMs: number;
+    /** Number of currently tracked application-level connections. */
+    activeConnections: number;
+    /** `Date.now()` when the snapshot was taken. */
+    sampledAt: number;
+};
+/**
+ * Describes a single worker backend as seen by the primary-process
+ * load balancer.
+ */
+type BackendCandidate = {
+    /** Stable identifier, e.g. `"worker-0"`. */
+    id: string;
+    /** Zero-based index in the worker pool. */
+    workerIndex: number;
+    /** Hostname/IP the worker listens on. */
+    host: string;
+    /** TCP port the worker listens on. */
+    port: number;
+    /** OS pid of the worker process, set once the worker reports in. */
+    pid?: number;
+    /** `true` when the worker is considered able to serve traffic. */
+    healthy: boolean;
+    /** `true` after the worker has sent its `"defuss:worker-ready"` message. */
+    ready: boolean;
+    /** `Date.now()` of the last heartbeat received from this worker. */
+    lastHeartbeatAt?: number;
+    /** Number of TCP proxy connections the primary is currently forwarding to this worker. */
+    activeProxyConnections: number;
+    /** Most recent resource snapshot from the worker. */
+    stats?: WorkerRuntimeStats;
+};
+/**
+ * Context object passed to a {@link LoadBalancerFunction} on every
+ * inbound connection so it can make a routing decision.
+ */
+type LoadBalancerContext = {
+    /** Healthy, ready backend candidates to choose from. */
+    candidates: BackendCandidate[];
+    /** Parsed HTTP request head (method, path, host, headers). */
+    request: ParsedRequest;
+    /** Raw client TCP socket (for advanced inspection). */
+    socket: Socket;
+    /** Monotonically incrementing counter for round-robin tracking. */
+    previousIndex: number;
+};
+/**
+ * Signature for a pluggable load-balancer strategy.
+ *
+ * Receives a {@link LoadBalancerContext} and must return (or resolve)
+ * the {@link BackendCandidate} that should receive the connection.
+ */
+type LoadBalancerFunction = (context: LoadBalancerContext) => BackendCandidate | Promise<BackendCandidate>;
+/**
+ * User-facing configuration object passed to {@link startServer} or
+ * {@link setServerConfig}.  Every field is optional; omitted values
+ * fall back to sensible defaults (see {@link ResolvedServerConfig}).
+ */
+type ServerConfigInput = {
+    /** Bind address for the public-facing load balancer (default `"0.0.0.0"`). */
+    host?: string;
+    /** Public-facing TCP port (default `3000`). */
+    port?: number;
+    /** Bind address for per-worker listeners (default `"127.0.0.1"`). */
+    workerHost?: string;
+    /** First port in the worker port range (default `3001`). */
+    baseWorkerPort?: number;
+    /** Number of worker processes, or `"auto"` for one per available core. */
+    workers?: number | "auto";
+    /** Max time (ms) the load balancer waits for a request head before blind-forwarding (default `10`). */
+    requestInspectionTimeoutMs?: number;
+    /** Max bytes buffered while sniffing the request head (default `16384`). */
+    maxHeaderBytes?: number;
+    /** Enable TCP half-open on proxy sockets (default `true`). */
+    allowHalfOpen?: boolean;
+    /** Interval (ms) at which workers send heartbeat stats (default `60000`). */
+    workerHeartbeatIntervalMs?: number;
+    /** A worker is considered stale after this many ms without a heartbeat (default `150000`). */
+    workerHeartbeatStaleAfterMs?: number;
+    /** Max time (ms) to wait for graceful shutdown before force-killing (default `10000`). */
+    gracefulShutdownTimeoutMs?: number;
+    /** Re-fork workers that exit unexpectedly (default `true`). */
+    respawnWorkers?: boolean;
+    /** Custom load-balancer function. */
+    loadBalancer?: LoadBalancerFunction;
+    /** Structured logger override (defaults to `console`). */
+    logger?: Partial<LoggerLike>;
+    /** Extra environment variables forwarded to forked workers. */
+    workerEnv?: Record<string, string>;
+    /** Install `SIGINT`/`SIGTERM` handlers automatically (default `true`). */
+    installSignalHandlers?: boolean;
+    /**
+     * Optional telemetry sink for emitting counters, histograms, and
+     * gauges.  Defaults to a silent no-op when omitted.
+     *
+     * @example
+     * ```ts
+     * import { createOpenTelemetrySink, OtelMeterAdapter } from "defuss-open-telemetry";
+     * import { metrics } from "@opentelemetry/api";
+     *
+     * setServerConfig({
+     *   telemetry: createOpenTelemetrySink({
+     *     meter: new OtelMeterAdapter(metrics.getMeter("my-app")),
+     *     prefix: "defuss.express.",
+     *   }),
+     * });
+     * ```
+     */
+    telemetry?: TelemetrySink;
+};
+/**
+ * Fully resolved server configuration with all defaults applied.
+ * Produced by {@link resolveServerConfig}.
+ */
+type ResolvedServerConfig = {
+    host: string;
+    port: number;
+    workerHost: string;
+    baseWorkerPort: number;
+    workers: number;
+    requestInspectionTimeoutMs: number;
+    maxHeaderBytes: number;
+    allowHalfOpen: boolean;
+    workerHeartbeatIntervalMs: number;
+    workerHeartbeatStaleAfterMs: number;
+    gracefulShutdownTimeoutMs: number;
+    respawnWorkers: boolean;
+    loadBalancer?: LoadBalancerFunction;
+    logger: LoggerLike;
+    workerEnv: Record<string, string>;
+    installSignalHandlers: boolean;
+    /** Active telemetry sink (defaults to {@link noopTelemetrySink}). */
+    telemetry: TelemetrySink;
+};
+/** Value returned by {@link startServer} describing the running process. */
+type StartServerResult = {
+    /** Whether this process is the `"primary"` load balancer or a `"worker"`. */
+    mode: "primary" | "worker";
+    /** OS-level process id. */
+    pid: number;
+    /** Host the process is listening on. */
+    host: string;
+    /** Port the process is listening on. */
+    port: number;
+    /** Worker index (only set in worker mode). */
+    workerIndex?: number;
+    /** Worker port (only set in worker mode). */
+    workerPort?: number;
+    /** Total number of workers (only set in primary mode). */
+    workers?: number;
+};
+
+/**
+ * Apply partial configuration and store it as the current config.
+ * Returns the fully resolved result.
+ */
+declare const setServerConfig: (next: ServerConfigInput) => ResolvedServerConfig;
+/** Return the current resolved server configuration. */
+declare const getServerConfig: () => ResolvedServerConfig;
+
+/**
+ * Cycle through candidates sequentially.  `previousIndex` is
+ * incremented per connection so each worker gets an equal share.
+ */
+declare const roundRobinLoadBalancer: LoadBalancerFunction;
+/**
+ * Pick the candidate with the fewest active proxy connections.
+ * Useful under heterogeneous request durations.
+ */
+declare const leastConnectionsLoadBalancer: LoadBalancerFunction;
+/**
+ * Composite scoring balancer that accounts for active connections,
+ * CPU pressure, and heap utilisation.  Formula:
+ *
+ * ```
+ * score = connections × 10 + cpuPercent × 2 + (heapUsed / heapTotal) × 100
+ * ```
+ *
+ * The candidate with the **lowest** score wins.
+ */
+declare const resourceAwareLoadBalancer: LoadBalancerFunction;
+/** Default balancer — currently {@link roundRobinLoadBalancer}. */
+declare const defaultLoadBalancer: LoadBalancerFunction;
+
+/**
+ * Start the defuss-express server.
+ *
+ * In the **primary** process this forks worker children, waits for at
+ * least one to become ready, and opens a TCP load-balancer on the
+ * configured public port.
+ *
+ * In a **worker** process this binds the Express-like app to its
+ * assigned worker port and begins IPC heartbeat reporting.
+ *
+ * @param app        - An Express-compatible application instance.
+ * @param nextConfig - Optional partial config (merged with defaults).
+ * @returns Metadata about the started process.
+ */
+declare const startServer: (app: ExpressLike, nextConfig?: ServerConfigInput) => Promise<StartServerResult>;
+/**
+ * Stop the defuss-express server gracefully.
+ *
+ * In the primary process this closes the listening socket, sends
+ * `SIGTERM` to all workers, and waits for shutdown.  In a worker it
+ * destroys active connections and closes the app server.
+ */
+declare const stopServer: () => Promise<void>;
+
+export { express as default, defaultLoadBalancer, express, express as expressDefault, getServerConfig, leastConnectionsLoadBalancer, resourceAwareLoadBalancer, roundRobinLoadBalancer, setServerConfig, startServer, stopServer };
+export type { BackendCandidate, ExpressLike, LoadBalancerContext, LoadBalancerFunction, ParsedRequest, ResolvedServerConfig, ServerConfigInput, StartServerResult, WorkerRuntimeStats };