@daloyjs/core 1.0.0-rc.8 → 1.0.0-rc.9

package/dist/adapters/node.js

@@ -4,7 +4,7 @@
  */
 import { createServer } from "node:http";
 import { Readable } from "node:stream";
-import { DALOY_RAW_BODY, DALOY_RAW_STREAM, DALOY_REQUEST_RAW_BODY, DALOY_LIGHT_RESPONSE_OK, DALOY_REQUEST_ABORT, } from "../app.js";
+import { DALOY_RAW_BODY, DALOY_RAW_STREAM, DALOY_REQUEST_RAW_BODY, DALOY_LIGHT_RESPONSE_OK, DALOY_REQUEST_ABORT, DALOY_REQUEST_BODY_SOLICIT, } from "../app.js";
 import { BadRequestError } from "../errors.js";
 import { setClientCertificate, normalizePeerCertificate, } from "../mtls.js";
 import { setConnInfo } from "../conn-info.js";
@@ -34,15 +34,12 @@ export function serve(app, opts = {}) {
     const connectionsCheckingInterval = connectionTimeoutMs > 0
         ? Math.max(1_000, Math.min(5_000, Math.floor(connectionTimeoutMs / 2)))
         : undefined;
-    const server = createServer({
-        maxHeaderSize: opts.maxHeaderBytes ?? 16 * 1024,
-        ...(connectionsCheckingInterval !== undefined ? { connectionsCheckingInterval } : {}),
-    }, (req, res) => {
+    const handleRequest = (req, res, onBodyPull) => {
         // GET/HEAD: no body work, dispatch directly. Keep this first so the GET
         // hot path doesn't pay for any of the buffering bookkeeping below.
         const method = req.method;
         if (method === "GET" || method === "HEAD" || method === undefined) {
-            dispatchToApp(app, req, res, trustProxy, undefined);
+            dispatchToApp(app, req, res, trustProxy, undefined, onBodyPull);
             return;
         }
         // Refuse Fetch-forbidden methods (CONNECT/TRACE/TRACK) before building a
@@ -61,10 +58,60 @@ export function serve(app, opts = {}) {
         const cl = req.headers["content-length"];
         const n = cl ? Number(cl) : NaN;
         if (Number.isFinite(n) && n >= 0 && n <= bufferedBodyMaxBytes) {
-            bufferRequestBody(req, n).then((bytes) => dispatchToApp(app, req, res, trustProxy, bytes), (e) => writeAdapterError(res, e));
+            bufferRequestBody(req, n).then((bytes) => dispatchToApp(app, req, res, trustProxy, bytes, onBodyPull), (e) => writeAdapterError(res, e));
             return;
         }
-        dispatchToApp(app, req, res, trustProxy, undefined);
+        dispatchToApp(app, req, res, trustProxy, undefined, onBodyPull);
+    };
+    const server = createServer({
+        maxHeaderSize: opts.maxHeaderBytes ?? 16 * 1024,
+        ...(connectionsCheckingInterval !== undefined ? { connectionsCheckingInterval } : {}),
+    }, handleRequest);
+    // `Expect: 100-continue`: hold the interim response until the framework
+    // actually reaches for the body.
+    //
+    // Node's default is to answer `100 Continue` for anyone who asks, which
+    // solicits a body the framework may be about to refuse outright. A route with
+    // a request-body schema and a declared `Content-Length` over `bodyLimitBytes`
+    // is rejected by `readBodyLimited` *before* it reads a byte, so the interim
+    // `100` invited megabytes that could only ever be discarded — measured as
+    // `100` then `413` on the wire.
+    //
+    // Deferring to the first actual read makes the framework's own read decision
+    // the predicate, and that is what keeps this honest. An earlier attempt
+    // refused at header time against `bodyLimitBytes` directly, but that limit is
+    // only enforced where a body is *parsed*, so a route that declares no body
+    // schema never applies it: the same request answered `413` with `Expect` and
+    // `200` without it. `Expect` is a hint about when to send the body (RFC 9110
+    // §10.1.1), so it must never change the outcome — only when the client
+    // learns it. Keying off the read keeps the two paths in agreement by
+    // construction rather than by test coverage.
+    server.on("checkContinue", (req, res) => {
+        const cl = req.headers["content-length"];
+        const n = cl ? Number(cl) : NaN;
+        if (Number.isFinite(n) && n >= 0 && n <= bufferedBodyMaxBytes) {
+            // Small declared body: `handleRequest` buffers it eagerly, before dispatch,
+            // so there is no later read to key off. It is also under the buffer cap,
+            // so soliciting it immediately costs nothing worth deferring.
+            res.writeContinue();
+            handleRequest(req, res);
+            return;
+        }
+        // Streaming path (no `Content-Length`, or one above the buffer cap): answer
+        // the interim `100` the first time the framework pulls the body stream.
+        //
+        // The socket's own `resume` event is deliberately NOT the trigger. Node also
+        // resumes the stream on a microtask when it drains a body nobody read, which
+        // races the response: measured, that fired the `100` even for a request whose
+        // body was never wanted, and beat the `413` to the wire. The consumer's first
+        // `pull` is the only signal that means "the framework wants these bytes".
+        let sent = false;
+        handleRequest(req, res, () => {
+            if (sent || res.headersSent || res.writableEnded)
+                return;
+            sent = true;
+            res.writeContinue();
+        });
     });
     server.requestTimeout = connectionTimeoutMs;
     server.headersTimeout = connectionTimeoutMs;
@@ -148,10 +195,10 @@ export function serve(app, opts = {}) {
  * on body size remains `App.bodyLimitBytes`.
  */
 const DEFAULT_BUFFERED_BODY_MAX_BYTES = 256 * 1024;
-function dispatchToApp(app, req, res, trustProxy, bufferedBody) {
+function dispatchToApp(app, req, res, trustProxy, bufferedBody, onBodyPull) {
     let request;
     try {
-        request = toWebRequest(req, trustProxy, bufferedBody);
+        request = toWebRequest(req, trustProxy, bufferedBody, onBodyPull);
     }
     catch (e) {
         writeAdapterError(res, e);
@@ -537,7 +584,11 @@ Object.setPrototypeOf(LightRequest.prototype, Request.prototype);
 // construction for requests dispatched through this shim. Set once on the
 // prototype: zero per-request cost.
 LightRequest.prototype[DALOY_LIGHT_RESPONSE_OK] = true;
-function toWebRequest(req, trustProxy, bufferedBody) {
+function toWebRequest(req, trustProxy, bufferedBody, onBodyPull) {
+    // `onBodyPull` is attached to the finished Request below rather than wrapping
+    // the body stream: undici pulls a streaming body during `new Request(...)`,
+    // so a stream-level hook fired at construction — before the framework had
+    // decided anything — and re-solicited bodies it went on to refuse.
     const reqHeaders = req.headers;
     const forwardedHost = trustProxy ? firstHeader(reqHeaders["x-forwarded-host"]) : undefined;
     const host = forwardedHost ?? reqHeaders.host ?? "localhost";
@@ -588,12 +639,16 @@ function toWebRequest(req, trustProxy, bufferedBody) {
         req2[DALOY_REQUEST_RAW_BODY] = bufferedBody;
         return req2;
     }
-    return new Request(url, {
+    const streamed = new Request(url, {
         method,
         headers,
         body: Readable.toWeb(req),
         duplex: "half",
     });
+    if (onBodyPull !== undefined) {
+        streamed[DALOY_REQUEST_BODY_SOLICIT] = onBodyPull;
+    }
+    return streamed;
 }
 function firstHeader(v) {
     if (v === undefined)

package/dist/app.d.ts

@@ -793,6 +793,31 @@ export declare const DALOY_REQUEST_RAW_BODY: unique symbol;
  * adapters can opt in; not part of the userland API surface.
  */
 export declare const DALOY_REQUEST_ABORT: unique symbol;
+/**
+ * Internal Symbol an adapter may set to a callback that the framework invokes
+ * immediately before it reads the request body — and only once it has decided
+ * the body is both wanted and within {@link AppOptions.bodyLimitBytes}.
+ *
+ * It exists for `Expect: 100-continue`. Node answers the interim `100` to
+ * anyone who asks, which solicits a body the framework may be about to refuse:
+ * a route with a body schema and a declared `Content-Length` over the limit is
+ * rejected before a byte is read, so the `100` invited megabytes that could
+ * only be discarded. The adapter defers its `writeContinue()` into this hook so
+ * the invitation tracks the framework's own decision.
+ *
+ * The framework's read decision has to be the trigger, because it is the only
+ * thing that makes the outcome independent of the `Expect` header. `Expect` is
+ * a hint about *when* to send the body (RFC 9110 §10.1.1); refusing at header
+ * time against `bodyLimitBytes` instead looks equivalent but is not, since that
+ * limit is only applied where a body is parsed — a route declaring no body
+ * schema never applies it, so the same request answered `413` with `Expect` and
+ * `200` without.
+ *
+ * Adapter-facing only; userland code should not depend on it.
+ *
+ * @since 1.0.0-rc.9
+ */
+export declare const DALOY_REQUEST_BODY_SOLICIT: unique symbol;
 /**
  * Internal Symbol set by handlers/serializers to attach a raw stream
  * (Node `Readable` or Web `ReadableStream`) to a `Response`. The Node

package/dist/app.js

@@ -136,6 +136,8 @@ const MCP_ROUTE_MARKER = Symbol.for("daloyjs.mcp.route");
  */
 const RESPONSE_CACHE_HOOK_MARKER = Symbol.for("daloyjs.response-cache.hook");
 const TENANCY_HOOK_MARKER = Symbol.for("daloyjs.tenancy.hook");
+const IDEMPOTENCY_HOOK_MARKER = Symbol.for("daloyjs.idempotency.hook");
+const EARLY_REJECTION_MARKER = Symbol.for("daloyjs.middleware.earlyRejectionHooks");
 /**
  * Apply a topology-aware security preset on top of caller-supplied
  * options. Returns a new options object where preset defaults fill in
@@ -222,6 +224,31 @@ export const DALOY_REQUEST_RAW_BODY = Symbol.for("daloyjs.request.rawBody");
  * adapters can opt in; not part of the userland API surface.
  */
 export const DALOY_REQUEST_ABORT = Symbol.for("daloyjs.request.abort");
+/**
+ * Internal Symbol an adapter may set to a callback that the framework invokes
+ * immediately before it reads the request body — and only once it has decided
+ * the body is both wanted and within {@link AppOptions.bodyLimitBytes}.
+ *
+ * It exists for `Expect: 100-continue`. Node answers the interim `100` to
+ * anyone who asks, which solicits a body the framework may be about to refuse:
+ * a route with a body schema and a declared `Content-Length` over the limit is
+ * rejected before a byte is read, so the `100` invited megabytes that could
+ * only be discarded. The adapter defers its `writeContinue()` into this hook so
+ * the invitation tracks the framework's own decision.
+ *
+ * The framework's read decision has to be the trigger, because it is the only
+ * thing that makes the outcome independent of the `Expect` header. `Expect` is
+ * a hint about *when* to send the body (RFC 9110 §10.1.1); refusing at header
+ * time against `bodyLimitBytes` instead looks equivalent but is not, since that
+ * limit is only applied where a body is parsed — a route declaring no body
+ * schema never applies it, so the same request answered `413` with `Expect` and
+ * `200` without.
+ *
+ * Adapter-facing only; userland code should not depend on it.
+ *
+ * @since 1.0.0-rc.9
+ */
+export const DALOY_REQUEST_BODY_SOLICIT = Symbol.for("daloyjs.request.bodySolicit");
 /**
  * Internal Symbol set by handlers/serializers to attach a raw stream
  * (Node `Readable` or Web `ReadableStream`) to a `Response`. The Node
@@ -1028,6 +1055,29 @@ export class App {
             this.bootGuard.error = err;
             throw err;
         }
+        // Guard 3b: a stored-response layer mounted ahead of a request budget.
+        // `responseCache()` and `idempotency()` both answer from `beforeHandle` and
+        // end the hook chain, and `rateLimit()` / `loginThrottle()` enforce from that
+        // same phase — so a limiter mounted behind either one never counts the
+        // requests it serves. Measured: `rateLimit({ max: 2 })` behind a cache or a
+        // replay admitted six of six. The budget silently becomes infinite for
+        // exactly the traffic that repeats most, which is what the limit was written
+        // for. Same shape as the responseCache-ahead-of-gates finding, and the reason
+        // the five network-identity gates moved to `preBody`; `rateLimit` cannot
+        // follow them there because its `keyGenerator` is caller-supplied and may
+        // read `ctx.state`, so the unsafe order is refused instead.
+        const replayBeforeBudget = this.routeSecurityMarkers.find((r) => r.replayBeforeBudget !== null);
+        if (replayBeforeBudget !== undefined && this.bootGuard.error === undefined) {
+            this.bootGuard.error = new Error(`Route ${replayBeforeBudget.method} ${replayBeforeBudget.path} runs ` +
+                `${replayBeforeBudget.replayBeforeBudget} before rateLimit() / loginThrottle() in its ` +
+                `effective hook chain. Both act from beforeHandle, so a cache hit or an idempotent ` +
+                `replay returns a response and ends the chain before the limiter counts the request — ` +
+                `the declared budget is never spent on repeat traffic and is effectively unlimited. ` +
+                `Register rateLimit() first — as a global hook (new App({ hooks: rateLimit(...) })) or ` +
+                `an earlier app.use(...) — so every request is counted before a stored response can ` +
+                `short-circuit it. See https://daloyjs.dev/docs/security/boot-guards.`);
+            throw this.bootGuard.error;
+        }
         // Guard 4: session() + state-changing route without csrf().
         if (this.options.csrf === "off")
             return;
@@ -3185,6 +3235,12 @@ function securityMarkersFromHooks(layers) {
     // to tell whether the cache reads state before tenancy has written it.
     let cacheIndex = -1;
     let tenancyIndex = -1;
+    // First stored-response layer of either kind, and the first request-budget
+    // layer. Only the earliest of each matters: if any replay precedes any budget
+    // hook, that budget is preemptable.
+    let replayIndex = -1;
+    let replayName = "";
+    let budgetIndex = -1;
     for (let i = 0; i < layers.length; i++) {
         const record = layers[i];
         if (record[SESSION_HOOK_MARKER] === true)
@@ -3197,12 +3253,25 @@ function securityMarkersFromHooks(layers) {
             cacheIndex = i;
         if (tenancyIndex === -1 && record[TENANCY_HOOK_MARKER] === true)
             tenancyIndex = i;
+        if (replayIndex === -1) {
+            if (record[RESPONSE_CACHE_HOOK_MARKER] === true) {
+                replayIndex = i;
+                replayName = "responseCache()";
+            }
+            else if (record[IDEMPOTENCY_HOOK_MARKER] === true) {
+                replayIndex = i;
+                replayName = "idempotency()";
+            }
+        }
+        if (budgetIndex === -1 && Array.isArray(record[EARLY_REJECTION_MARKER]))
+            budgetIndex = i;
     }
     return {
         hasSession,
         hasCsrf,
         hasAuth,
         cacheBeforeTenancy: cacheIndex !== -1 && tenancyIndex !== -1 && cacheIndex < tenancyIndex,
+        replayBeforeBudget: replayIndex !== -1 && budgetIndex !== -1 && replayIndex < budgetIndex ? replayName : null,
     };
 }
 function isStateChangingMethod(method) {
@@ -3718,6 +3787,21 @@ function validateContext(ctx, def, opts) {
         if (!allowed.some((a) => ct.includes(a))) {
             throw new UnsupportedMediaTypeError(ct || "(none)", allowed);
         }
+        // Refuse an over-limit *declared* length here, before soliciting the body.
+        // `readBodyLimited` already makes the identical check on the identical
+        // boundary, so this changes no outcome — it is load-bearing purely for
+        // ordering, so that an adapter deferring `Expect: 100-continue` (see
+        // {@link DALOY_REQUEST_BODY_SOLICIT}) never invites bytes this request was
+        // always going to be refused for. Kept below the content-type check so a
+        // wrong media type still answers `415` rather than `413`, as before.
+        const declared = request.headers.get("content-length");
+        if (declared !== null) {
+            const declaredBytes = Number(declared);
+            if (Number.isFinite(declaredBytes) && declaredBytes > opts.bodyLimitBytes) {
+                throw new PayloadTooLargeError(opts.bodyLimitBytes);
+            }
+        }
+        request[DALOY_REQUEST_BODY_SOLICIT]?.();
         const raw = readBody(request, ct, opts.bodyLimitBytes, opts.multipart, opts.jsonMaxKeys, opts.jsonMaxDepth);
         if (isPromiseLike(raw))
             return raw.then(validateBodyAndFinish);

package/dist/idempotency.d.ts

@@ -246,6 +246,19 @@ export declare class MemoryIdempotencyStore implements IdempotencyStore {
     /** Test helper. Number of stored records (including expired). */
     size(): number;
 }
+/**
+ * Internal Symbol stamped on the hooks {@link idempotency} returns, so `App`'s
+ * boot guards can see where a stored-response replay sits in a route's effective
+ * hook chain.
+ *
+ * A replay is returned from `beforeHandle` and ends the hook chain, which means
+ * anything enforcing from the *same* phase but mounted later never runs. That is
+ * how a `rateLimit()` behind a replay stops counting. The marker lets the boot
+ * path refuse that order rather than leave the limiter silently infinite.
+ *
+ * @internal
+ */
+export declare const IDEMPOTENCY_HOOK_MARKER: unique symbol;
 /**
  * Idempotency-key middleware. Mount it ahead of the routes that need
  * exactly-once semantics under retries (typically the payment / write

package/dist/idempotency.js

@@ -294,6 +294,19 @@ function buildReplayResponse(stored, replayHeaderName) {
     return markSchemaValidatedResponse(new Response(body, { status: stored.status, headers }));
 }
 // ---------- Middleware ----------
+/**
+ * Internal Symbol stamped on the hooks {@link idempotency} returns, so `App`'s
+ * boot guards can see where a stored-response replay sits in a route's effective
+ * hook chain.
+ *
+ * A replay is returned from `beforeHandle` and ends the hook chain, which means
+ * anything enforcing from the *same* phase but mounted later never runs. That is
+ * how a `rateLimit()` behind a replay stops counting. The marker lets the boot
+ * path refuse that order rather than leave the limiter silently infinite.
+ *
+ * @internal
+ */
+export const IDEMPOTENCY_HOOK_MARKER = Symbol.for("daloyjs.idempotency.hook");
 /**
  * Idempotency-key middleware. Mount it ahead of the routes that need
  * exactly-once semantics under retries (typically the payment / write
@@ -361,7 +374,7 @@ export function idempotency(opts = {}) {
         store = new MemoryIdempotencyStore();
     }
     const keyPrefix = opts.groupId ? `${opts.groupId}:` : "";
-    return {
+    const hooks = {
         async beforeHandle(ctx) {
             const method = ctx.request.method.toUpperCase();
             if (!methods.has(method))
@@ -483,6 +496,8 @@ export function idempotency(opts = {}) {
             return undefined;
         },
     };
+    hooks[IDEMPOTENCY_HOOK_MARKER] = true;
+    return hooks;
 }
 function isPromiseLike(value) {
     return (value !== null &&

package/dist/sbom.cdx.json

@@ -1,15 +1,15 @@
 {
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:91539bfb-7f26-5f45-8628-f7951991c7ca",
+  "serialNumber": "urn:uuid:85b1efae-7e9c-5b6d-8081-af5e65efa14a",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-07-30T16:25:43.763Z",
+    "timestamp": "2026-08-01T11:35:20.075Z",
     "tools": [
       {
         "vendor": "DaloyJS",
         "name": "daloy-generate-sbom",
-        "version": "1.0.0-rc.8"
+        "version": "1.0.0-rc.9"
       }
     ],
     "authors": [
@@ -19,11 +19,11 @@
     ],
     "component": {
       "type": "library",
-      "bom-ref": "pkg:npm/@daloyjs/core@1.0.0-rc.8",
+      "bom-ref": "pkg:npm/@daloyjs/core@1.0.0-rc.9",
       "name": "@daloyjs/core",
-      "version": "1.0.0-rc.8",
+      "version": "1.0.0-rc.9",
       "description": "DaloyJS is a runtime-portable, contract-first TypeScript web framework with built-in OpenAPI (Hey API), typed client generation, large-scale maintainability, and security-first defaults. Hono-grade portability, Elysia-grade DX, FastAPI-grade docs, Fastify-grade ops — distributed via pnpm.",
-      "purl": "pkg:npm/@daloyjs/core@1.0.0-rc.8",
+      "purl": "pkg:npm/@daloyjs/core@1.0.0-rc.9",
       "licenses": [
         {
           "license": {
@@ -46,9 +46,9 @@
         }
       ],
       "swid": {
-        "tagId": "swidtag--daloyjs-core-1.0.0-rc.8",
+        "tagId": "swidtag--daloyjs-core-1.0.0-rc.9",
         "name": "@daloyjs/core",
-        "version": "1.0.0-rc.8",
+        "version": "1.0.0-rc.9",
         "tagVersion": 0,
         "patch": false
       }
@@ -57,7 +57,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "pkg:npm/@daloyjs/core@1.0.0-rc.8",
+      "ref": "pkg:npm/@daloyjs/core@1.0.0-rc.9",
       "dependsOn": []
     }
   ]

package/dist/sbom.spdx.json

@@ -2,10 +2,10 @@
   "spdxVersion": "SPDX-2.3",
   "dataLicense": "CC0-1.0",
   "SPDXID": "SPDXRef-DOCUMENT",
-  "name": "@daloyjs/core-1.0.0-rc.8",
-  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/@daloyjs/core-1.0.0-rc.8-91539bfb-7f26-5f45-8628-f7951991c7ca",
+  "name": "@daloyjs/core-1.0.0-rc.9",
+  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/@daloyjs/core-1.0.0-rc.9-85b1efae-7e9c-5b6d-8081-af5e65efa14a",
   "creationInfo": {
-    "created": "2026-07-30T16:25:43.763Z",
+    "created": "2026-08-01T11:35:20.075Z",
     "creators": [
       "Tool: daloy-generate-sbom",
       "Organization: DaloyJS"
@@ -16,7 +16,7 @@
     {
       "SPDXID": "SPDXRef-Package--daloyjs-core",
       "name": "@daloyjs/core",
-      "versionInfo": "1.0.0-rc.8",
+      "versionInfo": "1.0.0-rc.9",
       "downloadLocation": "https://github.com/daloyjs/daloy",
       "filesAnalyzed": false,
       "licenseConcluded": "MIT",
@@ -27,7 +27,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/@daloyjs/core@1.0.0-rc.8"
+          "referenceLocator": "pkg:npm/@daloyjs/core@1.0.0-rc.9"
         }
       ]
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@daloyjs/core",
-  "version": "1.0.0-rc.8",
+  "version": "1.0.0-rc.9",
   "description": "DaloyJS is a runtime-portable, contract-first TypeScript web framework with built-in OpenAPI (Hey API), typed client generation, large-scale maintainability, and security-first defaults. Hono-grade portability, Elysia-grade DX, FastAPI-grade docs, Fastify-grade ops \u2014 distributed via pnpm.",
   "type": "module",
   "publishConfig": {