@workerstack/testing 0.0.0-stage → 0.31.0

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

@@ -0,0 +1,42 @@
+/** The client's transcript: every exchange, compacted, and indexed by operation and entity. */
+import type { Redactor } from "../security/redact.ts";
+import { type Exchange, type SchemaVerdict } from "../runtime/exchange.ts";
+import { type SpoolOptions } from "../runtime/transcript/spool.ts";
+export declare class Journal {
+    private readonly redactor;
+    /**
+     * Every exchange, with bodies compacted for memory. The exchange a request returns to its
+     * caller is never compacted: it holds the real body, however large.
+     */
+    readonly transcript: Exchange[];
+    private readonly byOperationId;
+    private readonly byEntity;
+    private readonly stored;
+    private readonly spool;
+    private readonly validateAtCapture;
+    constructor(redactor: Redactor, options?: {
+        spool?: SpoolOptions;
+        validateAtCapture?: (exchange: Exchange) => SchemaVerdict | undefined;
+    });
+    /**
+     * Keeps a compacted copy. The caller's exchange is left whole: a check reading a 300 KiB page
+     * must see the page, not a hash of it. A response body kept only by reference is validated
+     * against its documented schema now, while it is whole, and the verdict kept beside it.
+     */
+    record(exchange: Exchange, entity: string | undefined): Promise<void>;
+    /** Marks an answer that was asked again: only the final answer is the backend's verdict. */
+    supersede(exchange: Exchange): void;
+    /** Exchanges that resolved to `operationId`, in order. */
+    exchangesFor(operationId: string): readonly Exchange[];
+    /** Exchanges that resolved to an operation of `entity`, in order. */
+    exchangesForEntity(entity: string): readonly Exchange[];
+    /**
+     * The exchange with its bodies, wherever they are kept. The transcript holds the most recent
+     * bodies in memory and moves older ones to disk once they pass a budget; a reader that judges
+     * bodies from the transcript — rather than from the exchange a request returned — asks here.
+     */
+    hydrate(exchange: Exchange): Promise<Exchange>;
+    /** Removes the bodies moved to disk. */
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=journal.d.ts.map

package/dist/api/client/journal.js

@@ -0,0 +1,75 @@
+/** The client's transcript: every exchange, compacted, and indexed by operation and entity. */
+import { isBodyRef } from "../runtime/exchange.js";
+import { BodySpool } from "../runtime/transcript/spool.js";
+import { releaseTranscriptBodies } from "../runtime/transcript/release.js";
+export class Journal {
+    redactor;
+    /**
+     * Every exchange, with bodies compacted for memory. The exchange a request returns to its
+     * caller is never compacted: it holds the real body, however large.
+     */
+    transcript = [];
+    byOperationId = new Map();
+    byEntity = new Map();
+    stored = new Map();
+    spool;
+    validateAtCapture;
+    constructor(redactor, options = {}) {
+        this.redactor = redactor;
+        this.spool = new BodySpool(options.spool ?? {});
+        this.validateAtCapture = options.validateAtCapture;
+    }
+    /**
+     * Keeps a compacted copy. The caller's exchange is left whole: a check reading a 300 KiB page
+     * must see the page, not a hash of it. A response body kept only by reference is validated
+     * against its documented schema now, while it is whole, and the verdict kept beside it.
+     */
+    async record(exchange, entity) {
+        const stored = { ...exchange };
+        await releaseTranscriptBodies(stored, this.redactor);
+        if (isBodyRef(stored.responseBody) && !isBodyRef(exchange.responseBody)) {
+            const verdict = this.validateAtCapture?.(exchange);
+            if (verdict !== undefined)
+                stored.schemaVerdict = verdict;
+        }
+        this.transcript.push(stored);
+        this.stored.set(exchange.seq, stored);
+        await this.spool.keep(stored);
+        if (stored.operationId !== undefined)
+            append(this.byOperationId, stored.operationId, stored);
+        if (entity !== undefined)
+            append(this.byEntity, entity, stored);
+    }
+    /** Marks an answer that was asked again: only the final answer is the backend's verdict. */
+    supersede(exchange) {
+        const stored = this.stored.get(exchange.seq);
+        if (stored !== undefined)
+            stored.superseded = true;
+    }
+    /** Exchanges that resolved to `operationId`, in order. */
+    exchangesFor(operationId) {
+        return this.byOperationId.get(operationId) ?? [];
+    }
+    /** Exchanges that resolved to an operation of `entity`, in order. */
+    exchangesForEntity(entity) {
+        return this.byEntity.get(entity) ?? [];
+    }
+    /**
+     * The exchange with its bodies, wherever they are kept. The transcript holds the most recent
+     * bodies in memory and moves older ones to disk once they pass a budget; a reader that judges
+     * bodies from the transcript — rather than from the exchange a request returned — asks here.
+     */
+    hydrate(exchange) {
+        return this.spool.hydrate(exchange);
+    }
+    /** Removes the bodies moved to disk. */
+    async dispose() {
+        await this.spool.dispose();
+    }
+}
+function append(index, key, exchange) {
+    const list = index.get(key) ?? [];
+    list.push(exchange);
+    index.set(key, list);
+}
+//# sourceMappingURL=journal.js.map

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

@@ -0,0 +1,15 @@
+/** What an exchange weighed on the wire, and the request id either side named. */
+/** What a request's start line names: its method, and the URL it goes to. */
+export interface RequestLine {
+    method: string;
+    url: URL;
+}
+/** Start line + headers + body. Host and Content-Length are filled when they would be on the wire. */
+export declare function requestMessageBytes({ method, url }: RequestLine, headers: Record<string, string>, body: {
+    bytes: number;
+    text?: string | undefined;
+}): number;
+export declare function responseMessageBytes(response: Response, headers: Record<string, string>, bodyBytes: number): number;
+/** Response header first, then the request. Empty when neither side sent one of the known names. */
+export declare function requestIdOf(requestHeaders: Record<string, string>, responseHeaders: Record<string, string>): string;
+//# sourceMappingURL=message.d.ts.map

package/dist/api/client/message.js

@@ -0,0 +1,47 @@
+/** What an exchange weighed on the wire, and the request id either side named. */
+import { utf8Bytes } from "../runtime/exchange.js";
+/** Start line + headers + body. Host and Content-Length are filled when they would be on the wire. */
+export function requestMessageBytes({ method, url }, headers, body) {
+    const sent = { ...headers };
+    if (!hasHeader(sent, "host"))
+        sent["host"] = url.host;
+    if (body.bytes > 0 && !hasHeader(sent, "content-length"))
+        sent["content-length"] = String(body.bytes);
+    const start = `${method} ${url.pathname}${url.search} HTTP/1.1`;
+    if (body.text !== undefined)
+        return headBytes(start, sent) + utf8Bytes(body.text);
+    return headBytes(start, sent) + body.bytes;
+}
+export function responseMessageBytes(response, headers, bodyBytes) {
+    const sent = { ...headers };
+    if (bodyBytes > 0 && !hasHeader(sent, "content-length"))
+        sent["content-length"] = String(bodyBytes);
+    const { status, statusText } = response;
+    const start = statusText === "" ? `HTTP/1.1 ${status}` : `HTTP/1.1 ${status} ${statusText}`;
+    return headBytes(start, sent) + bodyBytes;
+}
+function headBytes(startLine, headers) {
+    let text = `${startLine}\r\n`;
+    for (const [key, value] of Object.entries(headers))
+        text += `${key}: ${value}\r\n`;
+    return utf8Bytes(`${text}\r\n`);
+}
+function hasHeader(headers, name) {
+    const want = name.toLowerCase();
+    return Object.keys(headers).some((key) => key.toLowerCase() === want);
+}
+const REQUEST_ID_HEADERS = ["x-request-id", "request-id", "x-correlation-id", "correlation-id"];
+/** Response header first, then the request. Empty when neither side sent one of the known names. */
+export function requestIdOf(requestHeaders, responseHeaders) {
+    return headerOf(responseHeaders, REQUEST_ID_HEADERS) ?? headerOf(requestHeaders, REQUEST_ID_HEADERS) ?? "";
+}
+function headerOf(headers, names) {
+    for (const name of names) {
+        for (const [key, value] of Object.entries(headers)) {
+            if (key.toLowerCase() === name && value.trim() !== "")
+                return value.trim();
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=message.js.map

package/dist/api/client/param-style.d.ts

@@ -0,0 +1,29 @@
+/**
+ * One OAS style/explode serializer for every parameter location: query, path, header, cookie, and a
+ * form body's fields. It follows OAS 3.1 §4.8.12.4: query and cookie default to `form`, exploded;
+ * path and header to `simple`, not exploded. Every value is percent-encoded per RFC 3986 unless the
+ * parameter allows reserved characters; a header is never percent-encoded.
+ */
+import type { ParamIn, ParamStyle } from "../spec/graph/parameters.ts";
+/** A parameter: where it goes, its name, and how the document says to write it. */
+export interface StyledParam extends ParamStyle {
+    in: ParamIn;
+    name: string;
+}
+export type Pair = [string, string];
+/**
+ * `value` as the parameter sends it: key/value pairs for a query or cookie parameter, one string for
+ * a path or header parameter. An absent value sends nothing.
+ */
+export declare function serializeParam(param: StyledParam & {
+    in: "query" | "cookie";
+}, value: unknown): Pair[];
+export declare function serializeParam(param: StyledParam & {
+    in: "path" | "header";
+}, value: unknown): string;
+export declare function serializeParam(param: StyledParam, value: unknown): Pair[] | string;
+/** A form body field's pairs, unencoded: the body's own encoder encodes them. */
+export declare function unencodedPairs(param: ParamStyle & {
+    name: string;
+}, value: unknown): Pair[];
+//# sourceMappingURL=param-style.d.ts.map

package/dist/api/client/param-style.js

@@ -0,0 +1,78 @@
+/**
+ * One OAS style/explode serializer for every parameter location: query, path, header, cookie, and a
+ * form body's fields. It follows OAS 3.1 §4.8.12.4: query and cookie default to `form`, exploded;
+ * path and header to `simple`, not exploded. Every value is percent-encoded per RFC 3986 unless the
+ * parameter allows reserved characters; a header is never percent-encoded.
+ */
+/* encodeURIComponent leaves these sub-delims as they are; RFC 3986 reserves them. */
+const SUB_DELIMS = /[!'()*]/g;
+/* Every reserved character, encoded: what `allowReserved` sends as it is. */
+const RESERVED = /%(?:3A|2F|3F|23|5B|5D|40|21|24|26|27|28|29|2A|2B|2C|3B|3D)/g;
+const strict = (text) => encodeURIComponent(text).replace(SUB_DELIMS, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`);
+const reservedKept = (text) => strict(text).replace(RESERVED, decodeURIComponent);
+const asIs = (text) => text;
+function textOf(item) {
+    return item !== null && typeof item === "object" ? JSON.stringify(item) : String(item);
+}
+function shapeOf(value, encode) {
+    if (Array.isArray(value))
+        return { items: value.map((item) => encode(textOf(item))) };
+    if (typeof value !== "object" || value === null)
+        return { scalar: encode(String(value)) };
+    const entries = Object.entries(value).filter(([, item]) => item !== undefined);
+    return { entries: entries.map(([key, item]) => [encode(key), encode(textOf(item))]) };
+}
+/* The style and explode a parameter is written with, the document's or the OAS default. deepObject
+ * is defined only exploded. */
+function resolved(param) {
+    const style = param.style ?? (param.in === "query" || param.in === "cookie" ? "form" : "simple");
+    return { explode: style === "deepObject" || (param.explode ?? style === "form"), style };
+}
+/* What a non-exploded array or object is joined with. A space cannot go out bare, so it is encoded. */
+function delimiterOf(style, encode) {
+    if (style === "spaceDelimited")
+        return encode(" ");
+    return style === "pipeDelimited" ? "|" : ",";
+}
+/* Key/value pairs: the form styles, spaceDelimited, pipeDelimited and deepObject. */
+function pairsOf(name, shape, how) {
+    if ("scalar" in shape)
+        return [[name, shape.scalar]];
+    if ("items" in shape) {
+        return how.explode ? shape.items.map((item) => [name, item]) : [[name, shape.items.join(how.delimiter)]];
+    }
+    if (how.style === "deepObject")
+        return shape.entries.map(([key, item]) => [`${name}[${key}]`, item]);
+    return how.explode ? shape.entries : [[name, shape.entries.flat().join(how.delimiter)]];
+}
+const PREFIX = { label: ".", matrix: ";" };
+/* One string: the simple, label and matrix styles. */
+function stringOf(name, shape, { style, explode }) {
+    const prefix = PREFIX[style] ?? "";
+    const matrix = style === "matrix";
+    if ("scalar" in shape)
+        return matrix ? (shape.scalar === "" ? `;${name}` : `;${name}=${shape.scalar}`) : prefix + shape.scalar;
+    const pieces = "items" in shape ? shape.items : shape.entries.map(([key, item]) => (explode ? `${key}=${item}` : `${key},${item}`));
+    if (!explode)
+        return matrix ? `;${name}=${pieces.join(",")}` : prefix + pieces.join(",");
+    if (!matrix)
+        return prefix + pieces.join(style === "label" ? "." : ",");
+    return pieces.map((piece) => ("items" in shape ? `;${name}=${piece}` : `;${piece}`)).join("");
+}
+export function serializeParam(param, value) {
+    const how = resolved(param);
+    const pairs = param.in === "query" || param.in === "cookie";
+    if (value === undefined || value === null)
+        return pairs ? [] : "";
+    const encode = param.in === "header" ? asIs : param.allowReserved === true ? reservedKept : strict;
+    const shape = shapeOf(value, encode);
+    if (!pairs)
+        return stringOf(param.name, shape, how);
+    return pairsOf(encode(param.name), shape, { ...how, delimiter: delimiterOf(how.style, encode) });
+}
+/** A form body field's pairs, unencoded: the body's own encoder encodes them. */
+export function unencodedPairs(param, value) {
+    const how = resolved({ ...param, in: "query" });
+    return pairsOf(param.name, shapeOf(value, asIs), { ...how, delimiter: delimiterOf(how.style, asIs) });
+}
+//# sourceMappingURL=param-style.js.map

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

@@ -0,0 +1,87 @@
+/**
+ * One request's credential: resolved for every attempt, placed on it, and renewed at most once.
+ *
+ * Every attempt asks the source again, so a credential that went stale during a wait is renewed by
+ * the store before it is sent; one that lapses during the attempt's own slot and rate waits is
+ * resolved once more after them (`lapsed`, in `request.ts`). A 401 renews what that attempt sent,
+ * once per request, and the retry sends the renewal; a renewal that failed leaves the 401 as the
+ * answer. A refusal of a value a renewal issued goes to the run's control read (`control.ts`)
+ * instead, and is renewed only when the control judges it lapsed. A probe expects the refusal, and
+ * a forged value is one, so neither is renewed, and the control read's own answer is its verdict.
+ * What a principal's credential places registers on the run's redactor; a forged value is no secret.
+ */
+import type { Exchange } from "../runtime/exchange.ts";
+import type { Redactor } from "../security/redact.ts";
+import type { ControlRead, Controls } from "./control.ts";
+import { type Actor, type CredentialSource, type Resolution, type SendsByScheme } from "./credential-source.ts";
+/** What one attempt placed: whose credential, under which schemes, and what each scheme sends. */
+export interface Placement {
+    principal?: string;
+    schemes: string[];
+    forged: boolean;
+    sends: SendsByScheme;
+}
+/** An attempt that carries no credential. */
+export declare const NOTHING_PLACED: Placement;
+export interface RequestCredential {
+    /** What the next attempt places. Raises `UnsatisfiedSecurity` when the request's security cannot be met. */
+    next(): Promise<Placement>;
+    /** After a 401: renews what the last attempt sent, once per request. Whether the request should be sent again. */
+    renew(): Promise<boolean>;
+    /** Whether what the last attempt placed is no longer current (renewed since, or stale); never for a probe. Never awaits. */
+    lapsed(): boolean;
+    /**
+     * The request was refused and not renewed: when it carried a value a renewal issued, the control
+     * read (`send`, once per value) judges it. Whether it should be sent again: the value lapsed after
+     * it was accepted, and its renewal, shared with every request refused on it, issued a credential.
+     */
+    refused(send: (read: ControlRead) => Promise<Exchange>): Promise<boolean>;
+    /** The request was answered 2xx: a value a renewal issued that it carried is proven, so a later refusal may be a lapse. */
+    accepted(): void;
+}
+/** A request's actor, as the client hands it to the source. */
+export interface Acting {
+    actor: Actor;
+    /** `<METHOD> <path>`: what a refusal names. */
+    route: string;
+    operationId?: string | undefined;
+    probe?: boolean | undefined;
+    /** The client's own control read: its answer is the verdict, so it is never renewed or judged. */
+    control?: true | undefined;
+}
+/** The credential of one request, over the client's source. */
+export declare function requestCredential(wire: {
+    controls: Controls;
+    credentials: CredentialSource | undefined;
+    redactor: Redactor;
+}, acting: Acting): RequestCredential;
+/** What `request` would send, resolved by `source`, with nothing sent; a client without one has nothing to place. */
+export declare function resolveWith(source: CredentialSource | undefined, request: {
+    actor: Actor;
+    route: string;
+    operationId?: string;
+    probe: boolean;
+}): Promise<Resolution>;
+/** Where one attempt goes before its credential: the URL, the query the caller named, and its header layers. */
+export interface Unplaced {
+    url: URL;
+    /** Query parameters the caller set, which a placed one must not override. */
+    callerQuery: ReadonlySet<string>;
+    /** Globals, then the `resolveHeaders` hook's, then the caller's: later layers win. */
+    layers: ReadonlyArray<Readonly<Record<string, string>>>;
+}
+/**
+ * The attempt's URL and headers with the credential placed: a header set, a query parameter on a copy
+ * of the URL, a cookie merged into the Cookie header. Raises `CredentialCollision` when any layer
+ * already sends something under a placed name, which would override or shadow the scheme.
+ */
+export declare function placeOn(placement: Placement, unplaced: Unplaced): {
+    url: URL;
+    headers: Record<string, string>;
+};
+/** The header names and query parameters a placement put on a request, which a hop to another origin must drop. */
+export declare function placedNames(placement: Placement): {
+    headers: string[];
+    query: ReadonlySet<string>;
+};
+//# sourceMappingURL=placing.d.ts.map

package/dist/api/client/placing.js

@@ -0,0 +1,174 @@
+/**
+ * One request's credential: resolved for every attempt, placed on it, and renewed at most once.
+ *
+ * Every attempt asks the source again, so a credential that went stale during a wait is renewed by
+ * the store before it is sent; one that lapses during the attempt's own slot and rate waits is
+ * resolved once more after them (`lapsed`, in `request.ts`). A 401 renews what that attempt sent,
+ * once per request, and the retry sends the renewal; a renewal that failed leaves the 401 as the
+ * answer. A refusal of a value a renewal issued goes to the run's control read (`control.ts`)
+ * instead, and is renewed only when the control judges it lapsed. A probe expects the refusal, and
+ * a forged value is one, so neither is renewed, and the control read's own answer is its verdict.
+ * What a principal's credential places registers on the run's redactor; a forged value is no secret.
+ */
+import { headerValue } from "../runtime/headers.js";
+import { CredentialCollision, UnsatisfiedSecurity, } from "./credential-source.js";
+/** An attempt that carries no credential. */
+export const NOTHING_PLACED = /* @__PURE__ */ Object.freeze({ forged: false, schemes: [], sends: {} });
+/** The credential of one request, over the client's source. */
+export function requestCredential(wire, acting) {
+    const probe = acting.probe === true || "forged" in acting.actor;
+    const request = {
+        actor: acting.actor,
+        route: acting.route,
+        ...(acting.operationId === undefined ? {} : { operationId: acting.operationId }),
+        probe,
+    };
+    let last;
+    let renewal;
+    let renewed = false;
+    /* Renews what `sent` carried and places the renewal on the next attempt; false when the store blocked it. */
+    const renewFrom = async (sent) => {
+        renewed = true;
+        const next = await sent.refresh();
+        /* A renewal the store BLOCKED sends nothing more: the refusal this request got is its answer. */
+        if (next.kind !== "sends")
+            return false;
+        wire.controls.renewed(next);
+        renewal = next;
+        return true;
+    };
+    const judged = (sent) => acting.control !== true && sent?.kind === "sends" && wire.controls.renewal(sent);
+    return {
+        accepted: () => {
+            if (judged(last))
+                wire.controls.accepted(last);
+        },
+        next: async () => {
+            last = renewal ?? (await resolveWith(wire.credentials, request));
+            renewal = undefined;
+            return placementOf(last, { actor: acting.actor, redactor: wire.redactor });
+        },
+        /* A probe sends what it resolved, as it renews nothing: the refusal it expects is the answer. */
+        lapsed: () => !probe && last?.kind === "sends" && last.lapsed(),
+        refused: async (send) => {
+            /* Only a value a renewal issued is judged: any other refusal is the answer as it stands. */
+            if (!judged(last))
+                return false;
+            const verdict = await wire.controls.confirm(last, send);
+            return verdict === "lapsed" && !renewed && !probe && renewFrom(last);
+        },
+        renew: async () => {
+            if (renewed || probe || acting.control === true || last?.kind !== "sends" || wire.controls.renewal(last))
+                return false;
+            return renewFrom(last);
+        },
+    };
+}
+/** What `request` would send, resolved by `source`, with nothing sent; a client without one has nothing to place. */
+export function resolveWith(source, request) {
+    if (source !== undefined)
+        return source.resolve(request);
+    if ("anonymous" in request.actor)
+        return Promise.resolve({ kind: "anonymous" });
+    return Promise.resolve({ kind: "unsatisfied", reason: "this client holds no credentials" });
+}
+/*
+ * A principal whose operation's security is `[]` places nothing, yet the exchange is still theirs: what
+ * it creates is theirs to tear down.
+ */
+function placementOf(resolution, { actor, redactor }) {
+    switch (resolution.kind) {
+        case "unsatisfied":
+        case "blocked":
+            throw new UnsatisfiedSecurity(resolution.kind, resolution.reason);
+        case "sends":
+            refuseDeferredEnv(resolution.sentValues);
+            redactor.registerPlacement(resolution.secrets);
+            return { forged: false, principal: resolution.principal, schemes: resolution.schemes, sends: resolution.sends };
+        case "held":
+            redactor.registerPlacement(resolution.secrets);
+            return { forged: false, principal: resolution.principal, schemes: resolution.schemes, sends: resolution.sends };
+        case "forged":
+            if (resolution.secrets !== undefined)
+                redactor.registerPlacement(resolution.secrets);
+            return { forged: true, schemes: resolution.schemes, sends: resolution.sends };
+        default:
+            return "principal" in actor
+                ? { forged: false, principal: actor.principal, schemes: [], sends: {} }
+                : NOTHING_PLACED;
+    }
+}
+/* What `env()` reads as while doctor or plan defers an unset variable. */
+const DEFERRED_ENV = /^\$\{[A-Z0-9_]+\}$/;
+/*
+ * A run never defers env, so a `${NAME}` literal here means that rule broke: sending it would put
+ * the variable's name on the wire as a credential. A basic pair is `user:pass`, so each half is read.
+ */
+function refuseDeferredEnv(sentValues) {
+    for (const [scheme, value] of Object.entries(sentValues)) {
+        const literal = value.split(":").find((part) => DEFERRED_ENV.test(part));
+        if (literal !== undefined) {
+            throw new Error(`testing api: the ${scheme} credential is the unset variable ${literal}; a run never defers env, so this is a bug`);
+        }
+    }
+}
+/**
+ * The attempt's URL and headers with the credential placed: a header set, a query parameter on a copy
+ * of the URL, a cookie merged into the Cookie header. Raises `CredentialCollision` when any layer
+ * already sends something under a placed name, which would override or shadow the scheme.
+ */
+export function placeOn(placement, unplaced) {
+    const headers = Object.assign({}, ...unplaced.layers);
+    if (placement.schemes.length === 0)
+        return { headers, url: unplaced.url };
+    refuseCollisions(placement, unplaced);
+    const url = new URL(unplaced.url);
+    const cookies = [];
+    const query = [];
+    for (const sends of Object.values(placement.sends)) {
+        Object.assign(headers, sends.headers);
+        for (const [name, value] of Object.entries(sends.query)) {
+            query.push(`${encodeURIComponent(name)}=${encodeURIComponent(value)}`);
+        }
+        for (const [name, value] of Object.entries(sends.cookies))
+            cookies.push(`${name}=${value}`);
+    }
+    /* Appended as written, not through `searchParams`, which would rewrite the whole query as a form
+     * (a space as `+`, a reserved character escaped) and undo each parameter's declared style. No
+     * collision reached here, so appending is setting. */
+    if (query.length > 0)
+        url.search = [url.search.slice(1), ...query].filter(Boolean).join("&");
+    if (cookies.length > 0) {
+        const name = Object.keys(headers).find((key) => key.toLowerCase() === "cookie") ?? "cookie";
+        headers[name] = [headers[name], ...cookies].filter(Boolean).join("; ");
+    }
+    return { headers, url };
+}
+function refuseCollisions(placement, unplaced) {
+    const sent = unplaced.layers.flatMap((layer) => Object.keys(layer));
+    const cookies = new Set(unplaced.layers.flatMap((layer) => cookieNames(headerValue(layer, "cookie"))));
+    for (const [scheme, sends] of Object.entries(placement.sends)) {
+        const placed = new Set(Object.keys(sends.headers).map((name) => name.toLowerCase()));
+        const header = sent.findLast((name) => placed.has(name.toLowerCase()));
+        if (header !== undefined)
+            throw new CredentialCollision("header", { name: header, scheme });
+        const query = Object.keys(sends.query).find((name) => unplaced.callerQuery.has(name));
+        if (query !== undefined)
+            throw new CredentialCollision("query", { name: query, scheme });
+        const cookie = Object.keys(sends.cookies).find((name) => cookies.has(name));
+        if (cookie !== undefined)
+            throw new CredentialCollision("cookie", { name: cookie, scheme });
+    }
+}
+function cookieNames(header) {
+    return (header ?? "").split(";").map((pair) => pair.replace(/=.*$/s, "").trim());
+}
+/** The header names and query parameters a placement put on a request, which a hop to another origin must drop. */
+export function placedNames(placement) {
+    const sends = Object.values(placement.sends);
+    return {
+        headers: sends.flatMap((each) => Object.keys(each.headers)),
+        query: new Set(sends.flatMap((each) => Object.keys(each.query))),
+    };
+}
+//# sourceMappingURL=placing.js.map

package/dist/api/client/read-path.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Reading a value out of a JSON body by path, once. `$.a.b`, `a.b`, `$.items[0].id` and
+ * `$.items.0.id` are dotted paths; a leading `/` makes it a JSON pointer (`/items/0/id`).
+ * Auth flows, async receipts, x-wait and invite pointers all name values this way.
+ */
+export declare function readPath(body: unknown, pointer: string): unknown;
+/**
+ * Every node `path` names, fanning out at `[*]` and narrowing at `[?(@.field==value)]`:
+ * `$.items[*].name` is each item's name, `$.items[?(@.id=='a')].name` the name of the item whose
+ * id is `a`. A path with neither names at most one node, the same one `readPath` returns.
+ */
+export declare function readAll(body: unknown, path: string): unknown[];
+//# sourceMappingURL=read-path.d.ts.map

package/dist/api/client/read-path.js

@@ -0,0 +1,90 @@
+/**
+ * Reading a value out of a JSON body by path, once. `$.a.b`, `a.b`, `$.items[0].id` and
+ * `$.items.0.id` are dotted paths; a leading `/` makes it a JSON pointer (`/items/0/id`).
+ * Auth flows, async receipts, x-wait and invite pointers all name values this way.
+ */
+export function readPath(body, pointer) {
+    if (pointer.startsWith("/"))
+        return readJsonPointer(body, pointer);
+    /* A filter names items, not one node: the first match is the one a saved value means. */
+    if (FILTER_RE.test(pointer))
+        return readAll(body, pointer)[0];
+    /* `$.messages[0].id` and `$.messages.0.id` name the same node: brackets are read as segments. */
+    return pointer
+        .replace(/^\$\.?/, "")
+        .replace(/\[(\d+)\]/g, ".$1")
+        .split(".")
+        .filter(Boolean)
+        .reduce(step, body);
+}
+/* One segment down: a property of an object, an index of an array, nothing below a primitive. */
+function step(node, segment) {
+    if (node === null || typeof node !== "object")
+        return undefined;
+    if (!Array.isArray(node))
+        return node[segment];
+    const index = Number.parseInt(segment, 10);
+    return Number.isNaN(index) ? undefined : node[index];
+}
+function readJsonPointer(body, pointer) {
+    if (pointer === "/")
+        return body;
+    return pointer
+        .slice(1)
+        .split("/")
+        .map((raw) => raw.replace(/~1/g, "/").replace(/~0/g, "~"))
+        .reduce(step, body);
+}
+/* `[?(@.field==value)]`: a quoted string, a number, true, false or null. */
+const FILTER_RE = /\[\?\(@\.([A-Za-z0-9_]+)==(?:'([^']*)'|"([^"]*)"|([^)\]]+))\)\]/;
+/* The value a filter compares with. The regex matched, so exactly one of groups 2 to 4 is set. */
+function filterValue(match) {
+    if (match[2] !== undefined)
+        return match[2];
+    if (match[3] !== undefined)
+        return match[3];
+    const literal = match[4].trim();
+    if (literal === "true")
+        return true;
+    if (literal === "false")
+        return false;
+    if (literal === "null")
+        return null;
+    const number = Number(literal);
+    return Number.isNaN(number) ? literal : number;
+}
+function keepsEvery() {
+    return true;
+}
+/* The items whose field equals the filter's value. Group 1, the field, is not optional. */
+function keepsMatching(filter) {
+    const field = filter[1];
+    const value = filterValue(filter);
+    return (item) => item !== null && typeof item === "object" && item[field] === value;
+}
+function branchOf(path) {
+    const star = path.indexOf("[*]");
+    const filter = FILTER_RE.exec(path);
+    if (filter === null || (star >= 0 && star < filter.index)) {
+        return star < 0 ? undefined : { head: path.slice(0, star), keeps: keepsEvery, rest: path.slice(star + 3) };
+    }
+    const head = path.slice(0, filter.index);
+    return { head, keeps: keepsMatching(filter), rest: path.slice(filter.index + filter[0].length) };
+}
+/**
+ * Every node `path` names, fanning out at `[*]` and narrowing at `[?(@.field==value)]`:
+ * `$.items[*].name` is each item's name, `$.items[?(@.id=='a')].name` the name of the item whose
+ * id is `a`. A path with neither names at most one node, the same one `readPath` returns.
+ */
+export function readAll(body, path) {
+    const branch = branchOf(path);
+    if (branch === undefined) {
+        const node = readPath(body, path);
+        return node === undefined ? [] : [node];
+    }
+    const list = branch.head === "$" || branch.head === "" ? body : readPath(body, branch.head);
+    if (!Array.isArray(list))
+        return [];
+    return list.filter(branch.keeps).flatMap((item) => (branch.rest === "" ? [item] : readAll(item, `$${branch.rest}`)));
+}
+//# sourceMappingURL=read-path.js.map