@daloyjs/core 0.36.0 → 0.38.0

package/dist/cli.js

@@ -10,7 +10,9 @@
  * `process.argv`, `process.stdout`, dynamic `import()`, and `process.exit`.
  */
 import { runContractTests } from "./contract.js";
+import { diffOpenAPI } from "./openapi-diff.js";
 import { generateOpenAPI, openapiToYAML } from "./openapi.js";
+import { generateAsyncAPI, asyncapiToYAML } from "./asyncapi.js";
 const HELP = `daloy — DaloyJS CLI
 
 Usage:
@@ -25,19 +27,26 @@ Commands:
                          Exits non-zero on any violation so the
                          command can guard container HEALTHCHECK and CI
                          deploy steps.
+  diff <baseline> <current>
+                         Compare two OpenAPI 3.1 JSON documents and report
+                         added, removed, and changed operations. Exits 1
+                         when a breaking change is detected so it can gate
+                         CI; pass --json for machine-readable output.
 
 Options:
   --json                 Print machine-readable JSON instead of a table.
   --check                Run the contract test suite; exit 1 on errors.
   --schemas              Include per-route schema presence (body/query/...).
   --openapi              Print the OpenAPI 3.1 document for the App.
+  --asyncapi             Print the AsyncAPI 3.0 document for the App's
+                         WebSocket (app.ws()) surfaces.
   --ai                   Print an AI/codegen-friendly dump of the
                          route catalog with schemas and meta examples
                          (suitable for feeding to an LLM or for writing
                          to a sibling routes.json / routes.yaml).
-  --format <fmt>         Output format for --ai and --openapi: json | yaml
-                         (default: json). YAML saves ~20–40%% of LLM
-                         tokens versus JSON for the same payload.
+  --format <fmt>         Output format for --ai, --openapi and --asyncapi:
+                         json | yaml (default: json). YAML saves ~20–40%% of
+                         LLM tokens versus JSON for the same payload.
   --yaml                 Shorthand for --format yaml.
   --tag <tag>            Only show routes that declare this tag.
   --method <method>      Only show routes for this HTTP method.
@@ -69,8 +78,12 @@ Examples:
   daloy inspect --openapi > openapi.json
   daloy inspect --ai --yaml > routes.yaml
   daloy inspect --openapi --format yaml > openapi.yaml
+  daloy inspect --asyncapi > asyncapi.json
+  daloy inspect --asyncapi --format yaml > asyncapi.yaml
   daloy dev
   daloy dev src/server.ts
+  daloy diff openapi.published.json openapi.json
+  daloy diff --json openapi.published.json openapi.json
 `;
 const DEFAULT_ENTRIES = [
     "src/app.ts",
@@ -235,13 +248,14 @@ export function parseArgs(argv) {
         check: false,
         schemas: false,
         openapi: false,
+        asyncapi: false,
         ai: false,
         help: false,
         version: false,
     };
     let command = "inspect";
     let i = 0;
-    if (argv[0] === "inspect" || argv[0] === "dev" || argv[0] === "help" || argv[0] === "doctor") {
+    if (argv[0] === "inspect" || argv[0] === "dev" || argv[0] === "help" || argv[0] === "doctor" || argv[0] === "diff") {
         command = argv[0];
         i = 1;
     }
@@ -262,6 +276,9 @@ export function parseArgs(argv) {
             case "--openapi":
                 opts.openapi = true;
                 break;
+            case "--asyncapi":
+                opts.asyncapi = true;
+                break;
             case "--ai":
                 opts.ai = true;
                 break;
@@ -308,6 +325,7 @@ export function parseArgs(argv) {
                 if (a.startsWith("-")) {
                     throw new Error(`Unknown flag: ${a}`);
                 }
+                (opts.positionals ??= []).push(a);
                 opts.entry = a;
         }
     }
@@ -349,6 +367,9 @@ export async function runCli(argv, io) {
     if (command === "doctor") {
         return runDoctor(opts, io);
     }
+    if (command === "diff") {
+        return runDiff(opts, io);
+    }
     if (command !== "inspect") {
         io.stderr(`Unknown command: ${command}\n\n${HELP}`);
         return { exitCode: 2 };
@@ -372,6 +393,17 @@ export async function runCli(argv, io) {
         io.stdout(`${JSON.stringify(doc, null, opts.json ? 0 : 2)}\n`);
         return { exitCode: 0 };
     }
+    if (opts.asyncapi) {
+        const doc = generateAsyncAPI(app, {
+            info: { title: "App", version: "0.0.0" },
+        });
+        if (opts.format === "yaml") {
+            io.stdout(asyncapiToYAML(doc));
+            return { exitCode: 0 };
+        }
+        io.stdout(`${JSON.stringify(doc, null, opts.json ? 0 : 2)}\n`);
+        return { exitCode: 0 };
+    }
     if (opts.ai) {
         const dump = buildAiDump(app, opts);
         if (opts.format === "yaml") {
@@ -460,6 +492,58 @@ function formatContract(report) {
         out.push("FAIL.");
     return `${out.join("\n")}\n`;
 }
+/**
+ * `daloy diff <baseline> <current>` — compare two OpenAPI 3.1 JSON documents
+ * and report added, removed, and changed operations. Exits 1 when a breaking
+ * change is detected so it can gate CI; `--json` emits machine-readable output.
+ *
+ * @internal
+ */
+async function runDiff(opts, io) {
+    const positionals = opts.positionals ?? [];
+    if (positionals.length !== 2) {
+        io.stderr(`daloy diff requires two file paths: <baseline> <current>\n\n${HELP}`);
+        return { exitCode: 2 };
+    }
+    if (!io.readTextFile) {
+        io.stderr("daloy diff: this environment cannot read files.\n");
+        return { exitCode: 2 };
+    }
+    const [baselinePath, currentPath] = positionals;
+    let baseline;
+    let current;
+    try {
+        baseline = JSON.parse(await io.readTextFile(baselinePath));
+        current = JSON.parse(await io.readTextFile(currentPath));
+    }
+    catch (err) {
+        io.stderr(`daloy diff: failed to read or parse input: ${err.message}\n`);
+        return { exitCode: 1 };
+    }
+    const result = diffOpenAPI(baseline, current);
+    const hasBreaking = result.breaking.length > 0;
+    if (opts.json) {
+        io.stdout(`${JSON.stringify(result, null, 2)}\n`);
+        return { exitCode: hasBreaking ? 1 : 0 };
+    }
+    const out = [];
+    const fmt = (c) => `  [${c.severity === "breaking" ? "BREAKING" : "ok"}] ${c.kind} ${c.location}` +
+        (c.detail ? ` — ${c.detail}` : "");
+    const total = result.breaking.length + result.nonBreaking.length;
+    if (total === 0) {
+        out.push("Specs match: no changes detected.");
+    }
+    else {
+        out.push(`OpenAPI changes: ${total} · ${result.breaking.length} breaking`);
+        for (const change of result.breaking)
+            out.push(fmt(change));
+        for (const change of result.nonBreaking)
+            out.push(fmt(change));
+    }
+    out.push(hasBreaking ? "FAIL: breaking changes detected." : "OK.");
+    io.stdout(`${out.join("\n")}\n`);
+    return { exitCode: hasBreaking ? 1 : 0 };
+}
 /**
  * `daloy doctor` — boot-time + CLI audit. Loads the user's
  * App entry and runs the secure-by-default checklist. Exits non-zero on any
@@ -567,6 +651,31 @@ async function runDoctor(opts, io) {
                     "JSON parsers are not DoS-amplified by a multipart-sized blob.",
             });
         }
+        // Header-count cap audit. The framework's portable maxHeaderCount
+        // guard is the application-tier defence against header-*count*
+        // amplification (the "HTTP/2 Bomb" dimension). Surface a finding when
+        // it is disabled (0) or raised to an implausibly generous value, both
+        // of which let a header flood reach routing.
+        const maxHeaderCount = o.maxHeaderCount;
+        if (maxHeaderCount === 0) {
+            findings.push({
+                level: "warn",
+                code: "audit.maxHeaderCount.disabled",
+                message: "maxHeaderCount is 0 — the header-count flood guard is disabled. " +
+                    "A request carrying thousands of header fields reaches routing. " +
+                    "Keep a finite cap (default 100) unless an upstream proxy already " +
+                    "enforces one (NGINX max_headers, Node server.maxHeadersCount).",
+            });
+        }
+        else if (typeof maxHeaderCount === "number" && maxHeaderCount > 1000) {
+            findings.push({
+                level: "warn",
+                code: "audit.maxHeaderCount.blanket",
+                message: `maxHeaderCount is ${maxHeaderCount} (> 1000). Realistic requests ` +
+                    "carry a few dozen headers; a cap this high weakens the " +
+                    "header-count amplification defence.",
+            });
+        }
         // Idle-timeout / request-timeout audit. Reaffirms the
         // existing requestTimeoutMs check; also surface an explicit zero
         // idleTimeoutMs in production. The framework also keeps adapter

package/dist/client.d.ts

@@ -17,6 +17,13 @@ export type RoutesOf<A extends App> = A["routes"][number];
  * Typed client surface generated from an `App`. The result is a record keyed
  * by each route's `operationId` whose values are async methods inferred from
  * the route's request and response schemas.
+ *
+ * The per-method types are recovered from the `App`'s accumulated route tuple,
+ * which is built up as you **chain** `app.route(...)` calls. If the `App` type
+ * is widened back to its bare default — e.g. a `const app: App` annotation, a
+ * `: App` factory return type, or registering routes as separate statements
+ * rather than a chain — the tuple is erased and this type collapses to an
+ * untyped, string-indexed record.
  */
 export type ClientFor<A extends App> = {
     [R in Extract<RoutesOf<A>, {
@@ -58,10 +65,26 @@ export interface ClientOptions {
  * For non-TypeScript consumers, run `pnpm gen` to emit a fully-typed SDK
  * from the OpenAPI document instead.
  *
+ * @remarks
+ * The method signatures are inferred from the `App`'s accumulated route tuple,
+ * so chain your `app.route(...)` registrations and let TypeScript infer the
+ * variable's type. A widening `const app: App` annotation, a `: App` factory
+ * return type, or registering routes as separate statements erases the
+ * per-route types and yields an untyped client.
+ *
  * @example
  * ```ts
  * import { createClient } from "@daloyjs/core/client";
  *
+ * const app = new App().route({
+ *   method: "GET",
+ *   path: "/books/:id",
+ *   operationId: "getBook",
+ *   request: { params: z.object({ id: z.string() }) },
+ *   responses: { 200: { description: "OK", body: z.object({ id: z.string(), title: z.string() }) } },
+ *   handler: ({ params }) => ({ status: 200, body: { id: params.id, title: "Dune" } }),
+ * });
+ *
  * const client = createClient(app, { baseUrl: "https://api.example.com" });
  * const res = await client.getBook({ params: { id: "123" } });
  * if (res.status === 200) console.log(res.body.title);

package/dist/client.js

@@ -22,10 +22,26 @@
  * For non-TypeScript consumers, run `pnpm gen` to emit a fully-typed SDK
  * from the OpenAPI document instead.
  *
+ * @remarks
+ * The method signatures are inferred from the `App`'s accumulated route tuple,
+ * so chain your `app.route(...)` registrations and let TypeScript infer the
+ * variable's type. A widening `const app: App` annotation, a `: App` factory
+ * return type, or registering routes as separate statements erases the
+ * per-route types and yields an untyped client.
+ *
  * @example
  * ```ts
  * import { createClient } from "@daloyjs/core/client";
  *
+ * const app = new App().route({
+ *   method: "GET",
+ *   path: "/books/:id",
+ *   operationId: "getBook",
+ *   request: { params: z.object({ id: z.string() }) },
+ *   responses: { 200: { description: "OK", body: z.object({ id: z.string(), title: z.string() }) } },
+ *   handler: ({ params }) => ({ status: 200, body: { id: params.id, title: "Dune" } }),
+ * });
+ *
  * const client = createClient(app, { baseUrl: "https://api.example.com" });
  * const res = await client.getBook({ params: { id: "123" } });
  * if (res.status === 200) console.log(res.body.title);

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;
+        },
+    };
+}