@daloyjs/core 1.0.0-beta.6 → 1.0.0-rc.0

package/dist/app.js

@@ -1,7 +1,6 @@
 import { Router } from "./router.js";
 import { WebSocketRegistry, normalizeWebSocketOptions, } from "./websocket.js";
 import { BadRequestError, ForbiddenError, HttpError, InternalError, MethodNotAllowedError, NotFoundError, PayloadTooLargeError, RequestTimeoutError, TooManyRequestsError, UnsupportedMediaTypeError, ValidationError, } from "./errors.js";
-import { validate } from "./schema.js";
 import { readBodyLimited, safeJsonParse, randomId, assertNoDuplicateSingletonHeaders, assertNoReservedInternalHeaders, assertHeaderCountWithinLimit, DEFAULT_MAX_HEADER_COUNT, assertStrongSecret, timingSafeEqual, isForbiddenObjectKey, } from "./security.js";
 import { createLogger, noopLogger } from "./logger.js";
 import { generateOpenAPI, openapiToYAML, } from "./openapi.js";
@@ -195,10 +194,121 @@ export const DALOY_REQUEST_RAW_BODY = Symbol.for("daloyjs.request.rawBody");
  */
 export const DALOY_RAW_STREAM = Symbol.for("daloyjs.response.rawStream");
 /**
+ * Internal Symbol an adapter sets (once, on its request shim's prototype) to
+ * declare: "the object that ultimately consumes this request's `Response`
+ * only reads `status` / `headers` / {@link DALOY_RAW_BODY} — it never needs a
+ * branded WHATWG `Response`". When present on the incoming request,
+ * {@link serializeResult} may return a {@link LightResponse} and skip the
+ * ~2µs undici `Response` construction per request. Requests without the
+ * marker (Bun / Deno / Workers adapters, tests, direct `app.fetch()` callers)
+ * always get a real `Response`, so the public contract is unchanged.
+ */
+export const DALOY_LIGHT_RESPONSE_OK = Symbol.for("daloyjs.response.lightOk");
+/**
+ * Minimal `Response` stand-in returned on the Node-adapter hot path (gated by
+ * {@link DALOY_LIGHT_RESPONSE_OK}). Carries `status` + a real `Headers`
+ * instance + the raw body bytes via {@link DALOY_RAW_BODY}; every other
+ * WHATWG surface (body streams, `json()`, `clone()`, …) delegates to a
+ * lazily-materialized real `Response`, so hook code that inspects the
+ * response body still behaves exactly as before — it just pays the
+ * construction cost only when it actually does so. `instanceof Response`
+ * holds via prototype re-rooting; all overridden accessors below shadow
+ * undici's brand-checked ones.
+ */
+class LightResponse {
+    #status;
+    #headers;
+    #rawBody;
+    #real;
+    constructor(status, headers, rawBody) {
+        this.#status = status;
+        this.#headers = headers;
+        this.#rawBody = rawBody;
+        this[DALOY_RAW_BODY] = rawBody;
+    }
+    /** Build (once) and return an equivalent real `Response` for rare surfaces. */
+    #materialize() {
+        return (this.#real ??= new Response(this.#rawBody, {
+            status: this.#status,
+            headers: this.#headers,
+        }));
+    }
+    get status() {
+        return this.#status;
+    }
+    get headers() {
+        return this.#headers;
+    }
+    get ok() {
+        return this.#status >= 200 && this.#status <= 299;
+    }
+    // Spec constants for a synthesized (non-network) Response.
+    get statusText() {
+        return "";
+    }
+    get type() {
+        return "default";
+    }
+    get url() {
+        return "";
+    }
+    get redirected() {
+        return false;
+    }
+    get body() {
+        return this.#materialize().body;
+    }
+    get bodyUsed() {
+        return this.#real !== undefined ? this.#real.bodyUsed : false;
+    }
+    arrayBuffer() {
+        return this.#materialize().arrayBuffer();
+    }
+    blob() {
+        return this.#materialize().blob();
+    }
+    bytes() {
+        return this.#materialize().bytes();
+    }
+    formData() {
+        return this.#materialize().formData();
+    }
+    json() {
+        return this.#materialize().json();
+    }
+    text() {
+        return this.#materialize().text();
+    }
+    clone() {
+        return this.#materialize().clone();
+    }
+}
+// `instanceof Response` must hold for hook code and adapter checks. Every
+// own getter/method above shadows undici's brand-checked accessors.
+Object.setPrototypeOf(LightResponse.prototype, Response.prototype);
+/**
+ * The DaloyJS application: a contract-first router plus a web-standard
+ * `fetch(Request): Promise<Response>` handler that runs unchanged on Node,
+ * Bun, Deno, Cloudflare Workers, and Vercel via the adapters.
+ *
+ * Routes registered with {@link App.route} are validated against their
+ * declared schemas on the way in and out, accumulate in the typed
+ * {@link App.routes} tuple (powering OpenAPI generation and the typed
+ * client), and are served with secure defaults: body limits, request
+ * timeouts, security headers, and prod-mode error redaction.
+ *
+ * @typeParam Routes - Compile-time tuple of registered route definitions,
+ * grown by each {@link App.route} call.
  * @since 0.1.0
  */
 export class App {
+    /**
+     * Resolved constructor options. The security-relevant trio is always
+     * populated: `validateResponses` (default `true`), `bodyLimitBytes`
+     * (default 1 MiB), and `requestTimeoutMs` (default 30_000 ms).
+     */
     options;
+    /** Structured logger for the app. Defaults to a JSON-lines console logger; override via `options.logger`. */
     log;
     /**
      * Public registry: enables OpenAPI gen, typed-client gen, dead-route detection.
@@ -596,6 +706,26 @@ export class App {
         const origin = request.headers.get("origin");
         if (!origin || origin === "null")
             return;
+        // Fast path: when both the Origin header and the request URL are in the
+        // trivially-normalized shape (lowercase ASCII scheme://host[:port] with
+        // no userinfo / percent-escapes / IPv6 brackets), their origins can be
+        // compared as plain strings without two `new URL()` constructions per
+        // request. Anything unusual returns `undefined` and falls back to the
+        // exact WHATWG comparison below — the guard's accept/reject semantics
+        // are identical on both paths.
+        const fastHeaderOrigin = getOriginFast(origin);
+        if (fastHeaderOrigin !== undefined) {
+            const fastReqOrigin = typeof requestUrl === "string" ? getOriginFast(requestUrl) : requestUrl.origin;
+            if (fastReqOrigin !== undefined) {
+                if (fastHeaderOrigin === fastReqOrigin)
+                    return;
+                if (corsOriginAllows.some((allows) => allows(origin)))
+                    return;
+                throw new ForbiddenError(`Cross-origin ${method} from "${fastHeaderOrigin}" rejected: no registered cors() policy allows that origin. ` +
+                    `Register cors({ origin: [...] }) via app.use(...) to allow it, or pass ` +
+                    `app({ corsCrossOriginGuard: false }) / app({ secureDefaults: false }) to disable this guard.`);
+            }
+        }
         let originUrl;
         try {
             originUrl = new URL(origin);
@@ -932,6 +1062,9 @@ export class App {
             operationId: "getOpenAPIDocument",
             ...(tags.length ? { tags } : {}),
             summary: "OpenAPI 3.1 document",
+            // Framework-owned body (the generated spec document); the missing
+            // schema is intentional, not an OWASP API3 leak risk.
+            acknowledgeNoResponseBodySchema: true,
             responses: {
                 200: { description: "OpenAPI 3.1 document for this application." },
             },
@@ -947,6 +1080,7 @@ export class App {
                 operationId: "getOpenAPIDocumentYaml",
                 ...(tags.length ? { tags } : {}),
                 summary: "OpenAPI 3.1 document (YAML)",
+                acknowledgeNoResponseBodySchema: true,
                 responses: {
                     200: { description: "OpenAPI 3.1 document for this application, in YAML." },
                 },
@@ -985,6 +1119,7 @@ export class App {
             operationId: "getDocsUI",
             ...(tags.length ? { tags } : {}),
             summary: "Interactive API reference",
+            acknowledgeNoResponseBodySchema: true,
             responses: {
                 200: { description: "Interactive API documentation UI." },
             },
@@ -1082,6 +1217,8 @@ export class App {
             operationId: "getAsyncAPIDocument",
             ...(tags.length ? { tags } : {}),
             summary: "AsyncAPI 3.0 document",
+            // Framework-owned bodies on the AsyncAPI surface, like mountDocs above.
+            acknowledgeNoResponseBodySchema: true,
             responses: {
                 200: { description: "AsyncAPI 3.0 document for this application's WebSocket channels." },
             },
@@ -1094,6 +1231,7 @@ export class App {
                 operationId: "getAsyncAPIDocumentYaml",
                 ...(tags.length ? { tags } : {}),
                 summary: "AsyncAPI 3.0 document (YAML)",
+                acknowledgeNoResponseBodySchema: true,
                 responses: {
                     200: { description: "AsyncAPI 3.0 document for this application, in YAML." },
                 },
@@ -1115,6 +1253,7 @@ export class App {
             operationId: "getAsyncAPIUI",
             ...(tags.length ? { tags } : {}),
             summary: "Interactive AsyncAPI reference",
+            acknowledgeNoResponseBodySchema: true,
             responses: {
                 200: { description: "Interactive AsyncAPI documentation UI." },
             },
@@ -1443,6 +1582,8 @@ export class App {
             operationId: "metrics",
             tags: ["Observability"],
             summary: "Prometheus metrics scrape endpoint",
+            // Prometheus text exposition rendered by the framework registry.
+            acknowledgeNoResponseBodySchema: true,
             handler: async ({ request }) => {
                 if (buckets && rateLimitConfig) {
                     const key = healthRouteKey(request);
@@ -1561,6 +1702,8 @@ export class App {
             operationId: isHealth ? "healthcheck" : "readinesscheck",
             tags: ["Health"],
             summary: isHealth ? "Liveness probe" : "Readiness probe",
+            // Framework-serialized probe payload; missing schema is intentional.
+            acknowledgeNoResponseBodySchema: true,
             handler: async ({ request }) => {
                 if (buckets && rateLimitConfig) {
                     const key = healthRouteKey(request);
@@ -1799,6 +1942,20 @@ export class App {
         this.resetBootGuardCache();
         return this;
     }
+    /**
+     * Apply an ordered list of plugin extensions to the
+     * group-level hook chain. Each extension's `handler` is wrapped into a
+     * single-event {@link Hooks} bundle so subsequent route registrations
+     * pick it up via the normal hook composition path.
+     * @internal
+     */
+    applyExtensions(ordered) {
+        for (const ext of ordered) {
+            const hooks = { [ext.event]: ext.handler };
+            this.groupHooks.push(hooks);
+        }
+        this._coldPathHooksCache = undefined;
+    }
     /**
      * Decorate `ctx.state` with a value available inside every handler and hook.
      *
@@ -1821,22 +1978,10 @@ export class App {
      *
      * @param key - Property name on `ctx.state`.
      * @param value - Value bound to that property on every request.
+     * @param opts - Pass `{ override: true }` to replace an existing decoration (logged as a warning).
      * @returns This `App` instance for chaining.
+     * @throws Error if `key` is already decorated and `opts.override` is not `true`.
      */
-    /**
-     * Apply an ordered list of plugin extensions to the
-     * group-level hook chain. Each extension's `handler` is wrapped into a
-     * single-event {@link Hooks} bundle so subsequent route registrations
-     * pick it up via the normal hook composition path.
-     * @internal
-     */
-    applyExtensions(ordered) {
-        for (const ext of ordered) {
-            const hooks = { [ext.event]: ext.handler };
-            this.groupHooks.push(hooks);
-        }
-        this._coldPathHooksCache = undefined;
-    }
     decorate(key, value, opts = {}) {
         if (Object.prototype.hasOwnProperty.call(this.decorations, key) && opts.override !== true) {
             // Namespace-protected decorators. Refuse to silently
@@ -2254,7 +2399,11 @@ export class App {
                 if (isPromiseLike(routeOnRequestResult))
                     await routeOnRequestResult;
             }
-            ctx = await buildContext(request, getUrl, match.params, def, this.options);
+            // buildContext is sync unless a schema validator or body read actually
+            // suspends — branch on the promise so the fully-sync case never
+            // schedules a microtask.
+            const builtCtx = buildContext(request, getUrl, match.params, def, this.options);
+            ctx = isPromiseLike(builtCtx) ? await builtCtx : builtCtx;
             // Stable two-field write keeps `ctx.state`'s hidden class consistent across
             // requests for the common no-decorator case. The decorations spread only
             // fires when `app.decorate()` was actually called.
@@ -2325,7 +2474,11 @@ export class App {
                 }
                 return finalizedRaw;
             }
-            const serializeResultRes = serializeResult(result, def, this.options.validateResponses ?? true);
+            const serializeResultRes = serializeResult(result, def, this.options.validateResponses ?? true, 
+            // Adapter shims set this marker on their request prototype to declare
+            // that the response consumer only reads status/headers/raw-body — see
+            // DALOY_LIGHT_RESPONSE_OK. Everyone else gets a real Response.
+            request[DALOY_LIGHT_RESPONSE_OK] === true);
             let response = isPromiseLike(serializeResultRes)
                 ? await serializeResultRes
                 : serializeResultRes;
@@ -2440,13 +2593,6 @@ export class App {
         const req = url instanceof Request ? url : new Request(url, init);
         return this.fetch(req);
     }
-    /**
-     * Return a JSON-serializable summary of every registered route. Useful for
-     * dead-route detection, dashboards, and tests that want to assert against
-     * the route table without parsing the OpenAPI document.
-     *
-     * @returns Array of one {@link IntrospectedRoute} per registered route.
-     */
     /**
      * Emit a one-time development warning when any route declares a `2xx`
      * response without a body schema, because response-field stripping
@@ -2469,9 +2615,18 @@ export class App {
             routes: offending.slice(0, 20),
         }, `${offending.length} route(s) declare a 2xx response with no body schema; ` +
             "response field-level stripping (OWASP API3) is not applied there, so a handler that " +
-            "returns undeclared fields will leak them. Declare a response body schema, or ignore if " +
-            "the route intentionally returns no body. Run `daloy doctor` to list them.");
+            "returns undeclared fields will leak them. Declare a response body schema, or set " +
+            "`acknowledgeNoResponseBodySchema: true` on routes that intentionally return an opaque " +
+            "or body-less response. Run `daloy doctor` to list them. " +
+            "See https://daloyjs.dev/docs/security/owasp-api-top-10#api3");
     }
+    /**
+     * Return a JSON-serializable summary of every registered route. Useful for
+     * dead-route detection, dashboards, and tests that want to assert against
+     * the route table without parsing the OpenAPI document.
+     *
+     * @returns Array of one {@link IntrospectedRoute} per registered route.
+     */
     introspect() {
         return this.routes.map((r) => {
             const route = {
@@ -2639,6 +2794,12 @@ function detectHeaderMutatingMiddleware(layers) {
 /**
  * Topological sort of plugin extensions. Refuses-at-call
  * on cyclic ordering with a structured error naming the cycle.
+ *
+ * @param exts - Extensions to order by their `before` / `after` constraints (Kahn's algorithm).
+ * @returns The extensions in a valid execution order.
+ * @throws Error on duplicate extension names, on a `before`/`after` cycle
+ * (naming the members), or when two extensions mutate the same response
+ * header without declaring an ordering between each other.
  * @internal
  */
 export function topoSortExtensions(exts) {
@@ -2766,6 +2927,85 @@ function getPathnameFast(url) {
         end = h;
     return url.slice(pathStart, end);
 }
+/**
+ * Extract the WHATWG origin (`scheme://host[:port]`) from an absolute
+ * `http`/`https` URL or Origin-header value without constructing a `URL`.
+ * Companion to {@link getPathnameFast}, used by the cross-origin guard on
+ * state-changing requests.
+ *
+ * Returns `undefined` — signalling "fall back to `new URL(...).origin`" —
+ * whenever the input is not in the trivially-normalized shape a `URL` parse
+ * would return unchanged: non-`http(s)` schemes, uppercase characters
+ * (scheme/host case-folding), userinfo (`user@host`, which `URL.origin`
+ * strips), percent-escapes, non-ASCII hosts (IDNA/punycode), IPv6 literals
+ * (zero-compression normalization), empty hosts, backslashes (URL treats
+ * `\` as `/`), and explicit default ports (`:80` / `:443`, which
+ * `URL.origin` elides). The fast path therefore never *disagrees* with the
+ * WHATWG origin — it only answers when the answer is unambiguous.
+ */
+function getOriginFast(url) {
+    let hostStart;
+    if (url.startsWith("http://"))
+        hostStart = 7;
+    else if (url.startsWith("https://"))
+        hostStart = 8;
+    else
+        return undefined;
+    // Find the end of the authority: first "/", "?", or "#" after the scheme.
+    let end = url.length;
+    for (let i = hostStart; i < url.length; i++) {
+        const c = url.charCodeAt(i);
+        if (c === 47 /* / */ || c === 63 /* ? */ || c === 35 /* # */) {
+            end = i;
+            break;
+        }
+    }
+    if (end === hostStart)
+        return undefined; // empty host
+    for (let i = hostStart; i < end; i++) {
+        const c = url.charCodeAt(i);
+        // Reject anything that could normalize differently under a real URL
+        // parse: uppercase A-Z, userinfo "@", percent "%", IPv6 "[", backslash
+        // "\", raw whitespace/controls, and all non-ASCII.
+        if ((c >= 65 && c <= 90) /* A-Z */ ||
+            c === 64 /* @ */ ||
+            c === 37 /* % */ ||
+            c === 91 /* [ */ ||
+            c === 92 /* \ */ ||
+            c <= 32 /* controls + space */ ||
+            c >= 127 /* DEL + non-ASCII */) {
+            return undefined;
+        }
+    }
+    const authority = url.slice(hostStart, end);
+    const colon = authority.indexOf(":");
+    if (colon !== -1) {
+        const port = authority.slice(colon + 1);
+        // Trailing ":" alone, an empty port, or a default port all normalize to
+        // no port under URL — fall back rather than replicate that here. A
+        // second ":" (malformed / IPv6-ish) also falls back.
+        if (port.length === 0 || port.indexOf(":") !== -1)
+            return undefined;
+        if ((hostStart === 7 && port === "80") /* http default */ ||
+            (hostStart === 8 && port === "443") /* https default */) {
+            return undefined;
+        }
+        // Port must be all digits; anything else is not trivially normalized.
+        for (let i = 0; i < port.length; i++) {
+            const c = port.charCodeAt(i);
+            if (c < 48 || c > 57)
+                return undefined;
+        }
+        // Leading zeros normalize away under URL ("0080" -> "80"), and ports
+        // above 65535 make the URL constructor *throw* (the guard's malformed-
+        // origin rejection) — both must take the exact WHATWG path.
+        if (port.length > 1 && port.charCodeAt(0) === 48 /* 0 */)
+            return undefined;
+        if (port.length > 5 || (port.length === 5 && Number(port) > 65535))
+            return undefined;
+    }
+    return url.slice(0, end);
+}
 function mergeHooks(layers) {
     const pick = (key) => layers.map((h) => h[key]).filter((f) => typeof f === "function");
     const requiredScopes = requiredScopesFromHooks(layers);
@@ -3018,7 +3258,10 @@ function hasRequestSchema(request, key) {
  * It powers both the `daloy doctor` `audit.response.bodySchema` finding and
  * the development-mode boot warning emitted on the first request. The result
  * is advisory — a route may legitimately return no body — so callers treat
- * it as a `warn`, never a hard error.
+ * it as a `warn`, never a hard error. Routes that set
+ * `acknowledgeNoResponseBodySchema: true` (including the framework-mounted
+ * docs, AsyncAPI, health, and metrics routes, whose bodies DaloyJS itself
+ * serializes) are skipped: the missing schema is declared intentional.
  *
  * @param routes - Route definitions to inspect (typically `app.routes`).
  * @returns One entry per offending route with the affected `2xx` status codes.
@@ -3027,6 +3270,8 @@ function hasRequestSchema(request, key) {
 export function findRoutesMissingResponseBodySchema(routes) {
     const offending = [];
     for (const route of routes) {
+        if (route.acknowledgeNoResponseBodySchema === true)
+            continue;
         const statuses = [];
         const responses = route.responses;
         for (const key of Object.keys(responses)) {
@@ -3137,44 +3382,77 @@ function buildContext(request, getUrl, rawParams, def, opts) {
     if (!hasSchema) {
         return finishContext();
     }
-    return (async () => {
-        if (def.request?.params) {
-            const r = await validate(def.request.params, rawParams);
-            if (r.issues)
-                throw new ValidationError("params", toIssues(r.issues));
-            params = r.value;
+    const applyChecked = (r, part) => {
+        if (r.issues)
+            throw new ValidationError(part, toIssues(r.issues));
+        return r.value;
+    };
+    const validateBodyAndFinish = (raw) => {
+        const r = def.request.body["~standard"].validate(raw);
+        if (isPromiseLike(r)) {
+            return r.then((resolved) => {
+                body = applyChecked(resolved, "body");
+                return finishContext();
+            });
         }
-        if (hasQuerySchema) {
-            const r = await validate(def.request.query, buildQuery());
-            if (r.issues)
-                throw new ValidationError("query", toIssues(r.issues));
-            query = r.value;
+        body = applyChecked(r, "body");
+        return finishContext();
+    };
+    const stepBody = () => {
+        if (!def.request?.body)
+            return finishContext();
+        const ct = (request.headers.get("content-type") ?? "").toLowerCase();
+        const allowed = def.accepts ??
+            opts.allowedContentTypes ?? [
+            "application/json",
+            "application/x-www-form-urlencoded",
+            "multipart/form-data",
+        ];
+        if (!allowed.some((a) => ct.includes(a))) {
+            throw new UnsupportedMediaTypeError(ct || "(none)", allowed);
         }
-        if (hasHeadersSchema) {
-            const r = await validate(def.request.headers, buildHeaders());
-            if (r.issues)
-                throw new ValidationError("headers", toIssues(r.issues));
-            headers = r.value;
-        }
-        if (def.request?.body) {
-            const ct = (request.headers.get("content-type") ?? "").toLowerCase();
-            const allowed = def.accepts ??
-                opts.allowedContentTypes ?? [
-                "application/json",
-                "application/x-www-form-urlencoded",
-                "multipart/form-data",
-            ];
-            if (!allowed.some((a) => ct.includes(a))) {
-                throw new UnsupportedMediaTypeError(ct || "(none)", allowed);
-            }
-            const raw = await readBody(request, ct, opts.bodyLimitBytes, opts.multipart);
-            const r = await validate(def.request.body, raw);
-            if (r.issues)
-                throw new ValidationError("body", toIssues(r.issues));
-            body = r.value;
+        const raw = readBody(request, ct, opts.bodyLimitBytes, opts.multipart);
+        if (isPromiseLike(raw))
+            return raw.then(validateBodyAndFinish);
+        return validateBodyAndFinish(raw);
+    };
+    const stepHeaders = () => {
+        if (!hasHeadersSchema)
+            return stepBody();
+        const r = def.request.headers["~standard"].validate(buildHeaders());
+        if (isPromiseLike(r)) {
+            return r.then((resolved) => {
+                headers = applyChecked(resolved, "headers");
+                return stepBody();
+            });
         }
-        return finishContext();
-    })();
+        headers = applyChecked(r, "headers");
+        return stepBody();
+    };
+    const stepQuery = () => {
+        if (!hasQuerySchema)
+            return stepHeaders();
+        const r = def.request.query["~standard"].validate(buildQuery());
+        if (isPromiseLike(r)) {
+            return r.then((resolved) => {
+                query = applyChecked(resolved, "query");
+                return stepHeaders();
+            });
+        }
+        query = applyChecked(r, "query");
+        return stepHeaders();
+    };
+    if (def.request?.params) {
+        const r = def.request.params["~standard"].validate(rawParams);
+        if (isPromiseLike(r)) {
+            return r.then((resolved) => {
+                params = applyChecked(resolved, "params");
+                return stepQuery();
+            });
+        }
+        params = applyChecked(r, "params");
+    }
+    return stepQuery();
 }
 function headersToObject(h) {
     const o = {};
@@ -3205,26 +3483,79 @@ function toIssues(issues) {
             .join("."),
     }));
 }
-async function readBody(req, ct, limit, multipart) {
+/** Shared decoder for request-body text. Allocating one per request is wasted work. */
+const TEXT_DECODER = new TextDecoder();
+/**
+ * Synchronous fast path for {@link readBodyLimited}: returns the adapter's
+ * pre-buffered body bytes when they are available on the request via
+ * {@link DALOY_REQUEST_RAW_BODY}, or `undefined` when the caller must fall
+ * back to the async streaming read. Runs the exact same Content-Length
+ * validation and size-limit checks (in the same order, throwing the same
+ * errors) as `readBodyLimited`, so the security posture is identical — the
+ * only difference is that a symbol-cache hit never touches the microtask
+ * queue.
+ *
+ * @throws {BadRequestError} When `Content-Length` is present but invalid.
+ * @throws {PayloadTooLargeError} When the declared or actual size exceeds `limit`.
+ */
+function readBodyBytesFast(req, limit) {
+    const cl = req.headers.get("content-length");
+    if (cl) {
+        const n = Number(cl);
+        if (!Number.isFinite(n) || n < 0)
+            throw new BadRequestError("Invalid Content-Length");
+        if (n > limit)
+            throw new PayloadTooLargeError(limit);
+    }
+    const cached = req[DALOY_REQUEST_RAW_BODY];
+    if (cached instanceof Uint8Array) {
+        if (cached.byteLength > limit)
+            throw new PayloadTooLargeError(limit);
+        return cached;
+    }
+    return undefined;
+}
+function parseJsonBodyBytes(bytes) {
+    if (bytes.byteLength === 0)
+        return undefined;
+    return safeJsonParse(TEXT_DECODER.decode(bytes));
+}
+function parseUrlencodedBodyBytes(bytes) {
+    const params = new URLSearchParams(TEXT_DECODER.decode(bytes));
+    // Same Spring4Shell-class defense as queryToObject: Object.fromEntries
+    // would set __proto__ / constructor / prototype as own properties.
+    const out = {};
+    for (const [k, v] of params) {
+        if (isForbiddenObjectKey(k))
+            continue;
+        out[k] = v;
+    }
+    return out;
+}
+/**
+ * Read and parse a request body according to its content type. Plain
+ * (non-`async`) on purpose: when the adapter pre-buffered the body bytes
+ * (the common JSON POST case on Node), the parse completes synchronously and
+ * the caller stays on the sync dispatch fast path. Falls back to the
+ * streaming `readBodyLimited` promise otherwise. All parsing keeps the
+ * prototype-pollution-safe semantics of the previous implementation.
+ */
+function readBody(req, ct, limit, multipart) {
     if (ct.includes("application/json")) {
-        const bytes = await readBodyLimited(req, limit);
-        if (bytes.byteLength === 0)
-            return undefined;
-        return safeJsonParse(new TextDecoder().decode(bytes));
+        const fast = readBodyBytesFast(req, limit);
+        if (fast !== undefined)
+            return parseJsonBodyBytes(fast);
+        return readBodyLimited(req, limit).then(parseJsonBodyBytes);
     }
     if (ct.includes("application/x-www-form-urlencoded")) {
-        const bytes = await readBodyLimited(req, limit);
-        const params = new URLSearchParams(new TextDecoder().decode(bytes));
-        // Same Spring4Shell-class defense as queryToObject: Object.fromEntries
-        // would set __proto__ / constructor / prototype as own properties.
-        const out = {};
-        for (const [k, v] of params) {
-            if (isForbiddenObjectKey(k))
-                continue;
-            out[k] = v;
-        }
-        return out;
+        const fast = readBodyBytesFast(req, limit);
+        if (fast !== undefined)
+            return parseUrlencodedBodyBytes(fast);
+        return readBodyLimited(req, limit).then(parseUrlencodedBodyBytes);
     }
+    return readBodySlow(req, ct, limit, multipart);
+}
+async function readBodySlow(req, ct, limit, multipart) {
     if (ct.includes("multipart/form-data")) {
         // Fast-fail on an honestly-declared oversize body.
         const cl = req.headers.get("content-length");
@@ -3238,15 +3569,33 @@ async function readBody(req, ct, limit, multipart) {
         // in memory on runtimes whose adapter does not cap at the socket layer
         // (Workers / Deno / Vercel). `readBodyLimited` streams the body and
         // throws `PayloadTooLargeError` the instant it exceeds `limit`; we then
-        // re-parse the bounded bytes with the standard `formData()` parser,
-        // preserving the multipart boundary via the original Content-Type. This is
+        // re-parse the bounded bytes with the standard `formData()` parser. This is
         // Web-standard only (`Request` + `formData`), so it stays runtime-portable.
         const bytes = await readBodyLimited(req, limit);
-        const fd = await new Request(req.url, {
-            method: "POST",
-            headers: { "content-type": ct },
-            body: bytes,
-        }).formData();
+        // The `ct` argument is lower-cased by the caller for case-insensitive
+        // media-type matching, but multipart boundaries are case-SENSITIVE (RFC
+        // 2046 §5.1.1). Reconstructing the Request with the lower-cased boundary
+        // would stop it matching the delimiter in the raw body, so the platform
+        // parser throws and every upload from a client that uses a mixed-case
+        // boundary — Chromium/WebKit browsers (`----WebKitFormBoundary…`) and curl
+        // (`------------------------…`) — fails. Re-read the ORIGINAL-case
+        // Content-Type header to preserve the boundary verbatim.
+        const rawContentType = req.headers.get("content-type") ?? ct;
+        let fd;
+        try {
+            fd = await new Request(req.url, {
+                method: "POST",
+                headers: { "content-type": rawContentType },
+                body: bytes,
+            }).formData();
+        }
+        catch {
+            // A body the platform parser cannot read is a malformed client request,
+            // not a server fault: surface it as an RFC 9457 400 rather than letting
+            // the raw parser TypeError bubble up as a generic 500 (which would also
+            // pollute server-error monitoring with client-controlled input).
+            throw new BadRequestError("Malformed multipart/form-data body");
+        }
         const out = {};
         let fields = 0;
         let files = 0;
@@ -3298,7 +3647,7 @@ function normalizeSunset(value, method, path) {
     }
     return date.toUTCString();
 }
-function serializeResult(result, def, validateResponses) {
+function serializeResult(result, def, validateResponses, lightOk = false) {
     const spec = def.responses[result.status];
     if (!spec) {
         throw new InternalError(`Handler returned status ${result.status} which is not declared in responses for ${def.method} ${def.path}`);
@@ -3360,6 +3709,13 @@ function serializeResult(result, def, validateResponses) {
             body = bytes;
             rawBody = bytes;
         }
+        // Node-adapter hot path (opt-in via DALOY_LIGHT_RESPONSE_OK on the
+        // incoming request): skip the ~2µs undici Response construction. Only
+        // buffer-backed bodies qualify — streams keep the real Response so the
+        // adapter's stream plumbing is untouched.
+        if (lightOk && !isStream) {
+            return new LightResponse(result.status, headers, rawBody);
+        }
         const response = new Response(body, { status: result.status, headers });
         if (!isStream) {
             response[DALOY_RAW_BODY] = rawBody;
@@ -3449,6 +3805,8 @@ function serializeErr(err) {
  * for ergonomics and matches the factory pattern used by Express, Fastify,
  * and Hono adapters.
  *
+ * @param options - Same {@link AppOptions} accepted by the `App` constructor. Default: `{}`.
+ * @returns A new {@link App} instance.
  * @since 0.3.0
  */
 export function createApp(options = {}) {