@nifrajs/core 0.1.0-alpha.1

package/dist/server/server.js

@@ -0,0 +1,1660 @@
+import { FrameworkError } from "../errors.js";
+import { EMPTY_PARAMS, Router } from "../router/router.js";
+import { drainCapped, parseContentLength, readBoundedBytes } from "./body.js";
+import { parseCookies, serializeCookie } from "./cookies.js";
+import { jsonLogger } from "./logger.js";
+import { getWsRuntime } from "./ws-hook.js";
+/** The concrete `Request` for a source — itself when a real `Request` was passed (the Web path), or the
+ * lazily-built one (the Node adapter). A real `Request` IS a `RequestSource`, so no wrapper is allocated
+ * on the Web hot path. */
+function requestOf(source) {
+    return source.request ?? source;
+}
+function headerOf(source, name) {
+    return source.header?.(name) ?? source.headers.get(name);
+}
+const RESPONSE_RESULT = Symbol.for("nifra.response.result");
+const CONTEXT_SET = Symbol("nifra.context.set");
+const CONTEXT_SEARCH = Symbol("nifra.context.search");
+const functionToString = Function.prototype.toString;
+const CONTEXTLESS_ARROW = /^(?:async\s*)?\(\s*\)\s*(?::[\s\S]*?)?=>/;
+function isResponseResult(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        value[RESPONSE_RESULT] === true &&
+        typeof value.toResponse === "function");
+}
+/** Off-edge `waitUntil`: run the background work fire-and-forget, never leaking an unhandled
+ * rejection. Edge runtimes pass their own (Workers `ctx.waitUntil`) via the platform arg. */
+const fallbackWaitUntil = (promise) => {
+    void promise.catch(() => { });
+};
+const WS_PASS = { kind: "pass" };
+/** `app.ws()` (and everything downstream of it) needs the runtime `@nifrajs/core/ws` registers. */
+function requireWsRuntime() {
+    const runtime = getWsRuntime();
+    if (runtime === undefined) {
+        throw new FrameworkError("WS_RUNTIME_MISSING", 'app.ws() needs the WebSocket runtime, which ships as a subpath so no-WebSocket apps stay lean. Add `import "@nifrajs/core/ws"` at your server entry.');
+    }
+    return runtime;
+}
+/**
+ * Name + ergonomics for a plugin. `app.use(myPlugin)` applies it once; a second `use` of the same
+ * name is skipped (idempotent), so plugins can depend on each other without double-registering hooks.
+ *
+ * ```ts
+ * export const requestId = definePlugin("requestId", (app) => app.derive(() => ({ requestId: uuid() })))
+ * app.use(requestId)   // downstream handlers see c.requestId
+ * ```
+ */
+export function definePlugin(name, apply) {
+    return Object.assign(apply, { pluginName: name });
+}
+/**
+ * Define a type-**identity** plugin: it registers routes/hooks as a side effect but returns the app with
+ * its `Registry` + `Context` UNCHANGED. Use this (not {@link definePlugin}) for any plugin that doesn't
+ * add context types — e.g. one mounting an auth handler. It threads the caller's *concrete* server type
+ * through `use`, so routes declared after `app.use(plugin)` keep their types.
+ *
+ * Why a dedicated helper: `definePlugin((app) => app)` infers `app: Server<any, any>`, so `use` returns
+ * `Server<any, any>` and the whole typed client collapses to `any`. The explicit generic return type here
+ * (which a plain `Object.assign` can't preserve) is what keeps `use` returning the precise server type.
+ *
+ * ```ts
+ * export const audit = defineIdentityPlugin("audit", (app) => app.onResponse(logResponse))
+ * const api = server().get("/a", h).use(audit).get("/b", h) // /a AND /b stay typed
+ * ```
+ */
+export function defineIdentityPlugin(name, apply) {
+    return Object.assign(apply, { pluginName: name });
+}
+const DEFAULT_MAX_BODY_BYTES = 1_000_000;
+const DEFAULT_DRAIN_MS = 10_000;
+const DRAIN_POLL_MS = 10;
+const TEXT_DECODER = new TextDecoder();
+/**
+ * Shared never-aborting signal for `ctx.signal` when no timeout is armed — created lazily and
+ * cached. NOT a module-scope `new AbortController()`: edge runtimes (Cloudflare workerd) forbid
+ * constructing one in global scope; the first request builds it inside the handler, then it's
+ * reused at zero per-request cost.
+ */
+let neverAbortSignal;
+const getNeverAbortSignal = () => {
+    neverAbortSignal ??= new AbortController().signal;
+    return neverAbortSignal;
+};
+function jsonError(status, error, headers) {
+    return Response.json({ ok: false, error }, headers !== undefined ? { status, headers } : { status });
+}
+function validationError(issues) {
+    const serialized = issues.map((issue) => {
+        const path = issue.path?.map((seg) => String(typeof seg === "object" ? seg.key : seg));
+        return path !== undefined ? { message: issue.message, path } : { message: issue.message };
+    });
+    return Response.json({ ok: false, error: "validation", issues: serialized }, { status: 400 });
+}
+// Extract pathname + query WITHOUT a full WHATWG `new URL(req.url)` parse.
+// `req.url` from every supported runtime is an absolute, already-normalized URL, so the pathname is
+// the substring after `scheme://host[:port]` up to `?`/`#`. Query-schema routes also need the search
+// string; parsing both in one scanner avoids the old `pathnameOf()` + `searchOf()` double scan.
+export function urlPartsOf(url) {
+    const schemeEnd = url.indexOf("://");
+    const start = schemeEnd === -1 ? url.indexOf("/") : url.indexOf("/", schemeEnd + 3);
+    if (start === -1)
+        return { pathname: "/", search: "" };
+    let pathEnd = url.length;
+    let searchStart = -1;
+    let searchEnd = url.length;
+    for (let i = start; i < url.length; i++) {
+        const c = url.charCodeAt(i);
+        if (c === 63 /* ? */ && searchStart === -1) {
+            pathEnd = i;
+            searchStart = i;
+        }
+        else if (c === 35 /* # */) {
+            if (searchStart === -1)
+                pathEnd = i;
+            searchEnd = i;
+            break;
+        }
+    }
+    return {
+        pathname: url.slice(start, pathEnd),
+        search: searchStart === -1 ? "" : url.slice(searchStart, searchEnd),
+    };
+}
+// Extract the pathname WITHOUT a full WHATWG `new URL(req.url)` parse. Kept as a public-ish helper
+// for tests and callers that only need the path; the request hot path uses `urlPartsOf()` once.
+export function pathnameOf(url) {
+    return urlPartsOf(url).pathname;
+}
+// The query string ("?a=1", or "" when absent) — for lazily building `c.query` only when read.
+// The fragment (after the first `#`) bounds the search: a `?` that appears only inside the fragment
+// is NOT a query (matches WHATWG). Fragments never reach the server in `req.url`, so this is purely
+// for provable equivalence with `new URL(req.url).search`.
+export function searchOf(url) {
+    return urlPartsOf(url).search;
+}
+/** Accumulate into a NULL-PROTOTYPE record (every call site below creates one): with no inherited
+ * `constructor`/`toString`/`__proto__` accessors, a hostile key is just an own data key — the
+ * promotion logic can't collide with `Object.prototype` members, and `__proto__` needs no special
+ * case (direct assignment on a null-proto object creates an own property). */
+function setQueryValue(out, key, value) {
+    const existing = out[key];
+    if (existing === undefined) {
+        out[key] = value;
+    }
+    else if (typeof existing === "string") {
+        out[key] = [existing, value];
+    }
+    else {
+        existing.push(value);
+    }
+}
+function queryObjectFallback(search) {
+    // Manual iteration instead of Object.fromEntries: repeated keys must promote to arrays
+    // (fromEntries is last-wins), and __proto__ needs the same own-property guard.
+    const out = Object.create(null);
+    for (const [key, value] of new URLSearchParams(search)) {
+        setQueryValue(out, key, value);
+    }
+    return out;
+}
+/**
+ * Build the plain object passed to query schemas. Plain ASCII-ish queries avoid
+ * `URLSearchParams` + iterator allocations; encoded queries fall back to the Web API so `+`,
+ * percent-decoding, malformed escapes, and empty-key behavior stay exact. Repeated keys promote
+ * to `string[]` on BOTH paths (see {@link setQueryValue}).
+ */
+// Shared empty result for no-query requests: frozen + null-prototype (same shape contract as the
+// populated path), allocated once instead of per request.
+const EMPTY_QUERY = Object.freeze(Object.create(null));
+export function queryObjectOf(search) {
+    const start = search.charCodeAt(0) === 63 /* ? */ ? 1 : 0;
+    if (start >= search.length)
+        return EMPTY_QUERY;
+    for (let i = start; i < search.length; i++) {
+        const c = search.charCodeAt(i);
+        if (c === 37 /* % */ || c === 43 /* + */)
+            return queryObjectFallback(search);
+    }
+    const out = Object.create(null);
+    let pos = start;
+    while (pos <= search.length) {
+        const amp = search.indexOf("&", pos);
+        const end = amp === -1 ? search.length : amp;
+        if (end > pos) {
+            const eq = search.indexOf("=", pos);
+            const split = eq !== -1 && eq < end ? eq : end;
+            const key = search.slice(pos, split);
+            const value = split === end ? "" : search.slice(split + 1, end);
+            setQueryValue(out, key, value);
+        }
+        if (amp === -1)
+            break;
+        pos = amp + 1;
+    }
+    return out;
+}
+/** `application/x-www-form-urlencoded`, with or without a charset suffix. */
+function isUrlEncodedForm(contentType) {
+    return (contentType === "application/x-www-form-urlencoded" ||
+        contentType.startsWith("application/x-www-form-urlencoded;"));
+}
+const FORM_DECODER = new TextDecoder();
+/**
+ * Read an HTML-form body (urlencoded) into the plain object a body schema validates — same byte
+ * cap as the JSON path (a lying/absent Content-Length can't force an oversized buffer), same
+ * repeated-key → `string[]` promotion as query parsing, same `__proto__` guard.
+ */
+async function readBoundedForm(req, maxBytes) {
+    const read = await readBoundedBytes(req, maxBytes);
+    if (!read.ok) {
+        return read.status === 413
+            ? jsonError(413, "payload_too_large")
+            : jsonError(400, "invalid_content_length");
+    }
+    const out = Object.create(null);
+    // URLSearchParams owns the format's quirks (`+` as space, percent-decoding, empty keys);
+    // it never throws on junk input, so no try/catch is needed here.
+    for (const [key, value] of new URLSearchParams(FORM_DECODER.decode(read.bytes))) {
+        setQueryValue(out, key, value);
+    }
+    return out;
+}
+function decodeParams(raw) {
+    let out;
+    for (const key in raw) {
+        const value = raw[key];
+        // `decodeURIComponent` only changes strings containing `%`; for the common
+        // unencoded param (`/users/123`) skip the call and its throw-check entirely —
+        // semantically identical (no `%` ⇒ no escapes to decode), ~3× cheaper on that path. If every
+        // param is already plain, return the router's per-request object directly and skip a clone.
+        if (!value.includes("%")) {
+            continue;
+        }
+        try {
+            out ??= { ...raw };
+            out[key] = decodeURIComponent(value);
+        }
+        catch {
+            return null;
+        }
+    }
+    return out ?? raw;
+}
+class LazyResponseControls {
+    status;
+    _headers;
+    _cookies;
+    get headers() {
+        this._headers ??= {};
+        return this._headers;
+    }
+    cookie(name, value, options) {
+        // Secure-by-default: HttpOnly + Secure + SameSite=Lax + Path=/, overridable per call.
+        const merged = {
+            httpOnly: true,
+            secure: true,
+            sameSite: "lax",
+            path: "/",
+            ...options,
+        };
+        this._cookies ??= [];
+        this._cookies.push(serializeCookie(name, value, merged));
+    }
+    deleteCookie(name, options) {
+        // Expire immediately; default Path=/, and match the original path/domain or the browser keeps it.
+        this._cookies ??= [];
+        this._cookies.push(serializeCookie(name, "", { path: "/", ...options, maxAge: 0, expires: EPOCH }));
+    }
+}
+// Finalization only reads `status`, `_headers`, and `_cookies`. The user-visible mutator methods
+// live on `LazyResponseControls`, created by the `c.set` getter only when user code touches it.
+const EMPTY_RESPONSE_CONTROLS = Object.freeze({});
+function responseSet(ctx) {
+    return ctx[CONTEXT_SET]() ?? EMPTY_RESPONSE_CONTROLS;
+}
+function isContextlessNoArgArrow(handler) {
+    if (handler.length !== 0)
+        return false;
+    try {
+        return CONTEXTLESS_ARROW.test(functionToString.call(handler));
+    }
+    catch {
+        return false;
+    }
+}
+class RequestContext {
+    params;
+    signal;
+    env;
+    waitUntil;
+    body;
+    [CONTEXT_SEARCH];
+    setValue;
+    queryValue;
+    queryReady;
+    cookiesValue;
+    source;
+    maxBodyBytes;
+    constructor(source, params, search, signal, platform, maxBodyBytes) {
+        this.source = source;
+        this.params = params;
+        this[CONTEXT_SEARCH] = search;
+        this.signal = signal;
+        this.env = platform?.env;
+        this.waitUntil = platform?.waitUntil ?? fallbackWaitUntil;
+        this.maxBodyBytes = maxBodyBytes;
+        this.setValue = undefined;
+        this.body = undefined;
+        this.queryValue = undefined;
+        this.queryReady = false;
+        this.cookiesValue = undefined;
+    }
+    [CONTEXT_SET]() {
+        return this.setValue;
+    }
+    get set() {
+        this.setValue ??= new LazyResponseControls();
+        return this.setValue;
+    }
+    get req() {
+        return requestOf(this.source);
+    }
+    get query() {
+        if (!this.queryReady) {
+            this.queryValue = new URLSearchParams(this[CONTEXT_SEARCH]);
+            this.queryReady = true;
+        }
+        return this.queryValue;
+    }
+    set query(v) {
+        this.queryValue = v;
+        this.queryReady = true;
+    }
+    get cookies() {
+        this.cookiesValue ??= parseCookies(headerOf(this.source, "cookie"));
+        return this.cookiesValue;
+    }
+    boundedBody(maxBytes) {
+        return readBoundedBodyOrThrow(this.source, this.maxBodyBytes, maxBytes);
+    }
+    boundedJson(maxBytes) {
+        return readBoundedJsonBodyOrThrow(this.source, this.maxBodyBytes, maxBytes);
+    }
+}
+/** Backs `c.boundedBody`: bounded byte read that throws a flat 413/400 `Response` (caught by
+ * `runLifecycle` as control flow, like `throw redirect(...)`), so a handler can't ignore the cap.
+ * The byte-cap itself lives in `./body.ts` (shared with the schema path and `verifyWebhook`). */
+async function readBoundedBodyOrThrow(req, maxBodyBytes, maxBytes) {
+    const r = await readBoundedBytes(req, maxBytes ?? maxBodyBytes);
+    if (r.ok)
+        return r.bytes;
+    throw r.status === 413
+        ? jsonError(413, "payload_too_large")
+        : jsonError(400, "invalid_content_length");
+}
+/** Backs `c.boundedJson`: `readBoundedBodyOrThrow` + `JSON.parse`, throwing a flat 400 on bad JSON. */
+async function readBoundedJsonBodyOrThrow(req, maxBodyBytes, maxBytes) {
+    const parsed = await readBoundedJsonSource(req, maxBytes ?? maxBodyBytes);
+    if (parsed instanceof Response)
+        throw parsed;
+    return parsed;
+}
+/**
+ * Read a JSON body with the same byte cap used by schema validation and `c.boundedJson`.
+ * Non-chunked, framed requests with an in-cap `Content-Length` use the runtime-native `req.json()`;
+ * chunked or length-less requests fall back to the streaming byte-cap guard.
+ */
+async function readBoundedJsonSource(req, maxBytes) {
+    const declared = headerOf(req, "content-length");
+    if (declared !== null) {
+        // A present Content-Length must be a non-negative integer (HTTP grammar: `1*DIGIT`). A
+        // non-numeric / negative / fractional / exponential value (`Number()` would happily accept
+        // "abc"→NaN, "-5", "1.5", "1e3", "0x10") is malformed → 400, rather than silently falling
+        // through to the streaming guard — which is an UPPER-bound cap only, so a lying SMALLER length
+        // would otherwise be read in full. Real HTTP servers only hand us a valid framed length; this
+        // hardens hand-built Requests (tests, the in-process client) and crafted input.
+        const length = parseContentLength(declared);
+        if (length === undefined)
+            return jsonError(400, "invalid_content_length");
+        if (length > maxBytes)
+            return jsonError(413, "payload_too_large");
+        const chunked = headerOf(req, "transfer-encoding") !== null;
+        if (!chunked) {
+            try {
+                return await req.json();
+            }
+            catch {
+                return jsonError(400, "invalid_json");
+            }
+        }
+    }
+    const body = req.body;
+    if (body === null)
+        return jsonError(400, "invalid_json");
+    const drained = await drainCapped(body, maxBytes);
+    if (!drained.ok)
+        return jsonError(413, "payload_too_large");
+    try {
+        return JSON.parse(TEXT_DECODER.decode(drained.bytes));
+    }
+    catch {
+        return jsonError(400, "invalid_json");
+    }
+}
+/** A fixed past instant for cookie deletion (`Expires`). A literal epoch — deterministic, unlike an
+ * argless `new Date()`. */
+const EPOCH = new Date(0);
+/** Build the response headers init. The common path (no `c.set`) returns `undefined` so `Response`
+ * gets no `headers` at all. Cookies force a `Headers` object — multiple `Set-Cookie`s can't live in a
+ * `Record<string,string>` (the 2nd would overwrite the 1st), so they're `append`ed individually. */
+function headersInit(set) {
+    const cookies = set._cookies;
+    if (cookies === undefined || cookies.length === 0)
+        return set._headers;
+    const headers = new Headers(set._headers);
+    for (const cookie of cookies)
+        headers.append("set-cookie", cookie);
+    return headers;
+}
+// Keep the fast JSON respond path byte-identical to `Response.json` without probing it at module
+// scope: workerd forbids `Response.json()` during startup. A shared `Headers` is safe to reuse
+// across responses: the Response constructor copies `init.headers` into its own list.
+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. */
+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 toResponse(result, EMPTY_RESPONSE_CONTROLS);
+}
+/** Fused-lane respond with a context: read `c.set` once; untouched (the common case) → the fast
+ * JSON respond; touched → the generic `toResponse` with those controls (statuses, headers, cookies). */
+function fusedRespond(result, ctx) {
+    const set = ctx[CONTEXT_SET]();
+    if (set === undefined)
+        return fusedRespondNoSet(result);
+    return toResponse(result, set);
+}
+function toResponse(result, set) {
+    if (isResponseResult(result)) {
+        return appendCookiesToResponse(result.toResponse(), set);
+    }
+    if (result instanceof Response) {
+        return appendCookiesToResponse(result, set);
+    }
+    const headers = headersInit(set);
+    const status = set.status ?? (result === undefined ? 204 : 200);
+    if (headers === undefined && result !== undefined) {
+        // Fast respond (profiled ≈ −50 ns/req on every plain-JSON return): `JSON.stringify` + a
+        // prebuilt init beats `Response.json`'s internal init handling. Output is byte-identical —
+        // same body bytes, same probed content-type. `undefined` from stringify (a function/symbol
+        // result) delegates to Response.json so its TypeError contract stays the single source.
+        const body = JSON.stringify(result);
+        if (body !== undefined) {
+            return new Response(body, status === 200 ? JSON_INIT_200 : { status, headers: JSON_CT_HEADERS });
+        }
+    }
+    const init = headers === undefined ? { status } : { status, headers };
+    return result === undefined ? new Response(null, init) : Response.json(result, init);
+}
+function appendCookiesToResponse(response, set) {
+    // A handler may queue cookies (`c.set.cookie` — e.g. a session cookie) AND return its own Response
+    // (e.g. `redirect("/")` after login). Cookies accumulate additively, so append them to the
+    // returned Response — otherwise the canonical set-session-then-redirect pattern would silently drop
+    // the cookie. (Other `c.set` fields stay the returned Response's own concern.)
+    const cookies = set._cookies;
+    if (cookies !== undefined && cookies.length > 0) {
+        for (const cookie of cookies)
+            response.headers.append("set-cookie", cookie);
+    }
+    return response;
+}
+/**
+ * `finalize` for the node-direct path — mirror of {@link toResponse} that skips the `Response` build:
+ * a plain value becomes pre-stringified JSON primitives (the adapter `JSON.stringify`s once, here, not
+ * via `Response.json` + a body drain); a handler-returned `Response` is wrapped as-is, with queued
+ * cookies appended exactly as `toResponse` does (so the set-cookie-then-`redirect()` pattern still
+ * works on Node).
+ */
+function toNodeOutcome(result, set) {
+    if (isResponseResult(result)) {
+        const body = result.toNodeBody?.();
+        if (body !== undefined) {
+            return {
+                kind: "body",
+                status: body.status,
+                headers: appendCookiesToNodeHeaders(body.headers, set._cookies),
+                body: body.body,
+            };
+        }
+        return nodeOutcomeFromResponse(appendCookiesToResponse(result.toResponse(), set));
+    }
+    if (result instanceof Response) {
+        return nodeOutcomeFromResponse(appendCookiesToResponse(result, set));
+    }
+    const status = set.status ?? (result === undefined ? 204 : 200);
+    return {
+        kind: "json",
+        status,
+        headers: set._headers,
+        cookies: set._cookies,
+        body: result === undefined ? null : JSON.stringify(result),
+    };
+}
+// Stable module-level finalizers so `fetch`/`resolveNode` allocate no per-request closures.
+const IDENTITY_RESPONSE = (response) => response;
+const RESPONSE_TIMEOUT = () => jsonError(503, "request_timeout");
+const NODE_RESPONSE_BODY = Symbol.for("nifra.response.body");
+const NODE_FROM_RESPONSE = (response) => nodeOutcomeFromResponse(response);
+const NODE_TIMEOUT = () => ({
+    kind: "response",
+    response: jsonError(503, "request_timeout"),
+});
+function nodeOutcomeFromResponse(response) {
+    const body = nodeResponseBody(response);
+    return body === undefined
+        ? { kind: "response", response }
+        : { kind: "body", status: response.status, headers: responseHeadersForNode(response), body };
+}
+function nodeResponseBody(response) {
+    if (response.bodyUsed)
+        return undefined;
+    const body = response[NODE_RESPONSE_BODY];
+    return typeof body === "string" || body instanceof Uint8Array ? body : undefined;
+}
+function responseHeadersForNode(response) {
+    let headers;
+    response.headers.forEach((value, key) => {
+        headers ??= {};
+        headers[key] = value;
+    });
+    const setCookies = response.headers.getSetCookie?.();
+    if (setCookies !== undefined && setCookies.length > 0) {
+        headers ??= {};
+        headers["set-cookie"] = setCookies;
+    }
+    return headers;
+}
+function appendCookiesToNodeHeaders(headers, cookies) {
+    if (cookies === undefined || cookies.length === 0)
+        return headers;
+    const out = headers === undefined ? {} : { ...headers };
+    const existing = out["set-cookie"];
+    const setCookies = existing === undefined ? [] : typeof existing === "string" ? [existing] : [...existing];
+    out["set-cookie"] = [...setCookies, ...cookies];
+    return out;
+}
+/**
+ * The inline server. Routes are chainable and fully type-inferred. `derive`/
+ * `decorate` extend the handler context (`Ctx`) for routes defined *after* them,
+ * with full types; `Ctx` is server-only and never touches the client registry.
+ *
+ *   app.decorate("db", db).derive((c) => ({ user: auth(c) }))
+ *      .get("/me", (c) => c.user)            // c.user + c.db are typed
+ */
+export class Server {
+    router;
+    /** WebSocket routes, matched separately at upgrade time (a GET + `Upgrade: websocket`). */
+    wsRouter;
+    wsRouteCount;
+    /** In-process pub/sub backing `ws.subscribe(topic)` + `app.publish(topic, data)` (single-instance).
+     * Created by the first `app.ws()` via the `@nifrajs/core/ws` runtime — `undefined` until then, so a
+     * no-WebSocket app never constructs (or bundles) it. */
+    topics;
+    routeList;
+    maxBodyBytes;
+    requestTimeoutMs;
+    gracefulSignals;
+    logger;
+    bunServer;
+    derives;
+    decorations;
+    beforeHandleHooks;
+    afterHandleHooks;
+    onErrorHooks;
+    aroundHooks;
+    onRequestHooks;
+    onResponseHooks;
+    responseRequests;
+    /** Names of plugins/middleware already applied via `use` — for idempotent dedupe. */
+    appliedPlugins;
+    constructor(options = {}) {
+        this.router = new Router();
+        this.wsRouter = new Router();
+        this.wsRouteCount = 0;
+        this.topics = undefined;
+        this.routeList = [];
+        this.maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+        this.requestTimeoutMs = options.requestTimeoutMs ?? 0;
+        this.gracefulSignals = options.gracefulSignals ?? false;
+        this.logger = options.logger ?? jsonLogger();
+        this.bunServer = undefined;
+        this.derives = [];
+        this.decorations = {};
+        this.beforeHandleHooks = [];
+        this.afterHandleHooks = [];
+        this.onErrorHooks = [];
+        this.aroundHooks = [];
+        this.onRequestHooks = [];
+        this.onResponseHooks = [];
+        this.responseRequests = new WeakMap();
+        this.appliedPlugins = new Set();
+    }
+    /** Add a per-request, computed context extension for subsequent routes. */
+    derive(fn) {
+        this.derives.push(fn);
+        return this;
+    }
+    /** Add a static context value for subsequent routes. */
+    decorate(key, value) {
+        this.decorations[key] = value;
+        return this;
+    }
+    /**
+     * Run before routing on the raw request. Return a `Response` to short-circuit, or a replacement
+     * `Request` to continue routing with a rewritten method/URL/headers. Global.
+     */
+    onRequest(fn) {
+        this.onRequestHooks.push(fn);
+        return this;
+    }
+    /** Run after validation, before the handler; a non-`undefined` return short-circuits. Order-scoped. */
+    beforeHandle(fn) {
+        this.beforeHandleHooks.push(fn);
+        return this;
+    }
+    /**
+     * Wrap the matched route lifecycle for subsequent routes. This is intentionally generic over the
+     * route output, so wrappers like async context storage do not force Node's direct JSON path through
+     * a Web `Response`. The first registered wrapper is outermost.
+     */
+    around(fn) {
+        this.aroundHooks.push(fn);
+        return this;
+    }
+    /** Transform the handler's result before it is serialized. Order-scoped. */
+    afterHandle(fn) {
+        this.afterHandleHooks.push(fn);
+        return this;
+    }
+    /** Handle a thrown error; a non-`undefined` return becomes the response (else the default 500). Order-scoped. */
+    onError(fn) {
+        this.onErrorHooks.push(fn);
+        return this;
+    }
+    /** Transform every outgoing response — success, error, 404, 405, short-circuit. Global. */
+    onResponse(fn) {
+        this.onResponseHooks.push(fn);
+        return this;
+    }
+    use(arg) {
+        if (typeof arg === "function") {
+            const name = arg.pluginName;
+            if (name !== undefined) {
+                if (this.appliedPlugins.has(name))
+                    return this; // idempotent: already applied
+                this.appliedPlugins.add(name);
+            }
+            return arg(this);
+        }
+        if (arg.name !== undefined) {
+            if (this.appliedPlugins.has(arg.name))
+                return this;
+            this.appliedPlugins.add(arg.name);
+        }
+        if (arg.onRequest !== undefined)
+            this.onRequest(arg.onRequest);
+        if (arg.around !== undefined)
+            this.around(arg.around);
+        if (arg.beforeHandle !== undefined)
+            this.beforeHandle(arg.beforeHandle);
+        if (arg.afterHandle !== undefined)
+            this.afterHandle(arg.afterHandle);
+        if (arg.onResponse !== undefined)
+            this.onResponse(arg.onResponse);
+        if (arg.onError !== undefined)
+            this.onError(arg.onError);
+        return this;
+    }
+    get(path, schemaOrHandler, handler) {
+        return this.route("GET", path, schemaOrHandler, handler);
+    }
+    post(path, schemaOrHandler, handler) {
+        return this.route("POST", path, schemaOrHandler, handler);
+    }
+    put(path, schemaOrHandler, handler) {
+        return this.route("PUT", path, schemaOrHandler, handler);
+    }
+    patch(path, schemaOrHandler, handler) {
+        return this.route("PATCH", path, schemaOrHandler, handler);
+    }
+    delete(path, schemaOrHandler, handler) {
+        return this.route("DELETE", path, schemaOrHandler, handler);
+    }
+    /**
+     * Register a **WebSocket** route. The connection upgrades on a `GET` to `path` carrying
+     * `Upgrade: websocket`; the optional `handler.upgrade(c)` runs in the request context first and may
+     * reject (return a `Response`) or seed per-connection `ws.data`. WebSockets are served by the
+     * adapter (`listen()`, `@nifrajs/node`, `@nifrajs/deno`, `toFetchHandler`) — not by bare `app.fetch`, which
+     * has no socket (a WS path through `app.fetch` is a normal HTTP response).
+     *
+     *   app.ws("/chat", { open: (ws) => ws.send("hi"), message: (ws, data) => ws.send(data) })
+     */
+    ws(path, handler) {
+        // Boot-time guard: the WS runtime is a subpath (`@nifrajs/core/ws`) so no-WebSocket apps don't
+        // bundle it. Registration is the loud, early failure point — never the first connection.
+        const runtime = requireWsRuntime();
+        this.topics ??= runtime.createTopics();
+        // A `messageSchema` wraps `message` with validation once, here — every adapter then dispatches
+        // already-validated, typed messages (Bun/Deno/Node/Workers) with no per-adapter code.
+        this.wsRouter.add("GET", path, {
+            handler: runtime.wrapHandler(handler),
+        });
+        this.wsRouteCount += 1;
+        return this;
+    }
+    /**
+     * Broadcast `data` to every WebSocket connection subscribed to `topic` (via `ws.subscribe(topic)`).
+     * In-process and **single-instance** (see {@link TopicRegistry}) — a multi-instance deploy must bridge
+     * an external fan-out (Redis, a Durable Object) to this. A no-op when nobody is subscribed.
+     */
+    publish(topic, data) {
+        // No `app.ws()` yet ⇒ no registry and necessarily no subscribers — a publish is a no-op anyway.
+        this.topics?.publish(topic, data);
+    }
+    route(method, path, schemaOrHandler, handler) {
+        let rawHandler;
+        let schema;
+        if (handler !== undefined) {
+            schema = schemaOrHandler;
+            rawHandler = handler;
+        }
+        else {
+            schema = undefined;
+            rawHandler = schemaOrHandler;
+        }
+        this.register(method, path, schema, rawHandler);
+        // The accumulated registry type is compile-time only; the same instance
+        // carries every route, so the public methods re-type `this` per call.
+        return this;
+    }
+    /**
+     * Low-level route registration shared by the inline builder and `implement()`.
+     * Captures the server's current `derive`/`decorate` chain into the route — this
+     * is the "compiled", order-scoped per-route chain.
+     */
+    register(method, path, schema, handler) {
+        const bare = schema?.body === undefined &&
+            schema?.query === undefined &&
+            this.derives.length === 0 &&
+            this.beforeHandleHooks.length === 0 &&
+            this.afterHandleHooks.length === 0 &&
+            this.onErrorHooks.length === 0;
+        const fusedWeb = bare && this.aroundHooks.length === 0
+            ? this.buildFusedWeb(handler, Object.keys(this.decorations).length > 0 ? { ...this.decorations } : undefined, isContextlessNoArgArrow(handler))
+            : undefined;
+        this.router.add(method, path, {
+            // (context: never) => unknown -> InternalHandler: the framework invokes it
+            // with the concrete RawContext the typed handler expects, so this is sound.
+            handler: handler,
+            schema,
+            fusedWeb,
+            derives: [...this.derives],
+            decorations: { ...this.decorations },
+            hasDecorations: Object.keys(this.decorations).length > 0,
+            beforeHandle: [...this.beforeHandleHooks],
+            afterHandle: [...this.afterHandleHooks],
+            onError: [...this.onErrorHooks],
+            around: [...this.aroundHooks],
+            // Sync-fast-path eligibility (see RouteEntry.bare). Validation + every hook kind must be absent;
+            // decorations and generic around wrappers are fine: around wraps the inner bare route in
+            // `routeAndRun`, while the inner validation/derive/before/after/onError lifecycle remains empty.
+            // Most GET/no-schema routes qualify.
+            bare,
+            contextlessBare: bare && this.aroundHooks.length === 0 && isContextlessNoArgArrow(handler),
+            bodyOnly: schema?.body !== undefined &&
+                schema.query === undefined &&
+                this.derives.length === 0 &&
+                this.beforeHandleHooks.length === 0 &&
+                this.afterHandleHooks.length === 0 &&
+                this.onErrorHooks.length === 0,
+            queryOnly: schema?.body === undefined &&
+                schema?.query !== undefined &&
+                this.derives.length === 0 &&
+                this.beforeHandleHooks.length === 0 &&
+                this.afterHandleHooks.length === 0 &&
+                this.onErrorHooks.length === 0,
+        });
+        this.routeList.push({ method, path, schema });
+    }
+    /**
+     * Enumerate the registered routes (method, path, input schemas), in registration
+     * order. Powers `toOpenAPI` and other introspection; the router trie itself no
+     * longer holds the original patterns.
+     */
+    routes() {
+        return this.routeList;
+    }
+    /**
+     * Resolve a `Request` to a `Response` — the whole lifecycle, testable without a port. The
+     * optional `platform` carries edge inputs (`env`, `waitUntil`); edge adapters pass it, and
+     * Bun/Node/Deno omit it (then `c.env` is `undefined` and `c.waitUntil` runs fire-and-forget).
+     */
+    fetch(req, platform) {
+        // A real `Request` satisfies `RequestSource`, so it's passed straight through — no per-request
+        // wrapper allocation on the Web/Bun hot path.
+        return this.fetchSource(req, platform);
+    }
+    fetchSource(source, platform) {
+        // Non-`async` on purpose: `dispatch` may return a `Response` *synchronously* (the bare-route fast
+        // path, see RouteEntry.bare), and an `async fetch` would wrap every such result in a redundant
+        // promise + microtask. Returning `Response | Promise<Response>` matches Web/edge handlers, while
+        // `await app.fetch(...)` continues to work exactly as before.
+        const outcome = this.dispatch(source, platform, toResponse, IDENTITY_RESPONSE, RESPONSE_TIMEOUT, true);
+        if (this.onResponseHooks.length === 0) {
+            return outcome;
+        }
+        // onResponse sees every response — success, validation error, 404/405, timeout, onRequest
+        // short-circuit; normalize to a promise, then thread through the hooks.
+        return outcome instanceof Promise
+            ? outcome.then((response) => this.applyOnResponse(response, this.takeResponseRequest(source)))
+            : this.applyOnResponse(outcome, this.takeResponseRequest(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
+     * `Response` build + body drain (the bulk of the Node bridge cost, measured ≈4µs/req). A handler that
+     * returns a `Response`, an error/short-circuit, or any registered `onResponse` hook falls back to the
+     * full Web path (`{ kind: "response" }`), so behavior is identical — only the common JSON-data case is
+     * faster. Same lifecycle as {@link fetch} (body cap, validation, hooks all run); only the final
+     * render differs.
+     */
+    resolveNode(req, platform) {
+        return this.resolveNodeSource(req, platform);
+    }
+    resolveNodeSource(source, platform) {
+        // onResponse hooks transform a Response, so they force the Web path; wrap its result.
+        if (this.onResponseHooks.length > 0) {
+            const response = this.fetchSource(source, platform);
+            return response instanceof Promise
+                ? response.then((settled) => ({ kind: "response", response: settled }))
+                : { kind: "response", response };
+        }
+        // May resolve **synchronously** for a bare route + sync handler (RouteEntry.bare) — the `@nifrajs/node`
+        // adapter `await`s the result, so it transparently handles either; the sync case allocates no promise
+        // at all on the Node hot path.
+        return this.dispatch(source, platform, toNodeOutcome, NODE_FROM_RESPONSE, NODE_TIMEOUT, false);
+    }
+    /**
+     * Resolve a WebSocket upgrade — the seam every serving adapter uses. Returns `pass` (not a WS
+     * upgrade for a registered route → handle as normal HTTP), `reject` (a WS route matched but
+     * `upgrade()` rejected, or the path was malformed → return `response`), or `upgrade` (perform the
+     * runtime upgrade, then dispatch the native socket's events to `handler`, seeding `ws.data` with
+     * `data`). Runs the route's `upgrade(c)` guard in a real request context. Synchronous unless
+     * `upgrade()` is async; a throw rejects with a flat 500 (no detail leaked).
+     */
+    resolveWebSocketUpgrade(req, platform) {
+        if (this.wsRouteCount === 0)
+            return WS_PASS;
+        if (req.headers.get("upgrade")?.toLowerCase() !== "websocket")
+            return WS_PASS;
+        const url = urlPartsOf(req.url);
+        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 ? EMPTY_PARAMS : decodeParams(match.params);
+        if (params === null)
+            return { kind: "reject", response: jsonError(400, "malformed_path") };
+        const handler = match.payload.handler;
+        // Non-null: wsRouteCount > 0 ⇒ ws() ran ⇒ the runtime created the registry.
+        const pubsub = this.topics;
+        // CSWSH guard, before any per-connection work or the user's upgrade(): reject a disallowed
+        // Origin with 403. Browsers don't CORS-protect WS handshakes but do send cookies, so this
+        // blocks cross-site authenticated sockets when the route opts in via `allowedOrigins`.
+        if (handler.allowedOrigins !== undefined) {
+            const origin = req.headers.get("origin");
+            const allowed = typeof handler.allowedOrigins === "function"
+                ? handler.allowedOrigins(origin)
+                : origin !== null && handler.allowedOrigins.includes(origin);
+            if (!allowed)
+                return { kind: "reject", response: jsonError(403, "forbidden_origin") };
+        }
+        if (handler.upgrade === undefined) {
+            return { kind: "upgrade", handler, data: undefined, pubsub };
+        }
+        const ctx = new RequestContext(req, params, url.search, getNeverAbortSignal(), platform, this.maxBodyBytes);
+        const settle = (value) => value instanceof Response
+            ? { kind: "reject", response: value }
+            : { kind: "upgrade", handler, data: value, pubsub };
+        try {
+            const result = handler.upgrade(ctx);
+            return result instanceof Promise
+                ? result.then(settle, () => ({
+                    kind: "reject",
+                    response: jsonError(500, "internal_error"),
+                }))
+                : settle(result);
+        }
+        catch {
+            return { kind: "reject", response: jsonError(500, "internal_error") };
+        }
+    }
+    /** Bun `fetch` when WS routes exist: try a WS upgrade first, else run the normal HTTP lifecycle.
+     * `undefined` ⇒ Bun owns the upgraded socket; a `Response` ⇒ a normal reply or a rejected upgrade.
+     * (The socket dispatch itself lives in `ws-bun.ts`, loaded via `@nifrajs/core/ws`.) */
+    bunFetchWithWebSocket(req, server) {
+        const handle = (o) => {
+            if (o.kind === "pass")
+                return this.fetch(req);
+            if (o.kind === "reject")
+                return o.response;
+            return server.upgrade(req, { data: { handler: o.handler, data: o.data } })
+                ? undefined
+                : jsonError(426, "upgrade_required");
+        };
+        const outcome = this.resolveWebSocketUpgrade(req);
+        return outcome instanceof Promise ? outcome.then(handle) : handle(outcome);
+    }
+    /**
+     * The shared lifecycle, generic over how the final value is rendered: `finalize` turns a handler's
+     * result + `set` into the output `T` (`toResponse` → a Web `Response`; `toNodeOutcome` → node-direct
+     * primitives), `wrapResponse` lifts an early/error `Response` into that same `T`, and `onTimeout`
+     * produces the 503. The Web `fetch` and `resolveNode` are thin callers over this one routing +
+     * context + lifecycle implementation — no duplication across the trust boundary.
+     */
+    dispatch(source, platform, finalize, wrapResponse, onTimeout, 
+    // True only from the Web `fetch` path — unlocks each route's fused lane, whose output type IS
+    // `Response` (`T = Response` there by construction; the node path always passes false).
+    webFast) {
+        // onRequest hooks may be async, so a hooked app takes the async path; with no hooks (the common
+        // case) routing stays synchronous, letting a bare route resolve with no lifecycle promise at all.
+        if (this.onRequestHooks.length === 0) {
+            return this.routeAndRun(source, platform, finalize, wrapResponse, onTimeout, webFast);
+        }
+        return this.runWithOnRequest(source, platform, finalize, wrapResponse, onTimeout, webFast);
+    }
+    /**
+     * onRequest short-circuit path. Synchronous as long as every hook returns synchronously (the
+     * common case — e.g. CORS returning `undefined` for a non-preflight request): an `async` version
+     * here put EVERY request of any app with one onRequest hook onto the promise machinery, profiled
+     * at ~13% of a realistic request. The first hook that returns a Promise hands the REMAINING
+     * hooks to the async continuation; behavior is identical.
+     */
+    runWithOnRequest(source, platform, finalize, wrapResponse, onTimeout, webFast) {
+        const hooks = this.onRequestHooks;
+        const originalRequest = requestOf(source);
+        let current = source;
+        for (let i = 0; i < hooks.length; i++) {
+            const outcome = hooks[i](requestOf(current));
+            if (outcome instanceof Promise) {
+                return outcome.then((early) => this.continueOnRequest(early, i + 1, originalRequest, current, platform, finalize, wrapResponse, onTimeout, webFast));
+            }
+            if (outcome instanceof Request) {
+                current = outcome;
+                if (outcome !== originalRequest)
+                    this.responseRequests.set(originalRequest, outcome);
+                continue;
+            }
+            if (outcome !== undefined)
+                return wrapResponse(outcome);
+        }
+        return this.routeAndRun(current, platform, finalize, wrapResponse, onTimeout, webFast);
+    }
+    /** Async tail of {@link runWithOnRequest}: applies the first awaited hook's outcome, then runs
+     * the remaining hooks (awaiting freely — we're already async here). */
+    async continueOnRequest(first, nextIndex, originalRequest, sourceAtAwait, platform, finalize, wrapResponse, onTimeout, webFast) {
+        let current = sourceAtAwait;
+        let early = first;
+        let index = nextIndex;
+        for (;;) {
+            if (early instanceof Request) {
+                current = early;
+                if (early !== originalRequest)
+                    this.responseRequests.set(originalRequest, early);
+            }
+            else if (early !== undefined) {
+                return wrapResponse(early);
+            }
+            if (index >= this.onRequestHooks.length)
+                break;
+            const outcome = this.onRequestHooks[index](requestOf(current));
+            early = outcome instanceof Promise ? await outcome : outcome;
+            index++;
+        }
+        return this.routeAndRun(current, platform, finalize, wrapResponse, onTimeout, webFast);
+    }
+    takeResponseRequest(source) {
+        const request = requestOf(source);
+        const rewritten = this.responseRequests.get(request);
+        if (rewritten === undefined)
+            return request;
+        this.responseRequests.delete(request);
+        return rewritten;
+    }
+    /**
+     * Route → build context → run. Synchronous through to the handler for a **bare** route
+     * ({@link RouteEntry.bare}), so a sync handler produces its result with zero promise allocations;
+     * routes with validation/hooks keep the full async {@link runLifecycle}, unchanged.
+     */
+    routeAndRun(source, platform, finalize, wrapResponse, onTimeout, webFast) {
+        const url = urlPartsOf(source.url);
+        const match = this.router.find(source.method, url.pathname);
+        if (!match.found) {
+            if (match.reason === "method-not-allowed") {
+                return wrapResponse(jsonError(405, "method_not_allowed", { Allow: match.allowed.join(", ") }));
+            }
+            return wrapResponse(jsonError(404, "not_found"));
+        }
+        const params = match.params === EMPTY_PARAMS ? EMPTY_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.
+        let controller;
+        let signal = getNeverAbortSignal();
+        if (this.requestTimeoutMs > 0) {
+            controller = new AbortController();
+            signal = controller.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);
+        }
+        else if (entry.contextlessBare) {
+            outcome = this.runContextlessBare(entry, source, params, url.search, signal, 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);
+            if (entry.around.length === 0) {
+                outcome = entry.bare
+                    ? this.runBare(entry, ctx, finalize, wrapResponse)
+                    : entry.bodyOnly
+                        ? this.runBodyOnly(entry, source, ctx, finalize, wrapResponse)
+                        : entry.queryOnly
+                            ? this.runQueryOnly(entry, ctx, finalize, wrapResponse)
+                            : this.runLifecycle(entry, source, ctx, finalize, wrapResponse);
+            }
+            else {
+                outcome = this.runWithAround(entry, ctx, () => entry.bare
+                    ? this.runBare(entry, ctx, finalize, wrapResponse)
+                    : entry.bodyOnly
+                        ? this.runBodyOnly(entry, source, ctx, finalize, wrapResponse)
+                        : entry.queryOnly
+                            ? this.runQueryOnly(entry, ctx, finalize, wrapResponse)
+                            : this.runLifecycle(entry, source, ctx, finalize, wrapResponse), finalize, wrapResponse);
+            }
+        }
+        // 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);
+        }
+        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) {
+        let result;
+        try {
+            result = entry.handler();
+        }
+        catch (err) {
+            return this.contextlessBareError(err, source, params, search, signal, 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 finalize(result, EMPTY_RESPONSE_CONTROLS);
+    }
+    contextlessBareError(err, source, params, search, signal, platform, wrapResponse) {
+        if (err instanceof Response)
+            return wrapResponse(err);
+        const ctx = new RequestContext(source, params, search, signal, platform, this.maxBodyBytes);
+        this.logRequestError(err, ctx);
+        return wrapResponse(jsonError(500, "internal_error"));
+    }
+    /**
+     * The synchronous fast path for a {@link RouteEntry.bare} route: apply static decorations, call the
+     * handler, render the result — **no `await`** unless the handler itself returns a promise. It mirrors
+     * the bare slice of {@link runLifecycle} (which a bare route would otherwise no-op through) and shares
+     * {@link logRequestError}; a bare route has no `onError` hooks, so error handling is fully synchronous
+     * (a thrown `Response` is control flow; anything else is a logged flat 500). This is where nifra skips
+     * the per-request async-frame tax — the same win codegen routers get, but without `eval`.
+     */
+    runBare(entry, ctx, finalize, wrapResponse) {
+        let result;
+        try {
+            if (entry.hasDecorations)
+                Object.assign(ctx, entry.decorations);
+            result = entry.handler(ctx);
+        }
+        catch (err) {
+            return this.bareError(err, ctx, wrapResponse);
+        }
+        if (result instanceof Promise) {
+            // Async handler on an otherwise-bare route: finish on a microtask, with the same error handling.
+            return result.then((value) => finalize(value, responseSet(ctx)), (err) => this.bareError(err, ctx, wrapResponse));
+        }
+        return finalize(result, responseSet(ctx));
+    }
+    /** Bare-route error rendering — identical to {@link runLifecycle}'s catch minus the (absent) onError
+     * loop: a thrown `Response` is returned as deliberate control flow; anything else is logged + 500. */
+    /**
+     * Build a route's fused Web lane (see {@link RouteEntry.fusedWeb}). Composition happens once at
+     * registration; the returned closure is what every request to the route runs. Behavior is
+     * byte-identical to the generic `runBare`/`runContextlessBare` + `toResponse` pair — same
+     * decoration order, same error routing (thrown `Response` = control flow; anything else logs and
+     * 500s), same respond semantics (the lifecycle parity suite pins it).
+     */
+    buildFusedWeb(handler, decorations, contextless) {
+        const maxBodyBytes = this.maxBodyBytes;
+        const logError = (err, ctx) => {
+            if (err instanceof Response)
+                return err;
+            this.logRequestError(err, ctx);
+            return jsonError(500, "internal_error");
+        };
+        if (contextless && decorations === undefined) {
+            // `() => ...` 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) => {
+                let result;
+                try {
+                    result = contextlessHandler();
+                }
+                catch (err) {
+                    return logError(err, new RequestContext(source, params, search, signal, platform, maxBodyBytes));
+                }
+                if (result instanceof Promise) {
+                    return result.then(fusedRespondNoSet, (err) => logError(err, new RequestContext(source, params, search, signal, platform, maxBodyBytes)));
+                }
+                return fusedRespondNoSet(result);
+            };
+        }
+        return (source, params, search, signal, platform) => {
+            const ctx = new RequestContext(source, params, search, signal, platform, maxBodyBytes);
+            if (decorations !== undefined)
+                Object.assign(ctx, decorations);
+            let result;
+            try {
+                result = handler(ctx);
+            }
+            catch (err) {
+                return logError(err, ctx);
+            }
+            if (result instanceof Promise) {
+                return result.then((value) => fusedRespond(value, ctx), (err) => logError(err, ctx));
+            }
+            return fusedRespond(result, ctx);
+        };
+    }
+    bareError(err, ctx, wrapResponse) {
+        if (err instanceof Response)
+            return wrapResponse(err);
+        this.logRequestError(err, ctx);
+        return wrapResponse(jsonError(500, "internal_error"));
+    }
+    runWithAround(entry, ctx, run, finalize, wrapResponse) {
+        let outcome;
+        try {
+            outcome = this.runAround(entry.around, ctx, run);
+        }
+        catch (err) {
+            return this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse);
+        }
+        return outcome instanceof Promise
+            ? outcome.catch((err) => this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse))
+            : outcome;
+    }
+    runAround(hooks, ctx, run) {
+        const dispatch = (index) => {
+            if (index >= hooks.length)
+                return run();
+            const hook = hooks[index];
+            let called = false;
+            return hook(ctx, () => {
+                if (called)
+                    throw new Error("around next() called multiple times");
+                called = true;
+                return dispatch(index + 1);
+            });
+        };
+        return dispatch(0);
+    }
+    runBodyOnly(entry, source, ctx, finalize, wrapResponse) {
+        const contentType = headerOf(source, "content-type") ?? "";
+        if (contentType !== "application/json" && !contentType.includes("application/json")) {
+            if (isUrlEncodedForm(contentType)) {
+                // HTML form posts validate through the same schema as JSON (parity with Elysia/Hono).
+                // Off the JSON inline lane on purpose: forms are a fraction of API traffic, and the
+                // bounded form reader shares the streaming guard. JSON requests are untouched.
+                return readBoundedForm(source, this.maxBodyBytes).then((form) => {
+                    if (form instanceof Response)
+                        return wrapResponse(form);
+                    return this.finishBodyOnly(entry, form, ctx, finalize, wrapResponse);
+                });
+            }
+            return Promise.resolve(wrapResponse(jsonError(415, "unsupported_media_type")));
+        }
+        // Inline fast path (profiled): a framed, in-cap, non-chunked body parses with the native
+        // `req.json()` directly — one promise, one `.then` closure per request. The generic
+        // `readBoundedJson` (an extra async-fn frame + per-request `finish`/`applyValidation`
+        // closures) is kept for the chunked / length-less / oversized cases it exists for.
+        // Semantics are identical to readBoundedJsonSource — same checks, same error codes.
+        const declared = headerOf(source, "content-length");
+        if (declared !== null) {
+            const length = parseContentLength(declared);
+            if (length === undefined) {
+                return Promise.resolve(wrapResponse(jsonError(400, "invalid_content_length")));
+            }
+            if (length > this.maxBodyBytes) {
+                return Promise.resolve(wrapResponse(jsonError(413, "payload_too_large")));
+            }
+            if (headerOf(source, "transfer-encoding") === null) {
+                return source.json().then((parsed) => this.finishBodyOnly(entry, parsed, ctx, finalize, wrapResponse), 
+                // Native json() rejection = malformed JSON; anything past parse goes through
+                // finishBodyOnly's own error handling.
+                () => wrapResponse(jsonError(400, "invalid_json")));
+            }
+        }
+        try {
+            return this.readBoundedJson(source).then((parsed) => {
+                if (parsed instanceof Response)
+                    return wrapResponse(parsed);
+                return this.finishBodyOnly(entry, parsed, ctx, finalize, wrapResponse);
+            }, (err) => this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse));
+        }
+        catch (err) {
+            return this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse);
+        }
+    }
+    /** Validate + run the handler for the bodyOnly path — shared by the inline fast path and the
+     * streaming fallback. A method (not per-request closures) so the hot path allocates nothing
+     * beyond the one `.then` continuation. */
+    finishBodyOnly(entry, parsed, ctx, finalize, wrapResponse) {
+        try {
+            const bodySchema = entry.schema.body;
+            const validation = bodySchema["~standard"].validate(parsed);
+            if (validation instanceof Promise) {
+                return validation.then((result) => {
+                    try {
+                        const outcome = this.applyBodyValidation(entry, result, ctx, finalize, wrapResponse);
+                        return outcome instanceof Promise
+                            ? outcome.catch((err) => this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse))
+                            : outcome;
+                    }
+                    catch (err) {
+                        return this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse);
+                    }
+                }, (err) => this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse));
+            }
+            const outcome = this.applyBodyValidation(entry, validation, ctx, finalize, wrapResponse);
+            return outcome instanceof Promise
+                ? outcome.catch((err) => this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse))
+                : outcome;
+        }
+        catch (err) {
+            return this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse);
+        }
+    }
+    applyBodyValidation(entry, result, ctx, finalize, wrapResponse) {
+        if (result.issues !== undefined)
+            return wrapResponse(validationError(result.issues));
+        ctx.body = result.value;
+        if (entry.hasDecorations)
+            Object.assign(ctx, entry.decorations);
+        const handlerOutput = entry.handler(ctx);
+        return handlerOutput instanceof Promise
+            ? handlerOutput.then((value) => finalize(value, responseSet(ctx)))
+            : finalize(handlerOutput, responseSet(ctx));
+    }
+    runQueryOnly(entry, ctx, finalize, wrapResponse) {
+        try {
+            // Call the validator directly for the raw StandardResult (read `.issues`/`.value`) — skip
+            // `validateStandard`'s per-request wrapper-object allocation, mirroring the bodyOnly path.
+            const validation = entry.schema.query["~standard"].validate(queryObjectOf(ctx[CONTEXT_SEARCH]));
+            if (validation instanceof Promise) {
+                return validation.then((settled) => {
+                    try {
+                        const outcome = this.applyQueryValidation(entry, settled, ctx, finalize, wrapResponse);
+                        return outcome instanceof Promise
+                            ? outcome.catch((err) => this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse))
+                            : outcome;
+                    }
+                    catch (err) {
+                        return this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse);
+                    }
+                }, (err) => this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse));
+            }
+            return this.applyQueryValidation(entry, validation, ctx, finalize, wrapResponse);
+        }
+        catch (err) {
+            return this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse);
+        }
+    }
+    /** Validate-result → set `ctx.query` → run handler. A method (not a per-request closure), the
+     * query analogue of {@link applyBodyValidation}. */
+    applyQueryValidation(entry, result, ctx, finalize, wrapResponse) {
+        if (result.issues !== undefined)
+            return wrapResponse(validationError(result.issues));
+        ctx.query = result.value;
+        if (entry.hasDecorations)
+            Object.assign(ctx, entry.decorations);
+        const handlerOutput = entry.handler(ctx);
+        return handlerOutput instanceof Promise
+            ? handlerOutput.then((value) => finalize(value, responseSet(ctx)), (err) => this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse))
+            : finalize(handlerOutput, responseSet(ctx));
+    }
+    /**
+     * Thread the response through each global `onResponse` hook. Stays SYNCHRONOUS until a hook
+     * actually returns a Promise — an `async` version forced a promise + microtask on EVERY response
+     * of any app with an onResponse hook (cors/securityHeaders/etag/timing all use onResponse), the
+     * same ~13%/req tax the onRequest walk was de-async'd to avoid. The first async hook hands the
+     * rest to {@link continueOnResponse}.
+     */
+    applyOnResponse(response, req) {
+        const hooks = this.onResponseHooks;
+        let current = response;
+        for (let i = 0; i < hooks.length; i++) {
+            const next = hooks[i](current, req);
+            if (next instanceof Promise) {
+                return next.then((settled) => this.continueOnResponse(settled, i + 1, req));
+            }
+            current = next;
+        }
+        return current;
+    }
+    /** Async tail of {@link applyOnResponse}: runs the remaining hooks once one has gone async. */
+    async continueOnResponse(response, nextIndex, req) {
+        let current = response;
+        for (let i = nextIndex; i < this.onResponseHooks.length; i++) {
+            const next = this.onResponseHooks[i](current, req);
+            current = next instanceof Promise ? await next : next;
+        }
+        return current;
+    }
+    /**
+     * Bound the response time. On timeout we abort `ctx.signal` (so cancellation-aware
+     * 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) {
+        let timer;
+        const timeout = new Promise((resolve) => {
+            timer = setTimeout(() => {
+                controller.abort();
+                resolve(onTimeout());
+            }, this.requestTimeoutMs);
+        });
+        try {
+            return await Promise.race([work, timeout]);
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+    }
+    /**
+     * The post-match lifecycle: validate → derive → beforeHandle → handler → afterHandle, with onError.
+     * Generic over the render: a success value goes through `finalize(result, set)` (a Web `Response`, or
+     * node-direct primitives); an early/error `Response` (validation, thrown, 500) through `wrapResponse`.
+     */
+    async runLifecycle(entry, source, ctx, finalize, wrapResponse) {
+        try {
+            if (entry.schema?.body !== undefined) {
+                const bodyError = await this.readAndValidateBody(source, entry.schema.body, ctx);
+                if (bodyError !== undefined)
+                    return wrapResponse(bodyError);
+            }
+            if (entry.schema?.query !== undefined) {
+                // Repeated query keys promote to `string[]` (so an array schema validates `?a=1&a=2`); a
+                // single occurrence stays a string. Raw `.validate` (read `.issues`/`.value`) skips the
+                // validateStandard wrapper alloc.
+                const validation = entry.schema.query["~standard"].validate(queryObjectOf(ctx[CONTEXT_SEARCH]));
+                const result = validation instanceof Promise ? await validation : validation;
+                if (result.issues !== undefined)
+                    return wrapResponse(validationError(result.issues));
+                ctx.query = result.value;
+            }
+            // Context extensions: static decorations, then per-request derives.
+            // Each hook below only awaits when it actually returns a Promise — a sync hook
+            // skips the microtask tick (a fast-path; ~64 ns/hook).
+            if (entry.hasDecorations)
+                Object.assign(ctx, entry.decorations); // skip the no-op on bare routes
+            // The `.length` guards skip iterator setup for the common no-hook route (most
+            // routes have neither derives nor before/after hooks); a hooked route pays only
+            // the length check.
+            if (entry.derives.length > 0) {
+                for (const derive of entry.derives) {
+                    const extension = derive(ctx);
+                    Object.assign(ctx, extension instanceof Promise ? await extension : extension);
+                }
+            }
+            // beforeHandle: a non-undefined return short-circuits, skipping the handler.
+            if (entry.beforeHandle.length > 0) {
+                for (const hook of entry.beforeHandle) {
+                    const outcome = hook(ctx);
+                    const early = outcome instanceof Promise ? await outcome : outcome;
+                    if (early !== undefined)
+                        return finalize(early, responseSet(ctx));
+                }
+            }
+            const handlerOutput = entry.handler(ctx);
+            let result = handlerOutput instanceof Promise ? await handlerOutput : handlerOutput;
+            // afterHandle: transform the result before serialization.
+            if (entry.afterHandle.length > 0) {
+                for (const hook of entry.afterHandle) {
+                    const transformed = hook(result, ctx);
+                    result = transformed instanceof Promise ? await transformed : transformed;
+                }
+            }
+            return finalize(result, responseSet(ctx));
+        }
+        catch (err) {
+            return this.handleLifecycleError(entry, err, ctx, finalize, wrapResponse);
+        }
+    }
+    async handleLifecycleError(entry, err, ctx, finalize, wrapResponse) {
+        // A *thrown* Response is deliberate control flow, not an error — a guard throws a redirect/401,
+        // an action throws an error page. Return it as-is (Remix/SvelteKit semantics); don't run onError
+        // or log it as a 500. This is what makes `throw redirect(...)` / `requireSession(...)` work from
+        // any handler or loader.
+        if (err instanceof Response)
+            return wrapResponse(err);
+        // onError hooks may return a custom response; otherwise the default 500 stands.
+        for (const hook of entry.onError) {
+            const outcome = hook(err, ctx);
+            const handled = outcome instanceof Promise ? await outcome : outcome;
+            if (handled !== undefined)
+                return finalize(handled, responseSet(ctx));
+        }
+        // Never crash the server or leak internals. The client gets a flat 500; the detail goes to the
+        // (redacting) logger. Body-read failures and around-hook failures land here too.
+        this.logRequestError(err, ctx);
+        return wrapResponse(jsonError(500, "internal_error"));
+    }
+    /** Log an unhandled request error to the (redacting) logger — shared by {@link runLifecycle} and the
+     * bare fast path ({@link bareError}) so both record the same fields. Never throws; never leaks. */
+    logRequestError(err, ctx) {
+        this.logger.error("unhandled request error", {
+            method: ctx.req.method,
+            path: pathnameOf(ctx.req.url),
+            name: err instanceof Error ? err.name : "Error",
+            message: err instanceof Error ? err.message : String(err),
+            stack: err instanceof Error ? err.stack : undefined,
+        });
+    }
+    async readAndValidateBody(req, schema, ctx) {
+        const contentType = headerOf(req, "content-type") ?? "";
+        let parsed;
+        if (contentType === "application/json" || contentType.includes("application/json")) {
+            const json = await this.readBoundedJson(req);
+            if (json instanceof Response)
+                return json;
+            parsed = json;
+        }
+        else if (isUrlEncodedForm(contentType)) {
+            const form = await readBoundedForm(req, this.maxBodyBytes);
+            if (form instanceof Response)
+                return form;
+            parsed = form;
+        }
+        else {
+            // multipart/form-data (file uploads) stays 415 on the schema path by design — files don't
+            // fit a value schema; use a schema-less route + @nifrajs/uploads helpers for those.
+            return jsonError(415, "unsupported_media_type");
+        }
+        const validation = schema["~standard"].validate(parsed);
+        const result = validation instanceof Promise ? await validation : validation;
+        if (result.issues !== undefined)
+            return validationError(result.issues);
+        ctx.body = result.value;
+        return undefined;
+    }
+    /**
+     * Read the body as text, capped at `maxBodyBytes`. Rejects (`null`) on a
+     * `Content-Length` over the cap *before* buffering, and aborts mid-stream once the
+     * running byte count exceeds it — so a lying or absent length can't force us to
+     * buffer an oversized payload.
+     *
+     * Fast path: when a non-chunked request carries a `Content-Length` within the cap,
+     * a native `req.json()` is already bounded — under HTTP/1.1 + HTTP/2 framing the
+     * runtime delivers at most `Content-Length` bytes — so we skip the manual stream
+     * loop and a separate text decode. It trusts the wire
+     * *framing*, not the header value: nifra only ever receives framed Requests from the
+     * runtime's HTTP server, never a hand-built one with a mismatched length. Chunked or
+     * length-less bodies fall through to the streaming byte-cap guard below.
+     */
+    async readBoundedJson(req) {
+        return readBoundedJsonSource(req, this.maxBodyBytes);
+    }
+    /**
+     * Start a `Bun.serve` instance bound to `port` (use `0` for an ephemeral port).
+     *
+     * `reusePort` sets `SO_REUSEPORT` so **multiple processes can bind the same port** and the kernel
+     * load-balances connections across them — the standard way to use every core (Bun is
+     * single-threaded per process). Spawn one process per core, each calling
+     * `app.listen(PORT, { reusePort: true })`; see `examples/cluster.ts`. Every process must opt in,
+     * and all of them must be the same app. Linux balances ~evenly; macOS accepts the flag but may
+     * favor one socket (fine for dev, measure on Linux for production numbers).
+     */
+    listen(port, options) {
+        if (typeof Bun === "undefined") {
+            // listen() is the one Bun-specific seam. Off Bun, fail loud + actionable rather
+            // than letting the Bun.serve call below throw a bare `ReferenceError: Bun is not
+            // defined`. Exercised by the @nifrajs/deno suite (which runs on a non-Bun runtime).
+            throw new FrameworkError("BUN_REQUIRED", "listen() uses Bun.serve and runs only on Bun. Serve on Node with @nifrajs/node or on Deno with @nifrajs/deno, or hand app.fetch to any fetch-compatible runtime (Workers, etc.).");
+        }
+        // Bun's `Server` is the concrete handle; we expose the stable `RunningServer`
+        // subset so the public types don't depend on the ambient `Bun` global. The cast
+        // bridges them — Bun's `.port` is `number | undefined` (undefined only for unix
+        // sockets, never a TCP `listen`) and its `.stop` returns a promise we don't await.
+        // Pass only the request — Bun's `fetch` 2nd arg is the Bun `Server`, not our `platform`.
+        // With WS routes, hand Bun a `websocket` config + a fetch that upgrades matching requests (the
+        // `server` 2nd arg is how Bun exposes `upgrade`); otherwise the lean request-only fetch. The
+        // `websocket` handlers are one shared dispatcher — each connection's `ws.data.handler` is the
+        // matched route's handler, set by `server.upgrade`.
+        // With WS routes, the dispatcher comes from the `@nifrajs/core/ws` runtime — non-null because
+        // wsRouteCount > 0 means ws() ran, and ws() requires the runtime at registration.
+        const wsHandlers = this.wsRouteCount === 0
+            ? undefined
+            : getWsRuntime().bunHandlers(this.topics);
+        const reusePort = options?.reusePort === true;
+        const running = (wsHandlers === undefined
+            ? Bun.serve({ port, reusePort, fetch: (req) => this.fetch(req) })
+            : Bun.serve({
+                port,
+                reusePort,
+                fetch: (req, server) => this.bunFetchWithWebSocket(req, server),
+                // Bun's `ServerWebSocket<BunWsData>` is runtime-compatible with the handlers' structural
+                // `BunSocket` view (kept local so `Bun.*` types never leak into the published .d.ts); the
+                // `unknown` params bridge a TS structural-variance quirk. Round-trip covered by websocket.test.ts.
+                websocket: {
+                    open: (ws) => wsHandlers.open(ws),
+                    message: (ws, message) => wsHandlers.message(ws, message),
+                    close: (ws, code, reason) => wsHandlers.close(ws, code, reason),
+                },
+            }));
+        this.bunServer = running;
+        if (this.gracefulSignals)
+            this.installSignalHandlers();
+        return running;
+    }
+    /**
+     * Gracefully stop: wait for in-flight requests to finish (up to `drainMs`), then
+     * issue a single terminal stop — graceful if everything drained, forced if
+     * stragglers remain. Safe to call when not listening.
+     *
+     * 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.
+     */
+    async stop({ drainMs = DEFAULT_DRAIN_MS } = {}) {
+        const server = this.bunServer;
+        if (server === undefined)
+            return;
+        this.bunServer = undefined;
+        const deadline = Date.now() + drainMs;
+        while (server.pendingRequests > 0 && Date.now() < deadline) {
+            await Bun.sleep(DRAIN_POLL_MS);
+        }
+        server.stop(server.pendingRequests > 0); // force-close iff stragglers remain past the deadline
+    }
+    installSignalHandlers() {
+        // Drain, then let the process exit naturally — the stopped server no longer
+        // holds the event loop open. Opt-in (`gracefulSignals`), so taking over the
+        // signals is consented; we don't force `process.exit`.
+        const onSignal = () => {
+            void this.stop();
+        };
+        process.once("SIGTERM", onSignal);
+        process.once("SIGINT", onSignal);
+    }
+}
+/**
+ * Create a new {@link Server}. Pass an `Env` to type the platform bindings — `server<Env>()` makes
+ * `c.env: Env` in every handler + middleware, and types the `env` argument of `app.fetch` /
+ * `toFetchHandler`. Omit it and `c.env` is `unknown` (validate/cast before use).
+ */
+export function server(options) {
+    // `Env` is a phantom type-level marker: the runtime `env` arrives via `app.fetch(req, { env })` at
+    // request time, not stored on the builder — so seed the context type with a cast (as `derive`/
+    // `decorate` do for their `Ctx` extensions).
+    return new Server(options);
+}
+/** The single hub Durable Object id nifra routes WS upgrades to (one hub per app — see `@nifrajs/workers`). */
+const NIFRA_WS_HUB_ID = "nifra-ws-hub";
+export function toFetchHandler(app, options) {
+    const scheduled = options?.scheduled;
+    const webSocketHub = options?.webSocketHub;
+    const resolveWs = app.resolveWebSocketUpgrade?.bind(app);
+    return {
+        fetch: (request, env, ctx) => {
+            const platform = { env, waitUntil: (promise) => ctx.waitUntil(promise) };
+            // WebSocket broadcast on Workers: route upgrades to the hub Durable Object (it holds the
+            // connections + runs the app's pub/sub, so `app.publish` reaches every client). The hub itself
+            // resolves the route and rejects non-WS paths. See `@nifrajs/workers`' `createWebSocketHub`.
+            if (webSocketHub !== undefined &&
+                request.headers.get("upgrade")?.toLowerCase() === "websocket") {
+                const ns = webSocketHub(env);
+                return ns.get(ns.idFromName(NIFRA_WS_HUB_ID)).fetch(request);
+            }
+            // Workers WebSockets: a WS upgrade for a registered route becomes a `WebSocketPair` + a 101.
+            // Feature-detected, so non-Workers edge runtimes (which lack `WebSocketPair` — e.g. Deno Deploy
+            // uses `@nifrajs/deno`'s `Deno.upgradeWebSocket`) simply fall through to the normal `fetch`.
+            const Pair = globalThis.WebSocketPair;
+            if (resolveWs !== undefined && Pair !== undefined) {
+                const accept = (outcome) => {
+                    if (outcome.kind === "pass")
+                        return app.fetch(request, platform);
+                    if (outcome.kind === "reject")
+                        return outcome.response;
+                    const pair = new Pair();
+                    const server = pair[1];
+                    server.accept();
+                    getWsRuntime().attach(server, outcome.handler, outcome.data, {
+                        openNow: true,
+                        pubsub: outcome.pubsub,
+                    });
+                    // `webSocket` is a Workers-only `ResponseInit` field (absent from the standard type), and a
+                    // 101 status is only valid on the Workers runtime — both gated by the `Pair` feature check.
+                    return new Response(null, { status: 101, webSocket: pair[0] });
+                };
+                const out = resolveWs(request, platform);
+                return out instanceof Promise ? out.then(accept) : accept(out);
+            }
+            return app.fetch(request, platform);
+        },
+        ...(scheduled !== undefined
+            ? {
+                scheduled: (controller, env, ctx) => scheduled(controller, { env, waitUntil: (promise) => ctx.waitUntil(promise) }),
+            }
+            : {}),
+    };
+}
+//# sourceMappingURL=server.js.map