@jterrazz/test 18.1.0 → 18.3.0

package/dist/index.js

@@ -1,8 +1,8 @@
 import { a as endGroup, i as SIGNALS_GROUPS, o as signalGroup, r as KILL_GRACE_MS, t as ServedProcess } from "./shared-serve.js";
 import { i as safeRealpath, r as resolveRoot } from "./shared-resolve.js";
 import { a as getCallerDir, n as deferRewritesTo, r as writeInPlace, t as callSiteOf } from "./shared-in-place.js";
-import { t as isRecord } from "./shared-json-shape.js";
 import { n as refusal$1, t as invariant } from "./shared-refusal.js";
+import { t as isRecord } from "./shared-json-shape.js";
 import { a as field$1, c as containerLogs, d as findContainersByLabel, f as inspectContainer, h as requireDockerDaemon, l as execInContainer, m as removeContainers, p as readContainerFile, r as TestcontainersAdapter, u as fieldOf } from "./shared-testcontainers.adapter.js";
 import { _ as Matcher, d as structuralEquals, g as placeholderStringMatches, h as hasPlaceholders, l as isPlainObject, m as textEquals, n as isStreamBody, p as textContains, r as declared, u as renderExpected, v as match, y as CaptureScope } from "./shared-exchange.js";
 import { a as RUN_KEYS, s as SpecSyntaxError } from "./shared-spec-grammar.js";
@@ -24,9 +24,11 @@ import { basename, dirname, isAbsolute, join, normalize, relative, resolve, sep
 import { execFileSync, spawn, spawnSync } from "node:child_process";
 import { readdir } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
-import { createServer } from "node:http";
+import { connect, isIP } from "node:net";
+import { createServer, request } from "node:http";
 import { tmpdir } from "node:os";
 import { TestRunner, describe, it, onTestFinished, vi } from "vitest";
+import { checkServerIdentity, connect as connect$1, getCACertificates } from "node:tls";
 import { mock, mockDeep } from "vitest-mock-extended";
 //#region src/expectations/disk/directory.ts
 const DEFAULT_IGNORES = [
@@ -656,6 +658,11 @@ function createDockerReader(testDir, inspect = inspectContainer) {
 }
 //#endregion
 //#region src/expectations/http/response.ts
+/** A fresh golden records the content-type alone, and a golden with no body is given the body the response carried. */
+const DEFAULT_RECORDING = {
+	bodyKeptAbsent: false,
+	headers: ["content-type"]
+};
 /** Read-only accessor for an HTTP response, compared by `expect(...).toMatch(...)`. */
 var ResponseAccessor = class {
 	/** The JSON value the body holds, or its text when it is not JSON; null when the body is empty. */
@@ -664,15 +671,21 @@ var ResponseAccessor = class {
 	captures;
 	/** Response headers as a flat, lower-cased key-value map. */
 	headers;
+	/** @internal */
+	recording;
 	status;
 	/** @internal */
 	testDir;
-	constructor(response, testDir, captures) {
+	/** Why the exchange never answered, a golden's `unreachable: <reason>` line; undefined when it answered. */
+	unreachable;
+	constructor(response, testDir, captures, recording = DEFAULT_RECORDING) {
 		this.body = response.body;
 		this.headers = response.headers;
 		this.status = response.status;
+		this.unreachable = response.unreachable;
 		this.testDir = testDir;
 		this.captures = captures ?? new CaptureScope();
+		this.recording = recording;
 	}
 };
 //#endregion
@@ -1121,6 +1134,9 @@ function parseHeaders(headerLines, fileName) {
 }
 const PARAMETERS = /;.*$/su;
 const START_LINE = /^HTTP\/1\.1\s+(?<status>\S+)(?:\s+.*)?$/u;
+const UNREACHABLE_LINE = /^unreachable:\s*(?<reason>\S.*)$/u;
+/** The one line an exchange that never answered is written as. */
+const unreachableLine = (reason) => `unreachable: ${reason}`;
 const TEXT_MEDIA_TYPES = /* @__PURE__ */ new Set([
 	"application/javascript",
 	"application/x-ndjson",
@@ -1170,12 +1186,14 @@ function statedContentType(headers) {
 }
 function parseResponseFile(content, fileName, contentType) {
 	const { body, headerLines, startLine } = splitSections(content);
+	const reason = UNREACHABLE_LINE.exec(startLine.trim())?.groups?.reason;
+	if (reason !== void 0) return unreachableFile(reason, headerLines.length > 0 || body.length > 0, fileName);
 	const status = START_LINE.exec(startLine.trim())?.[1];
 	if (status === void 0) throw new Error(refusal$1({
-		fix: "start the response file with its status line: \"HTTP/1.1 200 OK\"",
+		fix: "start the response file with its status line: \"HTTP/1.1 200 OK\", or \"unreachable: <reason>\" for an exchange that never answers",
 		found: `${fileName}: the first line is "${startLine}"`,
 		read: "docs/guides/api-specs.md#http-request-files-full-format",
-		why: "A response file opens on `HTTP/1.1 <status>`."
+		why: "A response file opens on `HTTP/1.1 <status>`, or is the one line `unreachable: <reason>`."
 	}));
 	const headers = parseHeaders(headerLines, fileName);
 	return {
@@ -1185,6 +1203,25 @@ function parseResponseFile(content, fileName, contentType) {
 		status
 	};
 }
+function unreachableFile(reason, more, fileName) {
+	if (more) throw new Error(refusal$1({
+		fix: "keep the one line `unreachable: <reason>`, or state the status the exchange answers",
+		found: `${fileName}: "unreachable: ${reason}" is followed by headers or a body`,
+		read: "docs/guides/api-specs.md#unreachable-is-a-result",
+		why: "An exchange that never answered carries no header and no body, so its golden is one line."
+	}));
+	return unreachableResponse(reason);
+}
+/** The golden of an exchange that never answered: its reason, and no status, header or body. */
+function unreachableResponse(reason) {
+	return {
+		body: void 0,
+		hasBody: false,
+		headers: {},
+		status: "",
+		unreachable: reason
+	};
+}
 const STATUS_TEXT = {
 	200: "OK",
 	201: "Created",
@@ -1193,6 +1230,8 @@ const STATUS_TEXT = {
 	301: "Moved Permanently",
 	302: "Found",
 	304: "Not Modified",
+	307: "Temporary Redirect",
+	308: "Permanent Redirect",
 	400: "Bad Request",
 	401: "Unauthorized",
 	403: "Forbidden",
@@ -1206,6 +1245,7 @@ const STATUS_TEXT = {
 };
 /** A body is written as text or JSON by its `content-type`, the actual response's when the fixture states none. */
 function serializeResponseFile(response, contentType) {
+	if (response.unreachable !== void 0) return `${unreachableLine(response.unreachable)}\n`;
 	const statusNumber = Number(response.status);
 	const statusText = STATUS_TEXT[statusNumber];
 	const lines = [`HTTP/1.1 ${response.status}${statusText === void 0 ? "" : ` ${statusText}`}`];
@@ -1231,26 +1271,49 @@ function isJsonLike(text) {
 //#endregion
 //#region src/expectations/goldens/response-goldens.ts
 const STATUS_CODE = /^\d+$/u;
-/** Headers are the intersection with the actual response, so a freshly updated fixture passes the next run. */
-function buildUpdatedResponse(previous, actual, workdir) {
-	const scope = new CaptureScope();
-	const status = previous && structuralEquals(previous.status, String(actual.status), scope) ? previous.status : String(actual.status);
+const outcomeOf = (response) => response.unreachable === void 0 ? `HTTP/1.1 ${response.status}` : unreachableLine(response.unreachable);
+function updatedUnreachable(previous, reason, scope) {
+	return unreachableResponse(previous?.unreachable !== void 0 && structuralEquals(previous.unreachable, reason, scope) ? previous.unreachable : reason);
+}
+function updatedHeaders(previous, actual, scope) {
 	const headers = {};
-	if (previous) for (const [key, value] of Object.entries(previous.headers)) {
+	if (previous === null) {
+		for (const name of (actual.recording ?? DEFAULT_RECORDING).headers) {
+			const actualValue = actual.headers[name.toLowerCase()];
+			if (actualValue !== void 0) headers[name.toLowerCase()] = actualValue;
+		}
+		return headers;
+	}
+	for (const [key, value] of Object.entries(previous.headers)) {
 		const actualValue = actual.headers[key.toLowerCase()];
-		if (actualValue === void 0) continue;
-		headers[key] = structuralEquals(value, actualValue, scope) ? value : actualValue;
+		if (actualValue !== void 0) headers[key] = structuralEquals(value, actualValue, scope) ? value : actualValue;
 	}
-	else if (actual.headers["content-type"] !== void 0) headers["content-type"] = actual.headers["content-type"];
-	const hasBody = actual.body !== null && actual.body !== void 0;
+	return headers;
+}
+function updatedBody(previous, actual, workdir) {
+	const hasBody = !((actual.recording ?? DEFAULT_RECORDING).bodyKeptAbsent && previous?.hasBody === false) && actual.body !== null && actual.body !== void 0;
 	return {
 		body: previous?.hasBody === true && hasBody ? mergePreservingPlaceholders(previous.body, actual.body, workdir) : mergePreservingPlaceholders(null, actual.body, workdir),
-		hasBody,
-		headers,
+		hasBody
+	};
+}
+/** Headers are the intersection with the actual response, so a freshly updated fixture passes the next run. */
+function buildUpdatedResponse(stated, actual, workdir) {
+	const scope = new CaptureScope();
+	if (actual.unreachable !== void 0) return updatedUnreachable(stated, actual.unreachable, scope);
+	const previous = stated?.unreachable === void 0 ? stated : null;
+	const status = previous && structuralEquals(previous.status, String(actual.status), scope) ? previous.status : String(actual.status);
+	return {
+		...updatedBody(previous, actual, workdir),
+		headers: updatedHeaders(previous, actual, scope),
 		status
 	};
 }
+function compareOutcome(name, expected, actual, scope) {
+	return structuralEquals(expected.unreachable, actual.unreachable, scope) ? null : `Response outcome mismatch (${name})\n  expected: ${outcomeOf(expected)}\n  received: ${outcomeOf(actual)}`;
+}
 function compareResponse(name, expected, actual, scope) {
+	if (expected.unreachable !== void 0 || actual.unreachable !== void 0) return compareOutcome(name, expected, actual, scope);
 	if (!(STATUS_CODE.test(expected.status) ? Number(expected.status) === actual.status : structuralEquals(expected.status, String(actual.status), scope))) return `Response status mismatch (${name})\n  expected: ${expected.status}\n  received: ${actual.status}`;
 	for (const [key, value] of Object.entries(expected.headers)) {
 		const actualValue = actual.headers[key.toLowerCase()];
@@ -1603,7 +1666,7 @@ function declaredDatabaseKeys(services) {
 }
 //#endregion
 //#region src/services/containers/run-setup-container.adapter.ts
-function answered(value) {
+function answered$1(value) {
 	const error = field$1(value, "error");
 	if (typeof error === "string") return { error };
 	const host = field$1(value, "host");
@@ -1634,7 +1697,7 @@ var RunSetupContainer = class {
 		this.request = request;
 	}
 	async start() {
-		const answer = answered(await (await fetch(`${this.url}/containers`, {
+		const answer = answered$1(await (await fetch(`${this.url}/containers`, {
 			body: JSON.stringify(this.request),
 			method: "POST"
 		})).json());
@@ -2238,24 +2301,7 @@ function defineAction(definition) {
 	};
 }
 //#endregion
-//#region src/specifications/api/request/http.result.ts
-/** Result from an HTTP action (.request(), .get(), .post(), .put(), .delete()). */
-var HttpResult = class extends BaseResult {
-	responseData;
-	constructor(options) {
-		super(options);
-		this.responseData = options.response;
-	}
-	/** Access the HTTP response (status, headers, body) for assertions. */
-	get response() {
-		return new ResponseAccessor(this.responseData, this.testDir, this.captures);
-	}
-	get status() {
-		return this.responseData.status;
-	}
-};
-//#endregion
-//#region src/specifications/api/request/request-file.ts
+//#region src/expectations/http/request-file.ts
 function parseRequestFile(content, fileName) {
 	const { body, headerLines, startLine } = splitSections(content);
 	const start = /^(?<method>[A-Z]+)\s+(?<path>\S+)$/u.exec(startLine.trim());
@@ -2274,6 +2320,23 @@ function parseRequestFile(content, fileName) {
 	};
 }
 //#endregion
+//#region src/specifications/api/request/http.result.ts
+/** Result from an HTTP action (.request(), .get(), .post(), .put(), .delete()). */
+var HttpResult = class extends BaseResult {
+	responseData;
+	constructor(options) {
+		super(options);
+		this.responseData = options.response;
+	}
+	/** Access the HTTP response (status, headers, body) for assertions. */
+	get response() {
+		return new ResponseAccessor(this.responseData, this.testDir, this.captures);
+	}
+	get status() {
+		return this.responseData.status;
+	}
+};
+//#endregion
 //#region src/specifications/api/request/route.ts
 /** A path with no `:name` segment is sent as written; `{ params: {} }` states that it is the route. */
 const params = {
@@ -2356,15 +2419,15 @@ const ACCESSORS = [
 		probe: ".directory("
 	}
 ];
-const NO_WORKDIR = { workDir: null };
+const NO_WORKDIR$1 = { workDir: null };
 function bodyOf(body, testDir) {
 	const content = readFileSync(resolve(testDir, body.path), "utf8");
 	return body.path.endsWith(".json") ? JSON.parse(content) : content;
 }
-function writtenRequest(source, testDir) {
+function writtenRequest$1(source, testDir) {
 	return typeof source === "string" ? parseRequestFile(dedent(source), "the request in place") : parseRequestFile(readFileSync(resolve(testDir, source.path), "utf8"), source.path);
 }
-async function send({ body, headers: written, method, path, template }, read, { server }, { config, testDir }) {
+async function send$1({ body, headers: written, method, path, template }, read, { server }, { config, testDir }) {
 	if (isDiskDirectory(body)) throw new TypeError(refusal$1("disk-named-by-relative-path-at-runtime", {
 		fix: `name one file: .${method.toLowerCase()}(${JSON.stringify(path)}, file('./__requests__/body.json'))`,
 		found: `.${method.toLowerCase()}(${JSON.stringify(path)}, directory(${JSON.stringify(body.path)})), a directory where the body is one file`
@@ -2384,15 +2447,15 @@ async function send({ body, headers: written, method, path, template }, read, {
 }
 //#endregion
 //#region src/specifications/api/api.composition.ts
-const composition$6 = {
+const composition$7 = {
 	actions: [
 		defineAction({
 			accessors: ACCESSORS,
 			name: "request",
-			perform: async ([source], read, adapters, run) => await send(writtenRequest(source, run.testDir), read, adapters, run),
+			perform: async ([source], read, adapters, run) => await send$1(writtenRequest$1(source, run.testDir), read, adapters, run),
 			prepare: ([source]) => {
 				if (typeof source !== "string") requireDiskFile("request", source, ".http");
-				return NO_WORKDIR;
+				return NO_WORKDIR$1;
 			},
 			row: {
 				group: "Terminal action",
@@ -2404,13 +2467,13 @@ const composition$6 = {
 			accessors: ACCESSORS,
 			name: "get",
 			options: [params],
-			perform: async ([path, options], read, adapters, run) => await send({
+			perform: async ([path, options], read, adapters, run) => await send$1({
 				method: "GET",
 				...routeRequest("GET", path, options)
 			}, read, adapters, run),
 			prepare: ([path, options]) => {
 				routeRequest("GET", path, options);
-				return NO_WORKDIR;
+				return NO_WORKDIR$1;
 			},
 			row: {
 				group: "Terminal action",
@@ -2422,14 +2485,14 @@ const composition$6 = {
 			accessors: ACCESSORS,
 			name: "post",
 			options: [params],
-			perform: async ([path, body, options], read, adapters, run) => await send({
+			perform: async ([path, body, options], read, adapters, run) => await send$1({
 				body,
 				method: "POST",
 				...routeRequest("POST", path, options)
 			}, read, adapters, run),
 			prepare: ([path, _body, options]) => {
 				routeRequest("POST", path, options);
-				return NO_WORKDIR;
+				return NO_WORKDIR$1;
 			},
 			row: {
 				group: "Terminal action",
@@ -2441,14 +2504,14 @@ const composition$6 = {
 			accessors: ACCESSORS,
 			name: "put",
 			options: [params],
-			perform: async ([path, body, options], read, adapters, run) => await send({
+			perform: async ([path, body, options], read, adapters, run) => await send$1({
 				body,
 				method: "PUT",
 				...routeRequest("PUT", path, options)
 			}, read, adapters, run),
 			prepare: ([path, _body, options]) => {
 				routeRequest("PUT", path, options);
-				return NO_WORKDIR;
+				return NO_WORKDIR$1;
 			},
 			row: {
 				group: "Terminal action",
@@ -2460,13 +2523,13 @@ const composition$6 = {
 			accessors: ACCESSORS,
 			name: "delete",
 			options: [params],
-			perform: async ([path, options], read, adapters, run) => await send({
+			perform: async ([path, options], read, adapters, run) => await send$1({
 				method: "DELETE",
 				...routeRequest("DELETE", path, options)
 			}, read, adapters, run),
 			prepare: ([path, options]) => {
 				routeRequest("DELETE", path, options);
-				return NO_WORKDIR;
+				return NO_WORKDIR$1;
 			},
 			row: {
 				group: "Terminal action",
@@ -2501,7 +2564,7 @@ const composition$6 = {
 	}
 };
 const apiDefinition = defineSpecification()({
-	...composition$6,
+	...composition$7,
 	adapters: (config) => ({
 		clock: processClock,
 		databases: databaseSet(config),
@@ -2511,6 +2574,448 @@ const apiDefinition = defineSpecification()({
 	locate: getCallerDir
 });
 //#endregion
+//#region src/specifications/api/deployed/connect.capability.ts
+/** Read by the exchange, never armed: the address is where one request is sent, not a state of the world. */
+const connect$2 = defineCapability({
+	initial: null,
+	name: "connect",
+	phase: 0,
+	reduce: (_held, [address]) => address,
+	row: {
+		group: "Setup",
+		name: ".connect()",
+		probe: ".connect("
+	}
+});
+//#endregion
+//#region src/specifications/api/deployed/exchange.result.ts
+const EXCHANGE_RESULT_ROWS = [{
+	group: "Result accessor",
+	name: ".response",
+	probe: "result.response"
+}, {
+	group: "Result accessor",
+	name: ".tls",
+	probe: "result.tls"
+}];
+/** What one request to a deployed api hands back: the response, or why none came, and the certificate it came over; no table and no disk, which a deployed api keeps to itself. */
+var ExchangeResult = class {
+	answer;
+	recording;
+	scope = new CaptureScope();
+	testDir;
+	/** The certificate an https request was presented and the trust check's verdict; undefined over http, or when no handshake completed. */
+	tls;
+	constructor(options) {
+		this.answer = options.response;
+		this.recording = options.recording;
+		this.testDir = options.testDir;
+		this.tls = options.tls;
+	}
+	/** The whole response (status, headers, body), or `unreachable: <reason>`, compared whole: `toMatch(<.http text>)` or `toMatch(file(...))`. */
+	get response() {
+		return new ResponseAccessor(this.answer, this.testDir, this.scope, this.recording);
+	}
+};
+//#endregion
+//#region src/specifications/api/deployed/target.ts
+const SCHEME = /^[a-z][a-z\d+.-]*:\/\//iu;
+const BRACKETED = /^\[(?<host>[^\]]+)\](?::(?<port>\d+))?$/u;
+const HOST_AND_PORT = /^(?<host>[^:[\]\s]+)(?::(?<port>\d+))?$/u;
+/** The host a URL names, an IPv6 literal without its brackets. */
+function hostOf(url) {
+	return url.hostname.startsWith("[") ? url.hostname.slice(1, -1) : url.hostname;
+}
+/** The port a URL names, or its scheme's. */
+function portOf(url) {
+	if (url.port !== "") return Number(url.port);
+	return url.protocol === "https:" ? 443 : 80;
+}
+function refusedTarget(target, found, fix) {
+	return new Error(refusal$1({
+		fix,
+		found: `${JSON.stringify(target)}, ${found}`,
+		read: "docs/guides/api-specs.md#the-target",
+		why: "A request to a deployed api goes to one absolute http(s) URL: written whole, or a path from the `url` the specification names."
+	}));
+}
+/** A path is read from the base URL as written, its own path kept: `https://site.test/app` and `/health` are `https://site.test/app/health`. */
+function targetUrl(target, base) {
+	if (SCHEME.test(target)) {
+		const url = new URL(target);
+		if (url.protocol !== "http:" && url.protocol !== "https:") throw refusedTarget(target, `a ${url.protocol.slice(0, -1)} URL`, "name an http:// or https:// URL");
+		return url;
+	}
+	if (!target.startsWith("/")) throw refusedTarget(target, "neither an absolute URL nor a path", "write the URL whole, `https://site.test/health`, or a path from the `url` option, `/health`");
+	return new URL(`${base.replace(/\/+$/u, "")}${target}`);
+}
+/** `host:port`, `[v6]:port`, or a bare host, which keeps the URL's port. */
+function connectAddress(written, url) {
+	const address = written.trim();
+	const match = BRACKETED.exec(address) ?? HOST_AND_PORT.exec(address);
+	const host = match?.groups?.host;
+	if (host === void 0 || address.startsWith("[") && isIP(host) !== 6) throw new Error(refusal$1({
+		fix: "write the address as `.connect('10.0.0.5:30443')`, `.connect('[fd7a::1]:443')` or `.connect('node.test')`",
+		found: `.connect(${JSON.stringify(written)}), no address`,
+		read: "docs/guides/api-specs.md#setup-connect",
+		why: "`.connect()` names the one address the socket opens on: a host, and a port when it is not the port of the URL."
+	}));
+	const port = match?.groups?.port;
+	return {
+		host,
+		port: port === void 0 ? portOf(url) : Number(port)
+	};
+}
+//#endregion
+//#region src/specifications/api/deployed/tls-facts.ts
+const DAY_MS = 864e5;
+function firstOf(value) {
+	return Array.isArray(value) ? value[0] : value;
+}
+function altNamesOf(certificate) {
+	return (certificate.subjectaltname ?? "").split(",").map((name) => name.trim().slice(name.trim().indexOf(":") + 1)).filter((name) => name !== "");
+}
+/** Read at the moment of the exchange, so `daysRemaining` is the margin the deployed api had when it answered. */
+function tlsFacts(certificate, verdict, now) {
+	const validTo = new Date(certificate.valid_to);
+	return {
+		altNames: altNamesOf(certificate),
+		authorizationError: verdict.authorizationError,
+		authorized: verdict.authorizationError === void 0,
+		covers: (host) => checkServerIdentity(host, certificate) === void 0,
+		daysRemaining: Math.floor((validTo.getTime() - now) / DAY_MS),
+		issuer: firstOf(certificate.issuer.CN) ?? firstOf(certificate.issuer.O) ?? "",
+		protocol: verdict.protocol,
+		subject: firstOf(certificate.subject.CN) ?? "",
+		validFrom: new Date(certificate.valid_from),
+		validTo
+	};
+}
+//#endregion
+//#region src/specifications/api/deployed/unreachable.ts
+/** Why an exchange never answered, as the `unreachable: <reason>` line of its golden reads it. */
+const TIMEOUT = "timeout";
+const TLS = "tls";
+const REASONS = {
+	EAI_AGAIN: "dns",
+	EAI_FAIL: "dns",
+	EAI_NODATA: "dns",
+	EAI_NONAME: "dns",
+	ECONNABORTED: "reset",
+	ECONNREFUSED: "refused",
+	ECONNRESET: "reset",
+	EHOSTDOWN: "no route",
+	EHOSTUNREACH: "no route",
+	ENETDOWN: "no route",
+	ENETUNREACH: "no route",
+	ENODATA: "dns",
+	ENOTFOUND: "dns",
+	EPIPE: "reset"
+};
+/** The code node raised, when it raised one. */
+function codeOf(error) {
+	if (typeof error === "string") return error === "" ? void 0 : error;
+	const code = error !== null && typeof error === "object" ? Reflect.get(error, "code") : void 0;
+	return typeof code === "string" && code !== "" ? code : void 0;
+}
+/** `dns`, `refused`, `reset`, `no route`, or the code node raised; a handshake's own failure is `tls <CODE>`, its network's reads as the network's. */
+function unreachableReason(error, duringHandshake = false) {
+	const code = codeOf(error);
+	const reason = code === void 0 ? void 0 : REASONS[code];
+	if (reason !== void 0) return reason;
+	if (duringHandshake) return `${TLS} ${code ?? "handshake"}`;
+	return code ?? (error instanceof Error ? error.message : String(error));
+}
+/** A certificate the trust check refused, by the code it refused with. */
+function refusedCertificate(code) {
+	return `${TLS} ${code}`;
+}
+//#endregion
+//#region src/specifications/api/deployed/transport.ts
+const USER_AGENT = "@jterrazz/test";
+function flatHeaders(headers) {
+	return Object.fromEntries(Object.entries(headers).map(([name, value]) => [name, Array.isArray(value) ? value.join(", ") : String(value)]));
+}
+function headersOf(sent) {
+	const headers = {
+		host: sent.url.host,
+		"user-agent": USER_AGENT
+	};
+	for (const [name, value] of Object.entries(sent.headers)) headers[name.toLowerCase()] = value;
+	return headers;
+}
+async function opened(socket, event) {
+	await new Promise((resolve, reject) => {
+		socket.once(event, () => {
+			resolve();
+		});
+		socket.once("error", reject);
+	});
+}
+async function openSecure(address, url, route, hold) {
+	const name = hostOf(url);
+	const socket = connect$1({
+		checkServerIdentity: (_host, certificate) => checkServerIdentity(name, certificate),
+		host: address.host,
+		port: address.port,
+		rejectUnauthorized: false,
+		...route.ca === void 0 ? {} : { ca: [...getCACertificates("default"), route.ca] },
+		...isIP(name) === 0 ? { servername: name } : {}
+	});
+	hold(socket);
+	try {
+		await opened(socket, "secureConnect");
+	} catch (error) {
+		return {
+			tls: void 0,
+			unreachable: unreachableReason(error, true)
+		};
+	}
+	const refused = socket.authorized ? void 0 : codeOf(socket.authorizationError);
+	const tls = tlsFacts(socket.getPeerCertificate(), {
+		authorizationError: refused,
+		protocol: socket.getProtocol() ?? void 0
+	}, Date.now());
+	return refused === void 0 || route.insecure ? {
+		socket,
+		tls
+	} : {
+		tls,
+		unreachable: refusedCertificate(refused)
+	};
+}
+async function open$1(sent, route, hold) {
+	const address = route.connect ?? {
+		host: hostOf(sent.url),
+		port: portOf(sent.url)
+	};
+	if (sent.url.protocol === "https:") return await openSecure(address, sent.url, route, hold);
+	const socket = connect(address);
+	hold(socket);
+	await opened(socket, "connect");
+	return {
+		socket,
+		tls: void 0
+	};
+}
+async function exchanged(sent, socket) {
+	return await new Promise((resolve, reject) => {
+		const outgoing = request({
+			createConnection: () => socket,
+			headers: headersOf(sent),
+			method: sent.method,
+			path: `${sent.url.pathname}${sent.url.search}`
+		}, (response) => {
+			const chunks = [];
+			response.on("data", (chunk) => {
+				chunks.push(chunk);
+			});
+			response.once("end", () => {
+				resolve({
+					response,
+					text: Buffer.concat(chunks).toString("utf8")
+				});
+			});
+			response.once("error", reject);
+		});
+		outgoing.once("error", reject);
+		outgoing.end(sent.body);
+	});
+}
+async function answered(sent, route, hold, presented) {
+	const opening = await open$1(sent, route, hold);
+	presented(opening.tls);
+	if (!("socket" in opening)) return opening;
+	const { response, text } = await exchanged(sent, opening.socket);
+	return {
+		headers: flatHeaders(response.headers),
+		status: response.statusCode ?? 0,
+		text,
+		tls: opening.tls
+	};
+}
+/** One request and its whole response, under one deadline; a redirect is the answer, never followed. */
+async function exchange(sent, route) {
+	const sockets = [];
+	let tls;
+	let timer;
+	const deadline = new Promise((resolve) => {
+		timer = setTimeout(() => {
+			resolve({
+				tls,
+				unreachable: TIMEOUT
+			});
+		}, route.timeout);
+	});
+	try {
+		return await Promise.race([answered(sent, route, (held) => {
+			sockets.push(held);
+		}, (facts) => {
+			tls = facts;
+		}), deadline]);
+	} catch (error) {
+		return {
+			tls,
+			unreachable: unreachableReason(error)
+		};
+	} finally {
+		clearTimeout(timer);
+		for (const socket of sockets) socket.destroy();
+	}
+}
+//#endregion
+//#region src/specifications/api/deployed/request.action.ts
+const NO_WORKDIR = { workDir: null };
+function responseOf(answer) {
+	if (answer.unreachable !== void 0) return {
+		body: null,
+		headers: {},
+		status: 0,
+		unreachable: answer.unreachable
+	};
+	const contentType = answer.headers["content-type"];
+	return {
+		body: bodyKind(contentType) === "binary" ? null : readBody$1(answer.text, contentType) ?? null,
+		headers: answer.headers,
+		status: answer.status
+	};
+}
+async function send(written, read, { config, testDir }) {
+	const url = targetUrl(written.target, config.baseUrl);
+	const address = read(connect$2);
+	const answer = await exchange({
+		body: written.body,
+		headers: {
+			...written.headers,
+			...read(headers)
+		},
+		method: written.method,
+		url
+	}, {
+		ca: config.ca,
+		connect: address === null ? void 0 : connectAddress(address, url),
+		insecure: config.insecure,
+		timeout: config.timeout
+	});
+	return new ExchangeResult({
+		recording: config.recording,
+		response: responseOf(answer),
+		testDir,
+		tls: answer.tls
+	});
+}
+function writtenRequest(source, testDir) {
+	const parsed = typeof source === "string" ? parseRequestFile(dedent(source), "the request in place") : parseRequestFile(readFileSync(resolve(testDir, source.path), "utf8"), source.path);
+	return {
+		body: parsed.body,
+		headers: parsed.headers,
+		method: parsed.method,
+		target: parsed.path
+	};
+}
+/** A redirect is the answer, never followed; an exchange that never answered is the answer too, `unreachable: <reason>`. */
+const get = defineAction({
+	accessors: EXCHANGE_RESULT_ROWS,
+	name: "get",
+	perform: async ([target], read, _adapters, run) => await send({
+		headers: {},
+		method: "GET",
+		target
+	}, read, run),
+	row: {
+		group: "Terminal action",
+		name: ".get()",
+		probe: ".get('/"
+	}
+});
+//#endregion
+//#region src/specifications/api/deployed/deployed.composition.ts
+const composition$6 = {
+	actions: [defineAction({
+		accessors: EXCHANGE_RESULT_ROWS,
+		name: "request",
+		perform: async ([source], read, _adapters, run) => await send(writtenRequest(source, run.testDir), read, run),
+		prepare: ([source]) => {
+			if (typeof source !== "string") requireDiskFile("request", source, ".http");
+			return NO_WORKDIR;
+		},
+		row: {
+			group: "Terminal action",
+			name: ".request()",
+			probe: ".request(file("
+		}
+	}), get],
+	capabilities: [
+		connect$2,
+		headers,
+		sharing
+	],
+	options: {
+		ca: {
+			group: "Constructor option",
+			name: "ca",
+			probe: "ca:"
+		},
+		insecure: {
+			group: "Constructor option",
+			name: "insecure",
+			probe: "insecure:"
+		},
+		recordedHeaders: {
+			group: "Constructor option",
+			name: "recordedHeaders",
+			probe: "recordedHeaders:"
+		},
+		timeout: {
+			group: "Constructor option",
+			name: "timeout",
+			probe: "timeout:"
+		},
+		url: {
+			group: "Constructor option",
+			name: "url",
+			probe: "url:"
+		}
+	}
+};
+const apiDeployedDefinition = defineSpecification()({
+	...composition$6,
+	adapters: (_config) => ({}),
+	locate: getCallerDir
+});
+//#endregion
+//#region src/specifications/api/deployed/refused-setups.ts
+const IN_PROCESS_ONLY = /* @__PURE__ */ new Set([
+	"clock",
+	"delete",
+	"intercept",
+	"post",
+	"put",
+	"seed"
+]);
+function refusedSetup(name) {
+	return new Error(refusal$1({
+		fix: "seed, stub and pin the app with `server`, in this process; against a `url`, send the request (`.get()`, `.request()`) and compare the response",
+		found: `.${name}() on the chain of specification.api({ url })`,
+		read: "docs/guides/api-specs.md#deployed-target-url",
+		why: "A deployed api runs elsewhere: its database, its outbound network and its clock are its own, so its chain offers what a request can do, and a request other than a GET is written whole."
+	}));
+}
+/** The type already holds it; an untyped caller is told why rather than that the method is undefined. */
+function refusingInProcessSetups(chain) {
+	return new Proxy(chain, { get: (target, name, receiver) => {
+		if (typeof name === "string" && IN_PROCESS_ONLY.has(name)) return () => {
+			throw refusedSetup(name);
+		};
+		const value = Reflect.get(target, name, receiver);
+		if (typeof value !== "function") return value;
+		return (...args) => {
+			const next = Reflect.apply(value, target, args);
+			return next !== null && typeof next === "object" && !(next instanceof Promise) ? refusingInProcessSetups(next) : next;
+		};
+	} });
+}
+//#endregion
 //#region src/specifications/api/server/hono.adapter.ts
 const COMPOSED_HANDLER = "__COMPOSED_HANDLER";
 function targetOf(handler) {
@@ -2563,9 +3068,68 @@ var HonoAdapter = class {
 };
 //#endregion
 //#region src/specifications/api/api.handle.ts
+const DEFAULT_TIMEOUT_MS$1 = 5e3;
+const DEFAULT_RECORDED_HEADERS = ["content-type", "location"];
+const DEPLOYED_ONLY = [
+	"ca",
+	"insecure",
+	"recordedHeaders",
+	"timeout"
+];
+function refused(found, why, fix) {
+	return new Error(refusal$1({
+		fix,
+		found,
+		read: "docs/guides/api-specs.md#options",
+		why
+	}));
+}
+function refuseTarget(options) {
+	const hasServer = options.server !== void 0;
+	if (hasServer && options.url !== void 0) throw refused("specification.api({ server, url }), an app built here beside a deployed one", "`server` and `url` are exclusive: a request goes to the app this process builds, or to the one deployed at the url.", "keep `server` to test the app in this process, or `url` to probe the deployed one");
+	const deployedOnly = DEPLOYED_ONLY.filter((name) => options[name] !== void 0);
+	if (hasServer && deployedOnly.length > 0) throw refused(`specification.api({ server, ${deployedOnly.join(", ")} }), an option of a deployed api beside an app built here`, "`ca`, `insecure`, `recordedHeaders` and `timeout` shape requests sent over the network, which a `url` names; an app built in this process is answered without one.", "drop them, or name the deployed api with `url`");
+	if (!hasServer && (options.services !== void 0 || options.root !== void 0)) throw refused("specification.api({ url, services }), services beside a deployed url", "A deployed api is wired to its own services: services started here never reach it.", "drop `services` and `root`, or build the app with `server` to wire them");
+}
+function refuseUrl(url) {
+	if (typeof url !== "string" || url.trim() === "") throw refused(`specification.api({ url: ${JSON.stringify(url)} }), no app to specify`, "An api spec names the app it requests: a `server` it builds in this process, or a deployed `url`.", "build the app with `server`, or pass the absolute URL of the deployed api as `url`");
+	if (!/^https?:\/\/[^/\s]/u.test(url)) throw refused(`specification.api({ url: ${JSON.stringify(url)} }), no http(s) URL`, "A path is read from the base `url`, so the base is an absolute http:// or https:// URL.", "name the deployed api's base as an absolute URL, `url: 'https://site.test'`");
+}
+function refuseTimeout(timeout) {
+	if (timeout !== void 0 && (typeof timeout !== "number" || !Number.isFinite(timeout) || timeout <= 0)) throw refused(`specification.api({ url, timeout: ${typeof timeout === "number" ? String(timeout) : JSON.stringify(timeout)} }), no deadline`, "A request that never answers reads `unreachable: timeout` once its deadline passes, so the deadline is a positive number of milliseconds.", "pass the milliseconds one request may take, `timeout: 2000`, or leave the 5000 default");
+}
+/** Refused before anything starts: a target that is neither or both, and what a deployed target cannot carry. */
+function refuseOptions$1(options) {
+	refuseTarget(options);
+	if (options.server === void 0) {
+		refuseUrl(options.url);
+		refuseTimeout(options.timeout);
+	}
+}
+function openDeployed(options) {
+	const config = {
+		baseUrl: options.url,
+		ca: options.ca,
+		insecure: options.insecure ?? false,
+		recording: {
+			bodyKeptAbsent: true,
+			headers: options.recordedHeaders ?? DEFAULT_RECORDED_HEADERS
+		},
+		timeout: options.timeout ?? DEFAULT_TIMEOUT_MS$1
+	};
+	return {
+		api: refusingInProcessSetups(apiDeployedDefinition.open(config)),
+		cleanup: async () => {}
+	};
+}
 async function startApi(options) {
 	const callerDir = getCallerDir();
 	await registerMatchers();
+	refuseOptions$1(options);
+	if (options.server === void 0) return openDeployed(options);
+	return await startServed(options, callerDir);
+}
+async function startServed(options, callerDir) {
 	const root = resolveRoot(options.root, callerDir);
 	const services = declaredServices(options.services);
 	const databaseKeys = declaredDatabaseKeys(services);