npm - @daloyjs/core - Versions diffs - 0.36.0 → 0.37.0 - Mend

@daloyjs/core 0.36.0 → 0.37.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (77) hide show

package/README.md +21 -2
package/bin/daloy.mjs +2 -0
package/dist/adapters/bun.js +16 -9
package/dist/adapters/deno.js +7 -1
package/dist/adapters/node.d.ts +11 -0
package/dist/adapters/node.js +24 -0
package/dist/app.d.ts +144 -1
package/dist/app.js +208 -1
package/dist/asyncapi.d.ts +98 -0
package/dist/asyncapi.js +212 -0
package/dist/auto-ban.d.ts +205 -0
package/dist/auto-ban.js +222 -0
package/dist/bot-guard.d.ts +209 -0
package/dist/bot-guard.js +291 -0
package/dist/cli.d.ts +8 -0
package/dist/cli.js +88 -4
package/dist/concurrency-limit.d.ts +135 -0
package/dist/concurrency-limit.js +254 -0
package/dist/docs.d.ts +57 -6
package/dist/docs.js +34 -3
package/dist/errors.d.ts +20 -0
package/dist/errors.js +27 -0
package/dist/fetch-guard.js +4 -0
package/dist/fetch-resilience.d.ts +295 -0
package/dist/fetch-resilience.js +485 -0
package/dist/geo-block.d.ts +184 -0
package/dist/geo-block.js +153 -0
package/dist/hashing.d.ts +2 -1
package/dist/hashing.js +12 -1
package/dist/http-signatures.d.ts +303 -0
package/dist/http-signatures.js +782 -0
package/dist/idempotency.d.ts +204 -0
package/dist/idempotency.js +341 -0
package/dist/index.d.ts +38 -4
package/dist/index.js +18 -1
package/dist/ip-reputation.d.ts +198 -0
package/dist/ip-reputation.js +253 -0
package/dist/jwk.d.ts +15 -0
package/dist/jwk.js +24 -2
package/dist/load-shedding.d.ts +5 -0
package/dist/logger.js +6 -2
package/dist/metrics.d.ts +208 -0
package/dist/metrics.js +452 -0
package/dist/middleware.js +0 -10
package/dist/mtls.d.ts +266 -0
package/dist/mtls.js +488 -0
package/dist/multipart.js +1 -1
package/dist/openapi-diff.d.ts +79 -0
package/dist/openapi-diff.js +246 -0
package/dist/openapi.js +4 -1
package/dist/pagination.d.ts +210 -0
package/dist/pagination.js +353 -0
package/dist/rate-limit-redis.d.ts +8 -0
package/dist/rate-limit-redis.js +8 -0
package/dist/request-decompression.d.ts +200 -0
package/dist/request-decompression.js +363 -0
package/dist/response-cache.d.ts +205 -0
package/dist/response-cache.js +374 -0
package/dist/router.d.ts +22 -0
package/dist/router.js +64 -7
package/dist/safe-redirect.d.ts +2 -2
package/dist/safe-redirect.js +3 -8
package/dist/sbom.cdx.json +9 -9
package/dist/sbom.spdx.json +5 -5
package/dist/scheduler.d.ts +315 -0
package/dist/scheduler.js +546 -0
package/dist/security.d.ts +27 -7
package/dist/security.js +27 -7
package/dist/session.js +3 -3
package/dist/types.d.ts +33 -0
package/dist/waf.d.ts +213 -0
package/dist/waf.js +334 -0
package/dist/webhook-delivery.d.ts +263 -0
package/dist/webhook-delivery.js +311 -0
package/dist/websocket.d.ts +52 -0
package/dist/websocket.js +13 -0
package/package.json +76 -2

package/dist/webhook-delivery.d.ts ADDED Viewed

@@ -0,0 +1,263 @@
+/**
+ * Outbound webhook delivery — the sending counterpart to the inbound
+ * {@link verifyWebhookSignature} / {@link signWebhookPayload} helpers.
+ *
+ * Where the inbound helpers answer *&ldquo;is this webhook I received
+ * authentic?&rdquo;*, this module answers *&ldquo;how do I reliably and
+ * securely deliver a webhook to someone else?&rdquo;* — the three things a
+ * production webhook sender needs:
+ *
+ * - **Signed delivery with timestamped signatures.** Every request carries
+ *   an HMAC signature computed over `"<timestamp>.<body>"` (the Stripe /
+ *   Standard Webhooks convention), plus an idempotency id and a timestamp
+ *   header, so the receiver can authenticate the payload and reject
+ *   replays with {@link verifyWebhookSignature}.
+ * - **Retry with backoff.** Transient failures (network errors, timeouts,
+ *   `408` / `429` / `5xx`) are retried with exponential backoff and full
+ *   jitter, honouring a `Retry-After` header. The signature is computed
+ *   **once** so every retry carries the same id and signature — the
+ *   receiver can dedupe on the id.
+ * - **Dead-letter semantics.** When every attempt is exhausted (or the
+ *   upstream returns a permanent `4xx`), the failed delivery is handed to
+ *   a {@link WebhookDeadLetterSink} for later inspection or replay instead
+ *   of being silently dropped.
+ *
+ * Delivery is **SSRF-hardened by default**: the transport defaults to
+ * {@link fetchGuard}, so a webhook URL that resolves to cloud-metadata or
+ * an internal address is refused before any bytes are sent. Pass your own
+ * `fetch` (e.g. `fetchGuard({ allowPrivate: true })` or a
+ * {@link resilientFetch}) to change that posture deliberately.
+ *
+ * ```ts
+ * import { createWebhookSender, MemoryWebhookDeadLetterSink } from "@daloyjs/core";
+ *
+ * const deadLetters = new MemoryWebhookDeadLetterSink();
+ * const send = createWebhookSender({ secret: process.env.WEBHOOK_SECRET!, deadLetter: deadLetters });
+ *
+ * const result = await send({
+ *   url: "https://example.com/hooks",
+ *   eventType: "invoice.paid",
+ *   payload: { id: "in_123", amount: 4200 },
+ * });
+ * if (!result.ok) {
+ *   // result.deadLettered === true; inspect deadLetters.list()
+ * }
+ * ```
+ *
+ * @module
+ * @since 0.37.0
+ */
+import { type WebhookHmacAlgorithm } from "./security.js";
+/**
+ * A single webhook event to deliver. The `payload` is signed and sent as
+ * the request body; everything else shapes the request and the signature
+ * headers.
+ *
+ * @since 0.37.0
+ */
+export interface WebhookEvent {
+    /** Absolute `http(s)` URL of the receiver. */
+    url: string;
+    /**
+     * The event body. An object or array is JSON-serialised; a `string` is
+     * sent verbatim; a `Uint8Array` is sent as raw bytes. The signature is
+     * always computed over the exact bytes sent.
+     */
+    payload: unknown;
+    /**
+     * Optional event type (e.g. `"invoice.paid"`), emitted as a header and
+     * recorded on the dead letter. Purely informational.
+     */
+    eventType?: string;
+    /**
+     * Stable idempotency id, emitted in the id header so the receiver can
+     * dedupe retries. A random UUID is generated when omitted.
+     */
+    id?: string;
+    /**
+     * Extra request headers merged in **after** the signature headers, so
+     * they cannot overwrite the id / timestamp / signature headers.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Override the `Content-Type` header. Defaults to `application/json`
+     * for objects / strings and `application/octet-stream` for bytes.
+     */
+    contentType?: string;
+}
+/**
+ * A failed delivery handed to a {@link WebhookDeadLetterSink} after every
+ * attempt is exhausted. Carries enough context to inspect, alert on, or
+ * replay the delivery later.
+ *
+ * @since 0.37.0
+ */
+export interface WebhookDeadLetter {
+    /** The idempotency id used for the delivery. */
+    id: string;
+    /** The receiver URL. */
+    url: string;
+    /** The event type, when one was supplied. */
+    eventType?: string;
+    /** The exact body bytes that were signed and sent. */
+    payload: Uint8Array;
+    /** The `Content-Type` that was sent. */
+    contentType: string;
+    /** Total number of attempts made before giving up. */
+    attempts: number;
+    /** The last HTTP status seen, when the final failure was a response. */
+    lastStatus?: number;
+    /** The last error message, when the final failure was a thrown error. */
+    lastError?: string;
+    /** The Unix-seconds timestamp bound into the signature. */
+    timestamp: number;
+    /** Wall-clock time (ms since epoch) the delivery was dead-lettered. */
+    failedAt: number;
+}
+/**
+ * A sink that receives {@link WebhookDeadLetter}s for permanently-failed
+ * deliveries. Implement this to persist to a queue, database, or alerting
+ * pipeline. `add` may be async; the sender awaits it.
+ *
+ * @since 0.37.0
+ */
+export interface WebhookDeadLetterSink {
+    add(letter: WebhookDeadLetter): void | Promise<void>;
+}
+/**
+ * An in-memory, bounded {@link WebhookDeadLetterSink} suitable for tests
+ * and single-process apps. Holds the most recent `capacity` dead letters
+ * (default `1000`) in a ring buffer; older entries are evicted.
+ *
+ * @since 0.37.0
+ */
+export declare class MemoryWebhookDeadLetterSink implements WebhookDeadLetterSink {
+    #private;
+    constructor(capacity?: number);
+    /** Append a dead letter, evicting the oldest if at capacity. */
+    add(letter: WebhookDeadLetter): void;
+    /** A snapshot of the currently-held dead letters, oldest first. */
+    list(): readonly WebhookDeadLetter[];
+    /** Remove and return every held dead letter (e.g. for a replay sweep). */
+    drain(): WebhookDeadLetter[];
+    /** The number of dead letters currently held. */
+    get size(): number;
+}
+/**
+ * Per-attempt telemetry passed to {@link WebhookSenderOptions.onAttempt}.
+ *
+ * @since 0.37.0
+ */
+export interface WebhookAttempt {
+    /** The idempotency id of the delivery. */
+    id: string;
+    /** 1-based attempt number. */
+    attempt: number;
+    /** The HTTP status, when the attempt produced a response. */
+    status?: number;
+    /** The error, when the attempt threw (network error / timeout). */
+    error?: unknown;
+    /** Whether the sender will retry after this attempt. */
+    willRetry: boolean;
+    /** The backoff delay (ms) before the next attempt, when retrying. */
+    delayMs?: number;
+}
+/**
+ * The outcome of a {@link createWebhookSender} delivery. Never throws for
+ * an ordinary delivery failure — inspect `ok` / `deadLettered` instead.
+ *
+ * @since 0.37.0
+ */
+export interface WebhookDeliveryResult {
+    /** `true` when the receiver returned a 2xx response. */
+    ok: boolean;
+    /** The idempotency id used for the delivery. */
+    id: string;
+    /** The event type, when one was supplied. */
+    eventType?: string;
+    /** Total number of attempts made. */
+    attempts: number;
+    /** The final HTTP status, when the last attempt produced a response. */
+    status?: number;
+    /** The final response object, when the last attempt produced one. */
+    response?: Response;
+    /** The final error, when the last attempt threw. */
+    error?: unknown;
+    /** Whether the failed delivery was handed to the dead-letter sink. */
+    deadLettered: boolean;
+}
+/**
+ * Configuration for {@link createWebhookSender}. Only `secret` is
+ * required; every other field has a production-safe default.
+ *
+ * @since 0.37.0
+ */
+export interface WebhookSenderOptions {
+    /** HMAC secret used to sign every delivery. */
+    secret: string | Uint8Array;
+    /** HMAC digest. Default `"sha256"`. */
+    algorithm?: WebhookHmacAlgorithm;
+    /**
+     * Transport. Defaults to {@link fetchGuard} so webhook URLs that resolve
+     * to internal / cloud-metadata addresses are refused (SSRF defence).
+     * Pass your own to relax or extend that posture.
+     */
+    fetch?: typeof fetch;
+    /** Maximum total attempts (first try + retries). Default `5`. */
+    maxAttempts?: number;
+    /** Base backoff for the first retry, in ms. Default `500`. */
+    retryDelayMs?: number;
+    /** Upper bound on any single backoff delay, in ms. Default `30_000`. */
+    maxRetryDelayMs?: number;
+    /** Exponential backoff multiplier. Default `2`. */
+    backoffFactor?: number;
+    /** Apply full jitter to backoff. Default `true`. */
+    jitter?: boolean;
+    /** Per-attempt timeout, in ms. `0` disables. Default `10_000`. */
+    timeoutMs?: number;
+    /**
+     * Response statuses that trigger a retry. Default
+     * `[408, 429, 500, 502, 503, 504]`. Any other non-2xx status is a
+     * permanent failure (dead-lettered immediately).
+     */
+    retryableStatuses?: readonly number[];
+    /** Honour a `Retry-After` header on a retryable response. Default `true`. */
+    respectRetryAfter?: boolean;
+    /** Header carrying the idempotency id. Default `"webhook-id"`. */
+    idHeader?: string;
+    /** Header carrying the Unix-seconds timestamp. Default `"webhook-timestamp"`. */
+    timestampHeader?: string;
+    /** Header carrying the signature. Default `"webhook-signature"`. */
+    signatureHeader?: string;
+    /** Header carrying the event type. Default `"webhook-event-type"`. */
+    eventTypeHeader?: string;
+    /** `User-Agent` sent with every delivery. Default `"DaloyJS-Webhook/1.0"`. */
+    userAgent?: string;
+    /** Sink for permanently-failed deliveries. */
+    deadLetter?: WebhookDeadLetterSink;
+    /** Clock (ms since epoch). Default {@link Date.now}. Override in tests. */
+    now?: () => number;
+    /**
+     * Abortable sleep, primarily for deterministic tests. Defaults to a
+     * `setTimeout`-based sleep.
+     */
+    sleep?: (ms: number) => Promise<void>;
+    /** Per-attempt observer (e.g. to emit a metric). */
+    onAttempt?: (attempt: WebhookAttempt) => void;
+}
+/**
+ * Build a webhook sender bound to a signing secret and delivery policy.
+ * The returned `send(event)` function signs, delivers, retries, and
+ * dead-letters a single {@link WebhookEvent}, resolving to a
+ * {@link WebhookDeliveryResult} (it does not throw on ordinary delivery
+ * failure).
+ *
+ * @example
+ * ```ts
+ * const send = createWebhookSender({ secret: process.env.WEBHOOK_SECRET! });
+ * const result = await send({ url, eventType: "user.created", payload: { id } });
+ * ```
+ *
+ * @since 0.37.0
+ */
+export declare function createWebhookSender(options: WebhookSenderOptions): (event: WebhookEvent) => Promise<WebhookDeliveryResult>;

package/dist/webhook-delivery.js ADDED Viewed

@@ -0,0 +1,311 @@
+/**
+ * Outbound webhook delivery — the sending counterpart to the inbound
+ * {@link verifyWebhookSignature} / {@link signWebhookPayload} helpers.
+ *
+ * Where the inbound helpers answer *&ldquo;is this webhook I received
+ * authentic?&rdquo;*, this module answers *&ldquo;how do I reliably and
+ * securely deliver a webhook to someone else?&rdquo;* — the three things a
+ * production webhook sender needs:
+ *
+ * - **Signed delivery with timestamped signatures.** Every request carries
+ *   an HMAC signature computed over `"<timestamp>.<body>"` (the Stripe /
+ *   Standard Webhooks convention), plus an idempotency id and a timestamp
+ *   header, so the receiver can authenticate the payload and reject
+ *   replays with {@link verifyWebhookSignature}.
+ * - **Retry with backoff.** Transient failures (network errors, timeouts,
+ *   `408` / `429` / `5xx`) are retried with exponential backoff and full
+ *   jitter, honouring a `Retry-After` header. The signature is computed
+ *   **once** so every retry carries the same id and signature — the
+ *   receiver can dedupe on the id.
+ * - **Dead-letter semantics.** When every attempt is exhausted (or the
+ *   upstream returns a permanent `4xx`), the failed delivery is handed to
+ *   a {@link WebhookDeadLetterSink} for later inspection or replay instead
+ *   of being silently dropped.
+ *
+ * Delivery is **SSRF-hardened by default**: the transport defaults to
+ * {@link fetchGuard}, so a webhook URL that resolves to cloud-metadata or
+ * an internal address is refused before any bytes are sent. Pass your own
+ * `fetch` (e.g. `fetchGuard({ allowPrivate: true })` or a
+ * {@link resilientFetch}) to change that posture deliberately.
+ *
+ * ```ts
+ * import { createWebhookSender, MemoryWebhookDeadLetterSink } from "@daloyjs/core";
+ *
+ * const deadLetters = new MemoryWebhookDeadLetterSink();
+ * const send = createWebhookSender({ secret: process.env.WEBHOOK_SECRET!, deadLetter: deadLetters });
+ *
+ * const result = await send({
+ *   url: "https://example.com/hooks",
+ *   eventType: "invoice.paid",
+ *   payload: { id: "in_123", amount: 4200 },
+ * });
+ * if (!result.ok) {
+ *   // result.deadLettered === true; inspect deadLetters.list()
+ * }
+ * ```
+ *
+ * @module
+ * @since 0.37.0
+ */
+import { signWebhookPayload } from "./security.js";
+import { fetchGuard } from "./fetch-guard.js";
+/**
+ * An in-memory, bounded {@link WebhookDeadLetterSink} suitable for tests
+ * and single-process apps. Holds the most recent `capacity` dead letters
+ * (default `1000`) in a ring buffer; older entries are evicted.
+ *
+ * @since 0.37.0
+ */
+export class MemoryWebhookDeadLetterSink {
+    #capacity;
+    #items = [];
+    constructor(capacity = 1000) {
+        if (!Number.isInteger(capacity) || capacity < 1) {
+            throw new RangeError("MemoryWebhookDeadLetterSink: capacity must be a positive integer");
+        }
+        this.#capacity = capacity;
+    }
+    /** Append a dead letter, evicting the oldest if at capacity. */
+    add(letter) {
+        this.#items.push(letter);
+        if (this.#items.length > this.#capacity)
+            this.#items.shift();
+    }
+    /** A snapshot of the currently-held dead letters, oldest first. */
+    list() {
+        return [...this.#items];
+    }
+    /** Remove and return every held dead letter (e.g. for a replay sweep). */
+    drain() {
+        const out = this.#items;
+        this.#items = [];
+        return out;
+    }
+    /** The number of dead letters currently held. */
+    get size() {
+        return this.#items.length;
+    }
+}
+const DEFAULT_RETRYABLE_STATUSES = [408, 429, 500, 502, 503, 504];
+function defaultSleep(ms) {
+    if (ms <= 0)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        timer.unref?.();
+    });
+}
+function parseRetryAfter(value, now) {
+    if (!value)
+        return undefined;
+    const trimmed = value.trim();
+    if (/^\d+$/.test(trimmed))
+        return Number(trimmed) * 1000;
+    const dateMs = Date.parse(trimmed);
+    if (!Number.isNaN(dateMs))
+        return Math.max(0, dateMs - now);
+    return undefined;
+}
+/** Serialise a payload to body bytes + a default content type. */
+function encodePayload(payload) {
+    if (payload instanceof Uint8Array) {
+        return { bytes: payload, contentType: "application/octet-stream" };
+    }
+    if (typeof payload === "string") {
+        return { bytes: new TextEncoder().encode(payload), contentType: "application/json" };
+    }
+    return {
+        bytes: new TextEncoder().encode(JSON.stringify(payload ?? null)),
+        contentType: "application/json",
+    };
+}
+function randomId() {
+    const c = globalThis.crypto;
+    if (c?.randomUUID)
+        return c.randomUUID();
+    // Web-Crypto is mandatory on every runtime Daloy supports; this is an
+    // unreachable last-resort guard so a missing global never throws.
+    throw new Error("WebCrypto unavailable: cannot generate a webhook id");
+}
+/**
+ * Build a webhook sender bound to a signing secret and delivery policy.
+ * The returned `send(event)` function signs, delivers, retries, and
+ * dead-letters a single {@link WebhookEvent}, resolving to a
+ * {@link WebhookDeliveryResult} (it does not throw on ordinary delivery
+ * failure).
+ *
+ * @example
+ * ```ts
+ * const send = createWebhookSender({ secret: process.env.WEBHOOK_SECRET! });
+ * const result = await send({ url, eventType: "user.created", payload: { id } });
+ * ```
+ *
+ * @since 0.37.0
+ */
+export function createWebhookSender(options) {
+    if (options.secret === undefined || options.secret === null || options.secret === "") {
+        throw new Error("createWebhookSender(): a non-empty signing secret is required");
+    }
+    const algorithm = options.algorithm ?? "sha256";
+    const transport = options.fetch ?? fetchGuard();
+    const maxAttempts = options.maxAttempts ?? 5;
+    const retryDelayMs = options.retryDelayMs ?? 500;
+    const maxRetryDelayMs = options.maxRetryDelayMs ?? 30_000;
+    const backoffFactor = options.backoffFactor ?? 2;
+    const jitter = options.jitter ?? true;
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const respectRetryAfter = options.respectRetryAfter ?? true;
+    if (!Number.isInteger(maxAttempts) || maxAttempts < 1) {
+        throw new RangeError("createWebhookSender(): maxAttempts must be a positive integer");
+    }
+    if (!Number.isFinite(timeoutMs) || timeoutMs < 0) {
+        throw new RangeError("createWebhookSender(): timeoutMs must be a non-negative number");
+    }
+    const retryStatuses = new Set(options.retryableStatuses ?? DEFAULT_RETRYABLE_STATUSES);
+    const idHeader = options.idHeader ?? "webhook-id";
+    const timestampHeader = options.timestampHeader ?? "webhook-timestamp";
+    const signatureHeader = options.signatureHeader ?? "webhook-signature";
+    const eventTypeHeader = options.eventTypeHeader ?? "webhook-event-type";
+    const userAgent = options.userAgent ?? "DaloyJS-Webhook/1.0";
+    const now = options.now ?? Date.now;
+    const sleep = options.sleep ?? defaultSleep;
+    function backoffFor(attempt, response) {
+        if (respectRetryAfter && response) {
+            const fromHeader = parseRetryAfter(response.headers.get("retry-after"), now());
+            if (fromHeader !== undefined)
+                return Math.min(maxRetryDelayMs, fromHeader);
+        }
+        const exp = retryDelayMs * backoffFactor ** (attempt - 1);
+        const capped = Math.min(maxRetryDelayMs, exp);
+        // Backoff jitter spreads load; it is not a security primitive.
+        return jitter ? Math.random() * capped : capped; // daloy-allow-weak-random: backoff jitter is not a security primitive
+    }
+    async function attemptOnce(url, headers, body) {
+        const controller = new AbortController();
+        let timer;
+        if (timeoutMs > 0) {
+            timer = setTimeout(() => controller.abort(), timeoutMs);
+            timer.unref?.();
+        }
+        try {
+            const response = await transport(url, {
+                method: "POST",
+                headers,
+                body: body,
+                signal: controller.signal,
+            });
+            return { response };
+        }
+        catch (error) {
+            return { error };
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    return async function send(event) {
+        const id = event.id ?? randomId();
+        const { bytes, contentType: defaultContentType } = encodePayload(event.payload);
+        const contentType = event.contentType ?? defaultContentType;
+        const timestamp = Math.floor(now() / 1000);
+        // Sign ONCE — every retry carries the same id + signature so the
+        // receiver can dedupe and the timestamp stays stable.
+        const signature = await signWebhookPayload({
+            payload: bytes,
+            secret: options.secret,
+            algorithm,
+            timestamp,
+        });
+        const baseHeaders = {
+            "content-type": contentType,
+            "user-agent": userAgent,
+            [idHeader]: id,
+            [timestampHeader]: String(timestamp),
+            [signatureHeader]: `${algorithm}=${signature}`,
+        };
+        if (event.eventType !== undefined)
+            baseHeaders[eventTypeHeader] = event.eventType;
+        // Caller headers are merged last but cannot clobber signature headers.
+        const reserved = new Set([
+            "content-type",
+            idHeader.toLowerCase(),
+            timestampHeader.toLowerCase(),
+            signatureHeader.toLowerCase(),
+            eventTypeHeader.toLowerCase(),
+        ]);
+        for (const [k, v] of Object.entries(event.headers ?? {})) {
+            if (!reserved.has(k.toLowerCase()))
+                baseHeaders[k] = v;
+        }
+        let lastStatus;
+        let lastResponse;
+        let lastError;
+        let madeAttempts = 0;
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            madeAttempts = attempt;
+            const { response, error } = await attemptOnce(event.url, baseHeaders, bytes);
+            if (response) {
+                lastResponse = response;
+                lastStatus = response.status;
+                lastError = undefined;
+                if (response.ok) {
+                    options.onAttempt?.({ id, attempt, status: response.status, willRetry: false });
+                    return { ok: true, id, eventType: event.eventType, attempts: attempt, status: response.status, response, deadLettered: false };
+                }
+                const retryable = retryStatuses.has(response.status) && attempt < maxAttempts;
+                const delayMs = retryable ? backoffFor(attempt, response) : undefined;
+                options.onAttempt?.({ id, attempt, status: response.status, willRetry: retryable, delayMs });
+                if (!retryable)
+                    break;
+                await sleep(delayMs);
+                continue;
+            }
+            // Thrown error. An SSRF refusal is a permanent decision about the
+            // target and is never retried; a per-attempt timeout (our own abort)
+            // and ordinary network errors are transient and retried.
+            lastError = error;
+            lastResponse = undefined;
+            lastStatus = undefined;
+            const isSsrf = error instanceof Error && error.name === "SsrfBlockedError";
+            const retryable = !isSsrf && attempt < maxAttempts;
+            const delayMs = retryable ? backoffFor(attempt) : undefined;
+            options.onAttempt?.({ id, attempt, error, willRetry: retryable, delayMs });
+            if (!retryable)
+                break;
+            await sleep(delayMs);
+        }
+        // Exhausted / permanent failure → dead-letter.
+        let deadLettered = false;
+        if (options.deadLetter) {
+            await options.deadLetter.add({
+                id,
+                url: event.url,
+                ...(event.eventType !== undefined ? { eventType: event.eventType } : {}),
+                payload: bytes,
+                contentType,
+                attempts: madeAttempts,
+                ...(lastStatus !== undefined ? { lastStatus } : {}),
+                ...(lastError !== undefined ? { lastError: lastError instanceof Error ? lastError.message : String(lastError) } : {}),
+                timestamp,
+                failedAt: now(),
+            });
+            deadLettered = true;
+        }
+        const result = {
+            ok: false,
+            id,
+            attempts: madeAttempts,
+            deadLettered,
+        };
+        if (event.eventType !== undefined)
+            result.eventType = event.eventType;
+        if (lastStatus !== undefined)
+            result.status = lastStatus;
+        if (lastResponse !== undefined)
+            result.response = lastResponse;
+        if (lastError !== undefined)
+            result.error = lastError;
+        return result;
+    };
+}

package/dist/websocket.d.ts CHANGED Viewed

@@ -84,6 +84,40 @@ export interface WebSocketContext<P extends string = string, S = AppState> {
     /** Subprotocols offered by the client (parsed from `Sec-WebSocket-Protocol`). */
     protocols: string[];
 }
+/**
+ * Optional contract/documentation metadata for a WebSocket route, mirroring
+ * the HTTP route `meta` block. Consumed by the built-in AsyncAPI generator
+ * ({@link generateAsyncAPI}) to describe the channel, its operations, and the
+ * payloads exchanged over the socket. Purely descriptive — it never changes
+ * runtime behavior or the RFC 6455 handshake.
+ *
+ * @since 0.37.0
+ */
+export interface WebSocketMeta {
+    /** Short channel summary surfaced as the AsyncAPI channel/operation summary. */
+    summary?: string;
+    /** Longer CommonMark description for the channel. */
+    description?: string;
+    /** Tags applied to the generated AsyncAPI operations. */
+    tags?: string[];
+    /**
+     * Schema describing messages the **server sends to clients** (outbound).
+     * Surfaced as the payload of the AsyncAPI `send` operation. Falls back to no
+     * outbound message when omitted.
+     */
+    send?: StandardSchemaV1;
+    /**
+     * Schema describing messages the **server receives from clients** (inbound).
+     * Surfaced as the payload of the AsyncAPI `receive` operation. Defaults to
+     * {@link WebSocketHandler.request}'s `body` schema when omitted.
+     */
+    receive?: StandardSchemaV1;
+    /**
+     * Stable identifier base used to derive the AsyncAPI `operationId`s and
+     * channel name for this route. Defaults to a slug derived from the path.
+     */
+    operationId?: string;
+}
 /**
  * User-supplied WebSocket lifecycle callbacks.
  *
@@ -98,6 +132,13 @@ export interface WebSocketHandler<P extends string = string, S = AppState, TData
     request?: {
         body?: StandardSchemaV1;
     };
+    /**
+     * Optional contract/documentation metadata consumed by the built-in
+     * AsyncAPI generator ({@link generateAsyncAPI}). Purely descriptive.
+     *
+     * @since 0.37.0
+     */
+    meta?: WebSocketMeta;
     /** Close the connection when queued outbound bytes exceed backpressureLimit. Default: true. */
     closeOnBackpressureLimit?: boolean;
     /** Maximum queued outbound bytes before backpressure handling triggers. Default: 1 MiB. */
@@ -224,6 +265,17 @@ export declare class WebSocketRegistry {
     private entries;
     add(path: PathString, handler: WebSocketHandler<any, any, any>, createState?: WebSocketStateFactory, options?: NormalizedWebSocketOptions): void;
     find(pathname: string): RouteMatch<WebSocketRouteEntry> | undefined;
+    /**
+     * List every registered WebSocket route entry in registration order.
+     *
+     * Returns a shallow copy so callers (the AsyncAPI generator, introspection
+     * tooling) cannot mutate the registry's internal array. The entry objects
+     * themselves are shared by reference and must be treated as read-only.
+     *
+     * @returns A new array of the registered {@link WebSocketRouteEntry} values.
+     * @since 0.37.0
+     */
+    list(): WebSocketRouteEntry[];
     get size(): number;
     runtimeOptions(): NormalizedWebSocketOptions;
 }

package/dist/websocket.js CHANGED Viewed

@@ -227,6 +227,19 @@ export class WebSocketRegistry {
     find(pathname) {
         return this.router.find("GET", pathname);
     }
+    /**
+     * List every registered WebSocket route entry in registration order.
+     *
+     * Returns a shallow copy so callers (the AsyncAPI generator, introspection
+     * tooling) cannot mutate the registry's internal array. The entry objects
+     * themselves are shared by reference and must be treated as read-only.
+     *
+     * @returns A new array of the registered {@link WebSocketRouteEntry} values.
+     * @since 0.37.0
+     */
+    list() {
+        return [...this.entries];
+    }
     get size() {
         return this._size;
     }