@daloyjs/core 0.36.0 → 0.37.0

package/dist/bot-guard.js

@@ -0,0 +1,291 @@
+/**
+ * Bot / User-Agent management middleware. Mirrors the bot-rule layer that
+ * Nginx, Cloudflare, and other WAFs run at the edge, but inside the app where
+ * the framework already owns request parsing and client-IP resolution.
+ *
+ * {@link botGuard} does three opt-in jobs:
+ *
+ * 1. **Block empty / missing `User-Agent`** — a common signature of crude
+ *    scrapers and vulnerability scanners (on by default).
+ * 2. **Block known-abusive `User-Agent` strings** — caller-supplied substrings
+ *    or `RegExp`s.
+ * 3. **Verify declared crawlers** — when a request *claims* to be Googlebot or
+ *    Bingbot, confirm it via reverse-DNS + forward-confirm (the method Google
+ *    and Bing themselves document) so a spoofed `User-Agent` can't impersonate a
+ *    trusted crawler. Verification results are cached per IP to keep DNS off the
+ *    hot path.
+ *
+ * The middleware is dependency-free and runtime-portable. The default DNS
+ * resolver is lazily imported from `node:dns/promises`; supply a custom
+ * {@link BotResolver} on non-Node runtimes or in tests.
+ *
+ * @example
+ * ```ts
+ * import { botGuard, WELL_KNOWN_BOTS } from "@daloyjs/core";
+ *
+ * app.use(
+ *   botGuard({
+ *     trustProxyHeaders: true,
+ *     blockedUserAgents: [/sqlmap/i, /nikto/i, "masscan"],
+ *     verifiedBots: WELL_KNOWN_BOTS, // spoofed Googlebot/Bingbot → 403
+ *   }),
+ * );
+ * ```
+ *
+ * @module
+ * @since 0.37.0
+ */
+import { ForbiddenError } from "./errors.js";
+const DEFAULT_MESSAGE = "Bot access denied";
+const DEFAULT_CACHE_TTL_MS = 60 * 60_000;
+const DEFAULT_CACHE_MAX = 10_000;
+/**
+ * Built-in {@link VerifiedBotRule} for Googlebot (and other Google crawlers),
+ * verified against Google's documented `*.googlebot.com` / `*.google.com`
+ * reverse-DNS domains.
+ *
+ * @since 0.37.0
+ */
+export const GOOGLEBOT = {
+    name: "Googlebot",
+    userAgent: /googlebot|google-inspectiontool|storebot-google|googleother|google-extended/i,
+    domains: [".googlebot.com", ".google.com"],
+};
+/**
+ * Built-in {@link VerifiedBotRule} for Bingbot, verified against Microsoft's
+ * documented `*.search.msn.com` reverse-DNS domain.
+ *
+ * @since 0.37.0
+ */
+export const BINGBOT = {
+    name: "Bingbot",
+    userAgent: /bingbot|bingpreview|adidxbot|msnbot/i,
+    domains: [".search.msn.com"],
+};
+/**
+ * Convenience bundle of the built-in verified-crawler rules
+ * ({@link GOOGLEBOT}, {@link BINGBOT}).
+ *
+ * @since 0.37.0
+ */
+export const WELL_KNOWN_BOTS = [GOOGLEBOT, BINGBOT];
+function matchesUserAgent(ua, patterns) {
+    const lower = ua.toLowerCase();
+    for (const pattern of patterns) {
+        if (typeof pattern === "string") {
+            if (pattern && lower.includes(pattern.toLowerCase()))
+                return true;
+        }
+        else if (pattern.test(ua)) {
+            return true;
+        }
+    }
+    return false;
+}
+function forwardedIpResolver(ctx) {
+    const headers = ctx.request.headers;
+    const forwarded = headers.get("x-forwarded-for");
+    if (forwarded) {
+        const first = forwarded.split(",")[0]?.trim();
+        if (first)
+            return first;
+    }
+    return ctx.request.headers.get("x-real-ip") ?? undefined;
+}
+function noIpResolver(_ctx) {
+    return undefined;
+}
+function createDefaultResolver() {
+    let dnsPromise = null;
+    const load = async () => {
+        if (!dnsPromise) {
+            dnsPromise = import("node:dns/promises")
+                .then((m) => ({
+                reverse: m.reverse,
+                lookup: m.lookup,
+            }))
+                .catch(() => null);
+        }
+        const dns = await dnsPromise;
+        if (!dns) {
+            throw new Error("botGuard: no DNS resolver available on this runtime. Pass options.resolver.");
+        }
+        return dns;
+    };
+    return {
+        async reverse(ip) {
+            const dns = await load();
+            return dns.reverse(ip);
+        },
+        async forward(hostname) {
+            const dns = await load();
+            const results = await dns.lookup(hostname, { all: true });
+            return results.map((r) => r.address);
+        },
+    };
+}
+/**
+ * Build the default DNS resolver backed by a lazily-imported
+ * `node:dns/promises`. Used internally by {@link botGuard} when no custom
+ * {@link BotGuardOptions.resolver} is supplied, and exported for tests. Throws
+ * on runtimes without `node:dns/promises` so callers are told to supply their
+ * own resolver.
+ *
+ * @returns A {@link BotResolver} backed by the platform's DNS.
+ * @internal
+ */
+export function _createDefaultBotResolver() {
+    return createDefaultResolver();
+}
+/**
+ * Confirm that `hostname` ends with one of the allowed `domains`. A leading dot
+ * in a domain enforces a subdomain boundary so `evil-googlebot.com` cannot match
+ * `.googlebot.com`; a bare domain also matches the apex exactly.
+ *
+ * @internal
+ */
+function hostnameMatchesDomains(hostname, domains) {
+    const host = hostname.toLowerCase().replace(/\.$/, "");
+    for (const domain of domains) {
+        const d = domain.toLowerCase();
+        if (d.startsWith(".")) {
+            if (host.endsWith(d))
+                return true;
+        }
+        else if (host === d || host.endsWith(`.${d}`)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Reverse-DNS + forward-confirm a client IP against a verified-bot rule, the way
+ * Google and Bing document. Returns `true` only when a PTR hostname both ends in
+ * an allowed domain and forward-resolves back to the same IP.
+ *
+ * @internal
+ */
+async function verifyCrawler(resolver, ip, rule) {
+    const hostnames = await resolver.reverse(ip);
+    for (const hostname of hostnames) {
+        if (!hostnameMatchesDomains(hostname, rule.domains))
+            continue;
+        const addresses = await resolver.forward(hostname);
+        if (addresses.includes(ip))
+            return true;
+    }
+    return false;
+}
+/**
+ * Bot / User-Agent management middleware. Blocks empty or known-abusive
+ * `User-Agent` strings and verifies declared crawlers (Googlebot/Bingbot) via
+ * reverse-DNS + forward-confirm, so a spoofed `User-Agent` cannot impersonate a
+ * trusted crawler.
+ *
+ * All checks are opt-in and allowlist-friendly: {@link BotGuardOptions.allowUserAgents}
+ * is consulted first and bypasses every other rule.
+ *
+ * @param opts - Bot-guard configuration.
+ * @returns A {@link Hooks} bundle ready for `app.use(...)`.
+ * @throws Error when `verifiedBots` is set without an IP source
+ *   (`resolveIp` or `trustProxyHeaders`), or when `mode` is invalid.
+ * @since 0.37.0
+ */
+export function botGuard(opts = {}) {
+    const blockEmpty = opts.blockEmptyUserAgent !== false;
+    const blocked = opts.blockedUserAgents ?? [];
+    const allowed = opts.allowUserAgents ?? [];
+    const verifiedBots = opts.verifiedBots ?? [];
+    const blockUnverifiable = opts.blockUnverifiableBots !== false;
+    const message = opts.message ?? DEFAULT_MESSAGE;
+    const cacheTtlMs = opts.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS;
+    const cacheMax = opts.cacheMaxEntries ?? DEFAULT_CACHE_MAX;
+    const mode = opts.mode ?? "block";
+    if (mode !== "block" && mode !== "log") {
+        throw new Error('botGuard(): mode must be "block" or "log".');
+    }
+    const resolveIp = opts.resolveIp ?? (opts.trustProxyHeaders ? forwardedIpResolver : noIpResolver);
+    if (verifiedBots.length > 0 && !opts.resolveIp && !opts.trustProxyHeaders) {
+        throw new Error("botGuard(): verifiedBots requires a client-IP source — provide resolveIp " +
+            "or set trustProxyHeaders, otherwise declared crawlers cannot be verified.");
+    }
+    const resolver = opts.resolver ?? createDefaultResolver();
+    // Per-IP verification cache (keyed by `ip\u0000botName`) so a crawler's DNS
+    // round-trip is paid once per TTL, not on every request.
+    const cache = new Map();
+    const readCache = (key) => {
+        const entry = cache.get(key);
+        if (!entry)
+            return undefined;
+        if (entry.expiresMs <= Date.now()) {
+            cache.delete(key);
+            return undefined;
+        }
+        return entry.verified;
+    };
+    const writeCache = (key, verified) => {
+        const now = Date.now();
+        cache.set(key, { verified, expiresMs: now + cacheTtlMs });
+        if (cache.size > cacheMax) {
+            for (const [k, v] of cache)
+                if (v.expiresMs <= now)
+                    cache.delete(k);
+        }
+    };
+    const reject = (event) => {
+        opts.onBlock?.(event);
+        if (mode === "block")
+            throw new ForbiddenError(message);
+    };
+    return {
+        async beforeHandle(ctx) {
+            const ua = ctx.request.headers.get("user-agent") ?? "";
+            // Allowlist wins over every other rule.
+            if (allowed.length > 0 && matchesUserAgent(ua, allowed))
+                return undefined;
+            if (!ua.trim()) {
+                if (blockEmpty)
+                    reject({ reason: "empty-user-agent", userAgent: ua });
+                return undefined;
+            }
+            if (blocked.length > 0 && matchesUserAgent(ua, blocked)) {
+                reject({ reason: "blocked-user-agent", userAgent: ua });
+                return undefined;
+            }
+            const rule = verifiedBots.find((r) => r.userAgent.test(ua));
+            if (!rule)
+                return undefined;
+            const ip = resolveIp(ctx);
+            if (!ip) {
+                if (blockUnverifiable) {
+                    reject({ reason: "unverifiable-bot", userAgent: ua, botName: rule.name });
+                }
+                return undefined;
+            }
+            const cacheKey = `${ip}\u0000${rule.name}`;
+            const cached = readCache(cacheKey);
+            if (cached === true)
+                return undefined;
+            if (cached === false) {
+                reject({ reason: "spoofed-bot", userAgent: ua, ip, botName: rule.name });
+                return undefined;
+            }
+            let verified;
+            try {
+                verified = await verifyCrawler(resolver, ip, rule);
+            }
+            catch {
+                // DNS failure — cannot confirm. Don't cache transient errors.
+                if (blockUnverifiable) {
+                    reject({ reason: "unverifiable-bot", userAgent: ua, ip, botName: rule.name });
+                }
+                return undefined;
+            }
+            writeCache(cacheKey, verified);
+            if (!verified) {
+                reject({ reason: "spoofed-bot", userAgent: ua, ip, botName: rule.name });
+            }
+            return undefined;
+        },
+    };
+}

package/dist/cli.d.ts

@@ -24,6 +24,11 @@ export interface CliIO {
      * can omit it.
      */
     spawn?: (command: string, args: readonly string[]) => Promise<number>;
+    /**
+     * Read a UTF-8 text file by path. Required for `daloy diff`; optional so
+     * unit tests that only exercise `inspect` can omit it.
+     */
+    readTextFile?: (path: string) => Promise<string>;
     /**
      * Override runtime detection (defaults to inspecting `globalThis.process.versions`).
      * Mainly exists for tests.
@@ -40,6 +45,7 @@ export interface CliOptions {
     check: boolean;
     schemas: boolean;
     openapi: boolean;
+    asyncapi: boolean;
     ai: boolean;
     /**
      * Output format for `--ai` and `--openapi`. Defaults to `"json"`.
@@ -61,6 +67,8 @@ export interface CliOptions {
     auditSecrets?: boolean;
     /** `daloy doctor` — disable the default-defaults audit. */
     noAuditDefaults?: boolean;
+    /** Positional arguments collected in order (used by `daloy diff`). */
+    positionals?: string[];
 }
 /** Runtime detected for `daloy dev`. */
 export type DevRuntime = "node" | "bun" | "deno";

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

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;