@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/cli/flags.d.ts

@@ -0,0 +1,64 @@
+import type { FlagKind, FlagKinds } from "./flag-kinds.ts";
+export interface FlagSpec<Kind extends FlagKind = FlagKind> {
+    kind: Kind;
+    /** A value that must parse as a number of this kind. */
+    number?: "integer" | "positive";
+    /** How the help names the value: `<file>`, `[n]`. */
+    value?: string;
+    /** One line of help; a flag two commands share says what it means to each. */
+    help: string;
+}
+/** Every flag, once: whether it takes a value, what kind, and what it is for. Parsing and help both read this. */
+export declare const FLAGS: {
+    readonly [Name in FlagName]: Readonly<FlagSpec<FlagKinds[Name]>>;
+};
+/** A flag some command takes, by name: a misspelled one does not compile. */
+export type FlagName = keyof FlagKinds;
+/** What parsing leaves for each kind: a switch is `true`, a value its text, an optional value either. */
+interface ValueOfKind {
+    boolean: true;
+    value: string;
+    "optional-value": string | true;
+}
+/** The flags of one kind, by name. */
+type NamesOf<Kind extends FlagKind> = {
+    [Name in FlagName]: FlagKinds[Name] extends Kind ? Name : never;
+}[FlagName];
+/** The flags a command was given, each typed by its kind in the table; one not given is absent. */
+export type Flags = {
+    [Name in FlagName]?: ValueOfKind[FlagKinds[Name]];
+};
+/** Whether some command takes `--name`. */
+export declare function isKnownFlag(name: string): name is FlagName;
+/** Every command: how it is called, and what it does. */
+export declare const COMMANDS: ReadonlyArray<{
+    usage: string;
+    help: string;
+}>;
+/** The help, made from the tables above: a flag cannot exist without its line. */
+export declare const USAGE: string;
+/** A command and its flags, as parsed. */
+export interface Args {
+    command: string;
+    flags: Flags;
+    /** Arguments that are not flags or flag values, in order: `testing api diff <runA> <runB>`. Absent when none. */
+    positionals?: string[];
+}
+/**
+ * `testing api <command> [--flag value | --flag=value | --switch] …`. A value flag must have its value;
+ * a switch takes none; a numeric value must be one. The first problem is returned as `error`
+ * rather than guessed around: `--max-in-flight -1` once hung a run, `--seed abc` seeded strings
+ * with `NaN`, and a flag followed by another flag silently became `true`. A flag no command
+ * knows is the problem reported first, wherever it stands.
+ */
+export declare function parseArgs(argv: readonly string[]): Args & {
+    error?: string;
+};
+/** The flags that can carry a value. */
+type ValueName = NamesOf<"value" | "optional-value">;
+/** A flag's value as given, or nothing when it is absent or a bare switch. */
+export declare function str(flags: Flags, name: ValueName): string | undefined;
+/** A comma-separated flag's items, trimmed, without empty ones. */
+export declare function list(flags: Flags, name: ValueName): string[] | undefined;
+export {};
+//# sourceMappingURL=flags.d.ts.map

package/dist/api/cli/flags.js

@@ -0,0 +1,250 @@
+/* The command line: every command and flag once, parsed from argv and printed as the help. */
+/** Every flag, once: whether it takes a value, what kind, and what it is for. Parsing and help both read this. */
+export const FLAGS = {
+    config: { help: "config module (.ts/.js/.mjs/.json) with a default export", kind: "value", value: "<file>" },
+    spec: { help: "OpenAPI document, http(s) URL or filesystem path", kind: "value", value: "<url|file>" },
+    "base-url": { help: "backend under test, overriding the config", kind: "value", value: "<url>" },
+    ops: {
+        help: "comma-separated operationIds to grade (row.*, cdn:asset.get); the rest is support",
+        kind: "value",
+        value: "<ids>",
+    },
+    only: {
+        help: "run, plan: comma-separated entities, each grading every operation it owns; conformance: defect names",
+        kind: "value",
+        value: "<names>",
+    },
+    profile: {
+        help: "named profile gating which operations run (built-in: full, cheap)",
+        kind: "value",
+        value: "<name>",
+    },
+    seed: {
+        help: "integer seed for fixture generation (default 1); with --fuzz or --precision, the seed that replays a case",
+        kind: "value",
+        number: "integer",
+        value: "<n>",
+    },
+    out: {
+        help: "run: history root, each run is <out>/<datetime>/ (default ./.testing/api/runs); baseline: the file written; init: the config written (default ./testing.api.config.ts)",
+        kind: "value",
+        value: "<dir|file>",
+    },
+    report: {
+        help: "run: comma-separated reports to write beside the run's own; junit writes junit.xml in the run directory",
+        kind: "value",
+        value: "<names>",
+    },
+    "keep-fixtures": { help: "leave created records in place instead of tearing them down", kind: "boolean" },
+    "keep-credentials": {
+        help: "write the credentials the run held to .testing/api/credentials.json (mode 0600), never under --out",
+        kind: "boolean",
+    },
+    "max-in-flight": {
+        help: "requests allowed in flight at once (default 4)",
+        kind: "value",
+        number: "positive",
+        value: "<n>",
+    },
+    quiet: { help: "no live progress on stderr (progress.log still written)", kind: "boolean" },
+    "save-exchanges": {
+        help: "persist every HTTP exchange under the run dir (default unless --profile cheap)",
+        kind: "boolean",
+    },
+    "no-save-exchanges": { help: "skip the exchange journal (cheap CI)", kind: "boolean" },
+    untagged: { help: "serve (or test) a document with every x-* tag stripped", kind: "boolean" },
+    defects: { help: "serve: comma-separated defects the demo API injects", kind: "value", value: "<names>" },
+    backend: {
+        help: "conformance and serve storage: memory | sqlite | postgres | d1 (default: all local; d1 is remote and opt-in)",
+        kind: "value",
+        value: "<name>",
+    },
+    dialect: {
+        help: "API shape: postgrest | classic | linked | jsonapi | plain | template (default: all)",
+        kind: "value",
+        value: "<name>",
+    },
+    parser: { help: "conformance: the document and suite checks only, without the defect matrix", kind: "boolean" },
+    fuzz: {
+        help: "conformance: inject random defect combinations instead of one at a time",
+        kind: "optional-value",
+        number: "positive",
+        value: "[n]",
+    },
+    precision: {
+        help: "conformance: vary cohort data against a correct backend; any finding is a false positive",
+        kind: "optional-value",
+        number: "positive",
+        value: "[n]",
+    },
+    "max-defects": {
+        help: "conformance: most defects per combination (default 4)",
+        kind: "value",
+        number: "positive",
+        value: "<n>",
+    },
+    "fuzz-seed": {
+        help: "conformance: seed for the combination pass of a full run (default 1)",
+        kind: "value",
+        number: "positive",
+        value: "<n>",
+    },
+    jobs: {
+        help: "conformance: legs run at once, each on its own thread (default: CPUs − 1, at most 4)",
+        kind: "value",
+        number: "positive",
+        value: "<n>",
+    },
+    "skip-backend": {
+        help: "conformance: comma-separated backends a full run may leave out when unreachable",
+        kind: "value",
+        value: "<names>",
+    },
+    legs: {
+        help: "conformance: run only these parts — suites, passes, shapes, recall, scope, fuzz",
+        kind: "value",
+        value: "<legs>",
+    },
+    shapes: {
+        help: "conformance: the shapes the shapes and recall legs judge behind; all when absent",
+        kind: "value",
+        value: "<names>",
+    },
+    "proven-out": {
+        help: "conformance: write the checks this run's defects proved to a file, for --aggregate",
+        kind: "value",
+        value: "<file>",
+    },
+    aggregate: {
+        help: "conformance: judge the proven-check files of a sharded run together; fails on any check none proved",
+        kind: "value",
+        value: "<dir>",
+    },
+    json: { help: "machine-readable output, for plan, doctor and diff", kind: "boolean" },
+    from: { help: "baseline: the run folder (or latest) whose findings become known", kind: "value", value: "<run>" },
+    force: { help: "baseline, init: overwrite an existing --out file", kind: "boolean" },
+    help: { help: "print this help", kind: "boolean" },
+};
+/** The table looked up by a name argv typed, before it is known to be a flag. */
+const SPECS = FLAGS;
+/** Whether some command takes `--name`. */
+export function isKnownFlag(name) {
+    return Object.hasOwn(FLAGS, name);
+}
+function isKind(name, kind) {
+    return isKnownFlag(name) && SPECS[name]?.kind === kind;
+}
+/** Every command: how it is called, and what it does. */
+export const COMMANDS = [
+    { help: "test a live backend and write a report", usage: "run     --config <file>" },
+    { help: "derive and print the test model (offline)", usage: "plan    --spec <url|file>" },
+    { help: "report what the API tester can and cannot test, and why", usage: "doctor  --spec <url|file>" },
+    {
+        help: "write a starter testing.api.config.ts from the document's security schemes",
+        usage: "init    --spec <url|file> [--out file]",
+    },
+    { help: "run a demo API to point the API tester at", usage: "serve   [--defects A,B]" },
+    { help: "self-test: injected defects vs detection", usage: "conformance" },
+    { help: "write a known-findings baseline from a run's report", usage: "baseline --from <run> [--out file]" },
+    { help: "new, fixed and persisting findings between two runs", usage: "diff    <runA> <runB> [--json]" },
+];
+/** The help, made from the tables above: a flag cannot exist without its line. */
+export const USAGE = /* @__PURE__ */ usage();
+function usage() {
+    const column = Math.max(...COMMANDS.map((command) => command.usage.length)) + 3;
+    const commands = COMMANDS.map((command) => `  testing api ${command.usage.padEnd(column)}${command.help}`);
+    const named = Object.entries(SPECS).map(([name, spec]) => [
+        `--${name}${spec.value === undefined ? "" : ` ${spec.value}`}`,
+        spec.help,
+    ]);
+    const width = Math.max(...named.map(([flag]) => flag.length)) + 2;
+    const flags = named.map(([flag, help]) => `  ${flag.padEnd(width)}${help}`);
+    return `testing api — test a live HTTP API against its OpenAPI document\n\n${commands.join("\n")}\n\nFlags\n${flags.join("\n")}\n`;
+}
+/**
+ * `testing api <command> [--flag value | --flag=value | --switch] …`. A value flag must have its value;
+ * a switch takes none; a numeric value must be one. The first problem is returned as `error`
+ * rather than guessed around: `--max-in-flight -1` once hung a run, `--seed abc` seeded strings
+ * with `NaN`, and a flag followed by another flag silently became `true`. A flag no command
+ * knows is the problem reported first, wherever it stands.
+ */
+export function parseArgs(argv) {
+    const leadingFlag = argv[0]?.startsWith("--") === true;
+    const command = leadingFlag ? "help" : (argv[0] ?? "help");
+    const rest = leadingFlag ? argv : argv.slice(1);
+    const flags = {};
+    const positionals = [];
+    let unknown;
+    let error;
+    for (let i = 0; i < rest.length; i++) {
+        const token = rest[i];
+        if (!token.startsWith("--")) {
+            positionals.push(token);
+            continue;
+        }
+        const read = readFlag(token, rest[i + 1]);
+        if (read.consumed)
+            i++;
+        if (!isKnownFlag(read.key))
+            unknown ??= read.key;
+        error ??= read.error;
+        keep(flags, read.key, read.value);
+    }
+    if (unknown !== undefined)
+        error = `unknown flag "--${unknown}"`;
+    const extra = positionals.length === 0 ? {} : { positionals };
+    return error === undefined ? { command, flags, ...extra } : { command, error, flags, ...extra };
+}
+/** One flag, its value inline, from the next token, or none; with the first problem it has. */
+function readFlag(token, next) {
+    const equals = token.indexOf("=");
+    const key = equals === -1 ? token.slice(2) : token.slice(2, equals);
+    const inline = equals === -1 ? undefined : token.slice(equals + 1);
+    const spec = SPECS[key];
+    if (spec === undefined || spec.kind === "boolean") {
+        const error = inline !== undefined && spec !== undefined ? `--${key} takes no value` : undefined;
+        return { consumed: false, error, key, value: inline ?? true };
+    }
+    if (inline !== undefined)
+        return { consumed: false, error: numberProblem(key, spec, inline), key, value: inline };
+    if (next !== undefined && !next.startsWith("--")) {
+        return { consumed: true, error: numberProblem(key, spec, next), key, value: next };
+    }
+    return {
+        consumed: false,
+        error: spec.kind === "optional-value" ? undefined : `--${key} needs a value`,
+        key,
+        value: true,
+    };
+}
+/** Keeps a flag whose value fits its kind; any other is unknown or already the error. */
+function keep(flags, name, value) {
+    if (isKind(name, "boolean") && value === true)
+        flags[name] = value;
+    else if (isKind(name, "value") && value !== true)
+        flags[name] = value;
+    else if (isKind(name, "optional-value"))
+        flags[name] = value;
+}
+function numberProblem(key, spec, value) {
+    if (spec.number === undefined)
+        return undefined;
+    const parsed = Number(value);
+    const integer = value.trim() !== "" && Number.isSafeInteger(parsed);
+    if (integer && (spec.number !== "positive" || parsed >= 1))
+        return undefined;
+    return `--${key} must be ${spec.number === "positive" ? "a positive" : "an"} integer, got "${value}"`;
+}
+/** A flag's value as given, or nothing when it is absent or a bare switch. */
+export function str(flags, name) {
+    const value = flags[name];
+    return typeof value === "string" ? value : undefined;
+}
+/** A comma-separated flag's items, trimmed, without empty ones. */
+export function list(flags, name) {
+    return str(flags, name)
+        ?.split(",")
+        .map((item) => item.trim())
+        .filter(Boolean);
+}
+//# sourceMappingURL=flags.js.map

package/dist/api/cli/legacy-run.d.ts

@@ -0,0 +1,4 @@
+export declare const LEGACY_REPORT = "oat-report.json";
+/** Why `run` cannot be read when it is a run folder from before the rename, else `undefined`. */
+export declare function legacyRunHint(run: string): string | undefined;
+//# sourceMappingURL=legacy-run.d.ts.map

package/dist/api/cli/legacy-run.js

@@ -0,0 +1,11 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+/* The report a run folder held before the package was renamed from oat; the API tester reads report.json. */
+export const LEGACY_REPORT = "oat-report.json";
+/** Why `run` cannot be read when it is a run folder from before the rename, else `undefined`. */
+export function legacyRunHint(run) {
+    if (!existsSync(join(run, LEGACY_REPORT)))
+        return undefined;
+    return `${run} is a run from before the rename (it holds ${LEGACY_REPORT}); those are not read. See docs/api/migrating-from-oat.md`;
+}
+//# sourceMappingURL=legacy-run.js.map

package/dist/api/cli/main.d.ts

@@ -0,0 +1,25 @@
+import type { Toolkit } from "./commands/conformance-toolkit.ts";
+import { type RunDeps } from "./commands/run.ts";
+import { type ServeDeps } from "./commands/serve.ts";
+import { type Writer } from "./writer.ts";
+/** What the commands reach outside the process through; each defaults to the real thing. */
+export interface CliDeps {
+    writer: Writer;
+    run?: RunDeps;
+    serve?: ServeDeps;
+    toolkit?: () => Promise<Toolkit>;
+}
+/** `testing api <command> …`: refuses what it cannot parse, prints help when asked, and runs the command. Returns the exit code. */
+export declare function main(argv?: readonly string[], deps?: CliDeps): Promise<number>;
+/**
+ * Runs a command line as the process: its exit code is the process's, and an error it did not expect is
+ * one line. `cli` is the API tester's own by default; the package's `testing` passes its dispatcher.
+ */
+export declare function start(deps?: CliDeps, cli?: (argv: readonly string[], deps: CliDeps) => Promise<number>): Promise<void>;
+/**
+ * Whether `moduleUrl` is the program Node was asked to run (`entry`, its argv[1]). Installed from
+ * a local path, the API tester is a symlink: Node gives the module its real path and leaves argv[1] the link,
+ * so the two are compared as real paths, and as written when either cannot be resolved.
+ */
+export declare function invokedDirectly(entry: string | undefined, moduleUrl: string): boolean;
+//# sourceMappingURL=main.d.ts.map

package/dist/api/cli/main.js

@@ -0,0 +1,76 @@
+import { realpathSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { messageOf } from "../errors/message.js";
+import { UsageError } from "../errors/usage-error.js";
+import { EXIT } from "../runtime/exit.js";
+import { commandBaseline } from "./commands/baseline.js";
+import { commandConformance } from "./commands/conformance.js";
+import { commandDiff } from "./commands/diff.js";
+import { commandDoctor } from "./commands/doctor.js";
+import { commandInit } from "./commands/init.js";
+import { commandPlan } from "./commands/plan.js";
+import { commandRun } from "./commands/run.js";
+import { commandServe } from "./commands/serve.js";
+import { parseArgs, USAGE } from "./flags.js";
+import { processWriter } from "./writer.js";
+/** Every command, by name. */
+const COMMANDS = {
+    baseline: ({ writer }, flags) => commandBaseline(writer, flags),
+    conformance: ({ writer, toolkit }, flags) => commandConformance(writer, flags, toolkit),
+    diff: ({ writer }, flags, positionals) => commandDiff(writer, flags, positionals),
+    doctor: ({ writer }, flags) => commandDoctor(writer, flags),
+    init: ({ writer }, flags) => commandInit(writer, flags),
+    plan: ({ writer }, flags) => commandPlan(writer, flags),
+    run: ({ writer, run }, flags) => commandRun(writer, flags, run),
+    serve: ({ writer, serve }, flags) => commandServe(writer, flags, serve),
+};
+/** `testing api <command> …`: refuses what it cannot parse, prints help when asked, and runs the command. Returns the exit code. */
+export async function main(argv = process.argv.slice(2), deps = { writer: processWriter }) {
+    const { writer } = deps;
+    const { command, error, flags, positionals } = parseArgs(argv);
+    if (error !== undefined) {
+        writer.err(`testing api: ${error}\n\n${USAGE}`);
+        return EXIT.usage;
+    }
+    if (command === "help" || flags.help === true) {
+        writer.out(USAGE);
+        return 0;
+    }
+    const run = COMMANDS[command];
+    if (run === undefined) {
+        writer.err(`testing api: unknown command "${command}"\n\n${USAGE}`);
+        return EXIT.usage;
+    }
+    return run(deps, flags, positionals ?? []);
+}
+/**
+ * Runs a command line as the process: its exit code is the process's, and an error it did not expect is
+ * one line. `cli` is the API tester's own by default; the package's `testing` passes its dispatcher.
+ */
+export function start(deps = { writer: processWriter }, cli = main) {
+    return cli(process.argv.slice(2), deps).then((code) => {
+        process.exitCode = code;
+    }, 
+    /* A usage error is the caller's to fix and names the mistake; anything else is the API tester failing. */
+    (error) => {
+        deps.writer.err(`testing api: ${messageOf(error).replace(/^testing api: /, "")}\n`);
+        process.exitCode = error instanceof UsageError ? EXIT.usage : EXIT.failed;
+    });
+}
+/**
+ * Whether `moduleUrl` is the program Node was asked to run (`entry`, its argv[1]). Installed from
+ * a local path, the API tester is a symlink: Node gives the module its real path and leaves argv[1] the link,
+ * so the two are compared as real paths, and as written when either cannot be resolved.
+ */
+export function invokedDirectly(entry, moduleUrl) {
+    if (entry === undefined)
+        return false;
+    try {
+        return realpathSync(fileURLToPath(moduleUrl)) === realpathSync(resolve(entry));
+    }
+    catch {
+        return moduleUrl === pathToFileURL(resolve(entry)).href;
+    }
+}
+//# sourceMappingURL=main.js.map

package/dist/api/cli/writer.d.ts

@@ -0,0 +1,15 @@
+export interface Writer {
+    /** Results: the report summary, `plan`, `doctor`, help. */
+    out(text: string): void;
+    /** Diagnostics: progress, warnings, refusals. */
+    err(text: string): void;
+    /** Pushes out what is buffered: a piped stdout holds text until exit unless asked. */
+    flush(): void;
+}
+/** The process's own streams, read at each write so a test that replaces them sees every line. */
+export declare const processWriter: Writer;
+/** A writer that keeps everything it is given, in order, for a caller that prints it later. */
+export declare function bufferWriter(): Writer & {
+    text: () => string;
+};
+//# sourceMappingURL=writer.d.ts.map

package/dist/api/cli/writer.js

@@ -0,0 +1,27 @@
+/*
+ * The one owner of terminal output. Everything the API tester prints goes through a writer, so a command can
+ * be run with its output captured, and the progress line and the report never interleave.
+ */
+/** The process's own streams, read at each write so a test that replaces them sees every line. */
+export const processWriter = {
+    err: (text) => {
+        process.stderr.write(text);
+    },
+    flush: () => {
+        process.stdout.uncork();
+    },
+    out: (text) => {
+        process.stdout.write(text);
+    },
+};
+/** A writer that keeps everything it is given, in order, for a caller that prints it later. */
+export function bufferWriter() {
+    const chunks = [];
+    return {
+        err: (text) => chunks.push(text),
+        flush: () => undefined,
+        out: (text) => chunks.push(text),
+        text: () => chunks.join(""),
+    };
+}
+//# sourceMappingURL=writer.js.map

package/dist/api/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export { start } from "./cli/main.ts";
+//# sourceMappingURL=cli.d.ts.map

package/dist/api/cli.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/*
+ * The executable. `node dist/api/cli.js …` is how CI, the labs and the tests run the API tester; `bin/testing.js`
+ * imports `start` and calls it itself, since its own argv[1] is the bin wrapper, not this module.
+ */
+import { invokedDirectly, start } from "./cli/main.js";
+export { start } from "./cli/main.js";
+if (invokedDirectly(process.argv[1], import.meta.url))
+    await start();
+//# sourceMappingURL=cli.js.map

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

@@ -0,0 +1,14 @@
+/** The exchange an attempt leaves: the backend's answer, or a network failure recorded as status 0. */
+import type { Exchange } from "../runtime/exchange.ts";
+import type { Pacing, Sent, Timed, Wire } from "./attempt.ts";
+import type { RequestStart } from "./types.ts";
+/** The error to raise for a failed send: a recorded `NetworkError`, or the error itself when it is not the network's. */
+export declare function failed(error: unknown, sent: Sent & {
+    probe: RequestStart;
+    started: number;
+}, wire: Wire): Promise<unknown>;
+/** The backend's answer, recorded and frozen: what the backend said is evidence no check may rewrite. */
+export declare function answered(landed: Timed, sent: Sent & {
+    pacing: Pacing | undefined;
+}, wire: Wire): Promise<Exchange>;
+//# sourceMappingURL=answer.d.ts.map

package/dist/api/client/answer.js

@@ -0,0 +1,143 @@
+/** The exchange an attempt leaves: the backend's answer, or a network failure recorded as status 0. */
+import { networkInterfaces } from "node:os";
+import { INLINE_BODY_LIMIT } from "../runtime/exchanges/media.js";
+import { answerBody, readSaveAs } from "../runtime/cookies/save-as.js";
+import { recordResponseHeaders } from "../runtime/cookies/set-cookie.js";
+import { classifyNetworkError, describeNetworkKind, NetworkError } from "../errors/network.js";
+import { hasUsableInterface, refineNetworkKind } from "../runtime/network/interfaces.js";
+import { sha256Hex } from "../runtime/exchanges/bytes.js";
+import { headerValue } from "../runtime/headers.js";
+import { DEFAULT_MAX_RETRY_AFTER_MS, retryAfterVerdict } from "../runtime/rate-limit/retry-after.js";
+import { requestIdOf, requestMessageBytes, responseMessageBytes } from "./message.js";
+import { readPath } from "./read-path.js";
+/** The error to raise for a failed send: a recorded `NetworkError`, or the error itself when it is not the network's. */
+export async function failed(error, sent, wire) {
+    const kind = networkKindOf(error, wire.network?.interfaces);
+    if (kind === null)
+        return error;
+    const { request, probe } = sent;
+    const url = sent.url.toString();
+    const message = `${request.method} ${url} failed (${kind}: ${describeNetworkKind(kind)})`;
+    const exchange = {
+        at: Date.now(),
+        durationMs: Math.round(performance.now() - sent.started),
+        method: request.method,
+        network: { attempt: sent.attempt, kind, message },
+        requestBody: request.options.body,
+        requestBytes: probe.requestBytes,
+        requestHeaders: sent.headers,
+        requestId: probe.requestId,
+        responseBody: { error: "network", kind, message },
+        responseBytes: 0,
+        responseHeaders: {},
+        seq: wire.nextSeq(),
+        status: 0,
+        url,
+        ...stamped(sent),
+    };
+    await wire.deliver(exchange, request.resolved?.entity ?? undefined);
+    return new NetworkError({ attempts: sent.attempt + 1, cause: error, kind, message, method: request.method, url });
+}
+/* What failed, refined to offline when this machine has no usable interface; `null` when it was not the network. */
+function networkKindOf(error, interfaces) {
+    const read = interfaces ?? networkInterfaces;
+    const raw = classifyNetworkError(error);
+    if (raw !== null)
+        return refineNetworkKind(raw, read);
+    return hasUsableInterface(read) ? null : "offline";
+}
+/** The backend's answer, recorded and frozen: what the backend said is evidence no check may rewrite. */
+export async function answered(landed, sent, wire) {
+    const { request, headers, body, url } = sent;
+    const { response, bodyBytes, digest } = landed;
+    const responseHeaders = recordResponseHeaders(response.headers);
+    const exchange = {
+        at: landed.at,
+        durationMs: Math.round(performance.now() - landed.started),
+        method: request.method,
+        requestBody: request.options.body,
+        requestBytes: requestMessageBytes({ method: request.method, url }, headers, body),
+        requestHeaders: headers,
+        requestId: requestIdOf(headers, responseHeaders),
+        responseBody: landed.parsed,
+        responseBytes: responseMessageBytes(response, responseHeaders, bodyBytes),
+        responseHeaders,
+        ...(digest === undefined ? {} : { responseDigest: digest }),
+        ...requestDigestOf(body),
+        seq: wire.nextSeq(),
+        status: response.status,
+        url: url.toString(),
+        ...paced(sent.pacing, landed.room),
+        ...stamped(sent),
+        ...traveled(landed, url),
+        ...overLimit(response.status, responseHeaders, wire.network),
+    };
+    registerSecrets(wire, exchange, request.options.context?.secrets ?? []);
+    await wire.deliver(exchange, request.resolved?.entity ?? undefined);
+    return Object.freeze(exchange);
+}
+/* The credentials a recipe will read from this answer, a form's included, scrubbed before anything records it. */
+function registerSecrets(wire, exchange, addresses) {
+    const headers = exchange.responseHeaders;
+    const source = {
+        body: answerBody({ body: exchange.responseBody, headers }),
+        cookies: {},
+        headers,
+        readJson: readPath,
+    };
+    for (const address of addresses) {
+        const value = readSaveAs(address, source);
+        if (typeof value === "string")
+            wire.redactor.registerSecret(value);
+    }
+}
+/* A body that will be stored by reference is hashed once, from the text that was sent. */
+function requestDigestOf(body) {
+    if (body.text === undefined || body.bytes <= INLINE_BODY_LIMIT)
+        return {};
+    return { requestDigest: { bytes: body.bytes, sha256: sha256Hex(Buffer.from(body.text)) } };
+}
+/* A 429 or 503 asking for a longer wait than the API tester accepts is marked before anything records it. */
+function overLimit(status, headers, network) {
+    const limitMs = network?.maxRetryAfterMs ?? DEFAULT_MAX_RETRY_AFTER_MS;
+    const exceeded = retryAfterVerdict({ header: headerValue(headers, "retry-after"), limitMs, status });
+    return exceeded === undefined ? {} : { retryAfterExceeded: exceeded };
+}
+function paced(pacing, room) {
+    return {
+        ...(pacing === undefined ? {} : { rateLimitCategory: pacing.rule.category, rateLimitSource: pacing.rule.source }),
+        ...(room === undefined ? {} : { rateLimitHadRoom: room }),
+    };
+}
+/* The redirects it followed, where it landed when that is elsewhere, and the cookies it was handed. */
+function traveled(landed, url) {
+    const cookies = landed.jar.snapshot();
+    const landing = landed.landing.toString();
+    return {
+        ...(landed.hops.length === 0 ? {} : { redirects: landed.hops }),
+        ...(landing === url.toString() ? {} : { finalUrl: landing }),
+        ...(Object.keys(cookies).length === 0 ? {} : { cookies }),
+    };
+}
+/** Who sent it, with which credential, for what, and which documented operation it is. */
+function stamped({ request, placement }) {
+    const { resolved, operationId, options } = request;
+    const { principal, schemes } = placement;
+    const context = options.context ?? {};
+    return {
+        /* Only a request meant to be refused is a probe; a dedicated credential alone is ordinary traffic. */
+        ...(options.probe === true ? { probe: true } : {}),
+        ...(operationId === undefined ? {} : { operationId }),
+        ...(resolved === null ? {} : { template: resolved.template }),
+        ...(resolved?.pathParams === undefined ? {} : { pathParams: resolved.pathParams }),
+        ...(principal === undefined ? {} : { principal }),
+        ...(schemes.length === 0 ? {} : { schemes }),
+        ...(placement.forged ? { forged: true } : {}),
+        ...(context.purpose === undefined ? {} : { purpose: context.purpose }),
+        ...(context.issuedBy === undefined ? {} : { issuedBy: context.issuedBy }),
+        ...(context.check === undefined ? {} : { check: context.check }),
+        ...(context.subject === undefined ? {} : { subject: context.subject }),
+        ...(options.fixture === undefined ? {} : { fixture: options.fixture }),
+    };
+}
+//# sourceMappingURL=answer.js.map