@mark1russell7/service 0.4.0 → 0.5.0

package/build/http.js

@@ -0,0 +1,789 @@
+import { realClock } from "./clock.js";
+import { convertible, valueIn } from "@mark1russell7/quantity";
+import { createServer } from "node:http";
+//#region src/http/transport.ts
+/** This function gives the path of a request target, without its query and fragment. */
+const pathOf = (url) => {
+	const raw = url ?? "/";
+	const end = raw.search(/[?#]/);
+	const path = end === -1 ? raw : raw.slice(0, end);
+	if (path.startsWith("/")) return path;
+	try {
+		return new URL(raw).pathname;
+	} catch {
+		return path;
+	}
+};
+/** This function gives a knob in milliseconds, or infinity for a time without a bound. */
+const millisecondsOf = (knobs, name, owner = "httpTransport") => {
+	const amount = knobs[name];
+	if (amount === void 0) throw new Error(`${owner} needs the knob ${name}: it has no defaults`);
+	if (!convertible(amount.unit, "s")) throw new Error(`the knob ${name} is not a time`);
+	if (amount.value === "infinite") return Number.POSITIVE_INFINITY;
+	const value = valueIn(amount, "ms");
+	if (!(value >= 0)) throw new Error(`the knob ${name} is less than zero`);
+	return value;
+};
+/**
+* This function gives the `Retry-After` of the knob `server_retry_after`, in whole seconds, rounded
+* up. The knob is necessary, and it has a bound.
+*/
+const retryAfterOf = (knobs, owner) => {
+	const retryAfter = millisecondsOf(knobs, "server_retry_after", owner);
+	if (!Number.isFinite(retryAfter)) throw new Error("the knob server_retry_after has no bound: a Retry-After needs a time");
+	return String(Math.ceil(retryAfter / 1e3));
+};
+/** This function tells if the headers of a call of `writeHead` name a header, an object or a flat list of names and values. */
+const names = (headers, name) => {
+	if (Array.isArray(headers)) return headers.some((each, at) => at % 2 === 0 && String(each).toLowerCase() === name);
+	return typeof headers === "object" && headers !== null && Object.keys(headers).some((key) => key.toLowerCase() === name);
+};
+/** This function gives the headers of a call of `writeHead` without one header. */
+const without = (headers, name) => {
+	if (Array.isArray(headers)) {
+		const kept = [];
+		for (let at = 0; at + 1 < headers.length; at += 2) if (String(headers[at]).toLowerCase() !== name) kept.push(headers[at], headers[at + 1]);
+		return kept;
+	}
+	if (typeof headers !== "object" || headers === null) return headers;
+	return Object.fromEntries(Object.entries(headers).filter(([key]) => key.toLowerCase() !== name));
+};
+/**
+* This function applies the rule of `Retry-After` to a call of `writeHead`, and gives its arguments.
+* A 503 without `Retry-After` gets the time of `server_retry_after` (RFC 9110). A 500 loses each
+* `Retry-After`, from the call and from the response.
+*/
+const retryRule = (res, args, retryAfter) => {
+	const status = typeof args[0] === "number" ? args[0] : res.statusCode;
+	const at = typeof args[1] === "string" ? 2 : 1;
+	if (status === 503 && !res.hasHeader("retry-after") && !names(args[at], "retry-after")) res.setHeader("retry-after", retryAfter);
+	if (status !== 500) return args;
+	res.removeHeader("retry-after");
+	if (!names(args[at], "retry-after")) return args;
+	const given = [...args];
+	given[at] = without(args[at], "retry-after");
+	return given;
+};
+const STATUS_TEXT = {
+	404: "Not Found",
+	500: "Internal Server Error",
+	503: "Service Unavailable"
+};
+/**
+* This function makes a server of `node:http` a transport of the lifecycle (S6 A8 and A13). It is not
+* a framework: it has no routes, no body parser and no middleware.
+* - The count of work in flight comes from events: each response until its `close`, and each upgraded
+*   connection until its `close`.
+* - `stopIntake` closes the listener, and new connections get a refusal. It closes the idle connections
+*   at once and at each `server_idle_sweep_interval`. Each later response gets `Connection: close`.
+* - `drain` waits until no work is in flight, or until the deadline. It gives the cooperative abort to
+*   the handlers through their context.
+* - `close` destroys each connection. A second close gives the same promise.
+* - The mounts share one port. The first request handler that gives true answers. After the stop of
+*   the intake, only the mounts until `close transports` answer, and each other request gets a 503.
+*/
+const httpTransport = (server, knobs, options = {}) => {
+	const clock = options.clock ?? realClock;
+	const idleClose = millisecondsOf(knobs, "server_idle_close");
+	const sweepEvery = millisecondsOf(knobs, "server_idle_sweep_interval");
+	if (sweepEvery === 0) throw new Error("the knob server_idle_sweep_interval is zero: a sweep needs an interval above zero");
+	const retryAfterHeader = retryAfterOf(knobs, "httpTransport");
+	for (const derived of ["server_idle_close_hint", "server_idle_close_buffer"]) if (knobs[derived] !== void 0) throw new Error(`the knob ${derived} comes from the transport: give only server_idle_close`);
+	if (server.listenerCount("request") > 0 || server.listenerCount("upgrade") > 0) throw new Error("the server has a request or upgrade listener of its own: mount it as a handler");
+	const buffer = server.keepAliveTimeoutBuffer ?? 0;
+	if (Number.isFinite(idleClose) && idleClose <= buffer) throw new Error(`the knob server_idle_close is ${idleClose} ms, at or below the keepAliveTimeoutBuffer of the server, ${buffer} ms: the server closes an idle connection at keepAliveTimeout + keepAliveTimeoutBuffer`);
+	server.keepAliveTimeout = Number.isFinite(idleClose) ? idleClose - buffer : 0;
+	const declared = {
+		...knobs,
+		server_idle_close_hint: Number.isFinite(idleClose) ? {
+			value: Math.floor(server.keepAliveTimeout / 1e3),
+			unit: "s"
+		} : {
+			value: "infinite",
+			unit: "s"
+		},
+		server_idle_close_buffer: {
+			value: buffer,
+			unit: "ms"
+		}
+	};
+	const requestMounts = [];
+	const upgradeMounts = [];
+	const responses = /* @__PURE__ */ new Set();
+	const upgraded = /* @__PURE__ */ new Set();
+	const sockets = /* @__PURE__ */ new Set();
+	const idleWaiters = /* @__PURE__ */ new Set();
+	const closedWaiters = /* @__PURE__ */ new Set();
+	const intake = new AbortController();
+	const cooperative = new AbortController();
+	let life = null;
+	const context = {
+		intake: intake.signal,
+		signal: cooperative.signal,
+		get life() {
+			return life;
+		},
+		retryAfter: knobs.server_retry_after
+	};
+	let intakeOpen = true;
+	let listenerOpen = server.listening;
+	let serverClosed = !server.listening;
+	let sweep = null;
+	let closing = null;
+	const inFlight = () => responses.size + upgraded.size;
+	const report = (error, req) => {
+		try {
+			options.onError?.(error, req);
+		} catch {}
+	};
+	const settled = () => {
+		if (inFlight() === 0) for (const done of [...idleWaiters]) done();
+		if (closing !== null && inFlight() === 0 && sockets.size === 0 && serverClosed) for (const done of [...closedWaiters]) done();
+	};
+	const keepsAlive = () => intakeOpen && (options.keepAlive?.() ?? life?.keepAlive() ?? true);
+	const live = (mounts) => intakeOpen ? [...mounts] : mounts.filter((mount) => mount.until === "close transports");
+	const throughDrain = () => requestMounts.some((mount) => mount.until === "close transports") || upgradeMounts.some((mount) => mount.until === "close transports");
+	const closeListener = () => {
+		if (!listenerOpen) return;
+		listenerOpen = false;
+		server.close();
+	};
+	const startSweep = () => {
+		if (!Number.isFinite(sweepEvery) || closing !== null) return;
+		sweep = clock.after(sweepEvery, () => {
+			sweep = null;
+			if (closing !== null) return;
+			server.closeIdleConnections();
+			startSweep();
+		});
+	};
+	/**
+	* This function watches the headers of each response when they go, whatever wrote them. Each 503
+	* gets `Retry-After`, and a 500 gets none. The response closes its connection while the transport
+	* cannot keep it.
+	*/
+	const watchHeaders = (res) => {
+		const writeHead = res.writeHead;
+		res.writeHead = ((...args) => {
+			if (res.headersSent) return writeHead.apply(res, args);
+			if (!keepsAlive()) {
+				res.shouldKeepAlive = false;
+				res.setHeader("connection", "close");
+			}
+			return writeHead.apply(res, retryRule(res, args, retryAfterHeader));
+		});
+	};
+	const answer = (res, status, headers = {}) => {
+		if (res.headersSent) {
+			res.destroy();
+			return;
+		}
+		const body = STATUS_TEXT[status] ?? "";
+		res.writeHead(status, {
+			"content-type": "text/plain; charset=utf-8",
+			"content-length": String(Buffer.byteLength(body)),
+			...headers
+		});
+		res.end(body);
+	};
+	const refuse = (res) => answer(res, 503, {
+		"retry-after": retryAfterHeader,
+		connection: "close"
+	});
+	const route = async (req, res) => {
+		const mounts = live(requestMounts);
+		try {
+			for (const mount of mounts) {
+				const given = mount.handler(req, res, context);
+				if ((typeof given === "boolean" ? given : await given) || res.headersSent || res.writableEnded) return;
+			}
+		} catch (error) {
+			report(error, req);
+			if (!res.writableEnded) answer(res, 500);
+			return;
+		}
+		if (intakeOpen) answer(res, 404);
+		else refuse(res);
+	};
+	const onRequest = (req, res) => {
+		responses.add(res);
+		res.once("close", () => {
+			responses.delete(res);
+			settled();
+		});
+		watchHeaders(res);
+		route(req, res);
+	};
+	const onUpgrade = (req, socket, head) => {
+		socket.on("error", () => {});
+		const mount = live(upgradeMounts).find((each) => each.matches(req));
+		if (mount === void 0) {
+			const status = intakeOpen ? 404 : 503;
+			const extra = intakeOpen ? "" : `Retry-After: ${retryAfterHeader}\r\n`;
+			socket.end(`HTTP/1.1 ${status} ${STATUS_TEXT[status]}\r\nConnection: close\r\nContent-Length: 0\r\n${extra}\r\n`);
+			return;
+		}
+		if (socket.destroyed) return;
+		upgraded.add(socket);
+		socket.once("close", () => {
+			upgraded.delete(socket);
+			settled();
+		});
+		try {
+			mount.handler(req, socket, head, context);
+		} catch (error) {
+			report(error, req);
+			socket.destroy();
+		}
+	};
+	const onConnection = (socket) => {
+		sockets.add(socket);
+		socket.once("close", () => {
+			sockets.delete(socket);
+			settled();
+		});
+	};
+	server.on("request", onRequest);
+	server.on("upgrade", onUpgrade);
+	server.on("connection", onConnection);
+	server.on("listening", () => {
+		listenerOpen = true;
+		serverClosed = false;
+	});
+	server.on("close", () => {
+		listenerOpen = false;
+		serverClosed = true;
+		settled();
+	});
+	const remover = (list, entry) => () => {
+		const at = list.indexOf(entry);
+		if (at >= 0) list.splice(at, 1);
+		if (!intakeOpen && closing === null && !throughDrain()) closeListener();
+	};
+	return {
+		server,
+		knobs: declared,
+		get connections() {
+			return sockets.size;
+		},
+		get intakeStopped() {
+			return !intakeOpen;
+		},
+		mount(handler, mountOptions = {}) {
+			const entry = {
+				handler,
+				until: mountOptions.until ?? handler.until ?? "stop intake"
+			};
+			requestMounts.push(entry);
+			return remover(requestMounts, entry);
+		},
+		upgrade(match, handler, mountOptions = {}) {
+			const entry = {
+				matches: typeof match === "string" ? (req) => pathOf(req.url) === match : match,
+				handler,
+				until: mountOptions.until ?? handler.until ?? "stop intake"
+			};
+			upgradeMounts.push(entry);
+			return remover(upgradeMounts, entry);
+		},
+		async start(_signal, given) {
+			life = given;
+			if (closing !== null) throw new Error("the transport closed: a closed transport does not start again");
+			if (server.listenerCount("request") > 1 || server.listenerCount("upgrade") > 1) throw new Error("the server has a request or upgrade listener of its own: mount it as a handler");
+			if (server.listening) return;
+			const listen = options.listen;
+			if (listen === void 0) throw new Error("the server does not listen, and the transport has no listen options");
+			if (typeof listen === "function") {
+				await listen(server);
+				return;
+			}
+			await new Promise((resolve, reject) => {
+				const failed = (error) => {
+					server.off("listening", listened);
+					reject(error);
+				};
+				const listened = () => {
+					server.off("error", failed);
+					resolve();
+				};
+				server.once("error", failed);
+				server.once("listening", listened);
+				server.listen(listen);
+			});
+		},
+		stopIntake() {
+			if (!intakeOpen) return;
+			intakeOpen = false;
+			intake.abort(/* @__PURE__ */ new Error("the transport stopped its intake"));
+			if (!throughDrain()) closeListener();
+			server.closeIdleConnections();
+			startSweep();
+		},
+		drain(deadline, signal) {
+			const abort = () => {
+				if (!cooperative.signal.aborted) cooperative.abort(signal.reason);
+			};
+			if (signal.aborted) abort();
+			else signal.addEventListener("abort", abort, { once: true });
+			if (inFlight() === 0 || deadline <= clock.now()) {
+				signal.removeEventListener("abort", abort);
+				return Promise.resolve();
+			}
+			return new Promise((resolve) => {
+				let cancel = () => {};
+				const done = () => {
+					idleWaiters.delete(done);
+					cancel();
+					signal.removeEventListener("abort", abort);
+					resolve();
+				};
+				idleWaiters.add(done);
+				cancel = clock.after(Math.max(0, deadline - clock.now()), done);
+			});
+		},
+		inFlight,
+		close() {
+			if (closing !== null) return closing;
+			intakeOpen = false;
+			if (!intake.signal.aborted) intake.abort(/* @__PURE__ */ new Error("the transport closed"));
+			if (!cooperative.signal.aborted) cooperative.abort(/* @__PURE__ */ new Error("the transport closed"));
+			sweep?.();
+			sweep = null;
+			closing = new Promise((resolve) => {
+				closedWaiters.add(resolve);
+			});
+			closeListener();
+			server.closeAllConnections();
+			for (const socket of [...upgraded]) socket.destroy();
+			for (const socket of [...sockets]) socket.destroy();
+			settled();
+			return closing;
+		}
+	};
+};
+//#endregion
+//#region src/http/probes.ts
+const KINDS = [
+	"startup",
+	"readiness",
+	"liveness",
+	"report"
+];
+const prefixProblem = (prefix) => prefix === "" || prefix.startsWith("/") && !prefix.endsWith("/") ? null : `the probe prefix "${prefix}" does not start with "/", or it ends with "/"`;
+const json = (status, body) => ({
+	status,
+	headers: {
+		"content-type": "application/health+json",
+		"cache-control": "no-store"
+	},
+	body: JSON.stringify(body)
+});
+/**
+* This function gives the response of a probe path from the cache of the health runtime. For a path
+* that is not a probe, it gives null. The paths are `/startup`, `/readiness`, `/liveness` and
+* `/report` after the prefix. `/readiness/<controller>` gives the readiness of one controller.
+*/
+const probeResponse = (health, method, path, prefix = "") => {
+	if (!path.startsWith(`${prefix}/`)) return null;
+	const parts = path.slice(prefix.length + 1).split("/");
+	const kind = KINDS.find((each) => each === parts[0]);
+	if (kind === void 0) return null;
+	const controller = parts[1];
+	if (parts.length > 2 || controller !== void 0 && (kind !== "readiness" || controller === "")) return null;
+	if (method !== "GET" && method !== "HEAD") return {
+		status: 405,
+		headers: {
+			allow: "GET, HEAD",
+			"content-length": "0"
+		},
+		body: ""
+	};
+	if (health === null || health === void 0) return json(503, {
+		status: "fail",
+		probe: kind
+	});
+	try {
+		const answer = health.probe(kind, controller === void 0 ? void 0 : decodeURIComponent(controller));
+		return {
+			...json(answer.status, answer.body),
+			headers: {
+				"content-type": answer.contentType,
+				"cache-control": "no-store"
+			}
+		};
+	} catch {
+		return json(404, {
+			status: "fail",
+			probe: kind,
+			controller
+		});
+	}
+};
+/** This function writes a probe response. A 503 gets `Retry-After`, when the writer has the time of a retry. */
+const write = (req, res, response, retryAfter) => {
+	const retry = response.status === 503 && retryAfter !== void 0 ? { "retry-after": retryAfter } : {};
+	res.writeHead(response.status, {
+		...response.headers,
+		...retry,
+		"content-length": String(Buffer.byteLength(response.body))
+	});
+	res.end(req.method === "HEAD" ? void 0 : response.body);
+};
+/**
+* This function gives a request handler that answers the probes on the port of the application. It
+* answers until `close transports`, thus its mount keeps the listener open through the drain. A path
+* that is not a probe goes to the next handler. Each 503 gets the `Retry-After` of the context.
+*/
+const probeHandler = (health, options) => {
+	const problem = prefixProblem(options.prefix);
+	if (problem !== null) throw new Error(problem);
+	const handler = (req, res, context) => {
+		const runtime = typeof health === "function" ? health() : health;
+		const response = probeResponse(runtime, req.method, pathOf(req.url), options.prefix);
+		if (response === null) return false;
+		const retryAfter = context?.retryAfter === void 0 ? void 0 : retryAfterOf({ server_retry_after: context.retryAfter }, "probeHandler");
+		write(req, res, response, retryAfter);
+		return true;
+	};
+	return Object.assign(handler, { until: "close transports" });
+};
+/**
+* This function makes a health server on a port of its own (S6 decision D5). It starts first and
+* closes last, thus the probes answer through the whole drain. Each probe answers from the cache, and
+* each 503 gets the `Retry-After` of `server_retry_after`.
+*/
+const probeServer = (options) => {
+	const { prefix = "", server = createServer(), server_retry_after, ...listen } = options;
+	const retryAfter = retryAfterOf({ server_retry_after }, "probeServer");
+	const problem = prefixProblem(prefix);
+	if (problem !== null) throw new Error(problem);
+	if (server.listenerCount("request") > 0) throw new Error("the probe server has a request listener of its own");
+	let health = null;
+	let closing = null;
+	const sockets = /* @__PURE__ */ new Set();
+	server.on("connection", (socket) => {
+		sockets.add(socket);
+		socket.once("close", () => sockets.delete(socket));
+	});
+	server.on("request", (req, res) => {
+		const response = probeResponse(health, req.method, pathOf(req.url), prefix);
+		write(req, res, response ?? {
+			status: 404,
+			headers: { "content-type": "text/plain; charset=utf-8" },
+			body: "Not Found"
+		}, retryAfter);
+	});
+	return {
+		server,
+		listen(runtime) {
+			health = runtime;
+			if (server.listening) return Promise.resolve();
+			return new Promise((resolve, reject) => {
+				const failed = (error) => {
+					server.off("listening", listened);
+					reject(error);
+				};
+				const listened = () => {
+					server.off("error", failed);
+					resolve();
+				};
+				server.once("error", failed);
+				server.once("listening", listened);
+				server.listen(listen);
+			});
+		},
+		close() {
+			if (closing !== null) return closing;
+			closing = new Promise((resolve) => {
+				if (!server.listening) {
+					resolve();
+					return;
+				}
+				server.close(() => resolve());
+				server.closeAllConnections();
+				for (const socket of [...sockets]) socket.destroy();
+			});
+			return closing;
+		}
+	};
+};
+//#endregion
+//#region src/http/outcome.ts
+const JSON_TYPE = "application/json; charset=utf-8";
+/**
+* This function gives an end as a record for a body: its kind and the count of its items. A cut and
+* a refusal also give their cause, and if the caller can send the request again. A failure gives
+* no detail.
+*/
+const endRecord = (end) => {
+	if (end.kind === "refused" || end.kind === "cut") return {
+		end: end.kind,
+		delivered: end.delivered,
+		retryable: end.retryable,
+		cause: end.cause
+	};
+	return {
+		end: end.kind,
+		delivered: end.delivered
+	};
+};
+/** This format writes each item and the end as one line of JSON (NDJSON). */
+const ndjson = {
+	contentType: "application/x-ndjson; charset=utf-8",
+	item: (value) => `${JSON.stringify(value)}\n`,
+	end: (end) => `${JSON.stringify(endRecord(end))}\n`
+};
+/** This format writes each item as an event of server-sent events, and the end as the event `end`. */
+const sse = {
+	contentType: "text/event-stream; charset=utf-8",
+	item: (value) => `data: ${JSON.stringify(value)}\n\n`,
+	end: (end) => `event: end\ndata: ${JSON.stringify(endRecord(end))}\n\n`
+};
+const valueResponse = (value) => {
+	if (value === void 0) return {
+		status: 204,
+		headers: {},
+		body: ""
+	};
+	if (typeof value === "string") return {
+		status: 200,
+		headers: { "content-type": "text/plain; charset=utf-8" },
+		body: value
+	};
+	if (value instanceof Uint8Array) return {
+		status: 200,
+		headers: { "content-type": "application/octet-stream" },
+		body: value
+	};
+	return {
+		status: 200,
+		headers: { "content-type": JSON_TYPE },
+		body: JSON.stringify(value)
+	};
+};
+const merge = (base, part) => part === void 0 ? base : {
+	status: part.status ?? base.status,
+	headers: {
+		...base.headers,
+		...part.headers
+	},
+	body: part.body ?? base.body
+};
+const keeps = (keepAlive) => typeof keepAlive === "function" ? keepAlive() : keepAlive;
+/**
+* This function applies the rules of the headers to a response. Each 503 gets `Retry-After`, and a
+* 500 gets none. The response closes its connection while the service cannot keep it.
+*/
+const ruled = (response, retryAfter, keepAlive) => {
+	const headers = { ...response.headers };
+	if (response.status === 503 && headers["retry-after"] === void 0) headers["retry-after"] = String(Math.max(0, Math.ceil(valueIn(retryAfter, "s"))));
+	if (response.status === 500) delete headers["retry-after"];
+	if (!keeps(keepAlive)) headers["connection"] = "close";
+	return {
+		...response,
+		headers
+	};
+};
+/** This function gives the status response of an end before the first byte of the body. */
+const endStatus = (end, options) => {
+	const body = JSON.stringify(endRecord(end));
+	switch (end.kind) {
+		case "refused": return {
+			status: 503,
+			headers: { "content-type": JSON_TYPE },
+			body
+		};
+		case "cut": return {
+			status: end.status ?? (end.retryable ? 503 : 500),
+			headers: { "content-type": JSON_TYPE },
+			body
+		};
+		case "failed": return merge({
+			status: 500,
+			headers: { "content-type": JSON_TYPE },
+			body
+		}, options.failed?.(end.error));
+		case "done": return {
+			status: 204,
+			headers: {},
+			body: ""
+		};
+	}
+};
+/**
+* This function maps a unary request to its response, from its items and its end (S6 A12 and A13).
+* - One value and the end `done`: 200 with the value, or the response of the `done` hook.
+* - No value and the end `done`: 204. More than one value: 500, because the route is not a stream.
+* - `refused`: 503. The work did not start, thus the caller can send it again. The service did not
+*   start, it stopped its intake, or a controller is not ready.
+* - `cut`: 503 for a route whose callers can send it again (S6 A12), and 500 for each other route.
+* - `failed`: 500 with no detail, or the response of the `failed` hook. A failure of the route is not a 503.
+*
+* Each 503 gets `Retry-After` (RFC 9110), and a 500 gets none. Each response gets `Connection: close`
+* while the service cannot keep the connection.
+*/
+const outcomeResponse = (items, end, options) => {
+	let response;
+	if (end.kind !== "done") response = endStatus(end, options);
+	else if (items.length === 1) response = merge(valueResponse(items[0]), options.done?.(items[0]));
+	else if (items.length === 0) response = endStatus(end, options);
+	else response = endStatus({
+		kind: "failed",
+		error: /* @__PURE__ */ new Error(`the work gave ${items.length} values, and a unary response has one`),
+		delivered: items.length
+	}, options);
+	return ruled(response, options.retryAfter, options.keepAlive);
+};
+/** This function writes a whole response of `node:http`. A response whose headers went gets no second status: it is destroyed. */
+const writeWhole = (res, response) => {
+	if (res.headersSent) {
+		res.destroy();
+		return;
+	}
+	if (response.headers["connection"] === "close") res.shouldKeepAlive = false;
+	if (response.status === 204) {
+		res.writeHead(204, response.headers);
+		res.end();
+		return;
+	}
+	const length = typeof response.body === "string" ? Buffer.byteLength(response.body) : response.body.byteLength;
+	res.writeHead(response.status, {
+		...response.headers,
+		"content-length": String(length)
+	});
+	res.end(response.body);
+};
+/**
+* This function writes the stream of a request to a response of `node:http`, and gives its end. It
+* gives null when the client closed the connection first. Then the work stops through `return()`.
+* - Unary (no format): it waits for the end, and it writes the status and the body of `outcomeResponse`.
+* - Stream: the status 200 goes with the first item, then each item goes as it comes, then the end
+*   goes in the body (in-band). The next item waits until the client reads, thus a slow client
+*   slows the work. An end before the first item gets a status, as a unary end does.
+*/
+const writeOutcome = async (res, stream, options) => {
+	const iterator = stream[Symbol.asyncIterator]();
+	let gone = () => {};
+	const closed = new Promise((resolve) => {
+		gone = () => resolve("gone");
+	});
+	const onClose = () => {
+		if (!res.writableFinished) gone();
+	};
+	res.once("close", onClose);
+	if (res.destroyed) gone();
+	const leave = async () => {
+		await iterator.return?.();
+		return null;
+	};
+	const next = async () => {
+		const step = await Promise.race([iterator.next(), closed]);
+		if (step === "gone") return step;
+		if (step.done === true) throw new Error("the stream of the request ended without its end");
+		return step.value;
+	};
+	/** This function writes one part of the body, and waits while the client reads slower than the work. */
+	const send = async (chunk) => {
+		if (res.write(chunk)) return true;
+		const drained = new Promise((resolve) => res.once("drain", () => resolve("drained")));
+		return await Promise.race([drained, closed]) === "drained";
+	};
+	try {
+		const format = options.stream;
+		if (format === void 0) {
+			const items = [];
+			for (;;) {
+				const event = await next();
+				if (event === "gone") return await leave();
+				if (event.kind === "item") {
+					items.push(event.value);
+					continue;
+				}
+				writeWhole(res, outcomeResponse(items, event, options));
+				return event;
+			}
+		}
+		const first = await next();
+		if (first === "gone") return await leave();
+		if (first.kind !== "item") {
+			if (first.kind === "done") writeWhole(res, ruled({
+				status: 200,
+				headers: {
+					"content-type": format.contentType,
+					"cache-control": "no-store"
+				},
+				body: format.end(first)
+			}, options.retryAfter, options.keepAlive));
+			else writeWhole(res, outcomeResponse([], first, options));
+			return first;
+		}
+		if (res.headersSent) {
+			res.destroy();
+			return await leave();
+		}
+		const head = ruled({
+			status: 200,
+			headers: {
+				"content-type": format.contentType,
+				"cache-control": "no-store"
+			},
+			body: ""
+		}, options.retryAfter, options.keepAlive);
+		if (head.headers["connection"] === "close") res.shouldKeepAlive = false;
+		res.writeHead(200, head.headers);
+		if (!await send(format.item(first.value))) return await leave();
+		for (;;) {
+			const event = await next();
+			if (event === "gone") return await leave();
+			if (event.kind === "item") {
+				if (!await send(format.item(event.value))) return await leave();
+				continue;
+			}
+			res.end(format.end(event));
+			return event;
+		}
+	} finally {
+		res.off("close", onClose);
+	}
+};
+/**
+* This function gives a request handler that does each request of a route through `life.request`
+* (S6 A12 and A13). The transport gives the lifecycle and `server_retry_after` through the context.
+* - A route name takes a request whose method and path are that name, for example `POST /orders`.
+*   A function gives the name of a route or of a pattern, or null for a request of another handler.
+* - Before the start of the transport, each request gets a retryable 503.
+* - The response is unary, or a stream with the option `stream`, as `writeOutcome` writes it.
+*/
+const handle = (controller, route, work, options = {}) => {
+	const nameOf = (req) => {
+		if (typeof route === "function") return route(req);
+		return `${req.method ?? "GET"} ${pathOf(req.url)}` === route ? route : null;
+	};
+	return async (req, res, context) => {
+		const name = nameOf(req);
+		if (name === null) return false;
+		const life = context.life;
+		const written = {
+			...options,
+			keepAlive: () => life?.keepAlive() ?? false,
+			retryAfter: context.retryAfter
+		};
+		if (life === null) {
+			writeWhole(res, outcomeResponse([], {
+				kind: "refused",
+				status: 503,
+				retryable: true,
+				cause: "the transport has not started",
+				delivered: 0
+			}, written));
+			return true;
+		}
+		const given = options.detail === void 0 ? {} : { detail: options.detail(req) };
+		await writeOutcome(res, life.request(controller, name, (signal) => work(req, signal), given), written);
+		return true;
+	};
+};
+//#endregion
+export { endRecord, handle, httpTransport, ndjson, outcomeResponse, pathOf, probeHandler, probeResponse, probeServer, sse, writeOutcome };
+
+//# sourceMappingURL=http.js.map