@mark1russell7/service 0.5.12 → 0.5.13

package/build/http-client.js

@@ -0,0 +1,612 @@
+import { realClock } from "./clock.js";
+import { B as zeroProblems, C as notSent, E as poolProblems, F as timeProblems, G as immediate, I as trackWithTimer, J as keepaliveSilent, K as keepaliveAnswered, L as wholeProblems, M as sendWithReissue, N as socketEnds, P as stepChecks, R as withinBound, S as ms, U as WHAT, V as MANIFESTATIONS, W as firstDetector, X as unwatched, Y as kernelGiveUp, _ as inFlight, a as helloDial, b as message, c as ageProblems, d as clientProblems, f as clientRecorder, g as idleCloseProblem, i as authority, j as roundTripCheck, l as attachClient, m as dialCheck, n as closeTimer, o as statusLineJudge, q as keepaliveReset, r as transition, s as STARTING_POLL, t as clientKnob, u as clientBounds, v as keepaliveOnProblems, w as operationTable, y as localStateCheck, z as wrapperTimerProblems } from "./machine-BhTRu3u9.js";
+//#region src/http-client/connection.ts
+/**
+* This factory makes an `http.Agent` of Node. It loads node:http only when a client connects.
+* Each request goes through `http.request` with the agent. The response settles at the end of its body.
+* A body that ends before it is complete rejects the response.
+*/
+const nodeAgent = async (options) => {
+	const http = await import("node:http");
+	const agent = new http.Agent(options);
+	const all = (lists) => Object.values(lists).flatMap((list) => list ?? []);
+	return {
+		request(request, events) {
+			const req = http.request({
+				host: request.host,
+				port: request.port,
+				method: request.method,
+				path: request.path,
+				headers: request.headers,
+				agent
+			});
+			const response = new Promise((resolve, reject) => {
+				req.on("socket", (socket) => {
+					events.socket(socket, req.reusedSocket);
+					if (socket.connecting) socket.once("connect", () => events.connect());
+					else if (!req.reusedSocket) events.connect();
+				});
+				req.on("response", (incoming) => {
+					const chunks = [];
+					incoming.on("data", (chunk) => chunks.push(chunk));
+					incoming.on("error", reject);
+					incoming.on("end", () => resolve({
+						status: incoming.statusCode ?? 0,
+						headers: incoming.headers,
+						body: Buffer.concat(chunks)
+					}));
+					incoming.on("close", () => {
+						if (!incoming.complete) reject(/* @__PURE__ */ new Error("the connection closed before the end of the body"));
+					});
+				});
+				req.on("error", reject);
+			});
+			req.end(request.body);
+			return {
+				response,
+				abort: (error) => req.destroy(error)
+			};
+		},
+		sockets: () => [...all(agent.sockets), ...all(agent.freeSockets)],
+		destroy: () => agent.destroy()
+	};
+};
+//#endregion
+//#region src/http-client/meets.ts
+/**
+* This function gives the manifestations that an HTTP client can meet, and the detectors of each,
+* from its knobs. The HTTP cells measured them on the agent of Node 24.21.0:
+* - The agent has no timer of a call, thus the timer of the wrapper finds each silent call in flight.
+* - The free socket timer closes an idle socket at `pool_idle_expiry` at most. Thus no request goes
+*   later on a socket that went silent while it was free.
+* - A FIN on a busy socket fails the call with "socket hang up". A FIN on a free socket destroys it.
+*/
+const httpClientMeetings = (name, knobs) => {
+	const call = {
+		by: "request_timeout",
+		within: knobs.request_timeout,
+		situation: "in flight",
+		effect: `the timer of the wrapper ends the call as indeterminate, and ${name} destroys its socket`
+	};
+	const idleExpiry = (situation) => ({
+		by: "pool_idle_expiry",
+		within: knobs.pool_idle_expiry,
+		situation,
+		effect: "the free socket timer of the agent closes the socket, and the next request opens a new socket"
+	});
+	const giveUp = kernelGiveUp(knobs.retrans_giveup_time, "the call fails as indeterminate");
+	const silent = (manifestation) => ({
+		manifestation,
+		what: WHAT[manifestation],
+		detectors: [
+			call,
+			giveUp,
+			idleExpiry("idle"),
+			keepaliveSilent(knobs.keepalive_idle)
+		]
+	});
+	return [
+		{
+			manifestation: "rst",
+			what: WHAT.rst,
+			detectors: [
+				immediate("in flight", "the call fails with ECONNRESET as indeterminate, and the next request opens a new socket"),
+				idleExpiry("idle"),
+				keepaliveReset(knobs.keepalive_idle)
+			]
+		},
+		{
+			manifestation: "fin",
+			what: WHAT.fin,
+			detectors: [immediate("in flight", "the call fails with \"socket hang up\" as indeterminate"), immediate("idle", "the agent destroys the free socket, and the next request opens a new socket")]
+		},
+		silent("blackhole"),
+		silent("freeze-host"),
+		{
+			manifestation: "freeze-process",
+			what: WHAT["freeze-process"],
+			detectors: [
+				call,
+				idleExpiry("idle"),
+				keepaliveAnswered()
+			]
+		},
+		{
+			manifestation: "app-stall",
+			what: "the server holds its reply, for example in a slow handler, and its kernel stays up",
+			detectors: [
+				call,
+				idleExpiry("idle"),
+				keepaliveAnswered()
+			]
+		}
+	];
+};
+//#endregion
+//#region src/http-client/client.ts
+/**
+* This request asks about the server, not about a resource (RFC 9110 §9.3.7). Thus it changes no
+* state. A server that does not route it still answers with a status, and the status tells that it is alive.
+*/
+const OPTIONS_STAR = {
+	method: "OPTIONS",
+	path: "*"
+};
+/**
+* These operations are the methods of HTTP, by their idempotency in RFC 9110 §9.2.2. A second
+* request of GET, HEAD, OPTIONS, TRACE, PUT or DELETE has the same effect as one. POST and PATCH do not.
+*/
+const HTTP_OPERATIONS = {
+	GET: { idempotent: true },
+	HEAD: { idempotent: true },
+	OPTIONS: { idempotent: true },
+	TRACE: { idempotent: true },
+	PUT: { idempotent: true },
+	DELETE: { idempotent: true },
+	POST: { idempotent: false },
+	PATCH: { idempotent: false }
+};
+/** This function gives the problems of a spec: the knobs that the agent cannot use. */
+const specProblems = (name, spec) => {
+	const { knobs } = spec;
+	const problems = [
+		...timeProblems(name, knobs),
+		...wrapperTimerProblems(name, knobs, {
+			connect_bound: "a connect",
+			request_timeout: "a call"
+		}),
+		...zeroProblems(name, "the agent", knobs, { bounded: ["pool_idle_expiry"] }),
+		...keepaliveOnProblems(name, knobs, "the agent"),
+		...wholeProblems(name, knobs, {
+			millis: [
+				"connect_bound",
+				"request_timeout",
+				"pool_idle_expiry",
+				"hint_buffer"
+			],
+			seconds: ["keepalive_idle"]
+		}),
+		...poolProblems(name, {
+			max: spec.pool.max,
+			min: 0
+		}),
+		...ageProblems(name, knobs, "the agent does not replace a connection at an age")
+	];
+	if (!Number.isFinite(ms(knobs.hint_buffer))) problems.push(`${name}'s hint_buffer is not a finite time: the agent subtracts it from the hint of the server`);
+	return problems;
+};
+/** This function gives the options of `new http.Agent` from a spec. Each timer of the agent comes from the declaration. */
+const agentOptions = (spec) => {
+	const { knobs } = spec;
+	return {
+		keepAlive: true,
+		timeout: ms(knobs.pool_idle_expiry),
+		agentKeepAliveTimeoutBuffer: ms(knobs.hint_buffer),
+		keepAliveMsecs: ms(knobs.keepalive_idle),
+		maxSockets: spec.pool.max,
+		maxFreeSockets: spec.pool.max,
+		scheduling: "lifo"
+	};
+};
+/** This function gives the bytes of the dial: `OPTIONS *` with the Host header, and a close after the answer. */
+const optionsRequest = (host, port) => `OPTIONS * HTTP/1.1\r\nHost: ${authority(host, port)}\r\nConnection: close\r\n\r\n`;
+/** This judge reads the status line of the answer. Any status passes, because it tells that an HTTP server answered. */
+const statusJudge = statusLineJudge(() => null);
+/** This dial function opens a TCP connection, sends `OPTIONS *`, and waits for the status line. It changes no state on the server. */
+const httpDial = (host, port, signal) => helloDial(optionsRequest(host, port), statusJudge)(host, port, signal);
+/**
+* This function makes an HTTP client, a dependency of a service over an `http.Agent` of Node.
+* - It sets each timer of the agent from the declaration. The agent sends no request again by itself,
+*   and the client sends again only an idempotent operation of its table.
+* - Its call is a request until the end of the body of its response. The wrapper has a timer for the
+*   connect and one for the call, because the agent has none.
+* - It tells the outcome of a call in three values. A request that did not get a connected socket
+*   did not leave the client. A failure after that is not certain.
+* - It destroys the socket of each call that is not `ok`, thus no later request gets that socket.
+* - It records each new socket of the pool (D1). HTTP gives no id of a connection.
+*
+* The core of the clients gives the outcomes, the second try, the calls in flight and the timer of a
+* call. It also gives the bounded close and the checks. This entry gives what the agent does in its own way.
+*/
+const httpClient = (name, spec, options = {}) => {
+	const problems = specProblems(name, spec);
+	if (problems.length > 0) throw new Error(problems.join("; "));
+	const { knobs } = spec;
+	const clock = options.clock ?? realClock;
+	const create = options.create ?? nodeAgent;
+	const dial = options.dial ?? httpDial;
+	const operations = operationTable(HTTP_OPERATIONS, spec.operations);
+	const requestTimeout = ms(knobs.request_timeout);
+	const connectBound = ms(knobs.connect_bound);
+	const check = spec.check ?? OPTIONS_STAR;
+	let agent = null;
+	let status = "none";
+	const joins = [];
+	const flight = inFlight();
+	const waiting = /* @__PURE__ */ new Set();
+	const emit = clientRecorder(options.record, clock, name);
+	const record = (on, to = status, detail) => {
+		const from = status;
+		status = to;
+		emit(from, to, on, detail);
+	};
+	const closing = () => status === "closing" || status === "end";
+	/**
+	* This function makes one try of a call. The try waits for a socket of the agent: a free one, or a
+	* new one in `connect_bound`. A failure before the socket is ready is certain: the request did not
+	* leave the client. After that, the try waits for the whole response in the rest of `request_timeout`.
+	*/
+	const attempt = async (call, signal) => {
+		const a = agent;
+		if (a === null) return notSent(`${name} has not connected`);
+		if (closing()) return notSent(`${name} is ${status}: the request did not leave the client`);
+		if (signal?.aborted) return notSent("the caller aborted the request before it left the client");
+		const started = clock.now();
+		const body = typeof call.body === "string" ? Buffer.from(call.body, "utf8") : call.body;
+		const headers = {
+			...call.headers,
+			...body === void 0 ? {} : { "content-length": String(body.byteLength) }
+		};
+		let socket;
+		let reused = false;
+		let left = false;
+		let ending = false;
+		let connectTimer = () => {};
+		let decide = () => {};
+		const leaving = new Promise((resolve) => {
+			let decided = false;
+			decide = (value) => {
+				if (decided) return;
+				decided = true;
+				resolve(value);
+			};
+		});
+		let deliver = null;
+		let early = null;
+		let settled = false;
+		const settleWith = (value, cause) => {
+			if (deliver === null) early ??= {
+				value,
+				cause
+			};
+			else deliver(value, cause);
+		};
+		let exchange = null;
+		const stop = (text) => {
+			if (left) return;
+			ending = true;
+			connectTimer();
+			exchange?.abort(new Error(text));
+			decide(notSent(text));
+		};
+		const ready = () => {
+			left = true;
+			connectTimer();
+			decide(true);
+		};
+		exchange = a.request({
+			host: spec.host,
+			port: spec.port,
+			method: call.method,
+			path: call.path,
+			headers,
+			body
+		}, {
+			socket(given, isReused) {
+				socket = given;
+				reused = isReused;
+				if (isReused) {
+					ready();
+					return;
+				}
+				connectTimer = clock.after(connectBound, () => {
+					if (left) return;
+					record("connect.failed", closing() ? status : "failing", "no connection in connect_bound");
+					stop("no connection in connect_bound: the request did not leave the client");
+				});
+			},
+			connect() {
+				const generation = joins.length + 1;
+				joins.push({
+					generation,
+					at: clock.now(),
+					...socketEnds(socket)
+				});
+				record("join", closing() ? status : "ready", `socket ${generation}`);
+				ready();
+			}
+		});
+		exchange.response.then((response) => settleWith({
+			outcome: "ok",
+			value: response
+		}), (error) => {
+			const cause = error instanceof Error ? error : new Error(message(error));
+			if (!left) {
+				connectTimer();
+				if (!ending) record("connect.failed", closing() ? status : "failing", message(error));
+				decide(notSent(message(error)));
+				return;
+			}
+			if (settled) return;
+			if (reused) record("reuse.failed", status, message(error));
+			settleWith({
+				outcome: "indeterminate",
+				error: message(error)
+			}, cause);
+		});
+		const abandoned = () => stop("the caller abandoned the request before it left the client");
+		signal?.addEventListener("abort", abandoned, { once: true });
+		const queued = clock.after(requestTimeout, () => stop("no socket in request_timeout: the request did not leave the client"));
+		waiting.add(stop);
+		const got = await leaving;
+		signal?.removeEventListener("abort", abandoned);
+		queued();
+		waiting.delete(stop);
+		if (got !== true) return got;
+		const sent = exchange;
+		return trackWithTimer(flight, clock, Math.max(0, requestTimeout - (clock.now() - started)), signal, "the caller abandoned the request after it left the client", "no whole response in request_timeout: the server can have the request", (settle) => {
+			deliver = settle;
+			if (early !== null) settle(early.value, early.cause);
+		}, (value, cause) => {
+			settled = true;
+			if (value.outcome !== "ok") sent.abort(cause ?? new Error(value.error));
+		});
+	};
+	const request = (call, sendOptions = {}) => {
+		const method = call.method.toUpperCase();
+		const named = call.operation ?? method;
+		return sendWithReissue({
+			clock,
+			bound: requestTimeout,
+			operation: operations[named],
+			options: sendOptions,
+			attempt: (signal) => attempt({
+				...call,
+				method
+			}, signal),
+			onReissue: () => record("command.reissue", status, named)
+		});
+	};
+	const handle = {
+		async connect(signal) {
+			record("status.connecting", "connecting");
+			agent = await create(agentOptions(spec));
+			if (signal.aborted) throw new Error(`${name}: the service stopped before the connect`);
+			await request(check, {
+				signal,
+				reissue: false
+			});
+		},
+		async close() {
+			const a = agent;
+			if (a === null || closing()) return;
+			record("close.request", "closing");
+			for (const stop of [...waiting]) stop("the client closed before the request left");
+			if (!await withinBound(clock, ms(knobs.close_bound), flight.idle())) {
+				record("close.bound");
+				const open = a.sockets().length;
+				flight.settleAll("the client closed with the request in flight");
+				a.destroy();
+				record("close.destroy", status, `open sockets: ${open}`);
+			} else a.destroy();
+			record("status.end", "end");
+		}
+	};
+	const declaration = {
+		system: spec.system,
+		knobs: {
+			connect_bound: knobs.connect_bound,
+			request_timeout: knobs.request_timeout,
+			pool_idle_expiry: knobs.pool_idle_expiry,
+			hint_buffer: knobs.hint_buffer,
+			keepalive_idle: knobs.keepalive_idle,
+			idle_refresh_interval: knobs.keepalive_idle,
+			max_connection_age: knobs.max_connection_age,
+			close_bound: knobs.close_bound,
+			retrans_giveup_time: knobs.retrans_giveup_time
+		},
+		operations
+	};
+	const checks = (checkOptions) => stepChecks(name, checkOptions, {
+		"local-state": localStateCheck(() => status === "ready"),
+		"round-trip": roundTripCheck(async (sendOptions) => {
+			const sent = await request(check, sendOptions);
+			return sent.outcome === "ok" && sent.value.status >= 500 ? {
+				outcome: "error",
+				error: `the server answered ${sent.value.status}`,
+				reply: true,
+				attempts: sent.attempts
+			} : sent;
+		}),
+		dial: dialCheck(dial, spec.host, spec.port)
+	});
+	return {
+		name,
+		declaration,
+		handle,
+		meets: httpClientMeetings(name, knobs),
+		get status() {
+			return status;
+		},
+		joins,
+		request,
+		checks,
+		attach: (svc, checkOptions) => attachClient(svc, name, declaration, handle, checks(checkOptions)),
+		problems(description) {
+			const idle = idleCloseProblem(name, knobs.pool_idle_expiry, knobs.server_idle_close);
+			return [...clientProblems(name, description, clientBounds(knobs)), ...idle === null ? [] : [idle]];
+		}
+	};
+};
+//#endregion
+//#region src/http-client/machine.ts
+/** The states where the agent exists and serves. */
+const SERVING = [
+	"connecting",
+	"ready",
+	"failing"
+];
+const OPEN = [...SERVING, "closing"];
+/**
+* The HTTP client of the service as a `mark1russell7.machine/1` document. It is the agent as the
+* wrapper sees it, not one socket: the document `node-http-agent` of `@mark1russell7/machines`
+* gives each socket of the agent. The state is the outcome of the last connect of a socket:
+* - `ready`: the last connect succeeded.
+* - `failing`: the last connect failed, or did not end in connect_bound. The agent does not connect
+*   again by itself. The next request tries again.
+*
+* A free socket that the agent closes does not change the state. A request on a reused socket that
+* fails records `reuse.failed`, and the state stays. A test records the transitions of the client
+* and replays them against this document.
+*/
+const HTTP_CLIENT_MACHINE = {
+	format: "mark1russell7.machine/1",
+	id: "service.machine.http-client",
+	title: "The HTTP client of the service, over an http.Agent of Node",
+	layer: "driver",
+	version: "0.1.0",
+	sources: [{
+		ref: "packages/service/src/http-client (the client implements this document)",
+		rung: "implemented"
+	}],
+	states: {
+		none: {
+			initial: true,
+			note: "the client exists, and its agent does not"
+		},
+		connecting: { note: "the check request of the startup opens the first socket" },
+		ready: { note: "the last connect succeeded. A dead free socket stays hidden until the free socket timer or a request meets it" },
+		failing: { note: "the last connect failed. A request that waits for a socket of a full pool does not change the state" },
+		closing: { note: "the client waits for its calls in flight in close_bound, then destroys each socket of the agent" },
+		end: {
+			final: true,
+			note: "the service closed the client"
+		}
+	},
+	events: {
+		"status.connecting": { kind: "local" },
+		join: {
+			kind: "rx",
+			note: "a new socket of the agent connected: the request on it leaves the client (D1)"
+		},
+		"connect.failed": {
+			kind: "local",
+			note: "a connect failed: its error, or connect_bound"
+		},
+		"reuse.failed": {
+			kind: "rx",
+			note: "a request on a free socket that the agent reused failed: the server closed that socket"
+		},
+		"command.reissue": { kind: "local" },
+		"close.request": { kind: "local" },
+		"close.bound": {
+			kind: "timer",
+			note: "a call in flight did not end in close_bound"
+		},
+		"close.destroy": {
+			kind: "local",
+			note: "the bound destroys each socket of the agent, and each call in flight is indeterminate"
+		},
+		"status.end": { kind: "local" }
+	},
+	knobs: {
+		connect_bound: clientKnob("connect.bound"),
+		request_timeout: clientKnob("request.bound"),
+		pool_idle_expiry: clientKnob("timeout"),
+		hint_buffer: clientKnob("agentKeepAliveTimeoutBuffer"),
+		keepalive_idle: clientKnob("keepAliveMsecs"),
+		close_bound: clientKnob("close.bound")
+	},
+	timers: {
+		connect_timeout: {
+			duration: {
+				knob: "connect_bound",
+				unit: "s"
+			},
+			arms: ["enter:connecting"],
+			cancels: ["join", "connect.failed"],
+			fires: "connect.failed",
+			note: "the timer of the wrapper on the connect of a new socket. The agent has no connect timer"
+		},
+		close: closeTimer()
+	},
+	transitions: [
+		transition("connect", "none", "status.connecting", "connecting"),
+		transition("join", [...SERVING], "join", "ready"),
+		transition("connect-failed", [...SERVING], "connect.failed", "failing", { timer: "connect_timeout" }),
+		transition("join-closing", "closing", "join", "closing"),
+		transition("connect-failed-closing", "closing", "connect.failed", "closing"),
+		...OPEN.map((state) => transition(`reuse-failed-${state}`, state, "reuse.failed", state)),
+		...OPEN.map((state) => transition(`reissue-${state}`, state, "command.reissue", state)),
+		transition("close", [...SERVING], "close.request", "closing"),
+		transition("close-bound", "closing", "close.bound", "closing", { timer: "close" }),
+		transition("close-destroy", "closing", "close.destroy", "closing"),
+		transition("end", "closing", "status.end", "end")
+	]
+};
+//#endregion
+//#region src/http-client/starting.ts
+/**
+* This poll is the poll of the checks that `HTTP_CLIENT_STARTING_KNOBS` fits. It is `STARTING_POLL` of
+* the core: each 5 s with a jitter of 20 %, and a timeout of 4 s (B6, O12). The poll does not depend on the driver.
+*/
+const HTTP_CLIENT_STARTING_POLL = STARTING_POLL;
+/**
+* These knobs are a declaration to start from. They come from what the HTTP cells measured on the
+* agent of Node 24.21.0 against a Node server at its defaults. The runtime has no defaults: a service gives
+* these knobs, or its own. Each value holds the borders that the cells measured:
+* - `connect_bound` 5 s: the connect timeout of DP44. The agent has no connect timer.
+* - `request_timeout` 9.5 s: in the slowest poll of 10 s (O13). The agent has no timer of a call.
+*   A frozen server held the call of undici until its headersTimeout, at 10.187 s.
+* - `pool_idle_expiry` 4 s: the free socket timer. The agent then closes a free socket at 4 s, the
+*   hint of 5 s less `hint_buffer`. That is below the idle close of the server.
+* - `hint_buffer` 1 s: the default of the agent.
+* - `server_idle_close` 6 s: a Node server closes an idle connection at its `keepAliveTimeout` of 5 s
+*   plus its buffer of 1 s. The cells measured 6.0003 s. O01 then has a margin of 2 s.
+* - `keepalive_idle` 1 s: the default of the agent. Node truncates it to whole seconds.
+* - `max_connection_age` "infinite": the agent does not replace a connection at an age.
+* - `close_bound` 2 s: a call in flight behind a black hole holds its socket with no bound.
+* - `retrans_giveup_time` 924.6 s: the give-up of Linux at `tcp_retries2 = 15`.
+*/
+const HTTP_CLIENT_STARTING_KNOBS = {
+	connect_bound: {
+		value: 5,
+		unit: "s"
+	},
+	request_timeout: {
+		value: 9.5,
+		unit: "s"
+	},
+	pool_idle_expiry: {
+		value: 4,
+		unit: "s"
+	},
+	hint_buffer: {
+		value: 1,
+		unit: "s"
+	},
+	server_idle_close: {
+		value: 6,
+		unit: "s"
+	},
+	keepalive_idle: {
+		value: 1,
+		unit: "s"
+	},
+	max_connection_age: {
+		value: "infinite",
+		unit: "s"
+	},
+	close_bound: {
+		value: 2,
+		unit: "s"
+	},
+	retrans_giveup_time: {
+		value: 924.6,
+		unit: "s"
+	}
+};
+//#endregion
+export { HTTP_CLIENT_MACHINE, HTTP_CLIENT_STARTING_KNOBS, HTTP_CLIENT_STARTING_POLL, HTTP_OPERATIONS, MANIFESTATIONS, OPTIONS_STAR, STARTING_POLL, agentOptions, firstDetector, httpClient, httpClientMeetings, httpDial, nodeAgent, optionsRequest, specProblems, statusJudge, unwatched };
+
+//# sourceMappingURL=http-client.js.map