@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/runtime/progress/format.js

@@ -0,0 +1,96 @@
+/** A progress snapshot as one logfmt line, one TSV row, or one JSON line. */
+import { progressFields } from "./fields.js";
+function logfmt(pairs) {
+    return Object.entries(pairs)
+        .map(([key, value]) => {
+        if (value !== "" && !/[\s="\\]/.test(value))
+            return `${key}=${value}`;
+        return `${key}=${JSON.stringify(value)}`;
+    })
+        .join(" ");
+}
+/** A column's dash, the "no value" of the text formats, as JSON's `null`. */
+function textOrNull(value) {
+    return value === "-" ? null : value;
+}
+function numberOrNull(value) {
+    return value === "-" ? null : Number(value);
+}
+export function formatProgressLine(snap, now = Date.now()) {
+    const f = progressFields(snap, now);
+    return logfmt({
+        ts: new Date(now).toISOString(),
+        status: f.status,
+        done: f.done,
+        total: f.total,
+        phase: f.phase,
+        entity: f.entity,
+        check: f.check,
+        msg: f.msg,
+        req: f.req,
+        find: f.find,
+        method: f.method,
+        path: f.path,
+        http: f.http,
+        req_id: f.req_id,
+        last_at: f.last_at,
+        last_ms: f.last_ms,
+        req_b: f.req_b,
+        res_b: f.res_b,
+        idle_ms: f.idle_ms,
+        elapsed_ms: f.elapsed_ms,
+    });
+}
+export function formatProgressTsv(snap, now = Date.now()) {
+    const f = progressFields(snap, now);
+    return [
+        now,
+        f.status,
+        f.done,
+        f.total,
+        f.phase,
+        f.entity,
+        f.check,
+        f.msg,
+        f.req,
+        f.find,
+        f.method,
+        f.path,
+        f.http,
+        f.req_id,
+        f.last_at,
+        f.last_ms,
+        f.req_b,
+        f.res_b,
+        f.idle_ms,
+        f.elapsed_ms,
+    ].join("\t");
+}
+export function formatProgressJsonl(snap, now = Date.now()) {
+    const f = progressFields(snap, now);
+    const inflight = snap.inflight !== undefined;
+    return JSON.stringify({
+        check: textOrNull(f.check),
+        done: snap.entityIndex ?? null,
+        elapsed_ms: Number(f.elapsed_ms),
+        entity: snap.entity ?? null,
+        find: snap.findings,
+        http: inflight ? null : (snap.last?.status ?? null),
+        idle_ms: numberOrNull(f.idle_ms),
+        last_at: textOrNull(f.last_at),
+        last_ms: numberOrNull(f.last_ms),
+        method: textOrNull(f.method),
+        req_id: f.req_id === "" ? null : textOrNull(f.req_id),
+        req_b: numberOrNull(f.req_b),
+        res_b: numberOrNull(f.res_b),
+        msg: textOrNull(f.msg),
+        path: textOrNull(f.path),
+        phase: snap.phase,
+        req: snap.requests,
+        status: f.status,
+        total: snap.entityTotal ?? null,
+        ts: new Date(now).toISOString(),
+        ts_ms: now,
+    });
+}
+//# sourceMappingURL=format.js.map

package/dist/api/runtime/progress/pump.d.ts

@@ -0,0 +1,16 @@
+/** When a progress snapshot is written: on change, on a forced phase, on a stall, and on a heartbeat. */
+import type { ProgressHandler, ProgressSnapshot } from "./types.ts";
+export declare const HEARTBEAT_MS = 5000;
+export interface ProgressPump {
+    emit: ProgressHandler;
+    stop: () => void;
+}
+export declare function progressEventKey(snap: ProgressSnapshot): string;
+/**
+ * Deduped writer plus a 5s heartbeat. The heartbeat re-formats `latest` at `now` so
+ * `idle_ms` climbs on the in-flight request (or on the last completed call after return).
+ */
+export declare function createProgressPump(startedAt: number, write: (snap: ProgressSnapshot, now: number) => void): ProgressPump;
+/** Progress lines for a terminal, glossary first, each handed to `write` with its newline. */
+export declare function createProgressPrinter(write: (text: string) => void, startedAt?: number): ProgressPump;
+//# sourceMappingURL=pump.d.ts.map

package/dist/api/runtime/progress/pump.js

@@ -0,0 +1,69 @@
+/** When a progress snapshot is written: on change, on a forced phase, on a stall, and on a heartbeat. */
+import { PROGRESS_GLOSSARY } from "./columns.js";
+import { STALL_MS } from "./fields.js";
+import { formatProgressLine } from "./format.js";
+export const HEARTBEAT_MS = 5_000;
+export function progressEventKey(snap) {
+    const inflight = snap.inflight === undefined ? "" : `${snap.inflight.method} ${snap.inflight.url} ${snap.inflight.at}`;
+    const finished = snap.last === undefined ? "" : String(snap.last.at);
+    return `${snap.phase}|${snap.entity ?? ""}|${snap.check ?? ""}|${snap.message ?? ""}|${inflight}|${finished}`;
+}
+/** A snapshot every reader wants as it happens: the run's start and end, a call going out, a seed. */
+function isForced(snap) {
+    return (snap.phase === "done" ||
+        snap.phase === "load" ||
+        snap.phase === "auth" ||
+        snap.inflight !== undefined ||
+        (snap.phase === "seed" && snap.check === undefined));
+}
+function isStalled(snap) {
+    return snap.inflight === undefined && snap.last !== undefined && Date.now() - snap.last.at >= STALL_MS;
+}
+/**
+ * Deduped writer plus a 5s heartbeat. The heartbeat re-formats `latest` at `now` so
+ * `idle_ms` climbs on the in-flight request (or on the last completed call after return).
+ */
+export function createProgressPump(startedAt, write) {
+    let latest;
+    let lastKey = "";
+    let lastWrite = 0;
+    const flush = (snap) => {
+        const now = Date.now();
+        write(snap, now);
+        lastWrite = now;
+    };
+    const timer = setInterval(() => {
+        if (latest === undefined)
+            return;
+        flush({ ...latest, elapsedMs: Date.now() - startedAt });
+    }, HEARTBEAT_MS);
+    timer.unref();
+    return {
+        emit(snap) {
+            latest = snap;
+            const key = progressEventKey(snap);
+            const keyChanged = key !== lastKey;
+            lastKey = key;
+            const stalled = isStalled(snap);
+            const force = isForced(snap);
+            const due = Date.now() - lastWrite >= 2_000;
+            if (force || keyChanged || stalled || due)
+                flush(snap);
+        },
+        stop() {
+            clearInterval(timer);
+        },
+    };
+}
+/** Progress lines for a terminal, glossary first, each handed to `write` with its newline. */
+export function createProgressPrinter(write, startedAt = Date.now()) {
+    let headed = false;
+    return createProgressPump(startedAt, (snap, now) => {
+        if (!headed) {
+            headed = true;
+            write(`${PROGRESS_GLOSSARY}\n`);
+        }
+        write(`${formatProgressLine(snap, now)}\n`);
+    });
+}
+//# sourceMappingURL=pump.js.map

package/dist/api/runtime/progress/types.d.ts

@@ -0,0 +1,39 @@
+/** Live run status: one snapshot per event, handed to whoever prints or records it. */
+export interface ProgressLast {
+    method: string;
+    url: string;
+    status: number;
+    durationMs: number;
+    requestBytes: number;
+    responseBytes: number;
+    /** Empty when the last call had no request-id / correlation-id header. */
+    requestId: string;
+    at: number;
+    /** Set when the last completed call never got an HTTP status. */
+    network?: string;
+}
+/** A request that has been dispatched and has not yet returned. */
+export interface ProgressInflight {
+    method: string;
+    url: string;
+    /** Wall clock when `fetch` was called, unix ms. */
+    at: number;
+    requestId?: string;
+    requestBytes?: number;
+}
+export interface ProgressSnapshot {
+    phase: "load" | "auth" | "seed" | "test" | "scenario" | "contract" | "teardown" | "done";
+    entity?: string;
+    entityIndex?: number;
+    entityTotal?: number;
+    check?: string;
+    requests: number;
+    findings: number;
+    last?: ProgressLast;
+    /** When set, formatters prefer this over `last` — the call is still on the wire. */
+    inflight?: ProgressInflight;
+    message?: string;
+    elapsedMs: number;
+}
+export type ProgressHandler = (snap: ProgressSnapshot) => void;
+//# sourceMappingURL=types.d.ts.map

package/dist/api/runtime/progress/types.js

@@ -0,0 +1,3 @@
+/** Live run status: one snapshot per event, handed to whoever prints or records it. */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/api/runtime/proven-id.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Ids teardown may delete.
+ *
+ * Teardown removes what was recorded, so recording is where an id the API tester merely sent — a value in a
+ * request body, a guess — would turn into a DELETE against a row somebody else owns. `ProvenId`
+ * is a string that came back from the backend: a response, a record it returned, a listing, an
+ * async receipt. The ledger, `onCreate` and `recordCreated` accept nothing else, and the
+ * constructors below are the only places allowed to make one (lint rule `testing/proven-id-origin`).
+ */
+declare const provenBrand: unique symbol;
+/** An id the backend gave back, never one the API tester only sent. */
+export type ProvenId = string & {
+    readonly [provenBrand]: true;
+};
+/** The created record's id as a response carried it, nested envelopes included. */
+export declare function answeredId(response: {
+    responseBody: unknown;
+}, keys: readonly string[]): ProvenId | undefined;
+/** The identity of a record the backend returned: a create's answer, a read, a listed row. */
+export declare function returnedId(record: Record<string, unknown>, identity: string): ProvenId | undefined;
+/**
+ * An id a create's answer carried, where `resolveCreatedId` looked for it. Only a declared or
+ * top-level one is trusted as it stands; any other is confirmed by a read before it is recorded.
+ */
+export declare function createdId(value: unknown): ProvenId | undefined;
+/** Ids a listing returned. */
+export declare function listedIds(ids: readonly string[]): ProvenId[];
+/** The job id an async start's receipt (its response, or the stream's id frame) names. */
+export declare function receiptId(receipt: unknown, idFrom: string): ProvenId | undefined;
+export {};
+//# sourceMappingURL=proven-id.d.ts.map

package/dist/api/runtime/proven-id.js

@@ -0,0 +1,38 @@
+/**
+ * Ids teardown may delete.
+ *
+ * Teardown removes what was recorded, so recording is where an id the API tester merely sent — a value in a
+ * request body, a guess — would turn into a DELETE against a row somebody else owns. `ProvenId`
+ * is a string that came back from the backend: a response, a record it returned, a listing, an
+ * async receipt. The ledger, `onCreate` and `recordCreated` accept nothing else, and the
+ * constructors below are the only places allowed to make one (lint rule `testing/proven-id-origin`).
+ */
+import { findCreatedId } from "./effects/ids.js";
+import { resolveAsyncId } from "./async.js";
+function scalar(value) {
+    return typeof value === "string" || typeof value === "number" ? String(value) : undefined;
+}
+/** The created record's id as a response carried it, nested envelopes included. */
+export function answeredId(response, keys) {
+    return scalar(findCreatedId(response.responseBody, keys));
+}
+/** The identity of a record the backend returned: a create's answer, a read, a listed row. */
+export function returnedId(record, identity) {
+    return scalar(record[identity]);
+}
+/**
+ * An id a create's answer carried, where `resolveCreatedId` looked for it. Only a declared or
+ * top-level one is trusted as it stands; any other is confirmed by a read before it is recorded.
+ */
+export function createdId(value) {
+    return scalar(value);
+}
+/** Ids a listing returned. */
+export function listedIds(ids) {
+    return ids.map((id) => id);
+}
+/** The job id an async start's receipt (its response, or the stream's id frame) names. */
+export function receiptId(receipt, idFrom) {
+    return scalar(resolveAsyncId(receipt, idFrom));
+}
+//# sourceMappingURL=proven-id.js.map

package/dist/api/runtime/query-capabilities.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Live resolution of the filter catalog: harvest `filterableFrom`, then the hook.
+ *
+ * Merge of tag + config is pure and lives in `spec/query-capabilities`. This file talks HTTP.
+ */
+import type { QueryCapabilitiesRequest } from "../config/types/hooks.ts";
+import type { QueryCapability } from "../spec/extensions/query-tag.ts";
+import type { SpecModel } from "../spec/graph/types.ts";
+import type { FilterableField, QueryCapabilities } from "../config/types/query.ts";
+import type { EffectiveQueryCapabilities } from "../spec/query/effective.ts";
+import type { Client } from "../client/client.ts";
+import type { JsonSchema } from "../spec/types.ts";
+export declare function resolveEntityCapabilities(input: {
+    tag: QueryCapability | null;
+    itemSchema?: JsonSchema | null;
+    global?: QueryCapabilities;
+    entity?: QueryCapabilities;
+    hook?: (request: QueryCapabilitiesRequest) => Promise<FilterableField[] | Partial<QueryCapabilities> | null>;
+    entityName: string;
+    scope: Record<string, string>;
+    model: SpecModel;
+    client: Client;
+    /** The principal it sends as: `as: { principal }`, the operation's security choosing the scheme. */
+    principal: string;
+}): Promise<EffectiveQueryCapabilities>;
+export declare function capabilitiesFromTag(tag: QueryCapability | null): EffectiveQueryCapabilities;
+//# sourceMappingURL=query-capabilities.d.ts.map

package/dist/api/runtime/query-capabilities.js

@@ -0,0 +1,69 @@
+/**
+ * Live resolution of the filter catalog: harvest `filterableFrom`, then the hook.
+ *
+ * Merge of tag + config is pure and lives in `spec/query-capabilities`. This file talks HTTP.
+ */
+import { parseRouteRef } from "../spec/routes.js";
+import { applyHarvest } from "../spec/query/harvest.js";
+import { applyHook } from "../spec/query/hook.js";
+import { readJsonPathList } from "../spec/query/json-path.js";
+import { emptyCapabilities, mergeQueryCapabilities } from "../spec/query/merge.js";
+import { fillPath } from "./fill-path.js";
+export async function resolveEntityCapabilities(input) {
+    let caps = mergeQueryCapabilities({
+        tag: input.tag,
+        ...(input.global === undefined ? {} : { global: input.global }),
+        ...(input.entity === undefined ? {} : { entity: input.entity }),
+        ...(input.itemSchema === undefined ? {} : { itemSchema: input.itemSchema }),
+    });
+    const get = async (operationId, scope = input.scope) => {
+        const op = resolveHarvestOp(input.model, operationId);
+        if (op === undefined) {
+            throw new Error(`testing api: harvest/get target "${operationId}" is not in the document`);
+        }
+        const exchange = await input.client.request(op.method, fillPath(op.path, scope), {
+            as: { principal: input.principal },
+            operationId: op.operationId,
+        });
+        return exchange.responseBody;
+    };
+    const harvest = async (from, axis) => {
+        const target = from.operationId ?? from.route;
+        if (target === undefined)
+            return;
+        const body = await get(target);
+        const names = readJsonPathList(body, from.path).filter((value) => typeof value === "string");
+        const types = from.typePath === undefined
+            ? []
+            : readJsonPathList(body, from.typePath).map((value) => (typeof value === "string" ? value : undefined));
+        caps = applyHarvest(caps, { axis, names, types });
+    };
+    if (caps.filterableFrom !== undefined)
+        await harvest(caps.filterableFrom, "filterable");
+    if (caps.sortableFrom !== undefined)
+        await harvest(caps.sortableFrom, "sortable");
+    if (caps.searchableFrom !== undefined)
+        await harvest(caps.searchableFrom, "searchable");
+    if (caps.selectableFrom !== undefined)
+        await harvest(caps.selectableFrom, "selectable");
+    if (input.hook !== undefined) {
+        const result = await input.hook({ entity: input.entityName, get, scope: input.scope });
+        caps = applyHook(caps, result);
+    }
+    return caps;
+}
+export function capabilitiesFromTag(tag) {
+    if (tag === null)
+        return emptyCapabilities();
+    return mergeQueryCapabilities({ tag });
+}
+function resolveHarvestOp(model, target) {
+    const byId = model.byOperationId.get(target);
+    if (byId !== undefined)
+        return byId;
+    const parsed = parseRouteRef(target.startsWith("/") ? `GET ${target}` : target);
+    if (parsed === null)
+        return undefined;
+    return model.byRoute.get(`${parsed.method} ${parsed.path}`);
+}
+//# sourceMappingURL=query-capabilities.js.map

package/dist/api/runtime/query.d.ts

@@ -0,0 +1,11 @@
+/** Query parameters as checks build them; an array value is sent as one parameter per item. */
+export type QueryParams = Record<string, string | readonly string[]>;
+/**
+ * Two sets of query parameters as one.
+ *
+ * A grammar that repeats its filter parameter for every term needs both terms sent, so `repeat`
+ * appends a key both sides carry. Otherwise the later value wins, which is what merging by
+ * object spread has always meant.
+ */
+export declare function mergeQuery(a: QueryParams, b: QueryParams, repeat: boolean): QueryParams;
+//# sourceMappingURL=query.d.ts.map

package/dist/api/runtime/query.js

@@ -0,0 +1,21 @@
+/**
+ * Two sets of query parameters as one.
+ *
+ * A grammar that repeats its filter parameter for every term needs both terms sent, so `repeat`
+ * appends a key both sides carry. Otherwise the later value wins, which is what merging by
+ * object spread has always meant.
+ */
+export function mergeQuery(a, b, repeat) {
+    if (!repeat)
+        return { ...a, ...b };
+    const merged = { ...a };
+    for (const [key, value] of Object.entries(b)) {
+        const before = merged[key];
+        merged[key] = before === undefined ? value : [...asList(before), ...asList(value)];
+    }
+    return merged;
+}
+function asList(value) {
+    return typeof value === "string" ? [value] : value;
+}
+//# sourceMappingURL=query.js.map

package/dist/api/runtime/rate-limit/bucket.d.ts

@@ -0,0 +1,21 @@
+/**
+ * A token bucket with a queue: concurrent requests against the same category are admitted one at
+ * a time, each computing its wait from the bucket's current state rather than racing on it.
+ * Burst capacity equals `rps` — up to one second's worth of headroom, the conventional default.
+ */
+export declare class RateBucket {
+    private readonly rps;
+    private tokens;
+    private last;
+    private cooldownUntil;
+    private queue;
+    constructor(rps: number);
+    /**
+     * A 429 said this budget is exhausted. Hold the next acquire for `waitMs`, then admit exactly
+     * one request — a full burst refill would immediately re-trip the limit we just hit.
+     */
+    penalize(waitMs: number): void;
+    /** Resolves once a token is consumed. Returns `false` when the caller had to wait for it. */
+    acquire(): Promise<boolean>;
+}
+//# sourceMappingURL=bucket.d.ts.map

package/dist/api/runtime/rate-limit/bucket.js

@@ -0,0 +1,54 @@
+/**
+ * A token bucket with a queue: concurrent requests against the same category are admitted one at
+ * a time, each computing its wait from the bucket's current state rather than racing on it.
+ * Burst capacity equals `rps` — up to one second's worth of headroom, the conventional default.
+ */
+export class RateBucket {
+    rps;
+    tokens;
+    last = performance.now();
+    cooldownUntil = 0;
+    queue = Promise.resolve();
+    constructor(rps) {
+        this.rps = rps;
+        this.tokens = rps;
+    }
+    /**
+     * A 429 said this budget is exhausted. Hold the next acquire for `waitMs`, then admit exactly
+     * one request — a full burst refill would immediately re-trip the limit we just hit.
+     */
+    penalize(waitMs) {
+        const until = performance.now() + Math.max(0, waitMs);
+        this.cooldownUntil = Math.max(this.cooldownUntil, until);
+        this.tokens = 1;
+        this.last = this.cooldownUntil;
+    }
+    /** Resolves once a token is consumed. Returns `false` when the caller had to wait for it. */
+    async acquire() {
+        let hadRoom = false;
+        const previous = this.queue;
+        this.queue = previous.then(async () => {
+            const now = performance.now();
+            if (now < this.cooldownUntil) {
+                await new Promise((resolve) => setTimeout(resolve, this.cooldownUntil - now));
+            }
+            const after = performance.now();
+            this.tokens = Math.min(this.rps, this.tokens + ((after - this.last) / 1000) * this.rps);
+            this.last = after;
+            if (this.tokens >= 1) {
+                /* A cooldown wait is not room — the API tester did not believe it was under its own pace. */
+                hadRoom = now >= this.cooldownUntil;
+                this.tokens -= 1;
+                return;
+            }
+            const waitMs = ((1 - this.tokens) / this.rps) * 1000;
+            await new Promise((resolve) => setTimeout(resolve, waitMs));
+            this.tokens = 0;
+            this.last = performance.now();
+            hadRoom = false;
+        });
+        await this.queue;
+        return hadRoom;
+    }
+}
+//# sourceMappingURL=bucket.js.map

package/dist/api/runtime/rate-limit/limiter.d.ts

@@ -0,0 +1,52 @@
+/** Resolves a request's category from the compiled rulebook and paces it through a shared bucket. */
+import type { CompiledRateLimitRule } from "./rules.ts";
+/** Writes that never declared `x-rate-limit` still share a real backend budget (JWT writes, etc.). */
+export declare const UNTAGGED_WRITE_CATEGORY = "untagged-write";
+export declare const UNTAGGED_CATEGORY = "untagged";
+/**
+ * The longest a 429's cooldown spreads the writes it held past its end. Released at one instant, they
+ * would land together and trip the limit again, in lockstep; each leaves at a random point instead,
+ * over the cooldown's own length or this, whichever is shorter.
+ */
+export declare const IMPLICIT_RELEASE_SPREAD_MS = 10000;
+/** The request a rate applies to: its method, its path below the base URL, and its operation. */
+export interface RateRoute {
+    method: string;
+    pathname: string;
+    operationId?: string | undefined;
+}
+export declare class RateLimiter {
+    private readonly rules;
+    private readonly buckets;
+    /** Cooldown-only: after an untagged 429, later untagged writes wait this out, then run free. */
+    private readonly implicitUntil;
+    /** Every request to the origin, whatever its route: the limit an edge in front of it holds. */
+    private readonly ceiling;
+    /** Where in its spread each held write leaves, from 0 to 1. */
+    private readonly random;
+    constructor(rules: readonly CompiledRateLimitRule[], options?: {
+        maxRps?: number;
+        random?: () => number;
+    });
+    /** Waits for room under the origin-wide ceiling, when one is set. */
+    acquireCeiling(): Promise<void>;
+    resolve(method: string, pathname: string, operationId?: string): CompiledRateLimitRule | undefined;
+    /**
+     * After a 429 on an untagged route, later untagged writes share this cooldown so they do not
+     * immediately re-trip. No ongoing rps — we do not know the undocumented rate.
+     */
+    implicitRule(method: string): CompiledRateLimitRule | undefined;
+    /**
+     * Feed a 429 wait into the matching bucket, or open the implicit untagged cooldown when the
+     * operation never declared a rate. Tags stay the proactive path; this is the reactive one.
+     */
+    noteBackoff(route: RateRoute, waitMs: number): CompiledRateLimitRule;
+    /**
+     * Wait out an implicit 429 cooldown, and then a random part of its spread. Returns `false` when the
+     * caller had to wait.
+     */
+    waitImplicit(method: string): Promise<boolean>;
+    acquire(rule: CompiledRateLimitRule): Promise<boolean>;
+    private bucketFor;
+}
+//# sourceMappingURL=limiter.d.ts.map

package/dist/api/runtime/rate-limit/limiter.js

@@ -0,0 +1,103 @@
+/** Resolves a request's category from the compiled rulebook and paces it through a shared bucket. */
+import { MUTATING } from "../../spec/methods.js";
+import { RateBucket } from "./bucket.js";
+/** Writes that never declared `x-rate-limit` still share a real backend budget (JWT writes, etc.). */
+export const UNTAGGED_WRITE_CATEGORY = "untagged-write";
+export const UNTAGGED_CATEGORY = "untagged";
+/**
+ * The longest a 429's cooldown spreads the writes it held past its end. Released at one instant, they
+ * would land together and trip the limit again, in lockstep; each leaves at a random point instead,
+ * over the cooldown's own length or this, whichever is shorter.
+ */
+export const IMPLICIT_RELEASE_SPREAD_MS = 10_000;
+function implicitCategory(method) {
+    return MUTATING.has(method.toUpperCase()) ? UNTAGGED_WRITE_CATEGORY : UNTAGGED_CATEGORY;
+}
+/** The reactive rule for an untagged category: no rate of its own, only the cooldown a 429 opened. */
+function implicitRuleFor(category) {
+    return {
+        category,
+        rps: 0,
+        source: "implicit",
+        test: (m) => implicitCategory(m) === category,
+    };
+}
+export class RateLimiter {
+    rules;
+    buckets = new Map();
+    /** Cooldown-only: after an untagged 429, later untagged writes wait this out, then run free. */
+    implicitUntil = new Map();
+    /** Every request to the origin, whatever its route: the limit an edge in front of it holds. */
+    ceiling;
+    /** Where in its spread each held write leaves, from 0 to 1. */
+    random;
+    constructor(rules, options = {}) {
+        this.rules = rules;
+        this.ceiling = options.maxRps === undefined ? undefined : new RateBucket(options.maxRps);
+        this.random = options.random ?? Math.random;
+    }
+    /** Waits for room under the origin-wide ceiling, when one is set. */
+    async acquireCeiling() {
+        await this.ceiling?.acquire();
+    }
+    resolve(method, pathname, operationId) {
+        return this.rules.find((rule) => rule.test(method, pathname, operationId));
+    }
+    /**
+     * After a 429 on an untagged route, later untagged writes share this cooldown so they do not
+     * immediately re-trip. No ongoing rps — we do not know the undocumented rate.
+     */
+    implicitRule(method) {
+        const category = implicitCategory(method);
+        if (!this.implicitUntil.has(category))
+            return undefined;
+        return implicitRuleFor(category);
+    }
+    /**
+     * Feed a 429 wait into the matching bucket, or open the implicit untagged cooldown when the
+     * operation never declared a rate. Tags stay the proactive path; this is the reactive one.
+     */
+    noteBackoff(route, waitMs) {
+        const { method, pathname, operationId } = route;
+        const tagged = this.resolve(method, pathname, operationId);
+        if (tagged !== undefined) {
+            this.bucketFor(tagged).penalize(waitMs);
+            return tagged;
+        }
+        const category = implicitCategory(method);
+        const now = performance.now();
+        const until = now + Math.max(0, waitMs);
+        const open = this.implicitUntil.get(category);
+        /* A 429 inside an open cooldown extends it from when it opened; one after it lapsed opens anew. */
+        this.implicitUntil.set(category, open !== undefined && now < open.until
+            ? { openedAt: open.openedAt, until: Math.max(open.until, until) }
+            : { openedAt: now, until });
+        return implicitRuleFor(category);
+    }
+    /**
+     * Wait out an implicit 429 cooldown, and then a random part of its spread. Returns `false` when the
+     * caller had to wait.
+     */
+    async waitImplicit(method) {
+        const cooldown = this.implicitUntil.get(implicitCategory(method));
+        const now = performance.now();
+        if (cooldown === undefined || now >= cooldown.until)
+            return true;
+        const spread = Math.min(cooldown.until - cooldown.openedAt, IMPLICIT_RELEASE_SPREAD_MS);
+        const leaves = cooldown.until + this.random() * spread;
+        await new Promise((resolve) => setTimeout(resolve, leaves - now));
+        return false;
+    }
+    async acquire(rule) {
+        return this.bucketFor(rule).acquire();
+    }
+    bucketFor(rule) {
+        let bucket = this.buckets.get(rule.category);
+        if (bucket === undefined) {
+            bucket = new RateBucket(rule.rps);
+            this.buckets.set(rule.category, bucket);
+        }
+        return bucket;
+    }
+}
+//# sourceMappingURL=limiter.js.map