@nifrajs/core 1.8.0 → 1.9.0

package/dist/server/server.js

@@ -1,3 +1,4 @@
+import { admitDeadline, createRequestBudget, createUnboundedRequestBudget, NIFRA_DEADLINE_HEADER, } from "@nifrajs/budget";
 import { FrameworkError, RouteConfigError } from "../errors.js";
 import { assuranceDeclarationsOf, assuranceEvidenceFor, NIFRA_ASSURANCE_IDS, } from "../internal/route-assurance.js";
 import { EMPTY_PARAMS, Router } from "../router/router.js";
@@ -107,10 +108,15 @@ const TEXT_DECODER = new TextDecoder();
  * reused at zero per-request cost.
  */
 let neverAbortSignal;
+let unboundedRequestBudget;
 const getNeverAbortSignal = () => {
     neverAbortSignal ??= new AbortController().signal;
     return neverAbortSignal;
 };
+const getUnboundedRequestBudget = () => {
+    unboundedRequestBudget ??= createUnboundedRequestBudget(getNeverAbortSignal());
+    return unboundedRequestBudget;
+};
 function jsonError(status, error, headers) {
     return Response.json({ ok: false, error }, headers !== undefined ? { status, headers } : { status });
 }
@@ -282,6 +288,13 @@ function decodeParams(raw) {
     }
     return out ?? raw;
 }
+function hasReplacementParam(params) {
+    for (const key in params) {
+        if (params[key].includes("\uFFFD"))
+            return true;
+    }
+    return false;
+}
 class LazyResponseControls {
     status;
     _headers;
@@ -329,39 +342,47 @@ function statusInit(init) {
     return typeof init === "number" ? { status: init } : init;
 }
 class RequestContext {
-    params;
-    signal;
-    env;
-    waitUntil;
-    body;
-    [CONTEXT_SEARCH];
-    setValue;
-    queryValue;
-    queryReady;
-    cookiesValue;
-    source;
-    maxBodyBytes;
-    constructor(source, params, search, signal, platform, maxBodyBytes) {
+    constructor(source, params, searchOrMaxBodyBytes, signal, budget, platform, maxBodyBytes) {
         this.source = source;
         this.params = params;
-        this[CONTEXT_SEARCH] = search;
-        this.signal = signal;
-        this.env = platform?.env;
-        this.waitUntil = platform?.waitUntil ?? fallbackWaitUntil;
+        if (typeof searchOrMaxBodyBytes === "number") {
+            this.maxBodyBytes = searchOrMaxBodyBytes;
+            return;
+        }
+        if (searchOrMaxBodyBytes !== undefined)
+            this.searchValue = searchOrMaxBodyBytes;
+        this.signalValue = signal;
+        this.budgetValue = budget;
+        if (platform !== undefined)
+            this.platformValue = platform;
         this.maxBodyBytes = maxBodyBytes;
-        this.setValue = undefined;
-        this.body = undefined;
-        this.queryValue = undefined;
-        this.queryReady = false;
-        this.cookiesValue = undefined;
+    }
+    static native(source, params, maxBodyBytes) {
+        return new RequestContext(source, params, maxBodyBytes);
     }
     [CONTEXT_SET]() {
         return this.setValue;
     }
+    get [CONTEXT_SEARCH]() {
+        this.searchValue ??= searchOf(this.source.url);
+        return this.searchValue;
+    }
     get set() {
         this.setValue ??= new LazyResponseControls();
         return this.setValue;
     }
+    get signal() {
+        return this.signalValue ?? getNeverAbortSignal();
+    }
+    get budget() {
+        return this.budgetValue ?? getUnboundedRequestBudget();
+    }
+    get env() {
+        return this.platformValue?.env;
+    }
+    get waitUntil() {
+        return this.platformValue?.waitUntil ?? fallbackWaitUntil;
+    }
     get req() {
         return requestOf(this.source);
     }
@@ -482,17 +503,16 @@ const JSON_CT_HEADERS = new Headers({
     "content-type": "application/json;charset=utf-8",
 });
 const JSON_INIT_200 = { status: 200, headers: JSON_CT_HEADERS };
-/** Fused-lane respond when the handler ran with NO context (so `c.set` can't exist): the fast
- * JSON respond directly, with `toResponse` + the empty controls as the exact-semantics fallback. */
+/** Fused-lane respond when `c.set` is untouched. Bun 1.3's native `Response.json` now beats the
+ * older hand-inlined stringify + Response construction on this lane while preserving the exact
+ * body/content-type contract; keep the generic fallback for non-JSON values. */
 function fusedRespondNoSet(result) {
     if (result !== undefined &&
         !(result instanceof Response) &&
         typeof result === "object" &&
         result !== null &&
         !isResponseResult(result)) {
-        const body = JSON.stringify(result);
-        if (body !== undefined)
-            return new Response(body, JSON_INIT_200);
+        return Response.json(result);
     }
     return toResponse(result, EMPTY_RESPONSE_CONTROLS);
 }
@@ -634,6 +654,9 @@ export class Server {
     maxBodyBytes;
     wsMaxPayloadBytes;
     requestTimeoutMs;
+    acceptInboundDeadlines;
+    maxInboundDeadlineMs;
+    deadlineAdmissionOptions;
     gracefulSignals;
     logger;
     /** App-wide validation-error fallback; a route's own `schema.onValidationError` takes precedence. */
@@ -674,6 +697,18 @@ export class Server {
         this.maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
         this.wsMaxPayloadBytes = options.wsMaxPayloadBytes ?? this.maxBodyBytes;
         this.requestTimeoutMs = options.requestTimeoutMs ?? 0;
+        this.acceptInboundDeadlines = options.acceptInboundDeadlines ?? false;
+        this.maxInboundDeadlineMs = options.maxInboundDeadlineMs ?? 30_000;
+        this.deadlineAdmissionOptions = Object.freeze({
+            localTimeoutMs: this.requestTimeoutMs,
+            maxInboundDeadlineMs: this.maxInboundDeadlineMs,
+        });
+        if (!Number.isFinite(this.requestTimeoutMs) || this.requestTimeoutMs < 0) {
+            throw new RangeError("requestTimeoutMs must be a finite non-negative number");
+        }
+        if (!Number.isFinite(this.maxInboundDeadlineMs) || this.maxInboundDeadlineMs <= 0) {
+            throw new RangeError("maxInboundDeadlineMs must be a finite positive number");
+        }
         this.gracefulSignals = options.gracefulSignals ?? false;
         this.logger = options.logger ?? jsonLogger();
         this.defaultOnValidationError = options.onValidationError;
@@ -1089,6 +1124,17 @@ export class Server {
             ? outcome.then((response) => this.applyOnResponseAndFinalize(response, this.takeResponseRequest(source)))
             : this.applyOnResponseAndFinalize(outcome, this.takeResponseRequest(source));
     }
+    /** Web response path when Bun already matched the route. The lifecycle and response hooks remain
+     * exactly the same as {@link fetchSource}; only portable URL scanning + trie lookup are skipped. */
+    fetchMatched(source, entry, params) {
+        const outcome = this.runMatched(source, undefined, entry, params, undefined, toResponse, IDENTITY_RESPONSE, RESPONSE_TIMEOUT, true);
+        if (this.onResponseHooks.length === 0 && this.onResponseFinalizedHooks.length === 0) {
+            return outcome;
+        }
+        return outcome instanceof Promise
+            ? outcome.then((response) => this.applyOnResponseAndFinalize(response, requestOf(source)))
+            : this.applyOnResponseAndFinalize(outcome, requestOf(source));
+    }
     /**
      * Like {@link fetch}, but renders a plain-data result **without** building a Web `Response` — the
      * `@nifrajs/node` adapter serializes the returned primitives straight to the socket, skipping the undici
@@ -1131,9 +1177,9 @@ export class Server {
         const match = this.wsRouter.find("GET", url.pathname);
         if (!match.found)
             return WS_PASS; // upgrade header, no WS route here → normal routing decides
-        const params = match.params === EMPTY_PARAMS || !url.pathname.includes("%")
-            ? match.params
-            : decodeParams(match.params);
+        // Inspect only captured values for escapes. Scanning the full pathname repeated work the router
+        // already did and made every plain dynamic route pay for unrelated static path bytes.
+        const params = match.params === EMPTY_PARAMS ? match.params : decodeParams(match.params);
         if (params === null)
             return { kind: "reject", response: jsonError(400, "malformed_path") };
         const handler = match.payload.handler;
@@ -1160,7 +1206,8 @@ export class Server {
         if (handler.upgrade === undefined) {
             return { kind: "upgrade", handler, data: undefined, pubsub };
         }
-        const ctx = new RequestContext(req, params, url.search, getNeverAbortSignal(), platform, this.maxBodyBytes);
+        const upgradeSignal = getNeverAbortSignal();
+        const ctx = new RequestContext(req, params, url.search, upgradeSignal, createUnboundedRequestBudget(upgradeSignal), platform, this.maxBodyBytes);
         const settle = (value) => value instanceof Response
             ? { kind: "reject", response: value }
             : { kind: "upgrade", handler, data: value, pubsub };
@@ -1283,37 +1330,63 @@ export class Server {
             }
             return wrapResponse(jsonError(404, "not_found"));
         }
-        const params = match.params === EMPTY_PARAMS || !url.pathname.includes("%")
-            ? match.params
-            : decodeParams(match.params);
+        // Inspect only captured values for escapes. Scanning the full pathname repeated work the router
+        // already did and made every plain dynamic route pay for unrelated static path bytes.
+        const params = match.params === EMPTY_PARAMS ? match.params : decodeParams(match.params);
         if (params === null) {
             return wrapResponse(jsonError(400, "malformed_path"));
         }
-        const entry = match.payload;
-        // A per-request cancellation signal. Only allocate a real controller when a
-        // timeout is armed; otherwise share a never-aborting signal so the (common)
-        // no-timeout path pays nothing.
+        return this.runMatched(source, platform, match.payload, params, url.search, finalize, wrapResponse, onTimeout, webFast);
+    }
+    /** Run a route that has already been matched by the runtime or Nifra's portable router. */
+    runMatched(source, platform, entry, params, search, finalize, wrapResponse, onTimeout, webFast) {
+        // Translate the absolute wire deadline once, clamp it to local policy, then use the resulting
+        // duration for both c.signal and c.budget. A client can only shorten work, never extend it.
+        // Most requests have neither a local timeout nor a propagated deadline. Detect that case with
+        // one header lookup and skip policy validation, wall-clock sampling, and admission objects. A
+        // present wire deadline still goes through the full fail-closed parser/clamp below.
+        const admission = !this.acceptInboundDeadlines
+            ? this.requestTimeoutMs === 0
+                ? undefined
+                : {
+                    ok: true,
+                    inherited: false,
+                    timeoutMs: this.requestTimeoutMs,
+                    deadline: Math.floor(Date.now() + this.requestTimeoutMs),
+                }
+            : this.requestTimeoutMs === 0 && headerOf(source, NIFRA_DEADLINE_HEADER) === null
+                ? undefined
+                : admitDeadline(source.headers, this.deadlineAdmissionOptions);
+        if (admission !== undefined && !admission.ok) {
+            return wrapResponse(jsonError(admission.status, admission.reason));
+        }
+        const effectiveTimeoutMs = admission?.timeoutMs ?? 0;
+        // Only allocate a controller for a finite budget; the historical no-timeout path remains
+        // allocation-light and exposes an unbounded budget that is never propagated on the wire.
         let controller;
         let signal = getNeverAbortSignal();
-        if (this.requestTimeoutMs > 0) {
+        if (effectiveTimeoutMs > 0) {
             controller = new AbortController();
             signal = controller.signal;
         }
+        const budget = controller === undefined
+            ? getUnboundedRequestBudget()
+            : createRequestBudget({ deadline: admission.deadline, signal });
         // A bare route runs synchronously (no schema/derives/hooks); everything else keeps the full async
         // lifecycle. `runBare` returns a value directly for a sync handler — no promise.
         let outcome;
         if (webFast && entry.fusedWeb !== undefined) {
             // Fused Web lane (bare route, no around): one closure end to end. Sound cast — webFast is
             // passed only by the `fetch` path, where T = Response by construction.
-            outcome = entry.fusedWeb(source, params, url.search, signal, platform);
+            outcome = entry.fusedWeb(source, params, search, signal, budget, platform, false);
         }
         else if (entry.contextlessBare) {
-            outcome = this.runContextlessBare(entry, source, params, url.search, signal, platform, finalize, wrapResponse);
+            outcome = this.runContextlessBare(entry, source, params, search, signal, budget, platform, finalize, wrapResponse);
         }
         else {
             // Build the context up front so `onError` always has it. Query, cookies, headers, and body helpers
             // stay lazy, but their accessors live on the prototype instead of allocating per-request closures.
-            const ctx = new RequestContext(source, params, url.search, signal, platform, this.maxBodyBytes);
+            const ctx = new RequestContext(source, params, search, signal, budget, platform, this.maxBodyBytes);
             if (entry.around.length === 0) {
                 outcome = entry.bare
                     ? this.runBare(entry, ctx, finalize, wrapResponse)
@@ -1336,29 +1409,32 @@ export class Server {
         // The request timeout only bounds work that is actually pending — a synchronous (bare) result is
         // already complete and can't time out, so it's returned as-is (no 503 race, no promise).
         if (controller !== undefined && outcome instanceof Promise) {
-            return this.withTimeout(outcome, controller, onTimeout);
+            const timedOut = admission?.inherited === true
+                ? () => wrapResponse(jsonError(504, "deadline_exceeded"))
+                : onTimeout;
+            return this.withTimeout(outcome, controller, timedOut, Math.max(0, Math.ceil(budget.remaining())));
         }
         return outcome;
     }
     /** The narrowest bare route: a syntactic `() => ...` handler cannot observe the context argument, so
      * successful requests can skip allocating `RequestContext`. Errors still allocate one for logging. */
-    runContextlessBare(entry, source, params, search, signal, platform, finalize, wrapResponse) {
+    runContextlessBare(entry, source, params, search, signal, budget, platform, finalize, wrapResponse) {
         let result;
         try {
             result = entry.handler();
         }
         catch (err) {
-            return this.contextlessBareError(err, source, params, search, signal, platform, wrapResponse);
+            return this.contextlessBareError(err, source, params, search, signal, budget, platform, wrapResponse);
         }
         if (result instanceof Promise) {
-            return result.then((value) => finalize(value, EMPTY_RESPONSE_CONTROLS), (err) => this.contextlessBareError(err, source, params, search, signal, platform, wrapResponse));
+            return result.then((value) => finalize(value, EMPTY_RESPONSE_CONTROLS), (err) => this.contextlessBareError(err, source, params, search, signal, budget, platform, wrapResponse));
         }
         return finalize(result, EMPTY_RESPONSE_CONTROLS);
     }
-    contextlessBareError(err, source, params, search, signal, platform, wrapResponse) {
+    contextlessBareError(err, source, params, search, signal, budget, platform, wrapResponse) {
         if (err instanceof Response)
             return wrapResponse(err);
-        const ctx = new RequestContext(source, params, search, signal, platform, this.maxBodyBytes);
+        const ctx = new RequestContext(source, params, search, signal, budget, platform, this.maxBodyBytes);
         this.logRequestError(err, ctx);
         return wrapResponse(jsonError(500, "internal_error"));
     }
@@ -1407,22 +1483,28 @@ export class Server {
             // `() => ...` can't observe the context — skip allocating one entirely (errors still build
             // one for the structured log, exactly like runContextlessBare).
             const contextlessHandler = handler;
-            return (source, params, search, signal, platform) => {
+            return (source, params, search, signal, budget, platform, nativeContext) => {
                 let result;
                 try {
                     result = contextlessHandler();
                 }
                 catch (err) {
-                    return logError(err, new RequestContext(source, params, search, signal, platform, maxBodyBytes));
+                    return logError(err, nativeContext
+                        ? RequestContext.native(source, params, maxBodyBytes)
+                        : new RequestContext(source, params, search, signal, budget, platform, maxBodyBytes));
                 }
                 if (result instanceof Promise) {
-                    return result.then(fusedRespondNoSet, (err) => logError(err, new RequestContext(source, params, search, signal, platform, maxBodyBytes)));
+                    return result.then(fusedRespondNoSet, (err) => logError(err, nativeContext
+                        ? RequestContext.native(source, params, maxBodyBytes)
+                        : new RequestContext(source, params, search, signal, budget, platform, maxBodyBytes)));
                 }
                 return fusedRespondNoSet(result);
             };
         }
-        return (source, params, search, signal, platform) => {
-            const ctx = new RequestContext(source, params, search, signal, platform, maxBodyBytes);
+        return (source, params, search, signal, budget, platform, nativeContext) => {
+            const ctx = nativeContext
+                ? RequestContext.native(source, params, maxBodyBytes)
+                : new RequestContext(source, params, search, signal, budget, platform, maxBodyBytes);
             if (decorations !== undefined)
                 Object.assign(ctx, decorations);
             let result;
@@ -1738,13 +1820,13 @@ export class Server {
      * handlers can bail) and return 503; the in-flight work keeps running but its
      * result is discarded — JS can't forcibly cancel a promise.
      */
-    async withTimeout(work, controller, onTimeout) {
+    async withTimeout(work, controller, onTimeout, timeoutMs) {
         let timer;
         const timeout = new Promise((resolve) => {
             timer = setTimeout(() => {
                 controller.abort();
                 resolve(onTimeout());
-            }, this.requestTimeoutMs);
+            }, timeoutMs);
         });
         try {
             return await Promise.race([work, timeout]);
@@ -1888,6 +1970,137 @@ export class Server {
     async readBoundedJson(req) {
         return readBoundedJsonSource(req, this.maxBodyBytes);
     }
+    /** Compile portable route registrations into Bun's native route table. Apps with request-rewrite
+     * hooks or WebSockets retain the single portable dispatcher because those features must run before
+     * route selection/upgrade. Named wildcards also stay on the fallback until Bun exposes their raw
+     * capture semantics; static and `:param` routes take the native lane. */
+    buildBunNativeRoutes() {
+        if (this.onRequestHooks.length > 0 || this.wsRouteCount > 0)
+            return undefined;
+        const routes = Object.create(null);
+        const mayUseFusedNative = this.requestTimeoutMs === 0 &&
+            this.onResponseHooks.length === 0 &&
+            this.onResponseFinalizedHooks.length === 0;
+        const unboundedSignal = mayUseFusedNative ? getNeverAbortSignal() : undefined;
+        const unboundedBudget = mayUseFusedNative ? getUnboundedRequestBudget() : undefined;
+        let count = 0;
+        for (const { method, path, entry } of this.rawEntries) {
+            if (path.includes("*"))
+                continue;
+            let methods = routes[path];
+            if (methods === undefined) {
+                methods = Object.create(null);
+                routes[path] = methods;
+            }
+            const paramNames = path
+                .split("/")
+                .filter((segment) => segment.charCodeAt(0) === 58 /* : */)
+                .map((segment) => segment.slice(1));
+            const fused = mayUseFusedNative ? entry.fusedWeb : undefined;
+            if (fused !== undefined) {
+                // Deliberately choose deadline-aware vs zero-admission closures HERE instead of branching on
+                // `acceptInboundDeadlines` per request. JSC can then flatten the default closure through the
+                // handler + Response.json; retaining that route-invariant branch cost ~7% on a dynamic GET.
+                if (paramNames.length === 0) {
+                    methods[method] = this.acceptInboundDeadlines
+                        ? (request) => request.headers.get(NIFRA_DEADLINE_HEADER) !== null
+                            ? this.fetchMatched(request, entry, EMPTY_PARAMS)
+                            : fused(request, EMPTY_PARAMS, undefined, unboundedSignal, unboundedBudget, undefined, true)
+                        : (request) => fused(request, EMPTY_PARAMS, undefined, unboundedSignal, unboundedBudget, undefined, true);
+                }
+                else if (paramNames.length === 1) {
+                    const paramName = paramNames[0];
+                    const handler = entry.handler;
+                    const decorations = entry.hasDecorations ? entry.decorations : undefined;
+                    const fail = (error, ctx) => {
+                        if (error instanceof Response)
+                            return error;
+                        this.logRequestError(error, ctx);
+                        return jsonError(500, "internal_error");
+                    };
+                    methods[method] = this.acceptInboundDeadlines
+                        ? (request) => {
+                            const params = request.params ?? EMPTY_PARAMS;
+                            if (params[paramName]?.includes("\uFFFD") === true)
+                                return this.fetchSource(request);
+                            if (request.headers.get(NIFRA_DEADLINE_HEADER) !== null) {
+                                return this.fetchMatched(request, entry, params);
+                            }
+                            const ctx = RequestContext.native(request, params, this.maxBodyBytes);
+                            if (decorations !== undefined)
+                                Object.assign(ctx, decorations);
+                            let result;
+                            try {
+                                result = handler(ctx);
+                            }
+                            catch (error) {
+                                return fail(error, ctx);
+                            }
+                            return result instanceof Promise
+                                ? result.then((value) => fusedRespond(value, ctx), (error) => fail(error, ctx))
+                                : fusedRespond(result, ctx);
+                        }
+                        : (request) => {
+                            const params = request.params ?? EMPTY_PARAMS;
+                            if (params[paramName]?.includes("\uFFFD") === true)
+                                return this.fetchSource(request);
+                            const ctx = RequestContext.native(request, params, this.maxBodyBytes);
+                            if (decorations !== undefined)
+                                Object.assign(ctx, decorations);
+                            let result;
+                            try {
+                                result = handler(ctx);
+                            }
+                            catch (error) {
+                                return fail(error, ctx);
+                            }
+                            return result instanceof Promise
+                                ? result.then((value) => fusedRespond(value, ctx), (error) => fail(error, ctx))
+                                : fusedRespond(result, ctx);
+                        };
+                }
+                else {
+                    methods[method] = this.acceptInboundDeadlines
+                        ? (request) => {
+                            const params = request.params ?? EMPTY_PARAMS;
+                            if (hasReplacementParam(params))
+                                return this.fetchSource(request);
+                            return request.headers.get(NIFRA_DEADLINE_HEADER) !== null
+                                ? this.fetchMatched(request, entry, params)
+                                : fused(request, params, undefined, unboundedSignal, unboundedBudget, undefined, true);
+                        }
+                        : (request) => {
+                            const params = request.params ?? EMPTY_PARAMS;
+                            if (hasReplacementParam(params))
+                                return this.fetchSource(request);
+                            return fused(request, params, undefined, unboundedSignal, unboundedBudget, undefined, true);
+                        };
+                }
+            }
+            else if (paramNames.length === 0) {
+                methods[method] = (request) => this.fetchMatched(request, entry, EMPTY_PARAMS);
+            }
+            else if (paramNames.length === 1) {
+                const paramName = paramNames[0];
+                methods[method] = (request) => {
+                    const params = request.params ?? EMPTY_PARAMS;
+                    if (params[paramName]?.includes("\uFFFD") === true)
+                        return this.fetchSource(request);
+                    return this.fetchMatched(request, entry, params);
+                };
+            }
+            else {
+                methods[method] = (request) => {
+                    const params = request.params ?? EMPTY_PARAMS;
+                    if (hasReplacementParam(params))
+                        return this.fetchSource(request);
+                    return this.fetchMatched(request, entry, params);
+                };
+            }
+            count += 1;
+        }
+        return count === 0 ? undefined : routes;
+    }
     /**
      * Start a `Bun.serve` instance bound to `port` (use `0` for an ephemeral port).
      *
@@ -1920,8 +2133,14 @@ export class Server {
             ? undefined
             : getWsRuntime().bunHandlers(this.topics);
         const reusePort = options?.reusePort === true;
+        const nativeRoutes = wsHandlers === undefined ? this.buildBunNativeRoutes() : undefined;
         const running = (wsHandlers === undefined
-            ? Bun.serve({ port, reusePort, fetch: (req) => this.fetch(req) })
+            ? Bun.serve({
+                port,
+                reusePort,
+                ...(nativeRoutes === undefined ? {} : { routes: nativeRoutes }),
+                fetch: (req) => this.fetch(req),
+            })
             : Bun.serve({
                 port,
                 reusePort,