@mark1russell7/service 0.5.11 → 0.5.13

package/build/websocket.js

@@ -0,0 +1,780 @@
+import { realClock } from "./clock.js";
+import { heartbeat } from "./heartbeat.js";
+import { i as heartbeatDetection } from "./timing-DGRi3XCI.js";
+import { A as retrySchedule, B as zeroProblems, C as notSent, D as readyWait, F as timeProblems, G as immediate, H as NEVER, I as trackWithTimer, J as keepaliveSilent, K as keepaliveAnswered, L as wholeProblems, M as sendWithReissue, N as socketEnds, O as retryBackoff, 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, h as finiteMs, i as authority, j as roundTripCheck, k as retryProblems, 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, w as operationTable, x as missesProblems, y as localStateCheck, z as wrapperTimerProblems } from "./machine-BhTRu3u9.js";
+//#region src/websocket/connection.ts
+/** This function gives a message of ws as one buffer. At the default `binaryType` of ws, a message is a buffer already. */
+const asBuffer = (data) => {
+	if (Buffer.isBuffer(data)) return data;
+	if (Array.isArray(data)) return Buffer.concat(data);
+	return Buffer.from(data);
+};
+/**
+* This function adapts a `WebSocket` of ws to a connection. It listens to `error` at once, because
+* in Node an error with no listener throws. It takes the socket from the event `upgrade`.
+*/
+const adaptWs = (ws) => {
+	let socket;
+	let listeners = null;
+	const held = [];
+	const deliver = (event) => {
+		if (listeners === null) held.push(event);
+		else event(listeners);
+	};
+	ws.on("upgrade", (response) => {
+		socket = response.socket;
+	});
+	ws.on("open", () => deliver((given) => given.open()));
+	ws.on("message", (data, binary) => deliver((given) => given.message(asBuffer(data), binary)));
+	ws.on("pong", (data) => deliver((given) => given.pong(data)));
+	ws.on("close", (code, reason) => deliver((given) => given.close(code, reason.toString("utf8"))));
+	ws.on("error", (error) => deliver((given) => given.error(error)));
+	return {
+		listen(given) {
+			listeners = given;
+			for (const event of held.splice(0)) event(given);
+		},
+		send: (data, callback) => ws.send(data, (error) => callback(error ?? void 0)),
+		ping: (data) => ws.ping(data),
+		close: (code, reason) => ws.close(code, reason),
+		terminate: () => ws.terminate(),
+		get socket() {
+			return socket;
+		},
+		get protocol() {
+			return ws.protocol;
+		}
+	};
+};
+/**
+* This factory makes a `WebSocket` of ws. It loads ws only when a client connects, thus a service
+* that does not use WebSocket does not need it. The specifier is a value, thus the package needs no types of ws.
+*/
+const nodeWs = async ({ url, protocols, options }) => {
+	const loaded = await import("ws");
+	const WebSocket = loaded.WebSocket ?? loaded.default;
+	if (WebSocket === void 0) throw new Error("ws gives no WebSocket class");
+	return adaptWs(new WebSocket(url, [...protocols], options));
+};
+//#endregion
+//#region src/websocket/meets.ts
+/**
+* This function gives the manifestations that a WebSocket client can meet, and the detectors of
+* each, from its knobs. The WS cells measured them on ws 8:
+* - At a heartbeat of 2 s, a timeout of 1 s and 1 miss, the drop came 0.999 s to 1.0035 s after the
+*   ping that got no pong. The slowest of 495 runs took 1.003761 s.
+* - `terminate()` closes the socket 0.3 ms to 1 ms after the drop. The close of the global WebSocket
+*   only writes a close frame, and its socket stayed ESTABLISHED.
+* - The kernel of a frozen server acknowledges each ping, thus only the heartbeat finds it.
+* - At `tcp_retries2 = 3`, the kernel gave up before a pong timeout of 10 s.
+* - Without a heartbeat, the client waited for the keepalive of undici: 70 s. ws sets no keepalive.
+*/
+const wsMeetings = (name, knobs, misses) => {
+	const interval = finiteMs(knobs.heartbeat_interval);
+	const detection = heartbeatDetection(knobs.heartbeat_interval, knobs.heartbeat_timeout, misses);
+	const heartbeat = (situation) => ({
+		by: "heartbeat_detection_time",
+		within: detection,
+		situation,
+		effect: `the heartbeat destroys the socket with terminate(), each call in flight fails as indeterminate, and ${name} connects again`
+	});
+	const call = {
+		by: "request_timeout",
+		within: knobs.request_timeout,
+		situation: "in flight",
+		effect: "the timer of the wrapper ends the call as indeterminate, and the connection stays"
+	};
+	const giveUp = kernelGiveUp(knobs.retrans_giveup_time, "each call in flight fails as indeterminate");
+	const silent = (manifestation) => ({
+		manifestation,
+		what: WHAT[manifestation],
+		detectors: [
+			call,
+			heartbeat("in flight"),
+			giveUp,
+			heartbeat("idle"),
+			keepaliveSilent(knobs.keepalive_idle)
+		]
+	});
+	return [
+		{
+			manifestation: "rst",
+			what: WHAT.rst,
+			detectors: [
+				immediate("in flight", "ws closes with code 1006, the call fails as indeterminate, and the client connects again"),
+				{
+					by: "heartbeat_interval",
+					within: interval === void 0 ? NEVER : knobs.heartbeat_interval,
+					situation: "idle",
+					effect: "the next ping frame gets a reset, and the client connects again"
+				},
+				keepaliveReset(knobs.keepalive_idle)
+			]
+		},
+		{
+			manifestation: "fin",
+			what: WHAT.fin,
+			detectors: [immediate("in flight", "the FIN arrives, ws closes with code 1006, and the call fails as indeterminate"), immediate("idle", "the FIN arrives, ws closes with code 1006, and the client connects again")]
+		},
+		silent("blackhole"),
+		silent("freeze-host"),
+		{
+			manifestation: "freeze-process",
+			what: WHAT["freeze-process"],
+			detectors: [
+				call,
+				heartbeat("in flight"),
+				heartbeat("idle"),
+				keepaliveAnswered()
+			]
+		},
+		{
+			manifestation: "app-stall",
+			what: "the server holds its reply, for example in a slow handler, and its library still answers each ping",
+			detectors: [
+				call,
+				{
+					...heartbeat("idle"),
+					within: NEVER,
+					effect: "the library of the server still answers each ping with a pong"
+				},
+				keepaliveAnswered()
+			]
+		}
+	];
+};
+//#endregion
+//#region src/websocket/client.ts
+/** These operations are in each table: a ping frame is idempotent (RFC 6455 §5.5.2). */
+const WS_OPERATIONS = { ping: { idempotent: true } };
+/** This function gives the problems of a spec: the knobs that the client cannot use. */
+const specProblems = (name, spec) => {
+	const { knobs } = spec;
+	const problems = [
+		...timeProblems(name, knobs),
+		...wrapperTimerProblems(name, knobs, {
+			connect_bound: "an open",
+			request_timeout: "a call",
+			heartbeat_timeout: "a ping of the heartbeat"
+		}),
+		...zeroProblems(name, "the client", knobs, { open: ["heartbeat_interval", "keepalive_idle"] }),
+		...wholeProblems(name, knobs, { seconds: ["keepalive_idle"] }),
+		...retryProblems(name, knobs),
+		...missesProblems(name, spec.heartbeatMisses, "heartbeat"),
+		...ageProblems(name, knobs, "the client does not replace its connection at an age")
+	];
+	const interval = finiteMs(knobs.heartbeat_interval);
+	const timeout = finiteMs(knobs.heartbeat_timeout);
+	if (interval !== void 0 && interval > 0 && timeout !== void 0 && spec.heartbeatMisses > 1 && timeout >= interval) problems.push(`${name}'s heartbeat_timeout is not below its heartbeat_interval: with one ping at a time, a tick sends no ping while a ping waits`);
+	if (spec.path !== void 0 && !spec.path.startsWith("/")) problems.push(`${name}'s path does not start with "/"`);
+	if (spec.password !== void 0) problems.push(`${name} takes no password: give the credentials in headers, for example authorization`);
+	return problems;
+};
+/** This function gives the URL of a spec. The client speaks ws:// only. */
+const wsUrl = (spec) => `ws://${authority(spec.host, spec.port)}${spec.path ?? "/"}`;
+/** This function gives the arguments of `new WebSocket` from a spec. Each timer of ws comes from the declaration. */
+const wsOptions = (spec) => {
+	const { knobs } = spec;
+	const keepalive = finiteMs(knobs.keepalive_idle);
+	return {
+		url: wsUrl(spec),
+		protocols: spec.protocols ?? [],
+		options: {
+			handshakeTimeout: ms(knobs.connect_bound),
+			autoPong: true,
+			closeTimeout: ms(knobs.close_bound),
+			keepAlive: keepalive !== void 0,
+			...keepalive === void 0 ? {} : { keepAliveInitialDelay: keepalive },
+			...spec.headers === void 0 ? {} : { headers: spec.headers }
+		}
+	};
+};
+/** The key of the dial. RFC 6455 §1.3 gives it as its example. The dial does not read the accept of the server. */
+const DIAL_KEY = "dGhlIHNhbXBsZSBub25jZQ==";
+/** This function gives the bytes of the dial: the upgrade request of RFC 6455 §4.1, with the subprotocols and the headers of the spec. */
+const upgradeRequest = (spec) => {
+	return `${[
+		`GET ${spec.path ?? "/"} HTTP/1.1`,
+		`Host: ${authority(spec.host, spec.port)}`,
+		"Upgrade: websocket",
+		"Connection: Upgrade",
+		`Sec-WebSocket-Key: ${DIAL_KEY}`,
+		"Sec-WebSocket-Version: 13",
+		...spec.protocols === void 0 || spec.protocols.length === 0 ? [] : [`Sec-WebSocket-Protocol: ${spec.protocols.join(", ")}`],
+		...Object.entries(spec.headers ?? {}).map(([header, value]) => `${header}: ${value}`)
+	].join("\r\n")}\r\n\r\n`;
+};
+/** This judge reads the status line of the answer to the upgrade. Only 101 passes: a WebSocket server takes the upgrade. */
+const upgradeJudge = statusLineJudge((status, line) => status === 101 ? null : /* @__PURE__ */ new Error(`the server answered ${JSON.stringify(line)} to the upgrade, not 101`));
+/** This function makes the dial of a spec: a new TCP connection, the upgrade request, and a wait for 101. The dial then destroys its socket. */
+const wsDial = (spec) => (host, port, signal) => helloDial(upgradeRequest({
+	...spec,
+	host,
+	port
+}), upgradeJudge)(host, port, signal);
+/** This function gives the payload of a ping: its sequence number as text. */
+const payload = (sequence) => Buffer.from(String(sequence), "latin1");
+/**
+* This function makes a WebSocket client, a dependency of a service over ws 8.
+* - It has one connection as one generation. The end of the connection ends the generation. The
+*   client then connects again by itself, after a backoff.
+* - Its calls are a request until its reply, and a ping until its pong. Each call has a timer of
+*   the wrapper, because ws has none.
+* - Its heartbeat sends a ping frame each interval, one at a time. A ping with no pong in its timeout
+*   is a miss. At the last miss, `terminate()` destroys the socket at once, and the client connects again.
+* - It tells the outcome of a call in three values, and it settles each call in flight at the end of its generation (C8, C10).
+* - It records the URL and the ends of the socket of each connection at its open (D1).
+*
+* These parts come from the core of the clients: the outcomes, the second try and the wait for a ready
+* client. The backoff and its schedule, the calls in flight, the bounded close and the checks come from
+* the core too. The heartbeat is the heartbeat of the package. This entry gives what ws does in its own way.
+*/
+const wsClient = (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 random = options.random ?? Math.random;
+	const create = options.create ?? nodeWs;
+	const dial = options.dial ?? wsDial(spec);
+	const turn = options.turn ?? (() => new Promise((resolve) => setImmediate(resolve)));
+	const operations = operationTable(WS_OPERATIONS, spec.operations);
+	const requestTimeout = ms(knobs.request_timeout);
+	const url = wsUrl(spec);
+	let status = "none";
+	let connection = null;
+	let token = 0;
+	let sequence = 0;
+	let beat = null;
+	let closed = null;
+	const retries = retrySchedule(clock, retryBackoff(knobs), random);
+	const joins = [];
+	const flight = inFlight();
+	const readied = readyWait(clock, () => status === "ready");
+	const replies = /* @__PURE__ */ new Map();
+	const pings = /* @__PURE__ */ new Map();
+	const listeners = /* @__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 waits for the backoff of the next try, then opens a new generation. */
+	const scheduleRetry = () => retries.schedule(() => {
+		if (closing()) return;
+		record("retry.connect", "connecting", `try ${retries.tries}, ${url}`);
+		open();
+	});
+	/** This function ends the generation that is open. It destroys the socket, because a close frame to a silent server gets no answer. */
+	const lose = (on, detail) => {
+		const c = connection;
+		if (c === null) return;
+		connection = null;
+		beat?.stop();
+		beat = null;
+		if (closing()) return;
+		record(on, "failing", detail);
+		flight.settleAll(`the generation ended with the call in flight (${detail})`);
+		c.terminate();
+		scheduleRetry();
+	};
+	/** This function gives a message of the server to the call that waits for it, or to the listeners. A late reply goes to nobody. */
+	const receive = (data, binary) => {
+		let matched = null;
+		try {
+			matched = spec.replies?.reply(data, binary) ?? null;
+		} catch {}
+		if (matched !== null) {
+			replies.get(matched.id)?.(matched.error === void 0 ? {
+				outcome: "ok",
+				value: {
+					data,
+					binary
+				}
+			} : {
+				outcome: "error",
+				error: matched.error,
+				reply: true
+			});
+			return;
+		}
+		for (const listener of [...listeners]) listener(data, binary);
+	};
+	/** This function counts a pong. Each pong answers the heartbeat. A pong for a ping answers each earlier ping too, as RFC 6455 §5.5.3 lets it. */
+	const pong = (data) => {
+		beat?.answer();
+		const text = data.toString("latin1");
+		if (!/^\d{1,15}$/.test(text)) return;
+		const upTo = Number(text);
+		for (const [at, settle] of [...pings]) if (at <= upTo) settle({
+			outcome: "ok",
+			value: void 0
+		});
+	};
+	/** This function starts the heartbeat of a generation: one ping at a time, while the client is ready. */
+	const startBeat = () => heartbeat({
+		interval: ms(knobs.heartbeat_interval),
+		timeout: ms(knobs.heartbeat_timeout),
+		misses: spec.heartbeatMisses,
+		clock,
+		turn,
+		due: () => status === "ready",
+		live: () => status === "ready",
+		ping: () => {
+			if (connection === null) throw new Error(`${name} has no connection`);
+			connection.ping(payload(sequence += 1));
+		},
+		onMiss: (misses) => record("heartbeat.miss", status, `${misses} of ${spec.heartbeatMisses}`),
+		onDead: () => lose("heartbeat.dead", `no pong in heartbeat_timeout, ${spec.heartbeatMisses} times in sequence`)
+	});
+	const join = (c) => {
+		connection = c;
+		retries.reset();
+		const generation = joins.length + 1;
+		joins.push({
+			generation,
+			at: clock.now(),
+			url,
+			protocol: c.protocol,
+			...socketEnds(c.socket)
+		});
+		record("join", "ready", `generation ${generation}, ${url}`);
+		beat = startBeat();
+		readied.wake();
+	};
+	/**
+	* This function opens one generation in `connect_bound`. A failure goes to `failing`, and the
+	* backoff starts. A connection that opens after its bound or after the close is destroyed at once.
+	* The promise resolves when this try ends.
+	*/
+	const open = () => {
+		const mine = token += 1;
+		let opened = null;
+		let joined = false;
+		let finish = () => {};
+		const ended = new Promise((resolve) => finish = resolve);
+		const stale = () => mine !== token || closing();
+		const fail = (detail) => {
+			bound();
+			finish();
+			if (stale()) return;
+			token += 1;
+			opened?.terminate();
+			record("connect.failed", "failing", detail);
+			scheduleRetry();
+		};
+		const bound = clock.after(ms(knobs.connect_bound), () => fail("no open connection in connect_bound"));
+		(async () => {
+			const c = await create(wsOptions(spec));
+			opened = c;
+			if (stale()) {
+				c.terminate();
+				return;
+			}
+			c.listen({
+				open: () => {
+					if (stale()) {
+						c.terminate();
+						return;
+					}
+					bound();
+					joined = true;
+					join(c);
+					finish();
+				},
+				message: (data, binary) => {
+					if (c === connection) receive(data, binary);
+				},
+				pong: (data) => {
+					if (c === connection) pong(data);
+				},
+				close: (code, reason) => {
+					if (c === connection) closed?.();
+					if (joined) {
+						if (c === connection) lose("connection.end", `code ${code}${reason === "" ? "" : `, ${reason}`}`);
+					} else if (!stale()) fail(`the connection closed before its open, with code ${code}`);
+				},
+				error: (error) => {
+					if (joined) {
+						if (c === connection) record("connection.error", status, message(error));
+					} else if (!stale()) fail(message(error));
+				}
+			});
+		})().catch((error) => fail(message(error)));
+		return ended;
+	};
+	/** This function gives the connection for a call, or the reason that the call does not leave the client. */
+	const usable = (signal) => {
+		if (status === "none") return notSent(`${name} has not connected`);
+		if (status !== "ready" || connection === null) return notSent(`${name} is ${status}, not ready: the call did not leave the client`);
+		if (signal?.aborted) return notSent("the caller aborted the call before it left the client");
+		return connection;
+	};
+	/** This function makes one try of a request: the write, then the reply, in `request_timeout`. */
+	const requestAttempt = (call, signal) => {
+		const c = usable(signal);
+		if ("outcome" in c) return Promise.resolve(c);
+		if (spec.replies === void 0) return Promise.resolve(notSent(`${name} has no replies in its spec: no message can answer a request`));
+		if (replies.has(call.id)) return Promise.resolve(notSent(`${name} has a request with the id ${call.id} in flight`));
+		return trackWithTimer(flight, clock, requestTimeout, signal, "the caller abandoned the request after it was written", "no reply in request_timeout: the server can have applied the request", (settle) => {
+			replies.set(call.id, settle);
+			try {
+				c.send(call.data, (error) => {
+					if (error !== void 0) settle({
+						outcome: "indeterminate",
+						error: `the write failed: ${message(error)}`
+					});
+				});
+			} catch (error) {
+				settle(notSent(message(error)));
+			}
+		}, () => {
+			replies.delete(call.id);
+		});
+	};
+	/** This function makes one try of a ping: the ping frame, then a pong, in `request_timeout`. */
+	const pingAttempt = (signal) => {
+		const c = usable(signal);
+		if ("outcome" in c) return Promise.resolve(c);
+		const at = sequence += 1;
+		return trackWithTimer(flight, clock, requestTimeout, signal, "the caller abandoned the ping after it was written", "no pong in request_timeout", (settle) => {
+			pings.set(at, settle);
+			try {
+				c.ping(payload(at));
+			} catch (error) {
+				settle(notSent(message(error)));
+			}
+		}, () => {
+			pings.delete(at);
+		});
+	};
+	const request = (operation, call, sendOptions = {}) => sendWithReissue({
+		clock,
+		bound: requestTimeout,
+		operation: operations[operation],
+		options: sendOptions,
+		attempt: (signal) => requestAttempt(call, signal),
+		beforeAgain: (left, signal) => readied.wait(left, signal),
+		onReissue: () => record("command.reissue", status, operation)
+	});
+	const ping = (sendOptions = {}) => sendWithReissue({
+		clock,
+		bound: requestTimeout,
+		operation: operations["ping"],
+		options: sendOptions,
+		attempt: (signal) => pingAttempt(signal),
+		beforeAgain: (left, signal) => readied.wait(left, signal),
+		onReissue: () => record("command.reissue", status, "ping")
+	});
+	const send = (data) => {
+		const c = usable(void 0);
+		if ("outcome" in c) return false;
+		try {
+			c.send(data, () => {});
+			return true;
+		} catch {
+			return false;
+		}
+	};
+	const handle = {
+		async connect(signal) {
+			if (signal.aborted) throw new Error(`${name}: the service stopped before the connect`);
+			record("status.connecting", "connecting");
+			await open();
+		},
+		async close() {
+			if (status === "none" || closing()) return;
+			record("close.request", "closing");
+			retries.cancel();
+			token += 1;
+			beat?.stop();
+			beat = null;
+			const c = connection;
+			if (c !== null) {
+				const handshake = flight.idle().then(() => new Promise((resolve) => {
+					closed = resolve;
+					c.close(1e3, "the client closed");
+				}));
+				if (!await withinBound(clock, ms(knobs.close_bound), handshake)) {
+					record("close.bound", "closing");
+					record("close.destroy", "closing");
+					c.terminate();
+				}
+				closed = null;
+			}
+			connection = null;
+			flight.settleAll("the client closed with the call in flight");
+			record("status.end", "end");
+		}
+	};
+	const interval = finiteMs(knobs.heartbeat_interval);
+	const declaration = {
+		system: spec.system,
+		knobs: {
+			connect_bound: knobs.connect_bound,
+			request_timeout: knobs.request_timeout,
+			heartbeat_interval: knobs.heartbeat_interval,
+			heartbeat_timeout: knobs.heartbeat_timeout,
+			heartbeat_detection_time: heartbeatDetection(knobs.heartbeat_interval, knobs.heartbeat_timeout, spec.heartbeatMisses),
+			retry_base: knobs.retry_base,
+			retry_cap: knobs.retry_cap,
+			keepalive_idle: knobs.keepalive_idle,
+			idle_refresh_interval: interval === void 0 ? knobs.keepalive_idle : knobs.heartbeat_interval,
+			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((sendOptions) => ping(sendOptions)),
+		dial: dialCheck(dial, spec.host, spec.port)
+	});
+	return {
+		name,
+		declaration,
+		handle,
+		meets: wsMeetings(name, knobs, spec.heartbeatMisses),
+		get status() {
+			return status;
+		},
+		joins,
+		request,
+		ping,
+		send,
+		onMessage(listener) {
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		},
+		checks,
+		attach: (svc, checkOptions) => attachClient(svc, name, declaration, handle, checks(checkOptions)),
+		problems: (description) => clientProblems(name, description, clientBounds(knobs))
+	};
+};
+//#endregion
+//#region src/websocket/machine.ts
+/** The states where the client can close, and the states where a call can start its second try. */
+const SERVING = [
+	"connecting",
+	"ready",
+	"failing"
+];
+const LIVE = [...SERVING, "closing"];
+/**
+* The WebSocket client of the service as a `mark1russell7.machine/1` document. It is one generation
+* at a time: one `WebSocket` of ws 8. The states:
+* - `ready`: the upgrade ended with 101, and the client sends each call. Its heartbeat sends a ping frame each interval.
+* - `failing`: no generation is open. The client connects again after its backoff.
+* - `closing`: the calls in flight, then the close handshake, in `close_bound`. At the bound, `terminate()`.
+*
+* The end of the connection and the last miss of the heartbeat end the generation. A test records
+* the transitions of the client and replays them against this document.
+*/
+const WS_CLIENT_MACHINE = {
+	format: "mark1russell7.machine/1",
+	id: "service.machine.websocket-client",
+	title: "The WebSocket client of the service, over ws 8",
+	layer: "driver",
+	version: "0.1.0",
+	sources: [{
+		ref: "packages/service/src/websocket (the client implements this document)",
+		rung: "implemented"
+	}],
+	states: {
+		none: {
+			initial: true,
+			note: "the client exists, and its first connection does not"
+		},
+		connecting: { note: "the TCP connect and the upgrade, in connect_bound" },
+		ready: { note: "the connection is open. The heartbeat finds a silent server, and the timer of a call ends a call that waits" },
+		failing: { note: "no generation is open. The client connects again after its backoff" },
+		closing: { note: "the calls in flight, then the close handshake, in close_bound. At the bound, terminate() destroys the socket" },
+		end: {
+			final: true,
+			note: "the service closed the client"
+		}
+	},
+	events: {
+		"status.connecting": { kind: "local" },
+		join: {
+			kind: "rx",
+			note: "the upgrade ended with 101: a new generation (D1)"
+		},
+		"connect.failed": {
+			kind: "local",
+			note: "the connect or the upgrade failed, or did not end in connect_bound"
+		},
+		"retry.connect": {
+			kind: "timer",
+			note: "the backoff ended: a new try"
+		},
+		"connection.error": {
+			kind: "rx",
+			note: "an error event of the connection. Its close follows"
+		},
+		"connection.end": {
+			kind: "rx",
+			note: "the connection closed: a reset, a FIN, a close frame of the server, or the kernel"
+		},
+		"heartbeat.miss": {
+			kind: "timer",
+			note: "a ping frame got no pong in heartbeat_timeout"
+		},
+		"heartbeat.dead": {
+			kind: "local",
+			note: "the last miss in sequence: terminate() destroys the socket at once"
+		},
+		"command.reissue": { kind: "local" },
+		"close.request": { kind: "local" },
+		"close.bound": {
+			kind: "timer",
+			note: "the calls in flight or the close handshake did not end in close_bound"
+		},
+		"close.destroy": {
+			kind: "local",
+			note: "terminate() destroys a socket that a silent server does not close"
+		},
+		"status.end": { kind: "local" }
+	},
+	knobs: {
+		connect_bound: clientKnob("handshakeTimeout"),
+		heartbeat_interval: clientKnob("heartbeat.interval"),
+		heartbeat_timeout: clientKnob("heartbeat.timeout"),
+		retry_base: clientKnob("retry.base"),
+		retry_cap: clientKnob("retry.cap"),
+		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 bound of the wrapper on the open. ws bounds the connect and the upgrade with the same time"
+		},
+		heartbeat: {
+			duration: {
+				expr: "heartbeat_interval + heartbeat_timeout",
+				unit: "s"
+			},
+			arms: ["join", "heartbeat.miss"],
+			cancels: [
+				"connection.end",
+				"heartbeat.dead",
+				"close.request"
+			],
+			fires: "heartbeat.miss",
+			note: "one ping at a time: a ping frame each interval, and a miss at its timeout with no pong. Each pong starts it again"
+		},
+		retry: {
+			duration: {
+				expr: "min(retry_cap, retry_base * pow(2, fired)) + retry_base",
+				unit: "s"
+			},
+			arms: [
+				"connect.failed",
+				"connection.end",
+				"heartbeat.dead"
+			],
+			cancels: ["close.request"],
+			fires: "retry.connect",
+			backoff: { resets: ["join"] },
+			note: "the most delay: the backoff doubles from retry_base to retry_cap, with a jitter up to retry_base"
+		},
+		close: closeTimer()
+	},
+	transitions: [
+		transition("connect", "none", "status.connecting", "connecting"),
+		transition("join", "connecting", "join", "ready"),
+		transition("connect-failed", "connecting", "connect.failed", "failing", { timer: "connect_timeout" }),
+		transition("retry", "failing", "retry.connect", "connecting", { timer: "retry" }),
+		transition("connection-end", "ready", "connection.end", "failing"),
+		transition("heartbeat-miss", "ready", "heartbeat.miss", "ready", { timer: "heartbeat" }),
+		transition("heartbeat-dead", "ready", "heartbeat.dead", "failing"),
+		transition("connection-error-ready", "ready", "connection.error", "ready"),
+		transition("connection-error-closing", "closing", "connection.error", "closing"),
+		...LIVE.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/websocket/starting.ts
+/**
+* This poll is the poll of the checks that `WS_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 WS_CLIENT_STARTING_POLL = STARTING_POLL;
+/** This count is the heartbeat misses to start from: 1, as in the WS cells. The drop came 0.999 s to 1.0035 s after the ping with no pong. */
+const WS_CLIENT_STARTING_MISSES = 1;
+/**
+* These knobs are a declaration to start from, from what the WS cells measured on ws 8. 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. ws sets no handshake timeout by default.
+* - `request_timeout` 9.5 s: in the slowest poll of 10 s (O13).
+* - `heartbeat_interval` 4 s: in the WST cells, a ping each 4 s kept a flow through a router that
+*   forgets it at 5 s. A ping each 6 s did not (O03).
+* - `heartbeat_timeout` 3 s: a stall of 1 s with a pong timeout of 3 s dropped nothing. The detection is 4 s + 3 s = 7 s.
+* - `retry_base` 0.5 s and `retry_cap` 4 s: the reconnect of the cells, from 500 ms, doubling to 4 s.
+*   The client adds a jitter up to the base. Thus the most delay is 4.5 s, in the slowest poll of 10 s.
+* - `keepalive_idle` "infinite": ws sets no keepalive, and the heartbeat refreshes an idle flow.
+* - `max_connection_age` "infinite": the client does not replace its connection at an age.
+* - `close_bound` 2 s: a close frame to a silent server gets no answer. The `closeTimeout` of ws is 30 s.
+* - `retrans_giveup_time` 924.6 s: the give-up of Linux at `tcp_retries2 = 15`.
+*/
+const WS_CLIENT_STARTING_KNOBS = {
+	connect_bound: {
+		value: 5,
+		unit: "s"
+	},
+	request_timeout: {
+		value: 9.5,
+		unit: "s"
+	},
+	heartbeat_interval: {
+		value: 4,
+		unit: "s"
+	},
+	heartbeat_timeout: {
+		value: 3,
+		unit: "s"
+	},
+	retry_base: {
+		value: .5,
+		unit: "s"
+	},
+	retry_cap: {
+		value: 4,
+		unit: "s"
+	},
+	keepalive_idle: {
+		value: "infinite",
+		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 { MANIFESTATIONS, STARTING_POLL, WS_CLIENT_MACHINE, WS_CLIENT_STARTING_KNOBS, WS_CLIENT_STARTING_MISSES, WS_CLIENT_STARTING_POLL, WS_OPERATIONS, adaptWs, firstDetector, nodeWs, readyWait, retryBackoff, retryProblems, retrySchedule, specProblems, statusLineJudge, unwatched, upgradeJudge, upgradeRequest, wsClient, wsDial, wsMeetings, wsOptions, wsUrl };
+
+//# sourceMappingURL=websocket.js.map