@luckystack/server 0.10.1 → 0.11.0

package/dist/loadSocket.d.ts

@@ -0,0 +1,21 @@
+import type { Server as HttpServer } from 'node:http';
+import type { Redis as RedisClient } from 'ioredis';
+import { Server as SocketIOServer } from 'socket.io';
+export interface LoadSocketOptions {
+    maxHttpBufferSize?: number;
+}
+export interface LoadSocketResult {
+    io: SocketIOServer;
+    /**
+     * The duplicated Redis pub/sub clients backing the Socket.io adapter. The
+     * server bootstrap owns them so graceful shutdown can `quit()` them — they are
+     * NOT closed by `io.close()` (which only tears down the engine + connections).
+     * Created here (instead of letting `attachSocketRedisAdapter` duplicate
+     * internally) precisely so the server holds a handle to disconnect them.
+     */
+    adapterClients: {
+        pubClient: RedisClient;
+        subClient: RedisClient;
+    };
+}
+export declare const loadSocket: (httpServer: HttpServer, options?: LoadSocketOptions) => LoadSocketResult;

package/dist/logSanitize.d.ts

@@ -0,0 +1 @@
+export declare const sanitizeForLog: (value: unknown) => unknown;

package/dist/originExemptRegistry.d.ts

@@ -0,0 +1,13 @@
+export interface OriginExemptMatcher {
+    /**
+     * A route is exempt when its path equals this prefix OR continues past it on a
+     * path-SEGMENT boundary (i.e. `<prefix>/...`). Matching is boundary-aware so a
+     * prefix can't bleed into a sibling route — `/webhooks` exempts `/webhooks` and
+     * `/webhooks/stripe` but NOT `/webhooksadmin`.
+     */
+    pathPrefix: string;
+}
+export declare const registerOriginExemptPath: (matcher: OriginExemptMatcher) => void;
+export declare const getOriginExemptPaths: () => readonly OriginExemptMatcher[];
+export declare const clearOriginExemptPaths: () => void;
+export declare const isOriginExemptPath: (routePath: string) => boolean;

package/dist/parseArgv.d.ts

@@ -1,2 +1 @@
-
-export {  }
+export {};

package/dist/portResolution.d.ts

@@ -0,0 +1,7 @@
+export interface ResolveServerPortInput {
+    optionsPort?: number | string;
+    parsedPort?: number | null;
+    defaultPort?: number | string;
+}
+export declare const normalizeServerPort: (value: number | string, source?: string) => number;
+export declare const resolveServerPort: ({ optionsPort, parsedPort, defaultPort, }: ResolveServerPortInput) => number;

package/dist/runtimeMapsLoader.d.ts

@@ -0,0 +1,46 @@
+import { type RuntimeMapsProvider } from '@luckystack/core';
+type RuntimeMapRecord = Record<string, unknown>;
+/**
+ * The shape that the generated maps module must export. `scripts/generateServerRequests.ts`
+ * emits exactly this shape: `{ apis, syncs, functions }` where each value is a
+ * `Record<string, Handler>`. Consumers can import this type to validate their
+ * generated file in CI or type-check the `loadGenerated` callback return.
+ */
+export interface GeneratedRuntimeMapsModule {
+    apis: RuntimeMapRecord;
+    syncs: RuntimeMapRecord;
+    functions: RuntimeMapRecord;
+}
+export interface ProdRuntimeMapsLoaderOptions {
+    /**
+     * Dynamic-import callback for the generated maps module of a given preset.
+     * Called once per preset per process lifetime; the result is cached.
+     *
+     * The resolved module must have shape `{ apis, syncs, functions }` (the
+     * shape `scripts/generateServerRequests.ts` emits — see
+     * {@link GeneratedRuntimeMapsModule}). A mis-shaped module logs a warning
+     * and results in every route for that preset returning `notFound`.
+     *
+     * Pass a function that calls `import()` with a path relative to YOUR
+     * server-side module — the framework cannot resolve a relative path on
+     * your behalf because dynamic-import resolution is module-scoped.
+     *
+     * @example
+     * loadGenerated: (preset) => import(`./prod/generatedApis.${preset}`)
+     */
+    loadGenerated: (preset: string) => Promise<unknown>;
+    /**
+     * Override the preset(s) to load. Skips the argv lookup. Accepts a single
+     * preset name or an array. Useful in tests or when the preset list comes
+     * from a non-argv source.
+     */
+    preset?: string | string[];
+}
+export declare const createProdRuntimeMapsProvider: (options: ProdRuntimeMapsLoaderOptions) => RuntimeMapsProvider;
+/**
+ * Convenience wrapper around `createProdRuntimeMapsProvider` +
+ * `registerRuntimeMapsProvider`. Most consumers want this — pass the
+ * loader callback once and the runtime is wired.
+ */
+export declare const registerProdRuntimeMapsProvider: (options: ProdRuntimeMapsLoaderOptions) => RuntimeMapsProvider;
+export {};

package/dist/securityHeadersRegistry.d.ts

@@ -0,0 +1,13 @@
+import type { IncomingMessage } from 'node:http';
+export type SecurityHeadersBuilder = (req: IncomingMessage) => Record<string, string> | null | undefined;
+/**
+ * Register a custom security-headers builder. Called for every HTTP
+ * request; return a plain object that gets merged on top of the framework
+ * defaults. Use for Content-Security-Policy, HSTS, Permissions-Policy.
+ *
+ * Last-write-wins: subsequent calls replace the previous builder. Pass
+ * `null` to unregister.
+ */
+export declare const registerSecurityHeaders: (builder: SecurityHeadersBuilder | null) => void;
+/** Read the active builder (or null). */
+export declare const getSecurityHeadersBuilder: () => SecurityHeadersBuilder | null;

package/dist/sse.d.ts

@@ -0,0 +1,11 @@
+import type { ServerResponse } from 'node:http';
+export declare const shouldUseHttpStream: ({ acceptHeader, queryString, }: {
+    acceptHeader: string | string[] | undefined;
+    queryString: string | undefined;
+}) => boolean;
+export declare const initSseResponse: (res: ServerResponse) => void;
+export declare const sendSseEvent: ({ res, event, data, }: {
+    res: ServerResponse;
+    event: string;
+    data: unknown;
+}) => void;

package/dist/stopServer.d.ts

@@ -0,0 +1,28 @@
+import type { Server as HttpServer } from 'node:http';
+import type { Server as SocketIOServer } from 'socket.io';
+import type { Redis as RedisClient } from 'ioredis';
+import type { StopLuckyStackServerOptions } from './types.js';
+export interface GracefulShutdownDeps {
+    httpServer: HttpServer;
+    ioServer: SocketIOServer;
+    adapterClients: {
+        pubClient: RedisClient;
+        subClient: RedisClient;
+    };
+}
+/**
+ * Run the graceful-shutdown sequence (MIS-016). Ordered + isolated:
+ *   1. Stop accepting NEW HTTP connections (`httpServer.close()` is kicked off
+ *      immediately; we await it last so in-flight requests can drain).
+ *   2. Dispatch the core `preServerStop` hook so consumers can flush queues /
+ *      release leases / close pools.
+ *   3. `flushErrorTrackers()` so buffered events aren't lost — bounded by the
+ *      timeout race.
+ *   4. Close the Socket.io server, then the HTTP server, then `quit()` the
+ *      Redis-adapter pub/sub clients.
+ *
+ * Every step is wrapped in {@link withTimeout} so a single failing/hanging step
+ * cannot hang the whole shutdown — the sequence always settles within
+ * `timeoutMs` per step. Never rejects.
+ */
+export declare const runGracefulShutdown: (deps: GracefulShutdownDeps, options?: StopLuckyStackServerOptions) => Promise<void>;

package/dist/types.d.ts

@@ -0,0 +1,138 @@
+import type { IncomingMessage, ServerResponse, Server as HttpServer } from 'node:http';
+import type { Server as SocketIOServer } from 'socket.io';
+export interface RouteContext {
+    routePath: string;
+    method: string;
+    queryString: string | undefined;
+    token: string | null;
+}
+export type StaticFileHandler = (req: IncomingMessage, res: ServerResponse) => unknown;
+export type FaviconHandler = (res: ServerResponse) => unknown;
+export type CustomRouteHandler = (req: IncomingMessage, res: ServerResponse, ctx: RouteContext) => Promise<boolean> | boolean;
+export type CustomRoutePhase = 'pre-params' | 'post-params';
+export interface CreateLuckyStackServerOptions {
+    /**
+     * Port the HTTP server listens on. Resolution order:
+     *   1. This option (`options.port`)
+     *   2. Second positional argv (`npm run server -- <bundles> <port>`), parsed
+     *      by `@luckystack/server/parseArgv`
+     *   3. `options.defaultPort` (the project's single-instance default, e.g. the
+     *      `backend` port from `config.ports.ts`)
+     *   4. `80` for generic consumers that supplied no port source
+     */
+    port?: number | string;
+    /**
+     * Project's single-instance default backend port. Sits BELOW positional argv
+     * so a multi-instance boot (`npm run server -- <preset> <port>`) still wins.
+     * The scaffold passes the `backend` value from `config.ports.ts` here, so the
+     * listen port has one static source of truth.
+     */
+    defaultPort?: number;
+    /** Bind address. Defaults to process.env.SERVER_IP or '127.0.0.1'. */
+    ip?: string;
+    /** Project-side static file handler (Vite output, etc.). Used as the catch-all. */
+    serveFile?: StaticFileHandler;
+    /** Project-side favicon handler. */
+    serveFavicon?: FaviconHandler;
+    /**
+     * Optional pre-fallback hook for project-specific HTTP routes. Return `true`
+     * if the route was handled (response ended). Return `false` (or omit return)
+     * to fall through to the framework's static file serving.
+     */
+    customRoutes?: CustomRouteHandler;
+    /**
+     * Enable dev-mode tooling (devkit hot reload, REPL, console init).
+     * Defaults to `resolveRuntimeMode() !== 'production'` (NODE_ENV-based).
+     */
+    enableDevTools?: boolean;
+    /**
+     * Maximum HTTP buffer size for socket.io. Defaults to 5 MB. Adjust if you
+     * stream large payloads through sockets.
+     */
+    maxHttpBufferSize?: number;
+    /** Fail boot if no DeployConfig has been registered. Default: false. */
+    requireDeployConfig?: boolean;
+    /** Fail boot if no ServicesConfig has been registered. Default: false. */
+    requireServicesConfig?: boolean;
+    /** Fail boot if no OAuth providers have been registered. Default: false. */
+    requireOAuthProviders?: boolean;
+    /**
+     * Dynamic-import callback for production runtime maps. When provided, the
+     * framework registers its built-in `RuntimeMapsProvider` and the consumer
+     * no longer needs a hand-rolled `server/prod/runtimeMaps.ts`. Pass a
+     * function that calls `import()` with a path relative to the consumer's
+     * server module — the framework cannot resolve that path on the
+     * consumer's behalf because dynamic-import resolution is module-scoped.
+     *
+     * @example
+     * loadGeneratedMaps: (preset) => import(`./prod/generatedApis.${preset}`)
+     */
+    loadGeneratedMaps?: (preset: string) => Promise<unknown>;
+    /**
+     * Override the preset(s) to load (skips argv lookup). Pass a single preset
+     * name or an array for multi-preset boots. Default: the first positional
+     * argv arg parsed by `@luckystack/server/parseArgv`, falling back to
+     * `'default'`.
+     */
+    runtimeMapsPreset?: string | string[];
+}
+export interface StopLuckyStackServerOptions {
+    /**
+     * Why the server is stopping — threaded into the `preServerStop` hook payload.
+     * Defaults to `'manual'` for a programmatic `stop()`; the signal handlers pass
+     * the received signal name.
+     */
+    reason?: 'SIGTERM' | 'SIGINT' | 'SIGHUP' | 'manual';
+    /**
+     * Soft budget (ms) for the whole shutdown sequence — the `preServerStop` hook
+     * fan-out, the bounded `flushErrorTrackers()` race, and closing the
+     * http/io/redis-adapter handles. Each step is wrapped so a single hanging step
+     * cannot stall the others past this deadline. Defaults to `10000`.
+     */
+    timeoutMs?: number;
+}
+export interface AfterListenOptions {
+    /**
+     * Re-throw instead of swallowing. Use only when the process is genuinely
+     * useless without this task. Default `false` — a listening server survives a
+     * failing post-listen task.
+     */
+    fatal?: boolean;
+    /** Label used in the failure log. Defaults to `post-listen task`. */
+    label?: string;
+}
+export interface RunningLuckyStackServer {
+    httpServer: HttpServer;
+    ioServer: SocketIOServer;
+    /**
+     * Start listening. Resolves when the HTTP server is ready. Logs the bound
+     * URL on success.
+     */
+    listen: (callback?: () => void) => Promise<HttpServer>;
+    /**
+     * Run work that belongs AFTER the server is accepting traffic — durable queue
+     * workers, warm-up passes, reconciliation jobs.
+     *
+     * A rejection here is logged loudly and swallowed by default, because the
+     * server is already up: killing a healthy process over one broken dependency
+     * turns an outage into a crash-loop (supervisor restarts, dependency is still
+     * down, repeat). Pass `{ fatal: true }` when the process genuinely has no
+     * purpose without the task — the rejection then propagates to the caller.
+     *
+     * Never resolves to the task's value; it is fire-and-report, not a pipeline
+     * stage. Read what you need inside the callback.
+     */
+    afterListen: (task: () => void | Promise<void>, options?: AfterListenOptions) => Promise<void>;
+    /**
+     * Graceful shutdown (MIS-016). Stops accepting new connections, dispatches the
+     * core `preServerStop` hook, flushes error-trackers (bounded by a timeout
+     * race), and closes the Socket.io server, the HTTP server, and the
+     * Redis-adapter pub/sub clients. Every step is isolated + time-bounded so one
+     * failing/hanging step cannot hang the whole shutdown. Idempotent — a second
+     * call returns the in-flight shutdown promise. Resolves once shutdown
+     * completes (or the timeout forces it to finish).
+     */
+    stop: (options?: StopLuckyStackServerOptions) => Promise<void>;
+    /** Alias of {@link stop} matching the `net.Server`-style `close({ timeoutMs })` API. */
+    close: (options?: StopLuckyStackServerOptions) => Promise<void>;
+}

package/dist/verifyBootstrap.d.ts

@@ -0,0 +1,18 @@
+export interface BootstrapRequirements {
+    /**
+     * If true, require a deploy config to have been registered. Defaults to
+     * false because single-instance deployments don't need one.
+     */
+    requireDeployConfig?: boolean;
+    /**
+     * If true, require a services config to have been registered. Defaults to
+     * false; only needed when running the router.
+     */
+    requireServicesConfig?: boolean;
+    /**
+     * If true, require an OAuth provider list to have been registered.
+     * Defaults to false (an app may use credentials only).
+     */
+    requireOAuthProviders?: boolean;
+}
+export declare const verifyBootstrap: (requirements?: BootstrapRequirements) => Promise<void>;

package/docs/argv-parsing.md

@@ -1,246 +1,5 @@
-# Argv Parsing (`parseServerArgv` + `applyServerArgv`)
+# Runtime arguments
 
-> Deep specs. Bron: `packages/server/src/argv.ts`, `packages/server/src/parseArgv.ts`. Bijgewerkt: 2026-08-16.
+Explicit runtime arguments let deployment choose bundles and bind port without editing generated source. Validate them before boot rather than continuing with an ambiguous or partial map; fail loudly on invalid input. Source: `../src/argv.ts`, `../src/parseArgv.ts`, `../src/portResolution.ts`.
 
-## Overview
-
-`@luckystack/server` accepts two positional CLI arguments on boot:
-
-```
-npm run server -- <bundle[,bundle...]> [port]
-```
-
-- Arg 0 — preset list. Comma-separated; duplicates collapsed; runtime maps from each preset are shallow-merged at boot.
-- Arg 1 — listen port. Numeric. Optional.
-
-Argv provides one shape consumed by `createProdRuntimeMapsProvider` (preset), `createLuckyStackServer` (port), and the browser-safe `@luckystack/core/config` port-override registry.
-
-The module exposes:
-
-- A pure parser: `parseServerArgv(argv)`.
-- A side-effect runner that reads `process.argv.slice(2)` once and registers the result: `applyServerArgv()`.
-- Read accessors: `getParsedBundles()`, `getParsedPort()`.
-- A side-effect-only entrypoint `@luckystack/server/parseArgv` that simply imports `applyServerArgv` and runs it.
-
-The side-effect entry MUST be the FIRST import in the consumer's `server.ts` because it registers the parsed port in `@luckystack/core/config`, and the consumer's config reads that override at top-level evaluation time. When no CLI port was supplied, the registry stays empty and `config.ts` uses the consumer-owned `config.ports.ts` backend value.
-
-Importing the consumer config before `parseArgv` runs can lock the static default into its OAuth callback base. The server listen path still reads the same registry through `getParsedPort()`, so both surfaces share one override without an environment writeback.
-
-## API Reference
-
-### `parseServerArgv(argv: string[]): ParsedServerArgv`
-
-**Signature:**
-
-```typescript
-export interface ParsedServerArgv {
-  bundles: string[];
-  port: number | null;
-}
-
-export const parseServerArgv = (argv: string[]): ParsedServerArgv;
-```
-
-**Parameters:**
-
-| Field | Type | Purpose |
-| --- | --- | --- |
-| `argv` | `string[]` | Positional args (typically `process.argv.slice(2)`). |
-
-**Returns:** `{ bundles, port }`:
-
-- `bundles: string[]` — deduplicated, trimmed, non-empty entries from arg 0. Empty array when arg 0 is missing or empty.
-- `port: number | null` — `parseInt(argv[1], 10)` when arg 1 is supplied; `null` otherwise.
-
-**Behavior:**
-
-- Reject more than 2 positional arguments by throwing `Error('[luckystack:argv] unexpected positional argument(s): "<rest>". Usage: npm run server -- <bundle[,bundle...]> [port]')`.
-- For arg 0: split on `,`, `trim()` each piece, drop falsy, collapse via `Array.from(new Set(...))`.
-- For arg 1: must match `/^\d+$/`. Otherwise throws `Error('[luckystack:argv] port argument must be numeric, got: "<value>". Usage: npm run server -- <bundle[,bundle...]> [port]')`.
-
-**Errors / Edge cases:**
-
-- Whitespace in arg 0 (`"billing, vehicles"`) is supported — trimmed.
-- A trailing comma (`"billing,"`) is silently dropped.
-- A leading `0` in the port string is accepted (`/^\d+$/`) and parsed normally.
-- An empty arg 0 (`""`) yields `bundles: []`; the downstream resolver falls back to `['default']`.
-
-**Example:**
-
-```typescript
-parseServerArgv(['billing,vehicles', '4001']);
-// => { bundles: ['billing', 'vehicles'], port: 4001 }
-
-parseServerArgv([]);
-// => { bundles: [], port: null }
-
-parseServerArgv(['billing', '4001', 'oops']);
-// => throws (too many positionals)
-
-parseServerArgv(['billing', 'PORT']);
-// => throws (non-numeric port)
-```
-
----
-
-### `applyServerArgv(): void`
-
-**Signature:**
-
-```typescript
-export const applyServerArgv = (): void;
-```
-
-**Parameters:** none. Reads `process.argv.slice(2)`.
-
-**Returns:** `void`.
-
-**Behavior:**
-
-- Idempotent. Subsequent calls return immediately via the module-level `hasRun` latch.
-- First call:
-  1. `parseServerArgv(process.argv.slice(2))` (throws on malformed input).
-  2. Caches `bundles` in module state.
-  3. Calls `registerPortOverride(port)`. A numeric port becomes visible through the browser-safe core/config entry; `null` clears the override.
-
-**Errors / Edge cases:**
-
-- Throwing during this call aborts boot before consumer config evaluates.
-- Calling `applyServerArgv` after consumer config has evaluated is too late — that module has already captured its callback base.
-
-**Example:**
-
-```typescript
-// server.ts — first line
-import '@luckystack/server/parseArgv';
-// rest of bootstrap...
-```
-
-Or call it explicitly when you control the boot timing:
-
-```typescript
-import { applyServerArgv } from '@luckystack/server';
-applyServerArgv();
-```
-
----
-
-### `getParsedBundles(): string[]`
-
-**Signature:**
-
-```typescript
-export const getParsedBundles = (): string[];
-```
-
-**Returns:** the cached `bundles` array. Empty until `applyServerArgv()` has run.
-
-**Behavior:**
-
-- Read-only; never throws.
-- Used by `createProdRuntimeMapsProvider` to resolve which preset(s) to load when neither `options.preset` nor a literal string is supplied.
-
-**Example:**
-
-```typescript
-import { applyServerArgv, getParsedBundles } from '@luckystack/server';
-
-applyServerArgv();
-console.log(getParsedBundles()); // e.g. ['billing', 'vehicles']
-```
-
----
-
-### `getParsedPort(): number | null`
-
-**Signature:**
-
-```typescript
-export const getParsedPort = (): number | null;
-```
-
-**Returns:** the port currently held in the core/config override registry. `null` when no positional port was registered.
-
-**Behavior:**
-
-- Read-only; never throws.
-- Consumed by `createLuckyStackServer` as one of the port-resolution fallbacks:
-  1. `options.port`
-  2. `getParsedPort()`
-  3. `options.defaultPort` (the scaffold's `config.ports.ts` backend)
-  4. `80` (generic final fallback)
-
-**Example:**
-
-```typescript
-import { getParsedPort } from '@luckystack/server';
-
-const port = getParsedPort();
-if (port !== null) {
-  console.log(`argv supplied port ${port}`);
-}
-```
-
----
-
-### Side-effect entrypoint: `@luckystack/server/parseArgv`
-
-**Module body (verbatim):**
-
-```typescript
-import { applyServerArgv } from './argv';
-
-applyServerArgv();
-```
-
-**Usage:** import as the FIRST line of your `server.ts`:
-
-```typescript
-import '@luckystack/server/parseArgv';
-```
-
-Consumer `config.ts` MUST be imported below this line because it reads `getPortOverride()` at module evaluation time. Importing core itself first is safe: the registry is mutable and browser-safe. With no CLI port, scaffold config intentionally falls back to its pure-data `config.ports.ts` value.
-
-## Resolution order summary
-
-| Consumer | Source of port |
-| --- | --- |
-| `createLuckyStackServer` | `options.port` -> `getParsedPort()` -> `options.defaultPort` -> `80` |
-| `createLuckyStackServer` IP | `options.ip` -> `SERVER_IP` -> `127.0.0.1` |
-| `createProdRuntimeMapsProvider` | `options.preset` (string -> single-entry array; non-empty array -> dedup) -> `getParsedBundles()` -> `['default']` |
-
-## CLI examples
-
-```bash
-# Default preset, config.ports.ts backend
-npm run server
-
-# Single bundle, config.ports.ts backend
-npm run server -- billing
-
-# Two bundles merged, port 4001
-npm run server -- billing,vehicles 4001
-
-# Whitespace in bundle list is fine
-npm run server -- "billing , vehicles" 4001
-
-# Invalid port — boot aborts with descriptive error
-npm run server -- billing PORT
-# Error: [luckystack:argv] port argument must be numeric, got: "PORT".
-
-# Extra positional — boot aborts
-npm run server -- billing 4001 oops
-# Error: [luckystack:argv] unexpected positional argument(s): "oops".
-```
-
-## Interaction with runtime maps
-
-`createProdRuntimeMapsProvider({ loadGenerated, preset? })` calls `getParsedBundles()` when `preset` is omitted or empty. Each resolved preset is dynamically imported via the consumer-supplied `loadGenerated` callback, then shallow-merged into one runtime view. Key collisions across presets throw at boot. See `runtime-maps.md` for the merge semantics.
-
-## Related
-
-- Function INDEX: `packages/server/CLAUDE.md`
-- Runtime maps: `packages/server/docs/runtime-maps.md`
-- Create server: `packages/server/docs/create-server.md`
-- Architecture: `docs/ARCHITECTURE_PACKAGING.md` (preset bundles, multi-service builds)
-- README: `packages/server/README.md`
+A selected bundle controls which generated routes load, not who may invoke them. Keep runtime map isolation and application authorization independent. See `./runtime-maps.md`, `../src/verifyBootstrap.ts`; consult source for current argument spelling and precedence.