@daloyjs/core 0.35.2 → 0.37.0

package/dist/concurrency-limit.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Per-route / per-client concurrency limiting with bounded FIFO queueing.
+ *
+ * Where the Node adapter's `maxConnections` caps *sockets* at accept time and
+ * `loadShedding()` rejects traffic under *process* pressure, {@link concurrencyLimit}
+ * bounds the number of requests **in flight through a given surface** — the
+ * in-app equivalent of HAProxy's `maxconn` + request queue. Each request tries
+ * to acquire a slot from a semaphore; if all slots are busy it waits in a
+ * bounded FIFO queue (up to {@link ConcurrencyLimitOptions.maxQueue}) for up to
+ * {@link ConcurrencyLimitOptions.queueTimeoutMs}, and is rejected with a fast
+ * `503 Service Unavailable` (+ `Retry-After`) once the queue is full or the
+ * wait times out. The slot is released when the response is finalized.
+ *
+ * The limiter can be partitioned with {@link ConcurrencyLimitOptions.scope}:
+ *
+ * - `"global"` (default) — one shared budget across the whole mount.
+ * - `"route"` — a separate budget per `method + path`, so a single hot endpoint
+ *   can't starve the others mounted under the same guard.
+ * - `"client"` — a separate budget per client identity (requires
+ *   {@link ConcurrencyLimitOptions.trustProxyHeaders} or a
+ *   {@link ConcurrencyLimitOptions.keyGenerator}); a heavy client can't consume
+ *   everyone else's slots.
+ * - a custom function — return a bucket key, or `undefined` to skip limiting
+ *   for that request (fail-open).
+ *
+ * The middleware is dependency-free and runtime-portable: it acquires in
+ * {@link "./types.js".Hooks.beforeHandle} and releases in
+ * {@link "./types.js".Hooks.onSend}, which the framework runs on the success,
+ * error, and short-circuit response paths alike, so a slot is never leaked.
+ *
+ * @example
+ * ```ts
+ * import { App, concurrencyLimit } from "@daloyjs/core";
+ *
+ * const app = new App();
+ * // At most 100 in flight per route, queue up to 50 more, wait at most 2s.
+ * app.use(concurrencyLimit({
+ *   maxConcurrent: 100,
+ *   maxQueue: 50,
+ *   queueTimeoutMs: 2000,
+ *   scope: "route",
+ * }));
+ * ```
+ *
+ * @module
+ * @since 0.37.0
+ */
+import type { BaseContext, Hooks } from "./types.js";
+/**
+ * Details of a request rejected by {@link concurrencyLimit}, passed to
+ * {@link ConcurrencyLimitOptions.onReject}.
+ *
+ * @since 0.37.0
+ */
+export interface ConcurrencyRejection {
+    /** The bucket key whose budget was exhausted. */
+    key: string;
+    /** Why the request was rejected. */
+    reason: "queue-full" | "queue-timeout";
+    /** In-flight requests for the bucket at rejection time. */
+    active: number;
+    /** Requests already waiting in the bucket's queue at rejection time. */
+    queued: number;
+}
+/**
+ * Configuration for {@link concurrencyLimit}.
+ *
+ * @since 0.37.0
+ */
+export interface ConcurrencyLimitOptions {
+    /**
+     * Maximum number of requests allowed in flight per bucket at once. Required,
+     * positive integer. Additional requests queue (up to {@link maxQueue}) or are
+     * rejected with `503`.
+     */
+    maxConcurrent: number;
+    /**
+     * Maximum number of requests allowed to wait in a bucket's FIFO queue while
+     * all slots are busy. Default `0` (no queue — overflow is rejected
+     * immediately). A waiting request is admitted in arrival order as slots free.
+     */
+    maxQueue?: number;
+    /**
+     * Maximum time, in ms, a request may wait in the queue before being rejected
+     * with `503`. Default `0`, which means "wait indefinitely" — only meaningful
+     * when {@link maxQueue} `> 0`. Set a finite value to bound tail latency.
+     */
+    queueTimeoutMs?: number;
+    /**
+     * How to partition the concurrency budget. `"global"` (default) shares one
+     * budget; `"route"` keys by `method + path`; `"client"` keys by client
+     * identity (needs {@link trustProxyHeaders} or {@link keyGenerator}); a
+     * function returns a custom bucket key (or `undefined` to skip limiting).
+     */
+    scope?: "global" | "route" | "client" | ((ctx: BaseContext<any, any>) => string | undefined);
+    /**
+     * Read `X-Forwarded-For` / `X-Real-IP` when `scope: "client"`. Off by default
+     * because those headers are client-spoofable unless every request reaches the
+     * app through a proxy chain you control.
+     */
+    trustProxyHeaders?: boolean;
+    /**
+     * Custom client-identity resolver for `scope: "client"`. Overrides
+     * {@link trustProxyHeaders}. Returning `undefined` skips limiting for the
+     * request (fail-open).
+     */
+    keyGenerator?: (ctx: BaseContext<any, any>) => string | undefined;
+    /** `Retry-After` seconds on the `503` rejection. Default `1`. `0` omits the header. */
+    retryAfterSeconds?: number;
+    /** `detail` for the `503` problem+json. Default `"Concurrency limit exceeded"`. */
+    message?: string;
+    /** Called when a request is rejected (queue full or wait timed out). */
+    onReject?: (rejection: ConcurrencyRejection) => void;
+}
+/**
+ * Bound the number of in-flight requests per route and/or per client with a
+ * bounded FIFO queue and a fast `503`, the in-app equivalent of HAProxy's
+ * `maxconn` + request queue. Complements the global `maxConnections` socket cap
+ * and `loadShedding()` process-pressure shedding.
+ *
+ * A request acquires a slot in `beforeHandle`; if the bucket is saturated it
+ * waits in a bounded FIFO queue (subject to {@link ConcurrencyLimitOptions.maxQueue}
+ * and {@link ConcurrencyLimitOptions.queueTimeoutMs}) and is rejected with `503`
+ * when the queue is full or the wait times out. The slot is released on the
+ * response path (`onSend`), so it is freed for success, error, and
+ * short-circuit responses alike.
+ *
+ * @param opts - Concurrency-limit configuration; `maxConcurrent` is required.
+ * @returns A {@link Hooks} bundle ready for `app.use(...)`.
+ * @throws Error when `maxConcurrent` is not a positive integer, `maxQueue` /
+ *   `queueTimeoutMs` / `retryAfterSeconds` are out of range, or `scope: "client"`
+ *   is used without an identity source.
+ * @since 0.37.0
+ */
+export declare function concurrencyLimit(opts: ConcurrencyLimitOptions): Hooks;

package/dist/concurrency-limit.js

@@ -0,0 +1,254 @@
+/**
+ * Per-route / per-client concurrency limiting with bounded FIFO queueing.
+ *
+ * Where the Node adapter's `maxConnections` caps *sockets* at accept time and
+ * `loadShedding()` rejects traffic under *process* pressure, {@link concurrencyLimit}
+ * bounds the number of requests **in flight through a given surface** — the
+ * in-app equivalent of HAProxy's `maxconn` + request queue. Each request tries
+ * to acquire a slot from a semaphore; if all slots are busy it waits in a
+ * bounded FIFO queue (up to {@link ConcurrencyLimitOptions.maxQueue}) for up to
+ * {@link ConcurrencyLimitOptions.queueTimeoutMs}, and is rejected with a fast
+ * `503 Service Unavailable` (+ `Retry-After`) once the queue is full or the
+ * wait times out. The slot is released when the response is finalized.
+ *
+ * The limiter can be partitioned with {@link ConcurrencyLimitOptions.scope}:
+ *
+ * - `"global"` (default) — one shared budget across the whole mount.
+ * - `"route"` — a separate budget per `method + path`, so a single hot endpoint
+ *   can't starve the others mounted under the same guard.
+ * - `"client"` — a separate budget per client identity (requires
+ *   {@link ConcurrencyLimitOptions.trustProxyHeaders} or a
+ *   {@link ConcurrencyLimitOptions.keyGenerator}); a heavy client can't consume
+ *   everyone else's slots.
+ * - a custom function — return a bucket key, or `undefined` to skip limiting
+ *   for that request (fail-open).
+ *
+ * The middleware is dependency-free and runtime-portable: it acquires in
+ * {@link "./types.js".Hooks.beforeHandle} and releases in
+ * {@link "./types.js".Hooks.onSend}, which the framework runs on the success,
+ * error, and short-circuit response paths alike, so a slot is never leaked.
+ *
+ * @example
+ * ```ts
+ * import { App, concurrencyLimit } from "@daloyjs/core";
+ *
+ * const app = new App();
+ * // At most 100 in flight per route, queue up to 50 more, wait at most 2s.
+ * app.use(concurrencyLimit({
+ *   maxConcurrent: 100,
+ *   maxQueue: 50,
+ *   queueTimeoutMs: 2000,
+ *   scope: "route",
+ * }));
+ * ```
+ *
+ * @module
+ * @since 0.37.0
+ */
+import { HttpError } from "./errors.js";
+const DEFAULT_MESSAGE = "Concurrency limit exceeded";
+/** Monotonic id so multiple mounted limiters use distinct per-request state slots. */
+let instanceCounter = 0;
+function assertPositiveInteger(name, value) {
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new Error(`concurrencyLimit(): ${name} must be a positive integer.`);
+    }
+}
+function assertNonNegativeInteger(name, value) {
+    if (!Number.isInteger(value) || value < 0) {
+        throw new Error(`concurrencyLimit(): ${name} must be a non-negative integer.`);
+    }
+}
+function forwardedKey(ctx) {
+    const forwarded = ctx.request.headers.get("x-forwarded-for");
+    const first = forwarded ? forwarded.split(",")[0].trim() : "";
+    if (first)
+        return first;
+    return ctx.request.headers.get("x-real-ip") ?? undefined;
+}
+/** Extract just the pathname from a request URL without a full `URL` parse where possible. */
+function pathnameOf(url) {
+    const schemeEnd = url.indexOf("://");
+    if (schemeEnd === -1) {
+        try {
+            return new URL(url).pathname;
+        }
+        catch {
+            return url;
+        }
+    }
+    const pathStart = url.indexOf("/", schemeEnd + 3);
+    if (pathStart === -1)
+        return "/";
+    let end = url.length;
+    const q = url.indexOf("?", pathStart);
+    if (q !== -1)
+        end = q;
+    const h = url.indexOf("#", pathStart);
+    if (h !== -1 && h < end)
+        end = h;
+    return url.slice(pathStart, end);
+}
+/**
+ * Build the per-request bucket-key resolver for the configured {@link ConcurrencyLimitOptions.scope}.
+ *
+ * @internal
+ */
+function buildScopeResolver(opts) {
+    const scope = opts.scope ?? "global";
+    if (typeof scope === "function")
+        return scope;
+    if (scope === "global")
+        return () => "global";
+    if (scope === "route") {
+        return (ctx) => `${ctx.request.method} ${pathnameOf(ctx.request.url)}`;
+    }
+    // scope === "client"
+    if (!opts.keyGenerator && !opts.trustProxyHeaders) {
+        throw new Error('concurrencyLimit(): scope "client" requires keyGenerator or trustProxyHeaders so ' +
+            "clients can be identified; otherwise every caller shares one bucket.");
+    }
+    const resolve = opts.keyGenerator ?? forwardedKey;
+    return (ctx) => {
+        const id = resolve(ctx);
+        return id === undefined ? undefined : `client:${id}`;
+    };
+}
+/**
+ * Bound the number of in-flight requests per route and/or per client with a
+ * bounded FIFO queue and a fast `503`, the in-app equivalent of HAProxy's
+ * `maxconn` + request queue. Complements the global `maxConnections` socket cap
+ * and `loadShedding()` process-pressure shedding.
+ *
+ * A request acquires a slot in `beforeHandle`; if the bucket is saturated it
+ * waits in a bounded FIFO queue (subject to {@link ConcurrencyLimitOptions.maxQueue}
+ * and {@link ConcurrencyLimitOptions.queueTimeoutMs}) and is rejected with `503`
+ * when the queue is full or the wait times out. The slot is released on the
+ * response path (`onSend`), so it is freed for success, error, and
+ * short-circuit responses alike.
+ *
+ * @param opts - Concurrency-limit configuration; `maxConcurrent` is required.
+ * @returns A {@link Hooks} bundle ready for `app.use(...)`.
+ * @throws Error when `maxConcurrent` is not a positive integer, `maxQueue` /
+ *   `queueTimeoutMs` / `retryAfterSeconds` are out of range, or `scope: "client"`
+ *   is used without an identity source.
+ * @since 0.37.0
+ */
+export function concurrencyLimit(opts) {
+    assertPositiveInteger("maxConcurrent", opts.maxConcurrent);
+    const maxConcurrent = opts.maxConcurrent;
+    const maxQueue = opts.maxQueue ?? 0;
+    assertNonNegativeInteger("maxQueue", maxQueue);
+    const queueTimeoutMs = opts.queueTimeoutMs ?? 0;
+    assertNonNegativeInteger("queueTimeoutMs", queueTimeoutMs);
+    const retryAfterSeconds = opts.retryAfterSeconds ?? 1;
+    assertNonNegativeInteger("retryAfterSeconds", retryAfterSeconds);
+    const message = opts.message ?? DEFAULT_MESSAGE;
+    const resolveKey = buildScopeResolver(opts);
+    const buckets = new Map();
+    // Unique per-request state slots so multiple concurrencyLimit() mounts on the
+    // same group don't clobber each other's acquired-flag / bucket-key bookkeeping.
+    const id = instanceCounter++;
+    const ACQUIRED_KEY = `__concurrencyAcquired_${id}`;
+    const BUCKET_KEY = `__concurrencyBucket_${id}`;
+    const reject503 = (rejection) => {
+        opts.onReject?.(rejection);
+        const headers = retryAfterSeconds > 0 ? { "retry-after": String(retryAfterSeconds) } : undefined;
+        throw new HttpError(503, {
+            type: "https://daloyjs.dev/errors/concurrency-limit",
+            title: "Service Unavailable",
+            detail: message,
+        }, headers);
+    };
+    const getBucket = (key) => {
+        let bucket = buckets.get(key);
+        if (!bucket) {
+            bucket = { active: 0, queue: [] };
+            buckets.set(key, bucket);
+        }
+        return bucket;
+    };
+    /** Release a slot back to a bucket: hand it to the next waiter, or free it. */
+    const release = (key) => {
+        const bucket = buckets.get(key);
+        if (!bucket)
+            return;
+        const next = bucket.queue.shift();
+        if (next) {
+            if (next.timer !== undefined)
+                clearTimeout(next.timer);
+            next.resolve();
+            return;
+        }
+        bucket.active--;
+        // Reclaim empty buckets so per-client / per-route keys don't leak memory.
+        if (bucket.active <= 0 && bucket.queue.length === 0) {
+            bucket.active = 0;
+            buckets.delete(key);
+        }
+    };
+    return {
+        async beforeHandle(ctx) {
+            const key = resolveKey(ctx);
+            if (key === undefined)
+                return undefined; // fail-open: not subject to limiting
+            const bucket = getBucket(key);
+            if (bucket.active < maxConcurrent) {
+                bucket.active++;
+            }
+            else if (maxQueue > 0 && bucket.queue.length < maxQueue) {
+                await new Promise((resolve, reject) => {
+                    const waiter = { resolve, reject, timer: undefined };
+                    if (queueTimeoutMs > 0) {
+                        waiter.timer = setTimeout(() => {
+                            const idx = bucket.queue.indexOf(waiter);
+                            if (idx !== -1)
+                                bucket.queue.splice(idx, 1);
+                            try {
+                                reject503({
+                                    key,
+                                    reason: "queue-timeout",
+                                    active: bucket.active,
+                                    queued: bucket.queue.length,
+                                });
+                            }
+                            catch (err) {
+                                reject(err);
+                            }
+                        }, queueTimeoutMs);
+                        const timer = waiter.timer;
+                        if (typeof timer.unref === "function")
+                            timer.unref();
+                    }
+                    bucket.queue.push(waiter);
+                });
+                // Admitted from the queue: the releaser left `active` unchanged for us.
+            }
+            else {
+                reject503({
+                    key,
+                    reason: "queue-full",
+                    active: bucket.active,
+                    queued: bucket.queue.length,
+                });
+            }
+            const state = ctx.state;
+            state[ACQUIRED_KEY] = true;
+            state[BUCKET_KEY] = key;
+            return undefined;
+        },
+        onSend(_res, ctx) {
+            if (!ctx)
+                return undefined;
+            const state = ctx.state;
+            if (state[ACQUIRED_KEY] !== true)
+                return undefined;
+            // Guard against a double release if onSend somehow runs twice.
+            state[ACQUIRED_KEY] = false;
+            const key = state[BUCKET_KEY];
+            if (typeof key === "string")
+                release(key);
+            return undefined;
+        },
+    };
+}

package/dist/docs.d.ts

@@ -92,18 +92,69 @@ export interface ScalarReferenceConfiguration {
     spec?: never;
     url?: never;
 }
+/**
+ * Override CDN URLs and pin Subresource Integrity (SRI) hashes for the docs
+ * UI assets.
+ *
+ * Supplying an `*Integrity` value emits an `integrity="…"` attribute plus a
+ * `crossorigin` attribute on the matching `<script>` / `<link>` tag so the
+ * browser refuses to execute a CDN asset whose bytes don't match the pinned
+ * hash. SRI is only meaningful against a **version-pinned** URL
+ * (e.g. `…/@scalar/api-reference@1.25.0`); pair each integrity hash with a
+ * pinned `*Url`, since the framework's default URLs intentionally track the
+ * latest upstream release and therefore cannot carry a stable hash.
+ *
+ * @since 0.37.0
+ */
+export interface DocsAssetOptions {
+    /** Override the Scalar API Reference bundle URL (useful for self-hosting). */
+    scalarScriptUrl?: string;
+    /**
+     * SRI hash for {@link scalarScriptUrl}. One or more space-separated
+     * `sha256-`/`sha384-`/`sha512-` base64 digests. Invalid values throw.
+     *
+     * @since 0.37.0
+     */
+    scalarScriptIntegrity?: string;
+    /** Override the Swagger UI stylesheet URL (useful for self-hosting). */
+    swaggerUiCssUrl?: string;
+    /**
+     * SRI hash for {@link swaggerUiCssUrl}. One or more space-separated
+     * `sha256-`/`sha384-`/`sha512-` base64 digests. Invalid values throw.
+     *
+     * @since 0.37.0
+     */
+    swaggerUiCssIntegrity?: string;
+    /** Override the Swagger UI bundle URL (useful for self-hosting). */
+    swaggerUiBundleUrl?: string;
+    /**
+     * SRI hash for {@link swaggerUiBundleUrl}. One or more space-separated
+     * `sha256-`/`sha384-`/`sha512-` base64 digests. Invalid values throw.
+     *
+     * @since 0.37.0
+     */
+    swaggerUiBundleIntegrity?: string;
+    /**
+     * `crossorigin` attribute value emitted alongside any pinned integrity
+     * hash. SRI on a cross-origin asset requires CORS, so this defaults to
+     * `"anonymous"`; use `"use-credentials"` only when the asset host needs
+     * credentialed requests.
+     *
+     * @since 0.37.0
+     */
+    crossOrigin?: "anonymous" | "use-credentials";
+}
 /** Shared options for {@link scalarHtml} and {@link swaggerUiHtml}. */
 export interface DocsOptions {
     /** Absolute or relative URL of the OpenAPI document to render. */
     specUrl: string;
     /** `<title>` of the generated HTML page. */
     title?: string;
-    /** Override CDN URLs for the docs UI assets (useful for self-hosting). */
-    assets?: {
-        scalarScriptUrl?: string;
-        swaggerUiCssUrl?: string;
-        swaggerUiBundleUrl?: string;
-    };
+    /**
+     * Override CDN URLs and pin SRI hashes for the docs UI assets (useful for
+     * self-hosting or supply-chain hardening). See {@link DocsAssetOptions}.
+     */
+    assets?: DocsAssetOptions;
     /** CSP `nonce` to apply to inline/script tags; must match the response CSP. */
     scriptNonce?: string;
 }

package/dist/docs.js

@@ -8,9 +8,37 @@
  * (You can self-host the assets if your CSP forbids CDNs.)
  */
 const JSDELIVR_ORIGIN = "https://cdn.jsdelivr.net";
+/**
+ * Matches a single Subresource Integrity digest: a `sha256-`/`sha384-`/
+ * `sha512-` prefix followed by standard base64 (with up to two `=` pads).
+ * Linear-time / ReDoS-safe (no nested or overlapping quantifiers).
+ */
+const SRI_HASH = /^sha(?:256|384|512)-[A-Za-z0-9+/]+={0,2}$/;
 function nonceAttr(nonce) {
     return nonce ? ` nonce="${escapeHtml(nonce)}"` : "";
 }
+/**
+ * Build the `integrity`/`crossorigin` attribute fragment for a docs asset.
+ *
+ * Returns an empty string when no `integrity` value is supplied. When one is
+ * supplied it is validated as one or more space-separated SRI digests and a
+ * `crossorigin` attribute (default `"anonymous"`) is emitted alongside it.
+ * A malformed integrity value throws a {@link TypeError} so a typo fails
+ * loudly instead of silently shipping a docs page with no SRI protection.
+ *
+ * @throws {TypeError} when `integrity` is provided but is not a valid SRI value.
+ */
+function integrityAttr(integrity, crossOrigin) {
+    if (integrity === undefined)
+        return "";
+    const tokens = integrity.trim().split(/\s+/);
+    if (integrity.trim() === "" || tokens.some((t) => !SRI_HASH.test(t))) {
+        throw new TypeError(`Invalid Subresource Integrity value: ${JSON.stringify(integrity)}. ` +
+            `Expected one or more space-separated "sha256-"/"sha384-"/"sha512-" base64 hashes.`);
+    }
+    const co = crossOrigin ?? "anonymous";
+    return ` integrity="${escapeHtml(integrity.trim())}" crossorigin="${escapeHtml(co)}"`;
+}
 /**
  * Render a Scalar API Reference HTML page that loads `opts.specUrl`.
  *
@@ -23,6 +51,7 @@ export function scalarHtml(opts) {
     const url = escapeHtml(opts.specUrl);
     const scriptUrl = escapeHtml(opts.assets?.scalarScriptUrl ??
         `${JSDELIVR_ORIGIN}/npm/@scalar/api-reference`);
+    const scriptSri = integrityAttr(opts.assets?.scalarScriptIntegrity, opts.assets?.crossOrigin);
     const nonce = nonceAttr(opts.scriptNonce);
     const configuration = scalarConfigurationAttr(opts.specUrl, opts.configuration);
     return `<!doctype html>
@@ -32,7 +61,7 @@ export function scalarHtml(opts) {
 <title>${title}</title>
 </head><body>
 <script id="api-reference" data-url="${url}"${configuration}${nonce}></script>
-<script src="${scriptUrl}"${nonce}></script>
+<script src="${scriptUrl}"${scriptSri}${nonce}></script>
 </body></html>`;
 }
 /**
@@ -46,16 +75,18 @@ export function swaggerUiHtml(opts) {
         `${JSDELIVR_ORIGIN}/npm/swagger-ui-dist/swagger-ui.css`);
     const bundleUrl = escapeHtml(opts.assets?.swaggerUiBundleUrl ??
         `${JSDELIVR_ORIGIN}/npm/swagger-ui-dist/swagger-ui-bundle.js`);
+    const cssSri = integrityAttr(opts.assets?.swaggerUiCssIntegrity, opts.assets?.crossOrigin);
+    const bundleSri = integrityAttr(opts.assets?.swaggerUiBundleIntegrity, opts.assets?.crossOrigin);
     const nonce = nonceAttr(opts.scriptNonce);
     return `<!doctype html>
 <html><head>
 <meta charset="utf-8" />
 <meta name="viewport" content="width=device-width, initial-scale=1" />
 <title>${title}</title>
-<link rel="stylesheet" href="${cssUrl}" />
+<link rel="stylesheet" href="${cssUrl}"${cssSri} />
 </head><body>
 <div id="swagger"></div>
-<script src="${bundleUrl}"${nonce}></script>
+<script src="${bundleUrl}"${bundleSri}${nonce}></script>
 <script${nonce}>window.onload=()=>SwaggerUIBundle({url:"${url}",dom_id:"#swagger"});</script>
 </body></html>`;
 }

package/dist/errors.d.ts

@@ -148,6 +148,11 @@ export declare function httpError(opts: HttpErrorOptions): HttpError;
  * `Retry-After` or `Allow`. In production mode, 5xx `detail` is scrubbed to
  * avoid information disclosure.
  *
+ * **Security note:** only **5xx** `detail` is scrubbed in production. A `4xx`
+ * `detail` is always returned to the client (it is assumed to be
+ * client-actionable), so never place secrets or internal diagnostics in the
+ * `detail` of a 4xx error.
+ *
  * Prefer the dedicated subclasses (`BadRequestError`, `NotFoundError`, ...)
  * for common statuses; instantiate `HttpError` directly only for unusual
  * status codes or fully-custom problem documents.
@@ -233,6 +238,21 @@ export declare class ValidationError extends HttpError {
 export declare class NotFoundError extends HttpError {
     constructor(detail?: string);
 }
+/**
+ * `409 Conflict` — the request could not be completed because it conflicts
+ * with the current state of the target resource. The built-in
+ * {@link idempotency} middleware throws this when a second request arrives
+ * with an `Idempotency-Key` that is still being processed by an in-flight
+ * request (the original response has not been produced yet). The response
+ * carries `Cache-Control: no-store` so a private cache cannot mask the
+ * conflict.
+ *
+ * @param detail - Optional human-readable explanation surfaced to the client.
+ * @since 0.37.0
+ */
+export declare class ConflictError extends HttpError {
+    constructor(detail?: string);
+}
 /**
  * `401 Unauthorized` — authentication is required and missing or invalid.
  * Pair with a `WWW-Authenticate` header on the response when issuing a

package/dist/errors.js

@@ -143,6 +143,11 @@ export function httpError(opts) {
  * `Retry-After` or `Allow`. In production mode, 5xx `detail` is scrubbed to
  * avoid information disclosure.
  *
+ * **Security note:** only **5xx** `detail` is scrubbed in production. A `4xx`
+ * `detail` is always returned to the client (it is assumed to be
+ * client-actionable), so never place secrets or internal diagnostics in the
+ * `detail` of a 4xx error.
+ *
  * Prefer the dedicated subclasses (`BadRequestError`, `NotFoundError`, ...)
  * for common statuses; instantiate `HttpError` directly only for unusual
  * status codes or fully-custom problem documents.
@@ -290,6 +295,28 @@ export class NotFoundError extends HttpError {
         this.name = "NotFoundError";
     }
 }
+/**
+ * `409 Conflict` — the request could not be completed because it conflicts
+ * with the current state of the target resource. The built-in
+ * {@link idempotency} middleware throws this when a second request arrives
+ * with an `Idempotency-Key` that is still being processed by an in-flight
+ * request (the original response has not been produced yet). The response
+ * carries `Cache-Control: no-store` so a private cache cannot mask the
+ * conflict.
+ *
+ * @param detail - Optional human-readable explanation surfaced to the client.
+ * @since 0.37.0
+ */
+export class ConflictError extends HttpError {
+    constructor(detail) {
+        super(409, {
+            type: "https://daloyjs.dev/errors/conflict",
+            title: "Conflict",
+            ...(detail ? { detail } : {}),
+        }, { "cache-control": "no-store" });
+        this.name = "ConflictError";
+    }
+}
 /**
  * `401 Unauthorized` — authentication is required and missing or invalid.
  * Pair with a `WWW-Authenticate` header on the response when issuing a

package/dist/fetch-guard.js

@@ -286,6 +286,10 @@ export function fetchGuard(options = {}) {
             const method = request.method.toUpperCase();
             const shouldDowngrade = res.status === 303 ||
                 ((res.status === 301 || res.status === 302) && method !== "GET" && method !== "HEAD");
+            // Committed to following this hop. Drain the intermediate 3xx body so
+            // the underlying socket isn't pinned until GC (Node/undici keep the
+            // connection open while an un-consumed body stream is outstanding).
+            void res.body?.cancel();
             request = shouldDowngrade
                 ? new Request(next, {
                     method: "GET",