@nifrajs/core 5.6.0 → 5.7.0

package/dist/server/server.js

@@ -10,6 +10,8 @@ import { authenticateMount, compileRouteProgram, executeRouteProgram, } from "..
 import { isSameOriginRequest } from "../internal/same-origin.js";
 import { decodeRouteParams, expandOptionalParams, } from "../router/pattern.js";
 import { EMPTY_PARAMS, METHODS, Router } from "../router/router.js";
+import { withAnswerSteps } from "./answer-step.js";
+import { isAuthenticatedRequest, markAuthenticatedRequest, } from "./auth.js";
 import { emitRequestErrorLog, renderBareError } from "./bare-error-lane.js";
 import { LAST_BEFORE_HANDLE } from "./before-handler.js";
 import { assertByteLimit, clientBodyErrorCode, hasTrustedBodyFraming, markTransportCap, markTrustedBodyFraming, UNLIMITED_BODY_BYTES, } from "./body.js";
@@ -26,9 +28,10 @@ import { needsResolving, resolveDotSegments } from "./request-target.js";
 import { applyStaticResponseHeaders, buildStaticResponseHeaders, claimHandedOver, fusedRespond, fusedRespondNoSet, handedBackResponse, recordResidentTexts, toResponse, writableResponse, } from "./respond.js";
 import { CONTEXT_REQUEST, CONTEXT_SEARCH, CONTEXT_SET, EMPTY_RESPONSE_CONTROLS, getNeverAbortSignal, getUnboundedRequestBudget, headerOf, isResponseResult, requestOf, } from "./runtime-core.js";
 import { normalizeStaticResponseHeaders } from "./static-headers.js";
+import { withTextSlots } from "./text-slots.js";
 import { plainValidationError } from "./validation.js";
 import { NIFRA_BACKEND_WS_RUNTIME } from "../mount.js";
-import { GET_WS_RUNTIME, INSTALL_EFFECT_LEDGER, INSTALL_IDEMPOTENCY, INSTALL_MCP, INSTALL_NODE_DIRECT, INSTALL_NOT_FOUND, INSTALL_RESPONSE_CONTRACT, INSTALL_RESPONSE_OBSERVER, INSTALL_SSE, INSTALL_WS, NODE_NATIVE_MOUNT, REPORT_ERROR, RESOLVE_NODE_MOUNT, } from "./install.js";
+import { GET_WS_RUNTIME, INSTALL_EFFECT_LEDGER, INSTALL_IDEMPOTENCY, INSTALL_MCP, INSTALL_NODE_DIRECT, INSTALL_NOT_FOUND, INSTALL_RESPONSE_CONTRACT, INSTALL_RESPONSE_OBSERVER, INSTALL_SSE, INSTALL_WS, NODE_NATIVE_MOUNT, REPORT_ERROR, RESOLVE_NODE_MOUNT, SERVER_LIFECYCLE, } from "./install.js";
 import { jsonLogger } from "./logger.js";
 // CORS uses this marker to say its request hook only handles OPTIONS preflight. Bun can keep
 // ordinary registered routes on its native table and send unmatched OPTIONS requests through the
@@ -303,13 +306,17 @@ function mountPriorityOf(priority) {
 function compareMounts(a, b) {
     return b.priority - a.priority || b.path.length - a.path.length || a.order - b.order;
 }
+/** Rebase a mounted request's path without losing the authentication mark used by child caches. */
 function stripMountPrefix(request, prefix) {
     if (prefix === "/")
         return request;
     const url = new URL(request.url);
     const rest = url.pathname.slice(prefix.length);
     url.pathname = rest === "" ? "/" : rest;
-    return new Request(url.href, request);
+    const childRequest = new Request(url.href, request);
+    if (isAuthenticatedRequest(request))
+        markAuthenticatedRequest(childRequest);
+    return childRequest;
 }
 function responseSet(ctx) {
     return ctx[CONTEXT_SET]() ?? EMPTY_RESPONSE_CONTROLS;
@@ -659,6 +666,7 @@ export class Server {
     deadlineAdmissionOptions;
     gracefulSignals;
     stopHooks;
+    stoppingHooks;
     fetchMounts;
     mountOrder;
     /** Number of composed mounts that must run before the parent route table. Keeps legacy mounts off the hot path. */
@@ -742,7 +750,7 @@ export class Server {
         ? fusedRespondNoSet(result, this.responseBodyTag, this.staticResponseHeaders, true)
         : toResponse(result, set, this.responseBodyTag, this.staticResponseHeaders, 
         // Response hooks write next, and they run for this same request object.
-        ctx !== undefined && this.onResponseHooks.length > 0 ? ctx[CONTEXT_REQUEST] : undefined);
+        ctx !== undefined && this.onResponseHooks.length > 0 ? ctx[CONTEXT_REQUEST] : undefined, this.onResponseHooks.length === 0);
     responseRequests;
     /** A request the WebSocket handshake check ran the onRequest hooks on and then passed to HTTP →
      * what the hooks returned, so `fetch` routes that instead of running the hooks a second time. */
@@ -808,6 +816,7 @@ export class Server {
         this.gracefulSignals =
             options.gracefulSignals === true ? {} : options.gracefulSignals || undefined;
         this.stopHooks = [];
+        this.stoppingHooks = [];
         this.fetchMounts = [];
         this.mountOrder = 0;
         this.preRouteMountCount = 0;
@@ -878,6 +887,18 @@ export class Server {
         this.stopHooks.push(fn);
         return this;
     }
+    /**
+     * Register a callback awaited as soon as `stop()` begins, while the server still serves: readiness
+     * should fail from here, and work that outlives a request (a poller, a queue consumer) should stop
+     * taking more. Hung callbacks are bounded.
+     */
+    onStopping(fn) {
+        this.assertConfigurable("onStopping()");
+        if (typeof fn !== "function")
+            throw new TypeError("onStopping callback must be a function");
+        this.stoppingHooks.push(fn);
+        return this;
+    }
     /**
      * Mount a legacy fetch handler under a literal path prefix. Mounted handlers sit behind typed
      * routes, so routes can move one at a time while the remaining legacy surface stays live.
@@ -1575,6 +1596,7 @@ export class Server {
         throw new RouteConfigError("INVALID_PATH", `group(${JSON.stringify(prefix)}) route path must start with "/": ${JSON.stringify(path)}`);
     }
     prepareRoute(method, path, schema, handler) {
+        schema = withTextSlots(schema);
         // Route provenance for the CLI's capability walk, which sets NIFRA_ROUTE_SITES while it loads the
         // app: the module that registered the route, read where a static scan cannot see the path.
         if (hookAuditRuntime &&
@@ -1604,6 +1626,15 @@ export class Server {
             defaultOnValidationError: this.defaultOnValidationError,
         }, method, path, schema, handler);
         const { pattern, bodyLimit, capabilities, routeDecorations, hasDecorations, idempotent, ledgered, responseContract, lanes, routeAssurance, } = compiled;
+        // A schema that writes its answer its own way (`t.bytes()`) wraps every stage that can answer.
+        const stages = withAnswerSteps(schema, method, path, {
+            handler,
+            beforeHandle: this.beforeHandleHooks,
+            afterHandle: this.afterHandleHooks,
+            onError: this.onErrorHooks,
+        });
+        handler = stages.handler;
+        const { beforeHandle, afterHandle, onError } = stages;
         if (idempotent !== undefined && this.idempotencyRuntime !== undefined) {
             handler = this.idempotencyRuntime.wrapHandler(handler);
         }
@@ -1622,11 +1653,11 @@ export class Server {
         const fusedBodyRunner = fusedBody
             ? this.buildFusedBodyRunner(handler, schema?.body, hasDecorations ? routeDecorations : undefined, bodyLimit ?? UNLIMITED_BODY_BYTES)
             : isFusedBodyLifecycle
-                ? this.buildFusedBodyDeriveBeforeAfterRunner(handler, this.derives[0], this.beforeHandleHooks[0], this.afterHandleHooks[0], schema?.body, bodyLimit ?? UNLIMITED_BODY_BYTES)
+                ? this.buildFusedBodyDeriveBeforeAfterRunner(handler, this.derives[0], beforeHandle[0], afterHandle[0], schema?.body, bodyLimit ?? UNLIMITED_BODY_BYTES)
                 : isFusedLifecycle && lifecycleHookLane === "derive-before"
-                    ? this.buildFusedDeriveBeforeRunner(handler, this.derives[0], this.beforeHandleHooks[0], undefined, schema?.query, bodyLimit ?? UNLIMITED_BODY_BYTES)
+                    ? this.buildFusedDeriveBeforeRunner(handler, this.derives[0], beforeHandle[0], undefined, schema?.query, bodyLimit ?? UNLIMITED_BODY_BYTES)
                     : isFusedLifecycle && lifecycleHookLane === "derive-before-after"
-                        ? this.buildFusedDeriveBeforeRunner(handler, this.derives[0], this.beforeHandleHooks[0], this.afterHandleHooks[0], schema?.query, bodyLimit ?? UNLIMITED_BODY_BYTES)
+                        ? this.buildFusedDeriveBeforeRunner(handler, this.derives[0], beforeHandle[0], afterHandle[0], schema?.query, bodyLimit ?? UNLIMITED_BODY_BYTES)
                         : undefined;
         const fusedWeb = bare && this.aroundHooks.length === 0
             ? this.buildFusedWeb(handler, hasDecorations ? routeDecorations : undefined, isContextlessNoArgArrow(handler), bodyLimit ?? UNLIMITED_BODY_BYTES)
@@ -1635,20 +1666,20 @@ export class Server {
                 : fusedBody
                     ? this.buildFusedBodyWeb(fusedBodyRunner)
                     : isFusedBodyLifecycle
-                        ? this.buildFusedBodyDeriveBeforeAfter(handler, this.derives[0], this.beforeHandleHooks[0], this.afterHandleHooks[0], schema?.body, bodyLimit ?? UNLIMITED_BODY_BYTES)
+                        ? this.buildFusedBodyDeriveBeforeAfter(handler, this.derives[0], beforeHandle[0], afterHandle[0], schema?.body, bodyLimit ?? UNLIMITED_BODY_BYTES)
                         : isFusedLifecycle && lifecycleHookLane === "derive-before"
-                            ? this.buildFusedDeriveBefore(handler, this.derives[0], this.beforeHandleHooks[0], schema?.query, bodyLimit ?? UNLIMITED_BODY_BYTES)
+                            ? this.buildFusedDeriveBefore(handler, this.derives[0], beforeHandle[0], schema?.query, bodyLimit ?? UNLIMITED_BODY_BYTES)
                             : isFusedLifecycle && lifecycleHookLane === "derive-before-after"
-                                ? this.buildFusedDeriveBeforeAfter(handler, this.derives[0], this.beforeHandleHooks[0], this.afterHandleHooks[0], schema?.query, bodyLimit ?? UNLIMITED_BODY_BYTES)
+                                ? this.buildFusedDeriveBeforeAfter(handler, this.derives[0], beforeHandle[0], afterHandle[0], schema?.query, bodyLimit ?? UNLIMITED_BODY_BYTES)
                                 : undefined;
         const program = compileRouteProgram({
             schema,
             handler: handler,
             derives: this.derives,
             authStages: compiled.authStages,
-            beforeHandle: this.beforeHandleHooks,
-            afterHandle: this.afterHandleHooks,
-            onError: this.onErrorHooks,
+            beforeHandle,
+            afterHandle,
+            onError,
             decorations: routeDecorations,
             hasDecorations,
             bodySchema: schema?.body,
@@ -1676,9 +1707,9 @@ export class Server {
             authStages: [...compiled.authStages],
             decorations: routeDecorations,
             hasDecorations,
-            beforeHandle: [...this.beforeHandleHooks],
-            afterHandle: [...this.afterHandleHooks],
-            onError: [...this.onErrorHooks],
+            beforeHandle: [...beforeHandle],
+            afterHandle: [...afterHandle],
+            onError: [...onError],
             lifecycleHookLane: lanes.lifecycleHookLane,
             around: [...this.aroundHooks],
             execution,
@@ -2064,6 +2095,7 @@ export class Server {
         // Cleanup the source registered (a pool, a queue consumer) belongs to the server that now runs
         // its routes; dropping it would leak the resource past `stop()`.
         this.stopHooks.push(...source.stopHooks);
+        this.stoppingHooks.push(...source.stoppingHooks);
         this.mcpResourceList.push(...source.mcpResourceList);
         this.mcpPromptList.push(...source.mcpPromptList);
     }
@@ -2691,16 +2723,20 @@ export class Server {
                         return refuse(jsonError(500, "internal_error"));
                     }
                 };
-                const child = mount.authStages.length === 0
-                    ? upgrade()
-                    : thenMaybe(authenticateMount(mount.authStages, request, platform, this.logger), (refusal) => refusal === undefined ? upgrade() : refuse(refusal));
                 const settle = (outcome) => outcome.kind === "pass" ||
                     (outcome.kind === "reject" && outcome.response.status === 404 && selected.fallbackOn404)
                     ? dispatch(selectedIndex + 1)
                     : outcome.kind === "reject"
                         ? refuse(outcome.response)
                         : outcome;
-                return child instanceof Promise ? child.then(settle) : settle(child);
+                const run = () => {
+                    const child = upgrade();
+                    return child instanceof Promise ? child.then(settle) : settle(child);
+                };
+                // Only a child's miss may fall through, never an authentication refusal.
+                return mount.authStages.length === 0
+                    ? run()
+                    : thenMaybe(authenticateMount(mount.authStages, request, platform, this.logger), (refusal) => (refusal === undefined ? run() : refuse(refusal)));
             };
             return dispatch(0);
         };
@@ -3094,20 +3130,26 @@ export class Server {
                 return fallback ?? jsonError(404, "not_found");
             const selected = mount;
             const run = () => {
+                const reused = selected.stripPrefix ? selected.wsPassed?.get(request) : undefined;
                 const childRequest = selected.stripPrefix
-                    ? (selected.wsPassed?.get(request) ?? stripMountPrefix(request, selected.path))
+                    ? (reused ?? stripMountPrefix(request, selected.path))
                     : request;
-                return selected.handler(childRequest, platform);
+                // HTTP authentication may have marked the original since the WebSocket pass.
+                if (reused !== undefined && isAuthenticatedRequest(request)) {
+                    markAuthenticatedRequest(reused);
+                }
+                const outcome = selected.handler(childRequest, platform);
+                if (!replayable || !selected.fallbackOn404)
+                    return outcome;
+                if (outcome instanceof Promise) {
+                    return outcome.then((response) => response.status === 404 ? dispatch(index + 1, response) : response);
+                }
+                return outcome.status === 404 ? dispatch(index + 1, outcome) : outcome;
             };
-            const outcome = mount.authStages.length === 0
+            // Keep gate refusals outside the child's 404 fallthrough path.
+            return mount.authStages.length === 0
                 ? run()
                 : thenMaybe(authenticateMount(mount.authStages, request, platform, this.logger), (refusal) => refusal ?? run());
-            if (!replayable || !mount.fallbackOn404)
-                return outcome;
-            if (outcome instanceof Promise) {
-                return outcome.then((response) => response.status === 404 ? dispatch(index + 1, response) : response);
-            }
-            return outcome.status === 404 ? dispatch(index + 1, outcome) : outcome;
         };
         return dispatch(first);
     }
@@ -4874,11 +4916,12 @@ export class Server {
      * The Bun semantics: poll `pendingRequests` (awaiting
      * `stop()`'s promise drops in-flight requests), and decide graceful-vs-forced in
      * ONE call (Bun can't escalate an already-graceful `stop()` to a forced close).
-     * New connections may be accepted during the drain window; in a real deploy the
-     * load balancer has already stopped routing here, and `drainMs` bounds it. Open WebSockets
-     * get a 1001 close at once and the same window to finish it, before any `onStop` hook runs.
+     * New connections may be accepted during the drain window; `delayMs` is the time a load balancer
+     * gets to stop routing here first. The `onStopping` hooks run before that delay, the `onStop`
+     * hooks after the drain. Open WebSockets get a 1001 close when the drain starts and the same
+     * window to finish it; a socket opened after `stop()` began is closed at once.
      */
-    async stop({ drainMs = DEFAULT_DRAIN_MS } = {}) {
+    async stop({ drainMs = DEFAULT_DRAIN_MS, delayMs = 0 } = {}) {
         const onSignal = this.signalHandler;
         if (onSignal !== undefined) {
             this.signalHandler = undefined;
@@ -4888,6 +4931,9 @@ export class Server {
         if (server === undefined)
             return;
         this.bunServer = undefined;
+        await this[SERVER_LIFECYCLE]("stopping");
+        if (delayMs > 0)
+            await Bun.sleep(delayMs);
         const sockets = this.bunSockets;
         this.bunSockets = undefined;
         if (sockets !== undefined)
@@ -4899,14 +4945,25 @@ export class Server {
             await Bun.sleep(DRAIN_POLL_MS);
         }
         server.stop(busy()); // force-close iff stragglers remain past the deadline
-        if (this.stopHooks.length === 0)
+        await this[SERVER_LIFECYCLE]("stopped");
+    }
+    /**
+     * @internal Run the `onStopping` or the `onStop` hooks, each bounded. A runtime adapter that drains
+     * its own listener calls it on either side of the drain, as `stop()` does here.
+     */
+    async [SERVER_LIFECYCLE](phase) {
+        const hooks = phase === "stopping" ? this.stoppingHooks : this.stopHooks;
+        if (hooks.length === 0)
             return;
-        const callbacks = this.stopHooks.map((hook) => Promise.resolve().then(hook));
-        const settled = Promise.allSettled(callbacks);
+        let timer;
         await Promise.race([
-            settled,
-            new Promise((resolve) => setTimeout(resolve, STOP_HOOK_TIMEOUT_MS)),
+            Promise.allSettled(hooks.map((hook) => Promise.resolve().then(hook))),
+            new Promise((resolve) => {
+                timer = setTimeout(resolve, STOP_HOOK_TIMEOUT_MS);
+            }),
         ]);
+        // A pending bound would hold the event loop open after every hook settled.
+        clearTimeout(timer);
     }
     installSignalHandlers(drain) {
         // Drain, then let the process exit naturally - the stopped server no longer