@nage-api/core 1.0.0-beta.2

package/dist/bootstrap/drain.d.ts

@@ -0,0 +1,48 @@
+/**
+ * In-flight request accounting, so shutdown can wait for the requests it has
+ * (PLAN.md §21).
+ *
+ * `app.close()` alone cannot do this. Nest runs `onModuleDestroy` *before* it
+ * closes the HTTP server, so a handler still executing when the signal arrives
+ * finds its connection pool already shut — measured, not assumed: a 600ms
+ * handler signalled at 200ms returned `pool is closed` with HTTP 200. Knowing
+ * the number of live requests is what lets the sequence be put the right way
+ * round.
+ *
+ * Counted in middleware rather than in an interceptor because an interceptor
+ * only sees requests that reach a matched route: a request that 404s, or that
+ * dies in body parsing, holds a connection just the same.
+ */
+/** The subset of a Node/Express response the tracker touches. */
+export interface DrainResponseLike {
+    once(event: 'close', listener: () => void): unknown;
+    setHeader?: (name: string, value: string) => void;
+    readonly headersSent?: boolean;
+}
+export type DrainMiddleware = (request: unknown, response: DrainResponseLike, next: () => void) => void;
+export interface RequestDrainOptions {
+    /** Consulted per request; `true` once a shutdown signal has been seen. */
+    readonly isDraining?: () => boolean;
+}
+export declare class RequestDrain {
+    #private;
+    constructor(options?: RequestDrainOptions);
+    /** Requests that have been accepted and not yet had their response closed. */
+    get active(): number;
+    /**
+     * The middleware. Install it first, ahead of helmet and the body parser, so
+     * the count covers the whole time the connection is held.
+     */
+    middleware(): DrainMiddleware;
+    /**
+     * Resolve when no request is in flight, or on the deadline.
+     *
+     * Returns whether it drained; the caller logs the difference, because "we cut
+     * off 3 requests" and "we finished cleanly" must not look the same in a deploy
+     * log.
+     */
+    whenIdle(timeoutMs: number): Promise<boolean>;
+}
+export declare function registerRequestDrain(app: object, drain: RequestDrain): void;
+export declare function requestDrainFor(app: object): RequestDrain | undefined;
+//# sourceMappingURL=drain.d.ts.map

package/dist/bootstrap/drain.js

@@ -0,0 +1,113 @@
+"use strict";
+/**
+ * In-flight request accounting, so shutdown can wait for the requests it has
+ * (PLAN.md §21).
+ *
+ * `app.close()` alone cannot do this. Nest runs `onModuleDestroy` *before* it
+ * closes the HTTP server, so a handler still executing when the signal arrives
+ * finds its connection pool already shut — measured, not assumed: a 600ms
+ * handler signalled at 200ms returned `pool is closed` with HTTP 200. Knowing
+ * the number of live requests is what lets the sequence be put the right way
+ * round.
+ *
+ * Counted in middleware rather than in an interceptor because an interceptor
+ * only sees requests that reach a matched route: a request that 404s, or that
+ * dies in body parsing, holds a connection just the same.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RequestDrain = void 0;
+exports.registerRequestDrain = registerRequestDrain;
+exports.requestDrainFor = requestDrainFor;
+class RequestDrain {
+    #active = 0;
+    #idle = new Set();
+    #isDraining;
+    constructor(options = {}) {
+        this.#isDraining = options.isDraining ?? (() => false);
+    }
+    /** Requests that have been accepted and not yet had their response closed. */
+    get active() {
+        return this.#active;
+    }
+    /**
+     * The middleware. Install it first, ahead of helmet and the body parser, so
+     * the count covers the whole time the connection is held.
+     */
+    middleware() {
+        return (_request, response, next) => {
+            this.#active += 1;
+            // A draining process keeps serving — the orchestrator may still be
+            // routing to it — but tells each client not to reuse the socket, so the
+            // connection is released at the end of the response instead of being cut
+            // when the listener closes. Requests are *not* refused here: a blanket 503
+            // would also refuse `/health/live`, and a liveness probe failing during a
+            // drain is what turns a graceful shutdown into a `SIGKILL`.
+            if (this.#isDraining() && response.headersSent !== true) {
+                response.setHeader?.('connection', 'close');
+            }
+            // `close` rather than `finish`: an aborted response never finishes, and a
+            // counter that only ever goes up makes the drain wait out its full
+            // deadline on every deploy.
+            let settled = false;
+            response.once('close', () => {
+                if (settled)
+                    return;
+                settled = true;
+                this.#active -= 1;
+                if (this.#active <= 0)
+                    this.#releaseIdleWaiters();
+            });
+            next();
+        };
+    }
+    /**
+     * Resolve when no request is in flight, or on the deadline.
+     *
+     * Returns whether it drained; the caller logs the difference, because "we cut
+     * off 3 requests" and "we finished cleanly" must not look the same in a deploy
+     * log.
+     */
+    async whenIdle(timeoutMs) {
+        if (this.#active <= 0)
+            return true;
+        if (timeoutMs <= 0)
+            return false;
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.#idle.delete(waiter);
+                resolve(false);
+            }, timeoutMs);
+            // Nothing about a shutdown deadline should itself hold the event loop
+            // open; the awaited promise is what keeps the sequence alive.
+            timer.unref();
+            const waiter = () => {
+                clearTimeout(timer);
+                resolve(true);
+            };
+            this.#idle.add(waiter);
+        });
+    }
+    #releaseIdleWaiters() {
+        const waiters = [...this.#idle];
+        this.#idle.clear();
+        for (const waiter of waiters)
+            waiter();
+    }
+}
+exports.RequestDrain = RequestDrain;
+/**
+ * The tracker belongs to one application instance.
+ *
+ * A `WeakMap` rather than a provider: the middleware has to be installed by
+ * `createApplication` (before helmet, outside the DI-managed middleware chain),
+ * and a module-level singleton would let one test suite's counter leak into the
+ * next application built in the same process.
+ */
+const drains = new WeakMap();
+function registerRequestDrain(app, drain) {
+    drains.set(app, drain);
+}
+function requestDrainFor(app) {
+    return drains.get(app);
+}
+//# sourceMappingURL=drain.js.map

package/dist/bootstrap/lifecycle.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Where the process is in its own life (PLAN.md §21).
+ *
+ * Readiness and shutdown are two views of one fact, and before this they were
+ * two facts: `/health/ready` answered from the dependency probes alone, so a
+ * process that had received `SIGTERM` and was draining still told the load
+ * balancer to send it traffic. Every request routed in that window is a request
+ * whose connection is about to be closed.
+ *
+ * Liveness deliberately does **not** read this. A draining process is healthy;
+ * failing liveness while it drains asks the orchestrator to `SIGKILL` the very
+ * process that is trying to finish its work.
+ */
+export type LifecyclePhase = 'starting' | 'live' | 'draining';
+export declare class LifecycleState {
+    #private;
+    get phase(): LifecyclePhase;
+    /** True from the moment a shutdown signal is observed. */
+    get draining(): boolean;
+    markLive(): void;
+    markDraining(): void;
+    /**
+     * Back to `starting`. A deployed process never does this — a signal is not
+     * something to undo — but a test runner that builds several applications in one
+     * process needs the phase not to leak from one to the next.
+     */
+    reset(): void;
+}
+export declare function processLifecycle(): LifecycleState;
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/bootstrap/lifecycle.js

@@ -0,0 +1,64 @@
+"use strict";
+/**
+ * Where the process is in its own life (PLAN.md §21).
+ *
+ * Readiness and shutdown are two views of one fact, and before this they were
+ * two facts: `/health/ready` answered from the dependency probes alone, so a
+ * process that had received `SIGTERM` and was draining still told the load
+ * balancer to send it traffic. Every request routed in that window is a request
+ * whose connection is about to be closed.
+ *
+ * Liveness deliberately does **not** read this. A draining process is healthy;
+ * failing liveness while it drains asks the orchestrator to `SIGKILL` the very
+ * process that is trying to finish its work.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LifecycleState = void 0;
+exports.processLifecycle = processLifecycle;
+class LifecycleState {
+    #phase = 'starting';
+    get phase() {
+        return this.#phase;
+    }
+    /** True from the moment a shutdown signal is observed. */
+    get draining() {
+        return this.#phase === 'draining';
+    }
+    markLive() {
+        // A late `markLive()` — a listener callback that fires after a signal
+        // already arrived — must not resurrect a draining process.
+        if (this.#phase === 'starting')
+            this.#phase = 'live';
+    }
+    markDraining() {
+        this.#phase = 'draining';
+    }
+    /**
+     * Back to `starting`. A deployed process never does this — a signal is not
+     * something to undo — but a test runner that builds several applications in one
+     * process needs the phase not to leak from one to the next.
+     */
+    reset() {
+        this.#phase = 'starting';
+    }
+}
+exports.LifecycleState = LifecycleState;
+/**
+ * The phase belongs to the **process**, not to an application object.
+ *
+ * A signal arrives at the process: if it hosted two applications, both are
+ * draining, and there is no meaningful state in which one of them is not. Holding
+ * it here rather than resolving it through DI also avoids a trap that cost a
+ * boot: `NestFactory.create` returns a Proxy that wraps every method in
+ * `ExceptionsZone`, whose default teardown is `process.exit(1)`. So
+ * `app.get(TOKEN)` for a token an application has not registered does not throw
+ * for a caller to catch — it kills the process. Measured: `createApplication` on a
+ * module that does not import `NageCoreModule` exited 1 before the listener was
+ * bound.
+ */
+let processState;
+function processLifecycle() {
+    processState ??= new LifecycleState();
+    return processState;
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/bootstrap/process-guards.d.ts

@@ -0,0 +1,42 @@
+/**
+ * What happens when an error escapes everything (PLAN.md §21, §18).
+ *
+ * Node's own policy is nearly right and reports nothing useful. An
+ * `uncaughtException` or an unhandled rejection prints a human-readable stack to
+ * stderr and exits 1 — so the one line describing why production died is the
+ * only line of the day that a JSON log shipper cannot parse, it carries no
+ * correlation id, and the pools are dropped rather than closed.
+ *
+ * The policy here keeps the crash and fixes the reporting:
+ *
+ *  - **Both events are fatal.** Nothing is swallowed. A process that has thrown
+ *    from outside a request has unknown state, and serving the next request from
+ *    unknown state is how a bug becomes a data defect.
+ *  - **One structured `fatal` line first**, through the framework logger, so the
+ *    reason survives in the same stream as everything else.
+ *  - **Then a bounded graceful shutdown** (`onFatal`), so in-flight responses get
+ *    a chance to finish and pools get closed. Bounded because the handler cannot
+ *    trust the very machinery it is shutting down.
+ *
+ * Installing a listener for these events also takes them off Node's default
+ * path, which is why the exit is explicit: a handler that logs and returns turns
+ * a crash into a zombie.
+ */
+import type { LoggerPort } from '@nage-api/contracts';
+export type FatalKind = 'uncaughtException' | 'unhandledRejection';
+export interface ProcessGuardOptions {
+    readonly logger: LoggerPort;
+    /**
+     * Graceful shutdown to attempt before exiting — normally the
+     * `ShutdownHandle.run` returned by `installShutdown`.
+     */
+    readonly onFatal?: (kind: FatalKind, error: unknown) => unknown;
+    /** How long `onFatal` may take before the process exits anyway. */
+    readonly gracePeriodMs?: number;
+    /** Injected so a test can assert the exit code without exiting the runner. */
+    readonly exit?: (code: number) => void;
+}
+/** Removes the listeners this installed. */
+export type DisposeProcessGuards = () => void;
+export declare function installProcessGuards(options: ProcessGuardOptions): DisposeProcessGuards;
+//# sourceMappingURL=process-guards.d.ts.map

package/dist/bootstrap/process-guards.js

@@ -0,0 +1,103 @@
+"use strict";
+/**
+ * What happens when an error escapes everything (PLAN.md §21, §18).
+ *
+ * Node's own policy is nearly right and reports nothing useful. An
+ * `uncaughtException` or an unhandled rejection prints a human-readable stack to
+ * stderr and exits 1 — so the one line describing why production died is the
+ * only line of the day that a JSON log shipper cannot parse, it carries no
+ * correlation id, and the pools are dropped rather than closed.
+ *
+ * The policy here keeps the crash and fixes the reporting:
+ *
+ *  - **Both events are fatal.** Nothing is swallowed. A process that has thrown
+ *    from outside a request has unknown state, and serving the next request from
+ *    unknown state is how a bug becomes a data defect.
+ *  - **One structured `fatal` line first**, through the framework logger, so the
+ *    reason survives in the same stream as everything else.
+ *  - **Then a bounded graceful shutdown** (`onFatal`), so in-flight responses get
+ *    a chance to finish and pools get closed. Bounded because the handler cannot
+ *    trust the very machinery it is shutting down.
+ *
+ * Installing a listener for these events also takes them off Node's default
+ * path, which is why the exit is explicit: a handler that logs and returns turns
+ * a crash into a zombie.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installProcessGuards = installProcessGuards;
+const DEFAULT_GRACE_PERIOD_MS = 5000;
+function installProcessGuards(options) {
+    const { logger } = options;
+    const exit = options.exit ?? ((code) => process.exit(code));
+    const gracePeriodMs = options.gracePeriodMs ?? DEFAULT_GRACE_PERIOD_MS;
+    let handling = false;
+    const handle = (kind, error) => {
+        // A rejection thrown from inside the fatal handler must not restart it.
+        if (handling)
+            return;
+        handling = true;
+        logger.fatal('Fatal error; the process will exit', {
+            kind,
+            error: error instanceof Error ? error.message : String(error),
+            stack: error instanceof Error ? error.stack : undefined,
+            // A rejection with a non-Error reason (`reject('nope')`, or a rejected
+            // fetch response) is the case where the stack is absent and the value is
+            // the only evidence there is.
+            ...(error instanceof Error ? {} : { value: safeValue(error) }),
+        });
+        // Set now, so that even if the event loop empties before either the shutdown
+        // or the grace period finishes, the process still reports a failure.
+        process.exitCode = 1;
+        let timer;
+        const grace = new Promise((resolve) => {
+            // Not `unref`ed: the grace period is what keeps the process alive long
+            // enough to close its pools, and an unreferenced timer would let it exit
+            // the moment the last request's socket closed.
+            timer = setTimeout(resolve, gracePeriodMs);
+        });
+        const attempt = (async () => {
+            await options.onFatal?.(kind, error);
+        })();
+        void Promise.race([attempt, grace]).then(() => {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            exit(1);
+        }, () => {
+            // The shutdown itself failed. Still exit: this path exists to guarantee
+            // the process does not keep serving.
+            if (timer !== undefined)
+                clearTimeout(timer);
+            exit(1);
+        });
+    };
+    const onUncaught = (error) => {
+        handle('uncaughtException', error);
+    };
+    const onRejection = (reason) => {
+        handle('unhandledRejection', reason);
+    };
+    process.on('uncaughtException', onUncaught);
+    process.on('unhandledRejection', onRejection);
+    return () => {
+        process.removeListener('uncaughtException', onUncaught);
+        process.removeListener('unhandledRejection', onRejection);
+    };
+}
+/** A rejection reason can be anything, including something that will not stringify. */
+function safeValue(value) {
+    // `Promise.reject()` with no reason is a real case, and `JSON.stringify` returns
+    // `undefined` for it however the types describe that.
+    if (value === undefined)
+        return 'undefined';
+    if (typeof value === 'string')
+        return value;
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        // A cyclic or getter-throwing reason must not turn the fatal handler into a
+        // second fatal error.
+        return '[unserializable]';
+    }
+}
+//# sourceMappingURL=process-guards.js.map

package/dist/bootstrap/query-parser.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The query parser the URL query DSL needs (PLAN.md §14.2).
+ *
+ * Express 5 changed its default `query parser` from `extended` to `simple`.
+ * Under `simple`, `?where[status]=active` does not become
+ * `{ where: { status: 'active' } }` — it becomes the single flat key
+ * `'where[status]'`. Nothing errors: `parseQuery` sees a top-level key it does
+ * not recognise, ignores it, and the request returns **the whole collection with
+ * a 200**. A client that asked to filter silently gets everything, which is the
+ * same class of failure as a missing allow-list.
+ *
+ * So the setting is applied explicitly rather than inherited. It is a named
+ * export as well as part of `bootstrap`, because an application built with
+ * `Test.createTestingModule(...).createNestApplication()` never goes through
+ * `bootstrap` and would otherwise test a differently-configured app than it ships.
+ */
+/** The Nest-shaped slice needed to reach that instance. */
+interface AppWithHttpAdapter {
+    getHttpAdapter: () => {
+        getInstance: () => unknown;
+    };
+}
+/**
+ * Enable bracketed query parsing on an application.
+ *
+ * A no-op on a platform whose instance has no `set` — Fastify parses brackets
+ * through its own querystring parser, so there is nothing to switch on and
+ * nothing to warn about.
+ *
+ * @returns whether the setting was applied
+ */
+export declare function enableQueryDsl(app: AppWithHttpAdapter): boolean;
+export {};
+//# sourceMappingURL=query-parser.d.ts.map

package/dist/bootstrap/query-parser.js

@@ -0,0 +1,37 @@
+"use strict";
+/**
+ * The query parser the URL query DSL needs (PLAN.md §14.2).
+ *
+ * Express 5 changed its default `query parser` from `extended` to `simple`.
+ * Under `simple`, `?where[status]=active` does not become
+ * `{ where: { status: 'active' } }` — it becomes the single flat key
+ * `'where[status]'`. Nothing errors: `parseQuery` sees a top-level key it does
+ * not recognise, ignores it, and the request returns **the whole collection with
+ * a 200**. A client that asked to filter silently gets everything, which is the
+ * same class of failure as a missing allow-list.
+ *
+ * So the setting is applied explicitly rather than inherited. It is a named
+ * export as well as part of `bootstrap`, because an application built with
+ * `Test.createTestingModule(...).createNestApplication()` never goes through
+ * `bootstrap` and would otherwise test a differently-configured app than it ships.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.enableQueryDsl = enableQueryDsl;
+/**
+ * Enable bracketed query parsing on an application.
+ *
+ * A no-op on a platform whose instance has no `set` — Fastify parses brackets
+ * through its own querystring parser, so there is nothing to switch on and
+ * nothing to warn about.
+ *
+ * @returns whether the setting was applied
+ */
+function enableQueryDsl(app) {
+    const instance = app.getHttpAdapter().getInstance();
+    const settable = instance;
+    if (typeof settable.set !== 'function')
+        return false;
+    settable.set('query parser', 'extended');
+    return true;
+}
+//# sourceMappingURL=query-parser.js.map

package/dist/bootstrap/shutdown.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Graceful shutdown, in the order the stages actually have to happen
+ * (PLAN.md §21).
+ *
+ * `app.enableShutdownHooks()` is not this. Nest 11's signal handler runs
+ * `onModuleDestroy` → `beforeApplicationShutdown` → close the HTTP server →
+ * `onApplicationShutdown`, so **modules destroy their pools while requests are
+ * still running**. Measured against a 600ms handler signalled at 200ms: the
+ * handler's query came back `pool is closed` and the client got that as a 200.
+ * A second measurement: one handler that never returns kept the process alive
+ * past 8 seconds, because nothing in that sequence has a deadline — the
+ * container survives until the orchestrator's `SIGKILL`.
+ *
+ * This runs the stages in the order that makes each one meaningful:
+ *
+ *  1. **Fail readiness.** The load balancer needs to stop choosing this
+ *     instance, and endpoint propagation is not instant (`readinessDelayMs`).
+ *  2. **Stop accepting connections**, and release keep-alive sockets that have
+ *     no request on them. Requests already in flight keep their sockets.
+ *  3. **Wait for those requests**, bounded by `drainTimeoutMs`. Past the
+ *     deadline the remaining sockets are cut, because a client that has hung is
+ *     not a reason to abandon the pools.
+ *  4. **`app.close()`** — only now do modules close pools, queues and Redis.
+ *  5. **Exit.** Zero if the sequence finished, non-zero if `forceExitAfterMs`
+ *     expired, so a deploy can tell a clean drain from a broken one.
+ */
+import type { LoggerPort, NageCoreConfig } from '@nage-api/contracts';
+import { type LifecycleState } from './lifecycle.js';
+import { RequestDrain } from './drain.js';
+/** The subset of `INestApplication` this needs; keeps tests free of a real app. */
+export interface ClosableApplication {
+    close(): Promise<void>;
+    getHttpServer?: () => unknown;
+}
+export interface ShutdownOptions {
+    readonly config?: NageCoreConfig;
+    readonly logger?: LoggerPort;
+    /** Defaults to `SIGTERM` and `SIGINT`. */
+    readonly signals?: readonly NodeJS.Signals[];
+    /** Injected so a test can assert the exit code without exiting the runner. */
+    readonly exit?: (code: number) => void;
+    readonly lifecycle?: LifecycleState;
+    readonly drain?: RequestDrain;
+}
+export interface ShutdownHandle {
+    readonly draining: boolean;
+    /** Run the sequence. Idempotent: a second call awaits the first. */
+    run(reason: string): Promise<number>;
+    /** Remove the signal listeners. Tests and embedded apps need this. */
+    dispose(): void;
+}
+export declare function installShutdown(app: ClosableApplication, options?: ShutdownOptions): ShutdownHandle;
+export declare function registerShutdownHandle(app: object, handle: ShutdownHandle): void;
+export declare function shutdownHandleFor(app: object): ShutdownHandle | undefined;
+//# sourceMappingURL=shutdown.d.ts.map