@nifrajs/core 1.12.0 → 2.0.0

package/dist/server/request-context.js

@@ -0,0 +1,184 @@
+import { drainCapped, parseContentLength, readBoundedBytes } from "./body.js";
+import { parseCookies, serializeCookie } from "./cookies.js";
+import { jsonError } from "./http.js";
+import { searchOf } from "./query.js";
+import { CONTEXT_SEARCH, CONTEXT_SET, fallbackWaitUntil, getNeverAbortSignal, getUnboundedRequestBudget, headerOf, requestOf, TEXT_DECODER, } from "./runtime-core.js";
+/** A fixed past instant for cookie deletion (`Expires`). A literal epoch - deterministic, unlike an
+ * argless `new Date()`. */
+const EPOCH = new Date(0);
+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 }));
+    }
+}
+/** Coerce `c.json`/`c.text`'s second arg - a status number (the common case) or a full `ResponseInit`. */
+function statusInit(init) {
+    return typeof init === "number" ? { status: init } : init;
+}
+export class RequestContext {
+    constructor(source, params, searchOrMaxBodyBytes, signal, budget, platform, maxBodyBytes) {
+        this.source = source;
+        this.params = params;
+        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;
+    }
+    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 clientIp() {
+        // The server resolves the trust declaration into `platform.clientIp` before the context is built,
+        // so this getter just surfaces the already-derived value (raw socket peer by default).
+        return this.platformValue?.clientIp;
+    }
+    get waitUntil() {
+        return this.platformValue?.waitUntil ?? fallbackWaitUntil;
+    }
+    get req() {
+        return requestOf(this.source);
+    }
+    get request() {
+        return requestOf(this.source);
+    }
+    json(body, init) {
+        return Response.json(body, statusInit(init));
+    }
+    text(body, init) {
+        const i = statusInit(init);
+        // Default to text/plain; if the caller passes their own headers, they own the content-type.
+        if (i?.headers !== undefined)
+            return new Response(body, i);
+        return new Response(body, { ...i, headers: { "content-type": "text/plain; charset=utf-8" } });
+    }
+    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.
+ */
+export 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");
+    }
+}
+//# sourceMappingURL=request-context.js.map

package/dist/server/request-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-context.js","sourceRoot":"","sources":["../../src/server/request-context.ts"],"names":[],"mappings":"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"}

package/dist/server/respond.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Response construction from a handler's return value: the header/cookie init, the fused-lane
+ * responders, the fast JSON path, and cookie append. Imports only the runtime-core primitives + the
+ * spine types, so the wire-response format lives in one module distinct from the request engine.
+ */
+import { type HandlerResult } from "./runtime-core.js";
+import type { CtxSet, RawContext } from "./server.js";
+/** 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. */
+export declare function fusedRespondNoSet(result: unknown): Response;
+/** 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). */
+export declare function fusedRespond(result: unknown, ctx: RawContext): Response;
+export declare function toResponse(result: HandlerResult, set: CtxSet): Response;
+export declare function appendCookiesToResponse(response: Response, set: CtxSet): Response;
+//# sourceMappingURL=respond.d.ts.map

package/dist/server/respond.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"respond.d.ts","sourceRoot":"","sources":["../../src/server/respond.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAGL,KAAK,aAAa,EAEnB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAqBrD;;gFAEgF;AAChF,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,GAAG,QAAQ,CAW3D;AAED;yGACyG;AACzG,wBAAgB,YAAY,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,UAAU,GAAG,QAAQ,CAIvE;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,GAAG,QAAQ,CAwBvE;AAED,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,QAAQ,CAUjF"}

package/dist/server/respond.js

@@ -0,0 +1,81 @@
+/**
+ * Response construction from a handler's return value: the header/cookie init, the fused-lane
+ * responders, the fast JSON path, and cookie append. Imports only the runtime-core primitives + the
+ * spine types, so the wire-response format lives in one module distinct from the request engine.
+ */
+import { CONTEXT_SET, EMPTY_RESPONSE_CONTROLS, isResponseResult, } from "./runtime-core.js";
+/** 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 `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. */
+export function fusedRespondNoSet(result) {
+    if (result !== undefined &&
+        !(result instanceof Response) &&
+        typeof result === "object" &&
+        result !== null &&
+        !isResponseResult(result)) {
+        return Response.json(result);
+    }
+    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). */
+export function fusedRespond(result, ctx) {
+    const set = ctx[CONTEXT_SET]();
+    if (set === undefined)
+        return fusedRespondNoSet(result);
+    return toResponse(result, set);
+}
+export 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 faster 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);
+}
+export 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;
+}
+//# sourceMappingURL=respond.js.map

package/dist/server/respond.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"respond.js","sourceRoot":"","sources":["../../src/server/respond.ts"],"names":[],"mappings":"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"}

package/dist/server/runtime-core.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Runtime-core: the small primitives shared across the server's request/response modules - the context
+ * symbols, the `ResponseResult` marker, the lazy never-abort signal / unbounded budget singletons, and
+ * the request-source accessors. Kept in one leaf (it only type-imports the server's spine types, never
+ * its values) so `request-context`, `respond`, `node-outcome`, and the kernel form a cycle-free graph.
+ */
+import { type RequestBudget } from "../budget.js";
+import type { CtxSet, RequestSource } from "./server.js";
+/** A handler returns a `Response` (used as-is) or any value (serialized to JSON). */
+export type HandlerResult = Response | unknown;
+export declare const RESPONSE_RESULT: unique symbol;
+export declare const CONTEXT_SET: unique symbol;
+export declare const CONTEXT_SEARCH: unique symbol;
+export interface ResponseResult {
+    readonly [RESPONSE_RESULT]: true;
+    toResponse(): Response;
+    toNodeBody?(): {
+        readonly status: number;
+        readonly headers: Readonly<Record<string, string | readonly string[]>> | undefined;
+        readonly body: string | Uint8Array;
+    };
+}
+export declare function isResponseResult(value: unknown): value is ResponseResult;
+/** 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. */
+export declare function requestOf(source: RequestSource): Request;
+export declare function headerOf(source: RequestSource, name: string): string | null;
+/** 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. */
+export declare const fallbackWaitUntil: (promise: Promise<unknown>) => void;
+export declare const EMPTY_RESPONSE_CONTROLS: CtxSet;
+export declare const TEXT_DECODER: TextDecoder;
+export declare const getNeverAbortSignal: () => AbortSignal;
+export declare const getUnboundedRequestBudget: () => RequestBudget;
+//# sourceMappingURL=runtime-core.d.ts.map

package/dist/server/runtime-core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-core.d.ts","sourceRoot":"","sources":["../../src/server/runtime-core.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAgC,KAAK,aAAa,EAAE,MAAM,cAAc,CAAA;AAC/E,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAExD,qFAAqF;AACrF,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,OAAO,CAAA;AAE9C,eAAO,MAAM,eAAe,eAAsC,CAAA;AAClE,eAAO,MAAM,WAAW,eAA8B,CAAA;AACtD,eAAO,MAAM,cAAc,eAAiC,CAAA;AAE5D,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,CAAC,eAAe,CAAC,EAAE,IAAI,CAAA;IAChC,UAAU,IAAI,QAAQ,CAAA;IACtB,UAAU,CAAC,IAAI;QACb,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;QACvB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC,CAAC,GAAG,SAAS,CAAA;QAClF,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAAA;KACnC,CAAA;CACF;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAOxE;AAED;;0BAE0B;AAC1B,wBAAgB,SAAS,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAExD;AAED,wBAAgB,QAAQ,CAAC,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAE3E;AAED;6FAC6F;AAC7F,eAAO,MAAM,iBAAiB,GAAI,SAAS,OAAO,CAAC,OAAO,CAAC,KAAG,IAE7D,CAAA;AAID,eAAO,MAAM,uBAAuB,EAAwB,MAAM,CAAA;AAElE,eAAO,MAAM,YAAY,aAAoB,CAAA;AAU7C,eAAO,MAAM,mBAAmB,QAAO,WAGtC,CAAA;AACD,eAAO,MAAM,yBAAyB,QAAO,aAG5C,CAAA"}

package/dist/server/runtime-core.js

@@ -0,0 +1,51 @@
+/**
+ * Runtime-core: the small primitives shared across the server's request/response modules - the context
+ * symbols, the `ResponseResult` marker, the lazy never-abort signal / unbounded budget singletons, and
+ * the request-source accessors. Kept in one leaf (it only type-imports the server's spine types, never
+ * its values) so `request-context`, `respond`, `node-outcome`, and the kernel form a cycle-free graph.
+ */
+import { createUnboundedRequestBudget } from "../budget.js";
+export const RESPONSE_RESULT = Symbol.for("nifra.response.result");
+export const CONTEXT_SET = Symbol("nifra.context.set");
+export const CONTEXT_SEARCH = Symbol("nifra.context.search");
+export function isResponseResult(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        value[RESPONSE_RESULT] === true &&
+        typeof value.toResponse === "function");
+}
+/** 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. */
+export function requestOf(source) {
+    return source.request ?? source;
+}
+export function headerOf(source, name) {
+    return source.header?.(name) ?? source.headers.get(name);
+}
+/** 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. */
+export const fallbackWaitUntil = (promise) => {
+    void promise.catch(() => { });
+};
+// 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.
+export const EMPTY_RESPONSE_CONTROLS = Object.freeze({});
+export 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;
+let unboundedRequestBudget;
+export const getNeverAbortSignal = () => {
+    neverAbortSignal ??= new AbortController().signal;
+    return neverAbortSignal;
+};
+export const getUnboundedRequestBudget = () => {
+    unboundedRequestBudget ??= createUnboundedRequestBudget(getNeverAbortSignal());
+    return unboundedRequestBudget;
+};
+//# sourceMappingURL=runtime-core.js.map

package/dist/server/runtime-core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-core.js","sourceRoot":"","sources":["../../src/server/runtime-core.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,4BAA4B,EAAsB,MAAM,cAAc,CAAA;AAM/E,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAA;AAClE,MAAM,CAAC,MAAM,WAAW,GAAG,MAAM,CAAC,mBAAmB,CAAC,CAAA;AACtD,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC,sBAAsB,CAAC,CAAA;AAY5D,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACb,KAAkD,CAAC,eAAe,CAAC,KAAK,IAAI;QAC7E,OAAQ,KAA2C,CAAC,UAAU,KAAK,UAAU,CAC9E,CAAA;AACH,CAAC;AAED;;0BAE0B;AAC1B,MAAM,UAAU,SAAS,CAAC,MAAqB;IAC7C,OAAO,MAAM,CAAC,OAAO,IAAK,MAA6B,CAAA;AACzD,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,MAAqB,EAAE,IAAY;IAC1D,OAAO,MAAM,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;AAC1D,CAAC;AAED;6FAC6F;AAC7F,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,OAAyB,EAAQ,EAAE;IACnE,KAAK,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;AAC9B,CAAC,CAAA;AAED,iGAAiG;AACjG,gGAAgG;AAChG,MAAM,CAAC,MAAM,uBAAuB,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,CAAW,CAAA;AAElE,MAAM,CAAC,MAAM,YAAY,GAAG,IAAI,WAAW,EAAE,CAAA;AAE7C;;;;;GAKG;AACH,IAAI,gBAAyC,CAAA;AAC7C,IAAI,sBAAiD,CAAA;AACrD,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAgB,EAAE;IACnD,gBAAgB,KAAK,IAAI,eAAe,EAAE,CAAC,MAAM,CAAA;IACjD,OAAO,gBAAgB,CAAA;AACzB,CAAC,CAAA;AACD,MAAM,CAAC,MAAM,yBAAyB,GAAG,GAAkB,EAAE;IAC3D,sBAAsB,KAAK,4BAA4B,CAAC,mBAAmB,EAAE,CAAC,CAAA;IAC9E,OAAO,sBAAsB,CAAA;AAC/B,CAAC,CAAA"}

package/dist/server/server-types.d.ts

@@ -0,0 +1,203 @@
+/**
+ * Public API-surface types for the server: construction options, the capacity-admission contract,
+ * route/tool/MCP descriptors, and the middleware bundle shape. Pure types (no runtime), split out of
+ * the server kernel so the descriptor/option vocabulary is one file, distinct from the engine.
+ */
+import type { CapabilityUseEvent } from "../internal/capability-runtime.js";
+import type { AssuranceEvidence } from "../internal/route-assurance.js";
+import type { Method } from "../router/router.js";
+import type { ClientIpTrust } from "./client-ip.js";
+import type { Context, Platform, RouteSchema } from "./context.js";
+import type { Logger } from "./logger.js";
+import type { MaybePromise, OnRequestResult } from "./server.js";
+/**
+ * The outcome of a capacity-admission decision. `admitted` requests carry a `release` the server calls
+ * exactly once when the response is finalized; a shed request carries a ready `429` Response.
+ */
+export type AdmissionDecision = {
+    readonly admitted: true;
+    release(): void;
+} | {
+    readonly admitted: false;
+    readonly response: Response;
+};
+/**
+ * A capacity-admission gate. Decides, per request, whether the instance has capacity to run it now -
+ * bounding *concurrency*, which rate limits (frequency) and deadlines (duration) do not. Provide an
+ * implementation (see `@nifrajs/middleware`'s `createAdmissionController`) as {@link ServerOptions.admission}.
+ *
+ * Enabling it trades the fused native-route lane for native matching + this gate (the gate cannot be a
+ * per-request `onRequest` hook without disabling native routes entirely); when unset, the request path
+ * is untouched.
+ */
+export interface AdmissionController {
+    admit(req: Request): AdmissionDecision | Promise<AdmissionDecision>;
+}
+export interface ServerOptions {
+    /**
+     * Max request body size (bytes), enforced **only when a route declares a body schema** - the cap
+     * lives in the schema-validated read path. Default 1_000_000.
+     *
+     * A route WITHOUT a body schema (raw body, file upload, BYO-validation) that reads `c.req` directly
+     * is not auto-bounded - use **`c.boundedBody(maxBytes?)`** / **`c.boundedJson(maxBytes?)`**, which
+     * apply this same cap (override per route by passing `maxBytes` - larger for an upload endpoint,
+     * smaller to tighten one).
+     */
+    readonly maxBodyBytes?: number;
+    /** Max inbound WebSocket message size (bytes) when `listen()`ing on Bun - frames over this are rejected
+     * by the runtime before reaching your handler (so a huge frame can't be JSON-parsed into memory).
+     * Default: `maxBodyBytes` (1 MB). */
+    readonly wsMaxPayloadBytes?: number;
+    /** Per-request timeout (ms): a slower request gets a 503 and `ctx.signal` aborts. 0 disables (default). */
+    readonly requestTimeoutMs?: number;
+    /**
+     * How to derive `c.clientIp` behind a reverse proxy or CDN. Omit (default) to trust only the raw
+     * socket peer and never believe a forwarded header. Set `{ trustedHops: n }` when the app sits
+     * behind `n` proxies you operate (the caller is read from `X-Forwarded-For` past those hops), or
+     * `{ header: name }` to trust one edge-set header's first value. Declaring trust the app can't
+     * actually enforce lets clients forge their IP, so leave it unset unless a proxy really fronts you.
+     */
+    readonly clientIp?: ClientIpTrust;
+    /**
+     * Admit the public `x-nifra-deadline` header and let it shorten local work. Disabled by default:
+     * services that participate in trusted cross-service deadline propagation opt in explicitly,
+     * while ordinary/public HTTP routes pay no header-admission tax and ignore hostile client values.
+     */
+    readonly acceptInboundDeadlines?: boolean;
+    /**
+     * Maximum time accepted from an inbound `x-nifra-deadline`, in milliseconds. An incoming absolute
+     * deadline may shorten this cap (and `requestTimeoutMs`, when configured), never extend it.
+     * Default 30_000; applies only when `acceptInboundDeadlines` is enabled and the header is present.
+     */
+    readonly maxInboundDeadlineMs?: number;
+    /** When `listen()`ing, install SIGTERM/SIGINT handlers that gracefully `stop()`. Default false. */
+    readonly gracefulSignals?: boolean;
+    /**
+     * Capacity-admission gate (see {@link AdmissionController}). Bounds concurrent in-flight work so a
+     * healthy instance sheds load (`429` + `Retry-After`) instead of accepting more than it can finish.
+     * Off by default. Enabling it disables the fused native-route fast path (requests route through the
+     * shared matched lane where the gate runs); when unset, the request path pays nothing.
+     */
+    readonly admission?: AdmissionController;
+    /**
+     * Optional token-only observation hook called by `useCapability(c, id)`. It receives no request,
+     * parameters, body, tenant, or values. Routes without capability declarations keep the old hot path.
+     */
+    readonly onCapabilityUse?: (event: CapabilityUseEvent) => void;
+    /** Structured logger for framework events (redacts secrets). Default: JSON to stderr. */
+    readonly logger?: Logger;
+    /**
+     * App-wide fallback fired when a route **without its own `onValidationError`** fails body/query
+     * validation. Same contract as the per-route hook (`(issues, ctx, kind) => Response | repaired-value |
+     * undefined`): a route's own hook takes precedence, and a route can fall through to the plain `422` by
+     * returning `undefined`. Use it for one app-wide error envelope (like tRPC's `errorFormatter` /
+     * Fastify's `setErrorHandler`) instead of repeating a formatter per route.
+     */
+    readonly onValidationError?: RouteSchema["onValidationError"];
+}
+/**
+ * MCP tool safety hints, surfaced in `tools/list`, that tell an agent how risky a `.tool()` call is - so it
+ * can decide whether to auto-invoke or confirm first. All optional; an omitted hint means "unknown". Mirrors
+ * the MCP spec's tool `annotations`.
+ */
+export interface ToolAnnotations {
+    /** Human-readable display title for the tool, distinct from the machine `name`. */
+    readonly title?: string;
+    /** The tool does not modify its environment (a pure read). */
+    readonly readOnlyHint?: boolean;
+    /** The tool may perform destructive updates - only meaningful when `readOnlyHint` is not `true`. */
+    readonly destructiveHint?: boolean;
+    /** Repeated calls with the same arguments have no additional effect beyond the first. */
+    readonly idempotentHint?: boolean;
+    /** The tool interacts with external entities (an "open world" beyond this server). */
+    readonly openWorldHint?: boolean;
+}
+/**
+ * A registered route's public descriptor - method, path, and input schemas. The
+ * router trie discards the original patterns, so this flat list is what lets tools
+ * (e.g. `toOpenAPI`) enumerate routes after registration.
+ */
+export interface RouteDescriptor {
+    readonly method: Method;
+    readonly path: string;
+    readonly schema: RouteSchema | undefined;
+    /** Effective enforcement evidence, populated only during reflection/introspection. */
+    readonly assurance?: readonly AssuranceEvidence[];
+    /** Normalized declared effect tokens, populated only when the route declares any. */
+    readonly capabilities?: readonly string[];
+    /** Set when the route is a declared dynamic route family (`schema.family`). */
+    readonly family?: boolean;
+    readonly tool?: {
+        readonly name: string;
+        readonly description: string;
+        readonly annotations?: ToolAnnotations;
+    };
+}
+/** A message in an MCP prompt's rendered output (see {@link Server.prompt}). */
+export interface PromptMessage {
+    readonly role: "user" | "assistant";
+    readonly content: {
+        readonly type: "text";
+        readonly text: string;
+    };
+}
+/** One declared argument of an MCP prompt, surfaced in `prompts/list`. */
+export interface PromptArgument {
+    readonly name: string;
+    readonly description?: string;
+    readonly required?: boolean;
+}
+/** An app-declared MCP resource - read-only data an agent can fetch through `nifra mcp`. */
+export interface McpResourceDescriptor {
+    readonly uri: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly mimeType?: string;
+    readonly read: () => MaybePromise<string | {
+        readonly text: string;
+        readonly mimeType?: string;
+    }>;
+}
+/** An app-declared MCP prompt - a reusable prompt template an agent can fetch through `nifra mcp`. */
+export interface McpPromptDescriptor {
+    readonly name: string;
+    readonly description: string;
+    readonly arguments?: readonly PromptArgument[];
+    readonly handler: (args: Record<string, string>) => MaybePromise<readonly PromptMessage[]>;
+}
+/**
+ * The handle `listen()` returns - the slice of Bun's server nifra holds and exposes.
+ * Declared explicitly (rather than `ReturnType<typeof Bun.serve>`) so the public type
+ * surface doesn't leak the ambient `Bun` global into consumers' `.d.ts` resolution.
+ */
+export interface RunningServer {
+    readonly port: number;
+    readonly hostname: string;
+    readonly pendingRequests: number;
+    stop(closeActiveConnections?: boolean): void;
+}
+/**
+ * A bundle of lifecycle hooks applied together via {@link Server.use} - the unit
+ * `@nifrajs/middleware` ships (cors, security headers, rate-limit). Every hook is
+ * optional and wired to its lifecycle point. Middleware is context-agnostic (sees
+ * the base `Context`); `use` does no context-type merging - the full type-merging
+ * plugin system is deferred, and `.use` is reserved as its future entry point.
+ */
+export interface Middleware {
+    readonly name?: string;
+    readonly onRequest?: (req: Request, platform?: Platform) => MaybePromise<OnRequestResult>;
+    readonly around?: <T>(context: Context, next: () => MaybePromise<T>) => MaybePromise<T>;
+    readonly beforeHandle?: (context: Context) => MaybePromise<unknown>;
+    readonly afterHandle?: (result: unknown, context: Context) => MaybePromise<unknown>;
+    readonly onResponse?: (response: Response, req: Request) => MaybePromise<Response>;
+    readonly onResponseFinalized?: (outcome: ResponseFinalization, req: Request) => MaybePromise<void>;
+    readonly onError?: (error: unknown, context: Context) => MaybePromise<unknown>;
+}
+/** The terminal response-pipeline outcome observed after every transforming `onResponse` hook. */
+export interface ResponseFinalization {
+    /** The final response, or the last response available when a transformation failed. */
+    readonly response: Response;
+    /** A response-hook failure. Terminal observers run fail-open before the error is rethrown. */
+    readonly error?: unknown;
+}
+//# sourceMappingURL=server-types.d.ts.map

package/dist/server/server-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-types.d.ts","sourceRoot":"","sources":["../../src/server/server-types.ts"],"names":[],"mappings":"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"}

package/dist/server/server-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=server-types.js.map

package/dist/server/server-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-types.js","sourceRoot":"","sources":["../../src/server/server-types.ts"],"names":[],"mappings":""}