@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/client/redirect.d.ts

@@ -0,0 +1,37 @@
+/** One attempt on the wire, following redirects itself when asked so every hop's cookies are kept. */
+import { CookieJar } from "../runtime/cookies/jar.ts";
+import { type RedirectHop } from "../runtime/cookies/redirect.ts";
+import type { ResponsePayload } from "../runtime/transcript/types.ts";
+import { stripCredentials } from "../security/strip.ts";
+import type { FenceAsk } from "./fence.ts";
+export interface FirstHop {
+    url: URL;
+    method: string;
+    body: RequestInit["body"];
+    /** Sent on every hop, and changed in place as hops strip and add to it. */
+    headers: Record<string, string>;
+    /** `manual` when the caller or the operation handles redirects itself. */
+    redirect: "manual" | undefined;
+}
+export interface Following {
+    /** Follow redirects here, through a cookie jar. Otherwise the first answer stands. */
+    follow: boolean;
+    send: (url: URL, init: RequestInit) => Promise<Response>;
+    fence: FenceAsk;
+    /** The caller's own Cookie header, kept on same-origin hops alongside the jar's. */
+    callerCookie: string | undefined;
+    /** Headers that carry a credential: stripped before a hop to another origin. */
+    credentialNames: Parameters<typeof stripCredentials>[1];
+    /** Query parameters the request placed a credential in: stripped from a hop to another origin. */
+    credentialQuery: ReadonlySet<string>;
+    /** What the caller asked to send, for the fence; a hop that drops the body sends none. */
+    body: unknown;
+}
+export interface Landed extends ResponsePayload {
+    response: Response;
+    hops: RedirectHop[];
+    landing: URL;
+    jar: CookieJar;
+}
+export declare function sendFollowing(first: FirstHop, how: Following): Promise<Landed>;
+//# sourceMappingURL=redirect.d.ts.map

package/dist/api/client/redirect.js

@@ -0,0 +1,64 @@
+/** One attempt on the wire, following redirects itself when asked so every hop's cookies are kept. */
+import { applyJarToHeaders, CookieJar } from "../runtime/cookies/jar.js";
+import { isRedirectStatus, MAX_REDIRECTS, redirectTarget } from "../runtime/cookies/redirect.js";
+import { omitHeader, recordResponseHeaders, setCookieHeadersFrom } from "../runtime/cookies/set-cookie.js";
+import { readResponsePayload } from "../runtime/transcript/payload.js";
+import { stripCredentials, stripQuery } from "../security/strip.js";
+export async function sendFollowing(first, how) {
+    const jar = new CookieJar();
+    const hops = [];
+    let current = { body: first.body, method: first.method, url: first.url };
+    applyJarToHeaders(first.headers, { callerCookie: how.callerCookie, jar, url: first.url });
+    const init = { headers: first.headers, method: first.method };
+    if (first.body !== undefined)
+        init.body = first.body;
+    if (first.redirect !== undefined)
+        init.redirect = first.redirect;
+    let answer = await sendHop(jar, { init, url: current.url }, how);
+    while (how.follow && isRedirectStatus(answer.response.status) && hops.length < MAX_REDIRECTS) {
+        const { response } = answer;
+        const next = redirectTarget({ location: response.headers.get("location"), status: response.status }, { method: current.method, url: current.url });
+        if (next === null)
+            break;
+        hops.push({
+            responseHeaders: recordResponseHeaders(response.headers),
+            status: response.status,
+            url: `${current.url}`,
+        });
+        current = { body: next.dropBody ? undefined : current.body, method: next.method, url: next.url };
+        const crossOrigin = next.url.origin !== first.url.origin;
+        prepareHop(first.headers, { crossOrigin, dropBody: next.dropBody, jar, url: current.url }, how);
+        await how.fence(current.url, current.method.toUpperCase(), next.dropBody ? undefined : how.body);
+        answer = await sendHop(jar, { init: hopInit(first.headers, current), url: current.url }, how);
+    }
+    return { ...answer, hops, jar, landing: current.url };
+}
+/* Another origin — scheme, host or port — gets no credential of ours, and only the jar's cookies. */
+function prepareHop(headers, hop, how) {
+    if (hop.crossOrigin) {
+        stripCredentials(headers, how.credentialNames);
+        stripQuery(hop.url, how.credentialQuery);
+    }
+    if (hop.dropBody) {
+        omitHeader(headers, "content-type");
+        omitHeader(headers, "content-length");
+    }
+    applyJarToHeaders(headers, {
+        callerCookie: hop.crossOrigin ? undefined : how.callerCookie,
+        jar: hop.jar,
+        url: hop.url,
+    });
+}
+function hopInit(headers, hop) {
+    const init = { headers, method: hop.method, redirect: "manual" };
+    if (hop.body !== undefined)
+        init.body = hop.body;
+    return init;
+}
+async function sendHop(jar, { init, url }, how) {
+    const response = await how.send(url, init);
+    const payload = await readResponsePayload(response);
+    jar.absorb(url, setCookieHeadersFrom(response.headers));
+    return { ...payload, response };
+}
+//# sourceMappingURL=redirect.js.map

package/dist/api/client/refresh.d.ts

@@ -0,0 +1,17 @@
+/** A 401 on a request that carried a principal's credential: renew it once, and ask once more. */
+import type { Exchange } from "../runtime/exchange.ts";
+/** What a request does once more after a 401. */
+export interface Reauthorize {
+    /** Renews the credential the refused attempt carried; false when this request may not renew. */
+    renew: () => Promise<boolean>;
+    supersede: (exchange: Exchange) => void;
+    send: () => Promise<Exchange>;
+    /**
+     * A 401 not renewed, or a renewal refused too: the control decides whether the principal or the
+     * route refused it. True when it judged the value lapsed and renewed it, so the request goes once more.
+     */
+    refused: (exchange: Exchange) => Promise<boolean>;
+}
+/** `exchange`, or, when it is a 401 the request may renew its credential for, the answer after the renewal. */
+export declare function afterUnauthorized(exchange: Exchange, again: Reauthorize): Promise<Exchange>;
+//# sourceMappingURL=refresh.d.ts.map

package/dist/api/client/refresh.js

@@ -0,0 +1,14 @@
+/** A 401 on a request that carried a principal's credential: renew it once, and ask once more. */
+/** `exchange`, or, when it is a 401 the request may renew its credential for, the answer after the renewal. */
+export async function afterUnauthorized(exchange, again) {
+    if (exchange.status !== 401)
+        return exchange;
+    if (!(await again.renew()) && !(await again.refused(exchange)))
+        return exchange;
+    again.supersede(exchange);
+    const resent = await again.send();
+    if (resent.status === 401)
+        await again.refused(resent);
+    return resent;
+}
+//# sourceMappingURL=refresh.js.map

package/dist/api/client/request.d.ts

@@ -0,0 +1,20 @@
+/** One request, prepared once and sent per attempt: headers, fence, pacing and the wire. */
+import type { Exchange } from "../runtime/exchange.ts";
+import type { Prepared, Wire } from "./attempt.ts";
+import type { RequestOptions } from "./types.ts";
+/**
+ * A request as the wire it is sent on will send it: its URL, operation, headers and credential. An
+ * absolute URL on the client's own origin is resolved like a path; one on another origin matches no
+ * operation, and a URL followed from a response carries no credential there.
+ */
+export declare function prepare(ctx: Wire, method: string, path: string, options: RequestOptions): Prepared;
+/**
+ * One attempt. Its credential is resolved first, so a request whose security cannot be met sends
+ * nothing, and the fence sees the placed headers before any wait. When the slot and rate waits
+ * outlast the credential (a renewal elsewhere replaced it, or it went stale), the attempt gives its
+ * slot back and runs once more from the credential: a renewal sends through these same slots, so it
+ * never runs while the attempt holds one. A network failure is recorded as an exchange with status
+ * 0 and raised as a `NetworkError`.
+ */
+export declare function sendAttempt(request: Prepared, attempt: number, wire: Wire): Promise<Exchange>;
+//# sourceMappingURL=request.d.ts.map

package/dist/api/client/request.js

@@ -0,0 +1,182 @@
+/** One request, prepared once and sent per attempt: headers, fence, pacing and the wire. */
+import { MissingValueError } from "../errors/missing-value.js";
+import { headerValue } from "../runtime/headers.js";
+import { credentialHeaderNames } from "../security/strip.js";
+import { answered, failed } from "./answer.js";
+import { bypassLayer } from "./bypass.js";
+import { withDeclared } from "./declared.js";
+import { fenceAsker } from "./fence.js";
+import { requestIdOf, requestMessageBytes } from "./message.js";
+import { placedNames, placeOn, requestCredential } from "./placing.js";
+import { sendFollowing } from "./redirect.js";
+import { addRequiredQuery, carriesMissingValue, encodeBody, requestUrl } from "./serialize.js";
+/**
+ * A request as the wire it is sent on will send it: its URL, operation, headers and credential. An
+ * absolute URL on the client's own origin is resolved like a path; one on another origin matches no
+ * operation, and a URL followed from a response carries no credential there.
+ */
+export function prepare(ctx, method, path, options) {
+    const verb = method.toUpperCase();
+    const at = requestUrl(ctx.baseUrl, path);
+    const foreign = at.origin !== new URL(ctx.baseUrl).origin;
+    const resolved = foreign ? null : (ctx.operationResolver?.(verb, ctx.relativePath(at)) ?? null);
+    /* The query is written once the operation is known: its styles say how. */
+    const styles = resolved?.paramStyles?.query;
+    const writing = { query: options.query, styles };
+    const url = requestUrl(ctx.baseUrl, path, writing);
+    const callerQuery = new Set(url.searchParams.keys());
+    addRequiredQuery(url, resolved?.requiredQuery ?? {}, writing);
+    const relative = ctx.relativePath(url);
+    /* A value the API tester did not have, written as text: nothing goes out. */
+    if (carriesMissingValue(url))
+        throw new MissingValueError(`${verb} ${relative}`);
+    const operationId = options.operationId ?? resolved?.operationId;
+    const actor = foreign && "via" in options.as ? { anonymous: true } : options.as;
+    /* Never the query: a presigned URL's signature is a secret no message repeats. */
+    const route = `${verb} ${foreign ? `${url.origin}${url.pathname}` : relative}`;
+    return {
+        callerHeaders: () => {
+            const raw = options.headers;
+            return { ...(typeof raw === "function" ? raw() : raw) };
+        },
+        callerQuery,
+        credential: requestCredential(ctx, { actor, control: options.control, operationId, probe: options.probe, route }),
+        method: verb,
+        operationId,
+        options,
+        relative,
+        resolved,
+        url,
+    };
+}
+/**
+ * One attempt. Its credential is resolved first, so a request whose security cannot be met sends
+ * nothing, and the fence sees the placed headers before any wait. When the slot and rate waits
+ * outlast the credential (a renewal elsewhere replaced it, or it went stale), the attempt gives its
+ * slot back and runs once more from the credential: a renewal sends through these same slots, so it
+ * never runs while the attempt holds one. A network failure is recorded as an exchange with status
+ * 0 and raised as a `NetworkError`.
+ */
+export async function sendAttempt(request, attempt, wire) {
+    const pacing = pacingOf(request, wire.rateLimiter);
+    for (let round = 1;; round += 1) {
+        const going = await placedAttempt(request, attempt, wire);
+        await wire.slots.acquire();
+        let landed;
+        try {
+            const room = await paced(pacing, request.method, wire.rateLimiter);
+            if (round === 1 && request.credential.lapsed())
+                continue;
+            landed = await onTheWire(going.sent, { ...going, room }, wire);
+        }
+        finally {
+            wire.slots.release();
+        }
+        return answered(landed, { ...going.sent, pacing }, wire);
+    }
+}
+/* The attempt with its credential placed and its first hop fenced: what goes on the wire once the waits are over. */
+async function placedAttempt(request, attempt, wire) {
+    const { options } = request;
+    const placement = await request.credential.next();
+    const { headers, url } = placeOn(placement, await unplaced(request, { placement, wire }));
+    const body = encodeBody(options.body, options.contentType);
+    if (body.contentType !== undefined)
+        headers["content-type"] = body.contentType;
+    /* The headers each hop sends: redirects strip and add to them, and the fence sees them as they are. */
+    const hopHeaders = { ...headers };
+    const fenced = { headers: hopHeaders, operationId: request.operationId, placement, purpose: options.context?.purpose };
+    const fence = fenceAsker(wire.fence, fenced);
+    await fence(url, request.method, options.body);
+    return { fence, hopHeaders, sent: { attempt, body, headers, placement, request, url } };
+}
+/**
+ * The attempt before its credential: the operation's declared header and cookie values, the cache
+ * bypass, then globals, then `resolveHeaders`, then the caller's headers.
+ */
+async function unplaced(request, { placement, wire }) {
+    const { options } = request;
+    const hooked = await wire.resolveHeaders?.({
+        method: request.method,
+        url: request.url.toString(),
+        ...(options.operationId === undefined ? {} : { operationId: options.operationId }),
+    });
+    const above = [wire.headers, hooked ?? {}, request.callerHeaders()];
+    const bypass = bypassLayer({ cache: options.cache, enabled: wire.cacheBypass, method: request.method, resolved: request.resolved }, above);
+    const layers = withDeclared(request.resolved, placement, [bypass, ...above]);
+    return { callerQuery: request.callerQuery, layers, url: request.url };
+}
+/* Rules are written against documented paths, which never include the base path. */
+function pacingOf(request, limiter) {
+    const tagged = limiter?.resolve(request.method, request.relative, request.operationId);
+    if (tagged !== undefined)
+        return { rule: tagged, tagged: true };
+    const implicit = limiter?.implicitRule(request.method);
+    return implicit === undefined ? undefined : { rule: implicit, tagged: false };
+}
+/*
+ * Two independent constraints, both held: maxInFlight bounds in-flight HTTP with no notion of
+ * time, a rate-limit category bounds throughput over time. Pacing sits entirely inside the
+ * in-flight slot and never changes what maxInFlight itself guarantees. The origin's ceiling holds
+ * alongside the route's own budget; neither replaces the other.
+ */
+async function paced(pacing, method, limiter) {
+    if (limiter === undefined)
+        return undefined;
+    await limiter.acquireCeiling();
+    if (pacing === undefined)
+        return undefined;
+    return pacing.tagged ? limiter.acquire(pacing.rule) : limiter.waitImplicit(method);
+}
+/** Sends the attempt and every redirect it follows, inside the hooks that watch the wire. */
+async function onTheWire(sent, going, wire) {
+    const { request, headers, body, url } = sent;
+    const { options } = request;
+    const probe = probeOf(sent);
+    const placed = placedNames(sent.placement);
+    wire.httpHooks?.start?.(probe);
+    const started = performance.now();
+    try {
+        const manual = options.redirect !== undefined || request.resolved?.redirects === true;
+        const following = await sendFollowing({
+            body: body.init,
+            headers: going.hopHeaders,
+            method: request.method,
+            redirect: manual ? "manual" : undefined,
+            url,
+        }, {
+            body: options.body,
+            callerCookie: headerValue(headers, "cookie"),
+            /* Every header that carries a credential: the known names, and whatever this request
+             * placed its credential under, an API key under a custom name included. */
+            credentialNames: credentialHeaderNames(placed.headers),
+            credentialQuery: placed.query,
+            fence: going.fence,
+            follow: options.redirect === "follow",
+            send: transport(wire.network),
+        });
+        return { ...following, at: Date.now(), room: going.room, started };
+    }
+    catch (error) {
+        throw await failed(error, { ...sent, probe, started }, wire);
+    }
+    finally {
+        wire.httpHooks?.end?.(probe);
+    }
+}
+function probeOf({ request, headers, body, url }) {
+    return {
+        at: Date.now(),
+        method: request.method,
+        requestBytes: requestMessageBytes({ method: request.method, url }, headers, body),
+        requestId: requestIdOf(headers, {}),
+        url: url.toString(),
+    };
+}
+function transport(network) {
+    const timeoutMs = network?.requestTimeoutMs;
+    const signal = timeoutMs === undefined ? undefined : AbortSignal.timeout(timeoutMs);
+    const send = network?.fetchImpl ?? fetch;
+    return (url, init) => send(url, signal === undefined ? init : { ...init, signal });
+}
+//# sourceMappingURL=request.js.map

package/dist/api/client/retry.d.ts

@@ -0,0 +1,29 @@
+/** When a request is asked again: after a network failure, a 429, a 503 that names a wait, or a gateway's 5xx. */
+import type { Exchange } from "../runtime/exchange.ts";
+import type { NetworkClientOptions } from "./types.ts";
+/** How long one request may take across every attempt and wait, unless configured. */
+export declare const DEFAULT_DEADLINE_MS: number;
+/** One request's network policy: how it may be resent, and until when. */
+export interface Resending {
+    method: string;
+    /** The caller's headers: an idempotency key among them makes a write repeatable. */
+    headers: () => Record<string, string>;
+    network: NetworkClientOptions | undefined;
+    /** `performance.now()` past which nothing is resent. */
+    deadline: number;
+}
+/** `dispatch`, resent after a network failure while the policy allows, then once more if the link recovers. */
+export declare function resilient(dispatch: (attempt: number) => Promise<Exchange>, policy: Resending): Promise<Exchange>;
+/** How a status retry asks again. */
+export interface StatusRetry {
+    method: string;
+    /** Supersedes `previous` and sends the request again. */
+    again: (previous: Exchange) => Promise<Exchange>;
+    /** `exchange`, or the answer after a refresh when it is a 401. */
+    reauthorized: (exchange: Exchange) => Promise<Exchange>;
+    /** Tells the rate limiter the server asked for `waitMs`. */
+    backedOff: (waitMs: number) => void;
+}
+/** The backend's final answer, after the waits it asked for and one more try past a gateway's 5xx. */
+export declare function untilAnswered(first: Exchange, retry: StatusRetry): Promise<Exchange>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/api/client/retry.js

@@ -0,0 +1,100 @@
+/** When a request is asked again: after a network failure, a 429, a 503 that names a wait, or a gateway's 5xx. */
+import { DEFAULT_NETWORK_RETRIES, networkRetryWaitMs } from "../runtime/network/policy.js";
+import { isNetworkError } from "../errors/network.js";
+import { sleep } from "../runtime/poll.js";
+import { GATEWAY_RETRY_MS, MAX_429_RETRIES, MAX_UNAVAILABLE_RETRIES, parseRetryAfter, retryWaitMs, } from "../runtime/rate-limit/retry-after.js";
+import { headerValue } from "../runtime/headers.js";
+import { BODILESS_READS, IDEMPOTENT } from "../spec/methods.js";
+/** How long one request may take across every attempt and wait, unless configured. */
+export const DEFAULT_DEADLINE_MS = 10 * 60_000;
+/** Failures that prove the request never reached the server. */
+const NEVER_SENT = /* @__PURE__ */ new Set(["offline", "dns", "refused", "unreachable"]);
+/* Statuses a gateway answers on its own; a read that met one is asked once more. */
+const GATEWAY_STATUSES = /* @__PURE__ */ new Set([502, 503, 504]);
+/*
+ * A failed request may be sent again only when doing so cannot do something twice: it never left
+ * this machine, or the method is idempotent, or it carries an idempotency key. A POST that timed
+ * out may well have created its record — resending it creates a second one, and the API tester would then
+ * report the duplicate as the backend's.
+ */
+function repeatable(error, policy) {
+    return (NEVER_SENT.has(error.kind) ||
+        IDEMPOTENT.has(policy.method) ||
+        Object.keys(policy.headers()).some((name) => /idempotency[-_]?key/i.test(name)));
+}
+/** `dispatch`, resent after a network failure while the policy allows, then once more if the link recovers. */
+export async function resilient(dispatch, policy) {
+    const { network } = policy;
+    const retries = network === undefined ? 0 : Math.max(0, network.retries ?? DEFAULT_NETWORK_RETRIES);
+    let last;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+        try {
+            return await dispatch(attempt);
+        }
+        catch (error) {
+            if (!isNetworkError(error) || !repeatable(error, policy))
+                throw error;
+            last = error;
+            const wait = networkRetryWaitMs(attempt);
+            if (performance.now() + wait > policy.deadline)
+                throw error;
+            if (attempt < retries)
+                await sleep(wait);
+        }
+    }
+    /* The last attempt reached here only with time left past its wait: the deadline still holds. */
+    const failed = last;
+    if ((await network?.awaitRecovery?.(failed)) === true)
+        return dispatch(retries + 1);
+    throw failed;
+}
+/** The backend's final answer, after the waits it asked for and one more try past a gateway's 5xx. */
+export async function untilAnswered(first, retry) {
+    return afterGateway(await afterWaits(first, retry), retry);
+}
+/*
+ * The waits the backend asks for, in whatever order it asks: a backend may shed load with a 503 and
+ * then rate-limit the retry with a 429, and each answer is followed as it comes. Each status keeps its
+ * own retries across the alternation, so the two together still end; a wait past the limit stands.
+ *
+ * 429 is reactive: the first one is never a seed/check failure. Tags pace proactively; this path
+ * honors the server even when the op has no x-rate-limit at all, and a wait past the limit never
+ * reaches the limiter, where it would hold back every request that shares the route's bucket.
+ * A 503 that names when to come back is a cue a well-behaved client follows; one that names no wait
+ * stands as the verdict.
+ */
+async function afterWaits(first, retry) {
+    let exchange = first;
+    let limited = 0;
+    let unavailable = 0;
+    while (exchange.retryAfterExceeded === undefined) {
+        const header = headerValue(exchange.responseHeaders, "retry-after");
+        if (exchange.status === 429 && limited < MAX_429_RETRIES) {
+            const waitMs = retryWaitMs(header, limited++);
+            retry.backedOff(waitMs);
+            if (waitMs > 0)
+                await sleep(waitMs);
+            exchange = await retry.reauthorized(await retry.again(exchange));
+            continue;
+        }
+        const waitMs = exchange.status === 503 ? parseRetryAfter(header) : null;
+        if (waitMs === null || unavailable >= MAX_UNAVAILABLE_RETRIES)
+            break;
+        unavailable++;
+        await sleep(waitMs);
+        exchange = await retry.again(exchange);
+    }
+    return exchange;
+}
+/* A gateway in front of the API answers 502, 503 or 504 now and then without the request reaching
+ * it. A read with no body is safe to ask again: once, after a pause. A status that persists stands,
+ * and a write is never repeated, and so does a 503 whose named wait is past the limit. */
+async function afterGateway(exchange, retry) {
+    if (!GATEWAY_STATUSES.has(exchange.status) || !BODILESS_READS.has(retry.method))
+        return exchange;
+    if (exchange.retryAfterExceeded !== undefined)
+        return exchange;
+    await sleep(GATEWAY_RETRY_MS);
+    return retry.again(exchange);
+}
+//# sourceMappingURL=retry.js.map

package/dist/api/client/serialize.d.ts

@@ -0,0 +1,27 @@
+/** A request as it goes on the wire: its URL with the query, and its body encoded for `fetch`. */
+import type { ParamStyle } from "../spec/graph/parameters.ts";
+import type { RequestOptions } from "./types.ts";
+type FetchBody = NonNullable<RequestInit["body"]>;
+export interface EncodedBody {
+    init?: FetchBody;
+    /** Set this header. `undefined` means do not touch Content-Type. */
+    contentType?: string;
+    text?: string;
+    bytes: number;
+}
+/** A request's query: the caller's values, and each parameter's declared style by name. */
+export interface QueryWriting {
+    query?: RequestOptions["query"];
+    styles?: Readonly<Record<string, ParamStyle>> | undefined;
+}
+/**
+ * `path` under `baseUrl` (or as given when absolute), with the caller's query written in each
+ * parameter's declared style. A value the caller sets replaces one the path already carries.
+ */
+export declare function requestUrl(baseUrl: string, path: string, { query, styles }?: QueryWriting): URL;
+/** The operation's required parameters the caller did not set. One the caller names — even as undefined — is theirs. */
+export declare function addRequiredQuery(url: URL, required: Readonly<Record<string, unknown>>, { query, styles }?: QueryWriting): void;
+export declare function carriesMissingValue(url: URL): boolean;
+export declare function encodeBody(body: unknown, contentType: string | null | undefined): EncodedBody;
+export {};
+//# sourceMappingURL=serialize.d.ts.map

package/dist/api/client/serialize.js

@@ -0,0 +1,93 @@
+/** A request as it goes on the wire: its URL with the query, and its body encoded for `fetch`. */
+import { isAbsoluteHttpUrl } from "../runtime/cookies/redirect.js";
+import { bodyByteLength, formDataBytes, isFormData, isRawBytes, isURLSearchParams, utf8Bytes, } from "../runtime/exchange.js";
+import { serializeParam } from "./param-style.js";
+/* Whether the URL already carries `name`, as itself or as a deepObject's `name[key]`. */
+function carries(url, name) {
+    return [...url.searchParams.keys()].some((key) => key === name || key.startsWith(`${name}[`));
+}
+/* Whether one raw `name=value` pair, its name decoded as a query decodes it, is among `names`. */
+function namedIn(pair, names) {
+    return [...new URLSearchParams(pair).keys()].some((name) => Object.hasOwn(names, name));
+}
+/* Appends each parameter's pairs, as its style writes them, already percent-encoded. */
+function appendQuery(url, values, styles = {}) {
+    const pairs = Object.entries(values).flatMap(([name, value]) => serializeParam({ ...styles[name], in: "query", name }, value));
+    if (pairs.length === 0)
+        return;
+    const added = pairs.map(([key, value]) => `${key}=${value}`).join("&");
+    url.search = url.search === "" ? added : `${url.search.slice(1)}&${added}`;
+}
+/**
+ * `path` under `baseUrl` (or as given when absolute), with the caller's query written in each
+ * parameter's declared style. A value the caller sets replaces one the path already carries.
+ */
+export function requestUrl(baseUrl, path, { query, styles } = {}) {
+    const url = new URL(isAbsoluteHttpUrl(path) ? path : `${baseUrl}${path}`);
+    const values = Object.fromEntries(Object.entries(query ?? {}).filter(([, value]) => value !== undefined));
+    /* Pair by pair, not through `searchParams`, which would rewrite the pairs it keeps as a form. */
+    url.search = url.search
+        .slice(1)
+        .split("&")
+        .filter((pair) => pair !== "" && !namedIn(pair, values))
+        .join("&");
+    appendQuery(url, values, styles);
+    return url;
+}
+/** The operation's required parameters the caller did not set. One the caller names — even as undefined — is theirs. */
+export function addRequiredQuery(url, required, { query, styles } = {}) {
+    const missing = Object.entries(required).filter(([name]) => !(name in (query ?? {})) && !carries(url, name));
+    appendQuery(url, Object.fromEntries(missing), styles);
+}
+/* A path segment or query value that is the text of a missing value, never something the API tester chose. */
+export function carriesMissingValue(url) {
+    return (url.pathname.split("/").some((segment) => decoded(segment) === "undefined") ||
+        [...url.searchParams.values()].includes("undefined"));
+}
+function decoded(segment) {
+    try {
+        return decodeURIComponent(segment);
+    }
+    catch {
+        return segment;
+    }
+}
+export function encodeBody(body, contentType) {
+    if (body === undefined)
+        return { bytes: 0 };
+    if (contentType === null)
+        return asIs(body);
+    /* fetch sets multipart/form-data; boundary=… — setting it ourselves drops the boundary. */
+    if (isFormData(body))
+        return { bytes: formDataBytes(body), init: body };
+    if (isURLSearchParams(body)) {
+        const text = body.toString();
+        const type = contentType ?? "application/x-www-form-urlencoded";
+        return { bytes: utf8Bytes(text), contentType: type, init: body, text };
+    }
+    if (isRawBytes(body) || typeof body === "string") {
+        const encoded = asIs(body);
+        if (contentType !== undefined)
+            encoded.contentType = contentType;
+        return encoded;
+    }
+    const text = JSON.stringify(body);
+    return { bytes: utf8Bytes(text), contentType: contentType ?? "application/json", init: text, text };
+}
+/* Sent as it is, without touching Content-Type; anything fetch cannot send is sent as JSON. */
+function asIs(body) {
+    const encoded = { bytes: bodyByteLength(body), init: asBodyInit(body) ?? JSON.stringify(body) };
+    if (typeof body === "string")
+        encoded.text = body;
+    return encoded;
+}
+function asBodyInit(body) {
+    if (typeof body === "string")
+        return body;
+    if (isFormData(body) || isURLSearchParams(body) || isRawBytes(body))
+        return body;
+    if (body instanceof ReadableStream)
+        return body;
+    return undefined;
+}
+//# sourceMappingURL=serialize.js.map

package/dist/api/client/slots.d.ts

@@ -0,0 +1,11 @@
+/** Admission control: at most `size` requests in flight, the rest waiting in order. */
+export declare class Slots {
+    private readonly size;
+    private inFlight;
+    private readonly waiting;
+    constructor(size: number);
+    /** Held for the duration of one attempt, and released in a finally. */
+    acquire(): Promise<void>;
+    release(): void;
+}
+//# sourceMappingURL=slots.d.ts.map

package/dist/api/client/slots.js

@@ -0,0 +1,20 @@
+/** Admission control: at most `size` requests in flight, the rest waiting in order. */
+export class Slots {
+    size;
+    inFlight = 0;
+    waiting = [];
+    constructor(size) {
+        this.size = size;
+    }
+    /** Held for the duration of one attempt, and released in a finally. */
+    async acquire() {
+        if (this.inFlight >= this.size)
+            await new Promise((resolve) => this.waiting.push(resolve));
+        this.inFlight += 1;
+    }
+    release() {
+        this.inFlight -= 1;
+        this.waiting.shift()?.();
+    }
+}
+//# sourceMappingURL=slots.js.map