@mark1russell7/service 0.1.0 → 0.3.0

package/build/redis.js

@@ -0,0 +1,853 @@
+import { n as mayReissue, t as realClock } from "./clock-DlJFFZlX.js";
+import { quantity, valueIn } from "@mark1russell7/quantity";
+import { connect } from "node:net";
+//#region src/redis/connection.ts
+/**
+* This factory makes an ioredis client. It loads ioredis only when a client connects, thus a
+* service that does not use Redis does not need ioredis.
+*/
+const ioredis = async (options) => {
+	return new (await (import("ioredis"))).default(options);
+};
+//#endregion
+//#region src/redis/meets.ts
+const never = {
+	value: "infinite",
+	unit: "s"
+};
+const s = (value) => quantity(Math.round(value * 1e6) / 1e6, "s");
+const seconds = (amount) => amount.value === "infinite" ? Number.POSITIVE_INFINITY : valueIn(amount, "s");
+const plus = (amount, more) => amount.value === "infinite" ? never : s(seconds(amount) + more);
+/**
+* This function gives the manifestations that a Redis client can meet, and the detectors of each, from
+* its knobs. A reset or a FIN arrives on the next segment. A black hole and a host that is gone give
+* no answer at all. A frozen process and a stalled server keep a kernel that acknowledges each
+* segment. Thus TCP keepalive does not fire on them, and only the client's own timers find them.
+*/
+const meetings = (name, knobs, heartbeat) => {
+	const keepalive = plus(knobs.keepalive_idle, 10);
+	const watchdog = (situation) => ({
+		by: "heartbeat_detection_time",
+		within: heartbeat,
+		situation,
+		effect: `the watchdog of ${name} closes the connection, and the client connects again`
+	});
+	const writeoff = {
+		by: "driver_writeoff_time",
+		within: knobs.driver_writeoff_time,
+		situation: "in flight",
+		effect: "ioredis destroys the socket of a command without data, and the client connects again"
+	};
+	const command = {
+		by: "request_timeout",
+		within: knobs.request_timeout,
+		situation: "in flight",
+		effect: "the command fails as indeterminate, and the state of the connection does not change"
+	};
+	const giveUp = {
+		by: "retrans_giveup_time",
+		within: knobs.retrans_giveup_time,
+		situation: "in flight",
+		effect: "the kernel gives up the retransmissions and closes the socket"
+	};
+	const silent = (manifestation, what) => ({
+		manifestation,
+		what,
+		detectors: [
+			command,
+			writeoff,
+			watchdog("in flight"),
+			giveUp,
+			watchdog("idle"),
+			{
+				by: "keepalive_idle",
+				within: keepalive,
+				situation: "idle",
+				effect: "TCP keepalive gives up, and the socket closes"
+			}
+		]
+	});
+	const acknowledged = (manifestation, what) => ({
+		manifestation,
+		what,
+		detectors: [
+			command,
+			writeoff,
+			watchdog("in flight"),
+			watchdog("idle"),
+			{
+				by: "keepalive_idle",
+				within: never,
+				situation: "idle",
+				effect: "the kernel of the server answers each probe"
+			}
+		]
+	});
+	const immediate = (situation, effect) => ({
+		by: "the next segment",
+		within: s(0),
+		situation,
+		effect
+	});
+	return [
+		{
+			manifestation: "rst",
+			what: "the server answers each segment with a reset, and refuses each new connection",
+			detectors: [
+				immediate("in flight", "the command fails, and the client connects again, and each attempt is refused"),
+				watchdog("idle"),
+				{
+					by: "keepalive_idle",
+					within: keepalive.value === "infinite" ? never : knobs.keepalive_idle,
+					situation: "idle",
+					effect: "the first probe gets a reset"
+				}
+			]
+		},
+		{
+			manifestation: "fin",
+			what: "the process of the server ends, and its kernel closes the connection",
+			detectors: [immediate("in flight", "the close arrives, and the command fails"), immediate("idle", "the close arrives")]
+		},
+		silent("blackhole", "the network drops each segment in the two directions"),
+		silent("freeze-host", "the host of the server stops, without a close: the death without a close"),
+		acknowledged("freeze-process", "the process of the server stops, and its kernel stays up"),
+		acknowledged("app-stall", "the server stops its replies for a time, for example a long command, and its kernel stays up")
+	];
+};
+/** This function gives the first detector of a manifestation in a situation, or null when no detector has an end (C3). */
+const firstDetector = (meeting, situation) => {
+	return meeting.detectors.filter((detector) => detector.situation === situation && detector.within.value !== "infinite").sort((a, b) => seconds(a.within) - seconds(b.within))[0] ?? null;
+};
+/** This function gives each manifestation and situation that no detector of the client finds: the standing rule, as a query (C3, E9). */
+const unwatched = (meets) => meets.flatMap((meeting) => ["in flight", "idle"].flatMap((situation) => firstDetector(meeting, situation) === null ? [{
+	manifestation: meeting.manifestation,
+	situation
+}] : []));
+//#endregion
+//#region src/redis/operations.ts
+/**
+* These are the Redis commands whose idempotency the client declares when the declaration does not
+* say. A second issue of an idempotent command has the same effect. Thus the client can send it
+* again after a failure that left its result unknown. The client does not send again a command
+* that is not in this table: a declaration that uses it says its idempotency itself.
+*/
+const SAME_EFFECT = [
+	"PING",
+	"ECHO",
+	"GET",
+	"MGET",
+	"STRLEN",
+	"GETRANGE",
+	"EXISTS",
+	"TYPE",
+	"TTL",
+	"PTTL",
+	"EXPIRETIME",
+	"HGET",
+	"HMGET",
+	"HGETALL",
+	"HKEYS",
+	"HVALS",
+	"HLEN",
+	"HEXISTS",
+	"SMEMBERS",
+	"SISMEMBER",
+	"SMISMEMBER",
+	"SCARD",
+	"ZRANGE",
+	"ZRANGEBYSCORE",
+	"ZSCORE",
+	"ZMSCORE",
+	"ZRANK",
+	"ZCARD",
+	"ZCOUNT",
+	"LRANGE",
+	"LINDEX",
+	"LLEN",
+	"XRANGE",
+	"XREVRANGE",
+	"XLEN",
+	"SCAN",
+	"SSCAN",
+	"HSCAN",
+	"ZSCAN",
+	"DBSIZE",
+	"INFO",
+	"CLIENT ID",
+	"SET",
+	"MSET",
+	"SETEX",
+	"PSETEX",
+	"DEL",
+	"UNLINK",
+	"EXPIRE",
+	"PEXPIRE",
+	"EXPIREAT",
+	"PEXPIREAT",
+	"PERSIST",
+	"HSET",
+	"HDEL",
+	"SADD",
+	"SREM",
+	"ZADD",
+	"ZREM"
+];
+/**
+* These commands change a state relative to the state before them. A second issue changes it again:
+* an INCR that the client sends again after a timeout counts two times.
+*/
+const CHANGE = [
+	"INCR",
+	"INCRBY",
+	"INCRBYFLOAT",
+	"DECR",
+	"DECRBY",
+	"HINCRBY",
+	"HINCRBYFLOAT",
+	"ZINCRBY",
+	"APPEND",
+	"LPUSH",
+	"RPUSH",
+	"LPOP",
+	"RPOP",
+	"BLPOP",
+	"BRPOP",
+	"LMOVE",
+	"BLMOVE",
+	"SPOP",
+	"XADD",
+	"XACK",
+	"PUBLISH",
+	"EVAL",
+	"EVALSHA",
+	"FCALL",
+	"MULTI",
+	"EXEC",
+	"GETDEL",
+	"GETSET",
+	"SETNX"
+];
+/** These are the operations of the client: the idempotency of each command that the table names. */
+const REDIS_OPERATIONS = Object.fromEntries([...SAME_EFFECT.map((command) => [command, { idempotent: true }]), ...CHANGE.map((command) => [command, { idempotent: false }])]);
+/** This function gives the name of a command as the table writes it: upper case, and CLIENT ID with its subcommand. */
+const commandName = (command, args) => {
+	const name = command.toUpperCase();
+	if ((name === "CLIENT" || name === "CONFIG" || name === "DEBUG") && typeof args[0] === "string") return `${name} ${args[0].toUpperCase()}`;
+	return name;
+};
+//#endregion
+//#region src/redis/client.ts
+const ms = (amount) => amount.value === "infinite" ? Number.POSITIVE_INFINITY : valueIn(amount, "ms");
+const finite = (amount) => {
+	const value = ms(amount);
+	return Number.isFinite(value) ? value : void 0;
+};
+const message = (error) => error instanceof Error ? error.message : String(error);
+/**
+* This function gives the time that the watchdog takes to find a silent server, at the most. A PING
+* starts each interval, from the start of the one before. Each one fails at its timeout, and the
+* last of `misses` failures in sequence closes the connection: `misses` intervals plus a timeout.
+*/
+const heartbeatDetection = (interval, timeout, misses) => interval.value === "infinite" ? {
+	value: "infinite",
+	unit: "s"
+} : quantity((misses * ms(interval) + ms(timeout)) / 1e3, "s");
+/** This function gives the problems of a spec: the knobs that the client cannot use. */
+const specProblems = (name, spec) => {
+	const problems = [];
+	const { knobs } = spec;
+	if (!Number.isInteger(spec.heartbeatMisses) || spec.heartbeatMisses < 1) problems.push(`${name}'s watchdog closes the connection after ${spec.heartbeatMisses} misses, not a whole number above zero`);
+	if (knobs.max_connection_age.value !== "infinite") problems.push(`${name} cannot replace its connection at an age: max_connection_age must be "infinite"`);
+	for (const [knob, amount] of Object.entries(knobs)) if (amount.value !== "infinite" && !(ms(amount) >= 0)) problems.push(`${name}'s ${knob} is not a time of zero or more`);
+	if (ms(knobs.request_timeout) <= 0) problems.push(`${name}'s request_timeout is not above zero: each command must have a bound`);
+	if (ms(knobs.heartbeat_timeout) <= 0) problems.push(`${name}'s heartbeat_timeout is not above zero`);
+	if (ms(knobs.retry_cap) < ms(knobs.retry_base)) problems.push(`${name}'s retry_cap is below its retry_base`);
+	return problems;
+};
+/** This dial function opens a TCP connection, sends an inline PING, and waits for +PONG. */
+const tcpDial = (host, port, signal) => new Promise((resolve, reject) => {
+	if (signal.aborted) {
+		reject(/* @__PURE__ */ new Error("the dial was aborted"));
+		return;
+	}
+	const socket = connect({
+		host,
+		port
+	});
+	let reply = "";
+	const end = (error) => {
+		signal.removeEventListener("abort", onAbort);
+		socket.destroy();
+		if (error === void 0) resolve();
+		else reject(error);
+	};
+	const onAbort = () => end(/* @__PURE__ */ new Error("the dial was aborted"));
+	signal.addEventListener("abort", onAbort, { once: true });
+	socket.once("connect", () => socket.write("PING\r\n"));
+	socket.on("data", (chunk) => {
+		reply += chunk.toString();
+		if (reply.includes("\r\n")) end(reply.startsWith("+PONG") ? void 0 : /* @__PURE__ */ new Error(`the reply was ${reply.trim()}`));
+	});
+	socket.once("error", (error) => end(error));
+	socket.once("close", () => end(/* @__PURE__ */ new Error("the server closed the dial")));
+});
+/**
+* This function makes a Redis client. It is a dependency of a service, with ioredis under it:
+* - It sets each timer of ioredis from the declaration, and it does not let ioredis send a command
+*   again (R5 §8).
+* - It tells the outcome of a command in three values, and it settles each command in flight as
+*   indeterminate when its connection closes (C8, C10).
+* - It records the server's id of each connection at `ready` (D1).
+* - A watchdog sends a PING in the band of the connection, and it connects again after the misses
+*   of the declaration. It also starts a client that stopped (principle 19).
+*/
+const redisClient = (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 ?? ioredis;
+	const dial = options.dial ?? tcpDial;
+	const turn = options.turn ?? (() => new Promise((resolve) => setImmediate(resolve)));
+	const operations = {
+		...REDIS_OPERATIONS,
+		...spec.operations
+	};
+	const requestTimeout = ms(knobs.request_timeout);
+	const detection = heartbeatDetection(knobs.heartbeat_interval, knobs.heartbeat_timeout, spec.heartbeatMisses);
+	let connection = null;
+	let status = "none";
+	let closing = false;
+	const joins = [];
+	const inFlight = /* @__PURE__ */ new Set();
+	const readyWaiters = /* @__PURE__ */ new Set();
+	const listeners = [];
+	const record = (from, to, on, detail) => options.record?.({
+		at: clock.now(),
+		machine: "client",
+		instance: name,
+		from,
+		to,
+		on,
+		...detail === void 0 ? {} : { detail }
+	});
+	let retrySince = null;
+	const retryStrategy = (times) => {
+		const now = clock.now();
+		retrySince ??= now;
+		if (now - retrySince > ms(knobs.client_retry_window)) {
+			record(status, status, "retry.window-ended");
+			return null;
+		}
+		const delay = Math.min(ms(knobs.retry_base) * 2 ** (times - 1), ms(knobs.retry_cap));
+		return Math.round(delay + random() * ms(knobs.retry_base));
+	};
+	const connectionOptions = {
+		host: spec.host,
+		port: spec.port,
+		...spec.db === void 0 ? {} : { db: spec.db },
+		...spec.username === void 0 ? {} : { username: spec.username },
+		...spec.password === void 0 ? {} : { password: spec.password },
+		lazyConnect: true,
+		connectTimeout: ms(knobs.connect_bound),
+		commandTimeout: requestTimeout,
+		socketTimeout: finite(knobs.driver_writeoff_time),
+		keepAlive: finite(knobs.keepalive_idle) ?? false,
+		enableOfflineQueue: false,
+		autoResendUnfulfilledCommands: false,
+		maxRetriesPerRequest: null,
+		enableReadyCheck: true,
+		connectionName: name,
+		retryStrategy
+	};
+	/** This function gives the outcome of a failed command: a reply of the server, a command that did not leave the client, or neither. */
+	const failed = (error) => {
+		const text = message(error);
+		if (error instanceof Error && error.name === "ReplyError") return {
+			outcome: "error",
+			error: text,
+			reply: true
+		};
+		if (/isn't writeable|enableOfflineQueue/i.test(text)) return {
+			outcome: "error",
+			error: text,
+			reply: false
+		};
+		return {
+			outcome: "indeterminate",
+			error: text
+		};
+	};
+	const onReady = async () => {
+		retrySince = null;
+		const c = connection;
+		if (c === null) return;
+		const generation = joins.length + 1;
+		const at = clock.now();
+		const socket = c.stream;
+		let clientId = null;
+		try {
+			const reply = await c.call("CLIENT", "ID");
+			clientId = typeof reply === "number" ? reply : Number(reply);
+			if (!Number.isFinite(clientId)) clientId = null;
+		} catch {
+			clientId = null;
+		}
+		if (connection !== c || c.status !== "ready") return;
+		joins.push({
+			generation,
+			at,
+			clientId,
+			localAddress: socket?.localAddress ?? null,
+			localPort: socket?.localPort ?? null,
+			remoteAddress: socket?.remoteAddress ?? null,
+			remotePort: socket?.remotePort ?? null
+		});
+		record("ready", "ready", "join", `generation ${generation}, client id ${clientId ?? "unknown"}`);
+		for (const wake of [...readyWaiters]) wake();
+	};
+	const onStatus = (to) => () => {
+		const from = status;
+		status = to;
+		record(from, to, `status.${to}`);
+		if (to === "close" || to === "end") for (const settle of [...inFlight]) settle({
+			outcome: "indeterminate",
+			error: `the connection closed with the command in flight (${from})`
+		});
+		if (to === "ready") onReady();
+	};
+	const watch = (c) => {
+		for (const state of [
+			"connecting",
+			"connect",
+			"ready",
+			"close",
+			"reconnecting",
+			"end"
+		]) {
+			const listener = onStatus(state);
+			c.on(state, listener);
+			listeners.push([state, listener]);
+		}
+		const onError = (error) => record(status, status, "error", message(error));
+		c.on("error", onError);
+		listeners.push(["error", onError]);
+	};
+	/** This function waits until the connection is ready, for `within` milliseconds at most. It gives true when it is ready. */
+	const waitReady = (within, signal) => new Promise((resolve) => {
+		if (connection?.status === "ready") {
+			resolve(true);
+			return;
+		}
+		let cancel = () => {};
+		const done = (value) => {
+			readyWaiters.delete(wake);
+			cancel();
+			signal?.removeEventListener("abort", aborted);
+			resolve(value);
+		};
+		const wake = () => done(true);
+		const aborted = () => done(false);
+		readyWaiters.add(wake);
+		cancel = clock.after(within, () => done(connection?.status === "ready"));
+		signal?.addEventListener("abort", aborted, { once: true });
+	});
+	const attempt = (command, args, signal) => {
+		const c = connection;
+		if (c === null) return Promise.resolve({
+			outcome: "error",
+			error: `${name} has not connected`,
+			reply: false
+		});
+		if (c.status !== "ready") return Promise.resolve({
+			outcome: "error",
+			error: `${name} is ${c.status}, not ready: the command did not leave the client`,
+			reply: false
+		});
+		if (signal?.aborted) return Promise.resolve({
+			outcome: "error",
+			error: "the caller aborted the command before it left the client",
+			reply: false
+		});
+		return new Promise((resolve) => {
+			let settled = false;
+			const settle = (value) => {
+				if (settled) return;
+				settled = true;
+				inFlight.delete(settle);
+				signal?.removeEventListener("abort", aborted);
+				resolve(value);
+			};
+			const aborted = () => settle({
+				outcome: "indeterminate",
+				error: "the caller abandoned the command after it was sent"
+			});
+			inFlight.add(settle);
+			signal?.addEventListener("abort", aborted, { once: true });
+			c.call(command, ...args).then((value) => settle({
+				outcome: "ok",
+				value
+			}), (error) => settle(failed(error)));
+		});
+	};
+	const send = async (command, args = [], sendOptions = {}) => {
+		const { signal } = sendOptions;
+		const operation = sendOptions.reissue === false ? void 0 : operations[commandName(command, args)];
+		const started = clock.now();
+		const first = await attempt(command, args, signal);
+		if (first.outcome === "ok") return {
+			outcome: "ok",
+			value: first.value,
+			attempts: 1
+		};
+		const again = !(first.outcome === "error" && first.reply) && operation !== void 0 && signal?.aborted !== true && mayReissue(operation, quantity((clock.now() - started) / 1e3, "s"));
+		const left = requestTimeout - (clock.now() - started);
+		if (!again || left <= 0 || !await waitReady(left, signal)) return {
+			...first,
+			attempts: 1
+		};
+		record(status, status, "command.reissue", commandName(command, args));
+		const bound = new AbortController();
+		const end = clock.after(Math.max(0, requestTimeout - (clock.now() - started)), () => bound.abort());
+		const forward = () => bound.abort();
+		signal?.addEventListener("abort", forward, { once: true });
+		const second = await attempt(command, args, bound.signal);
+		end();
+		signal?.removeEventListener("abort", forward);
+		return second.outcome === "ok" ? {
+			outcome: "ok",
+			value: second.value,
+			attempts: 2
+		} : {
+			...second,
+			attempts: 2
+		};
+	};
+	let misses = 0;
+	let nextPing = null;
+	const heartbeatInterval = ms(knobs.heartbeat_interval);
+	const ping = () => {
+		nextPing = clock.after(heartbeatInterval, ping);
+		const c = connection;
+		if (c === null || closing) return;
+		if (c.status === "end") {
+			record(status, status, "watchdog.revive");
+			retrySince = null;
+			c.connect().catch(() => {});
+			return;
+		}
+		if (c.status !== "ready") return;
+		const controller = new AbortController();
+		const timer = clock.after(ms(knobs.heartbeat_timeout), () => controller.abort());
+		attempt("PING", [], controller.signal).then(async (result) => {
+			timer();
+			const answered = result.outcome === "ok" || result.outcome === "error" && result.reply;
+			await turn();
+			if (answered) {
+				misses = 0;
+				return;
+			}
+			if (connection?.status !== "ready" || closing) return;
+			misses += 1;
+			record(status, status, "watchdog.miss", `${misses} of ${spec.heartbeatMisses}`);
+			if (misses >= spec.heartbeatMisses) {
+				misses = 0;
+				record(status, status, "watchdog.reconnect");
+				connection.disconnect(true);
+			}
+		});
+	};
+	const handle = {
+		async connect(signal) {
+			closing = false;
+			const c = await create(connectionOptions);
+			connection = c;
+			watch(c);
+			if (signal.aborted) throw new Error(`${name}: the service stopped before the connect`);
+			await c.connect().catch((error) => record(status, status, "connect.failed", message(error)));
+			if (Number.isFinite(heartbeatInterval)) nextPing = clock.after(heartbeatInterval, ping);
+		},
+		async close() {
+			closing = true;
+			nextPing?.();
+			nextPing = null;
+			const c = connection;
+			if (c === null) return;
+			const quit = c.quit().then(() => "quit", () => "quit");
+			let cancel = () => {};
+			const bound = new Promise((resolve) => {
+				cancel = clock.after(ms(knobs.close_bound), () => resolve("bound"));
+			});
+			const startedClose = clock.now();
+			const first = await Promise.race([quit, bound]);
+			cancel();
+			if (first === "bound") record(status, status, "close.bound");
+			if (c.status !== "end") c.disconnect(false);
+			const ended = (within) => c.status === "end" ? Promise.resolve() : new Promise((resolve) => {
+				let stop = () => {};
+				const end = () => {
+					c.off("end", end);
+					stop();
+					resolve();
+				};
+				c.on("end", end);
+				stop = clock.after(Math.max(0, within), end);
+			});
+			await ended(ms(knobs.close_bound) - (clock.now() - startedClose));
+			if (c.status !== "end") {
+				record(status, status, "close.destroy");
+				c.stream?.destroy?.();
+				await ended(0);
+			}
+			for (const [event, listener] of listeners) c.off(event, listener);
+			listeners.length = 0;
+			for (const settle of [...inFlight]) settle({
+				outcome: "indeterminate",
+				error: "the client closed with the command in flight"
+			});
+			status = "end";
+		}
+	};
+	const declaration = {
+		system: spec.system,
+		knobs: {
+			connect_bound: knobs.connect_bound,
+			request_timeout: knobs.request_timeout,
+			driver_writeoff_time: knobs.driver_writeoff_time,
+			keepalive_idle: knobs.keepalive_idle,
+			heartbeat_interval: knobs.heartbeat_interval,
+			heartbeat_timeout: knobs.heartbeat_timeout,
+			heartbeat_detection_time: detection,
+			client_retry_window: knobs.client_retry_window,
+			retry_base: knobs.retry_base,
+			retry_cap: knobs.retry_cap,
+			close_bound: knobs.close_bound,
+			max_connection_age: knobs.max_connection_age,
+			retrans_giveup_time: knobs.retrans_giveup_time
+		},
+		operations
+	};
+	const checks = (checkOptions) => {
+		const made = [];
+		const declare = (step, ownConnection, run) => {
+			if (!(step in checkOptions.steps)) return;
+			made.push([{
+				name: `${name}.${step}`,
+				dependency: name,
+				step,
+				ownConnection,
+				gates: checkOptions.steps[step] ?? null,
+				poll: checkOptions.poll
+			}, run]);
+		};
+		declare("local-state", true, () => connection?.status === "ready" ? "ok" : "error");
+		declare("round-trip", true, async (signal) => {
+			return (await send("PING", [], {
+				signal,
+				reissue: false
+			})).outcome === "ok" ? "ok" : "error";
+		});
+		declare("dial", false, async (signal) => {
+			await dial(spec.host, spec.port, signal);
+			return "ok";
+		});
+		return made;
+	};
+	return {
+		name,
+		declaration,
+		handle,
+		meets: meetings(name, knobs, detection),
+		get status() {
+			return connection === null ? "none" : connection.status;
+		},
+		joins,
+		send,
+		checks,
+		attach(svc, checkOptions) {
+			svc.dependency(name, declaration, handle);
+			for (const [check, run] of checks(checkOptions)) svc.check(check, run);
+			return svc;
+		},
+		problems(description) {
+			const found = [];
+			const teardown = description.shutdown.phases.find((phase) => phase.name === "tear down dependencies");
+			if (teardown === void 0) found.push(`${name} needs the phase "tear down dependencies" to close`);
+			else if (ms(knobs.close_bound) >= valueIn(teardown.cap, "ms")) found.push(`${name}'s close_bound of ${ms(knobs.close_bound)} ms does not fit in the cap of "tear down dependencies"`);
+			for (const check of description.checks) {
+				if (check.dependency !== name) continue;
+				const slowest = valueIn(check.poll.timeout, "ms");
+				if (check.step === "round-trip" && requestTimeout > slowest + valueIn(check.poll.interval, "ms") * (1 + check.poll.jitter)) found.push(`${name}'s request_timeout outlives one jittered poll of ${check.name} (B7, O13)`);
+			}
+			return found;
+		}
+	};
+};
+//#endregion
+//#region src/redis/machine.ts
+const t = (id, from, on, to, extra = {}) => ({
+	id,
+	from,
+	on,
+	to,
+	...extra
+});
+const knob = (key) => ({
+	key,
+	scope: "client",
+	unit: "s",
+	default: null
+});
+/** The states where the connection exists or tries to exist, thus where it can close. */
+const LIVE = [
+	"connecting",
+	"connect",
+	"ready",
+	"reconnecting"
+];
+const ANY = [
+	"none",
+	"connecting",
+	"connect",
+	"ready",
+	"close",
+	"reconnecting",
+	"end"
+];
+/**
+* The Redis client as a `mark1russell7.machine/1` document. Its states are the states of ioredis.
+* The wrapper adds its own events: the join at each `ready`, and the misses of its watchdog. It also
+* adds a command that it sends again, and the bound of its close. A test records the transitions of the
+* client and replays them against this document.
+*
+* The state `ready` hides states that the client cannot see (D4). In a black hole, ioredis stays
+* `ready` while the kernel retransmits, until `driver_writeoff_time` or the watchdog ends that
+* hidden interval. A timer of this document bounds each hidden interval.
+*/
+const REDIS_CLIENT_MACHINE = {
+	format: "mark1russell7.machine/1",
+	id: "service.machine.redis-client",
+	title: "The Redis client of the service, over ioredis 6",
+	layer: "driver",
+	version: "0.2.0",
+	sources: [{
+		ref: "packages/service/src/redis (the client implements this document)",
+		rung: "implemented"
+	}],
+	states: {
+		none: {
+			initial: true,
+			note: "the client exists, and its connection does not"
+		},
+		connecting: { note: "a TCP connection attempt" },
+		connect: { note: "the handshake: HELLO, then the ready check (INFO)" },
+		ready: { note: "it can hide a black hole or a frozen server, until a timer of the client ends it" },
+		close: { note: "the socket closed. Each command in flight settles as indeterminate" },
+		reconnecting: { note: "the delay of the retry strategy, which doubles to its cap" },
+		end: { note: "the retry window ended, or the service closed the client. The watchdog starts it again" }
+	},
+	events: {
+		"status.connecting": { kind: "local" },
+		"status.connect": { kind: "rx" },
+		"status.ready": { kind: "rx" },
+		"status.close": { kind: "rx" },
+		"status.reconnecting": { kind: "timer" },
+		"status.end": { kind: "local" },
+		join: {
+			kind: "rx",
+			note: "the reply of CLIENT ID at ready (D1)"
+		},
+		error: { kind: "rx" },
+		"connect.failed": { kind: "local" },
+		"command.written": { kind: "tx" },
+		"command.reissue": { kind: "local" },
+		data: { kind: "rx" },
+		heartbeat: { kind: "timer" },
+		"watchdog.miss": { kind: "local" },
+		"watchdog.reconnect": { kind: "local" },
+		"watchdog.revive": { kind: "local" },
+		"retry.window-ended": { kind: "local" },
+		"close.request": { kind: "local" },
+		"close.bound": { kind: "timer" },
+		"close.destroy": {
+			kind: "local",
+			note: "the bound destroys a socket that a silent server does not close"
+		}
+	},
+	knobs: {
+		connect_bound: knob("connectTimeout"),
+		driver_writeoff_time: knob("socketTimeout"),
+		heartbeat_interval: knob("watchdog.interval"),
+		close_bound: knob("close.bound")
+	},
+	timers: {
+		connect_timeout: {
+			duration: {
+				knob: "connect_bound",
+				unit: "s"
+			},
+			arms: ["enter:connecting"],
+			cancels: ["status.connect", "status.close"],
+			fires: "status.close",
+			note: "ioredis destroys the attempt"
+		},
+		writeoff: {
+			duration: {
+				knob: "driver_writeoff_time",
+				unit: "s"
+			},
+			arms: ["command.written"],
+			cancels: ["data", "status.close"],
+			fires: "status.close",
+			note: "ioredis destroys a socket that gives no data while a command waits: it ends the hidden interval of a black hole"
+		},
+		heartbeat: {
+			duration: {
+				knob: "heartbeat_interval",
+				unit: "s"
+			},
+			arms: ["enter:ready", "heartbeat"],
+			cancels: ["status.close", "status.end"],
+			fires: "heartbeat",
+			note: "a PING on the connection of the application"
+		},
+		close: {
+			duration: {
+				knob: "close_bound",
+				unit: "s"
+			},
+			arms: ["close.request"],
+			cancels: ["status.end"],
+			fires: "close.bound"
+		}
+	},
+	transitions: [
+		t("connect", [
+			"none",
+			"reconnecting",
+			"end",
+			"close"
+		], "status.connecting", "connecting"),
+		t("tcp", "connecting", "status.connect", "connect"),
+		t("ready", "connect", "status.ready", "ready"),
+		t("close", [...LIVE], "status.close", "close"),
+		t("retry", "close", "status.reconnecting", "reconnecting"),
+		t("end", [...LIVE, "close"], "status.end", "end"),
+		t("join", "ready", "join", "ready"),
+		t("miss", "ready", "watchdog.miss", "ready"),
+		t("watchdog-reconnect", "ready", "watchdog.reconnect", "ready"),
+		t("revive", "end", "watchdog.revive", "end"),
+		t("window-ended", "close", "retry.window-ended", "close"),
+		...ANY.map((state) => t(`error-${state}`, state, "error", state)),
+		...ANY.map((state) => t(`connect-failed-${state}`, state, "connect.failed", state)),
+		...ANY.map((state) => t(`reissue-${state}`, state, "command.reissue", state)),
+		...ANY.map((state) => t(`close-bound-${state}`, state, "close.bound", state, { timer: "close" })),
+		...ANY.map((state) => t(`close-destroy-${state}`, state, "close.destroy", state))
+	]
+};
+//#endregion
+export { REDIS_CLIENT_MACHINE, REDIS_OPERATIONS, commandName, firstDetector, heartbeatDetection, ioredis, meetings, redisClient, specProblems, tcpDial, unwatched };
+
+//# sourceMappingURL=redis.js.map