@mark1russell7/service 0.5.12 → 0.5.13

package/build/grpc.js

@@ -0,0 +1,859 @@
+import { realClock } from "./clock.js";
+import { i as heartbeatDetection } from "./timing-DGRi3XCI.js";
+import { B as zeroProblems, C as notSent, D as readyWait, F as timeProblems, G as immediate, H as NEVER, 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, h as finiteMs, i as authority, j as roundTripCheck, k as retryProblems, l as attachClient, m as dialCheck, n as closeTimer, r as transition, s as STARTING_POLL, t as clientKnob, u as clientBounds, w as operationTable, y as localStateCheck, z as wrapperTimerProblems } from "./machine-BhTRu3u9.js";
+//#region src/grpc/connection.ts
+/** These states are in the sequence of the enum of grpc-js: the index of a state is its value. */
+const GRPC_STATES = [
+	"IDLE",
+	"CONNECTING",
+	"READY",
+	"TRANSIENT_FAILURE",
+	"SHUTDOWN"
+];
+/** These functions give the bytes of a message as they are. The caller encodes and decodes its messages. */
+const identity = (bytes) => bytes;
+/** This function gives the state of a value of the enum of grpc-js. */
+const stateOf = (value) => GRPC_STATES[value] ?? "SHUTDOWN";
+/**
+* This function adapts a `Client` of grpc-js to a channel. The deadline of grpc-js is a time of the
+* wall clock, thus the adapter adds the timeout to `Date.now()`.
+*/
+const adaptGrpc = (grpc, client) => {
+	const channel = client.getChannel();
+	return {
+		state: (connect) => stateOf(channel.getConnectivityState(connect)),
+		watch(current, changed) {
+			try {
+				channel.watchConnectivityState(GRPC_STATES.indexOf(current), Number.POSITIVE_INFINITY, (error) => {
+					if (error === void 0) changed();
+				});
+			} catch {}
+		},
+		unary(method, request, metadata, timeout, done) {
+			const sent = new grpc.Metadata();
+			for (const [key, value] of Object.entries(metadata)) sent.add(key, value);
+			const deadline = Number.isFinite(timeout) ? Date.now() + timeout : Number.POSITIVE_INFINITY;
+			return client.makeUnaryRequest(method, identity, identity, request, sent, { deadline }, (error, value) => {
+				if (error === null) done({
+					code: 0,
+					details: ""
+				}, value ?? Buffer.alloc(0));
+				else done({
+					code: error.code ?? 2,
+					details: error.details ?? error.message ?? ""
+				}, void 0);
+			});
+		},
+		close: () => client.close()
+	};
+};
+/**
+* This factory makes a `Client` of grpc-js. It loads grpc-js only when a client connects, thus a
+* service that does not use gRPC does not need it. The specifier is a value, thus the package needs no types of grpc-js.
+*/
+const nodeGrpc = async ({ target, options }) => {
+	const loaded = await import("@grpc/grpc-js");
+	const grpc = loaded.Client === void 0 ? loaded.default : loaded;
+	if (grpc?.Client === void 0) throw new Error("@grpc/grpc-js gives no Client class");
+	return adaptGrpc(grpc, new grpc.Client(target, grpc.credentials.createInsecure(), options));
+};
+//#endregion
+//#region src/grpc/meets.ts
+/**
+* This function gives the manifestations that a gRPC client can meet, and the detectors of each,
+* from its knobs. The gRPC cells measured them on grpc-js 1.14.6:
+* - At its defaults, grpc-js has no detector: no keepalive, no deadline, and no TCP keepalive.
+* - A reset gave each call ECONNRESET in 1.1 ms to 1.4 ms. The FIN of a stopped server ended an idle connection in 43 µs.
+* - The keepalive ended a silent transport at keepalive_time + keepalive_timeout: 80.012 s at 60 s
+*   against etcd, and 320.005 s at 300 s against grpc-go (DP24).
+* - Without `keepaliveWithoutCalls`, grpc-js sends a PING only with a call in flight.
+* - At client_idle_timeout, the channel goes IDLE, and the client connects again. A server that does
+*   not answer then keeps the channel out of READY.
+*/
+const grpcMeetings = (name, knobs, withoutCalls) => {
+	const interval = finiteMs(knobs.keepalive_time);
+	const detection = heartbeatDetection(knobs.keepalive_time, knobs.keepalive_timeout, 1);
+	const keepalive = (situation) => ({
+		by: "heartbeat_detection_time",
+		within: situation === "idle" && !withoutCalls ? NEVER : detection,
+		situation,
+		effect: situation === "idle" && !withoutCalls ? "grpc-js sends no PING with no call in flight" : `the PING gets no ACK in keepalive_timeout, the transport ends, each call in flight fails with UNAVAILABLE, and ${name} connects again`
+	});
+	const deadline = {
+		by: "request_timeout",
+		within: knobs.request_timeout,
+		situation: "in flight",
+		effect: "the deadline ends the call with DEADLINE_EXCEEDED as indeterminate, and the transport stays"
+	};
+	const reconnect = {
+		by: "client_idle_timeout",
+		within: knobs.client_idle_timeout,
+		situation: "idle",
+		effect: `the channel goes IDLE, ${name} connects again, and the new connection does not become ready`
+	};
+	const giveUp = kernelGiveUp(knobs.retrans_giveup_time, "each call in flight fails with UNAVAILABLE");
+	const silent = (manifestation) => ({
+		manifestation,
+		what: WHAT[manifestation],
+		detectors: [
+			deadline,
+			keepalive("in flight"),
+			giveUp,
+			keepalive("idle"),
+			reconnect
+		]
+	});
+	return [
+		{
+			manifestation: "rst",
+			what: WHAT.rst,
+			detectors: [
+				immediate("in flight", "the reset arrives, each call fails with UNAVAILABLE as indeterminate, and the channel goes IDLE"),
+				{
+					by: "keepalive_time",
+					within: interval === void 0 || !withoutCalls ? NEVER : knobs.keepalive_time,
+					situation: "idle",
+					effect: "the next PING gets a reset, and the client connects again"
+				},
+				{
+					...reconnect,
+					effect: `the channel goes IDLE, ${name} connects again, and the server refuses the connect`
+				}
+			]
+		},
+		{
+			manifestation: "fin",
+			what: WHAT.fin,
+			detectors: [immediate("in flight", "the FIN arrives, and each call fails with UNAVAILABLE as indeterminate"), immediate("idle", "the FIN arrives, the channel goes IDLE, and the client connects again")]
+		},
+		silent("blackhole"),
+		silent("freeze-host"),
+		{
+			manifestation: "freeze-process",
+			what: WHAT["freeze-process"],
+			detectors: [
+				deadline,
+				keepalive("in flight"),
+				keepalive("idle"),
+				reconnect
+			]
+		},
+		{
+			manifestation: "app-stall",
+			what: "the server holds its reply, for example in a slow handler, and its library still answers each PING",
+			detectors: [
+				deadline,
+				{
+					...keepalive("idle"),
+					within: NEVER,
+					effect: "the library of the server still answers each PING with an ACK"
+				},
+				{
+					...reconnect,
+					within: NEVER,
+					effect: "the library of the server still takes a new connection"
+				}
+			]
+		}
+	];
+};
+//#endregion
+//#region src/grpc/client.ts
+/** The names of the status codes of gRPC, by their value. */
+const GRPC_CODES = [
+	"OK",
+	"CANCELLED",
+	"UNKNOWN",
+	"INVALID_ARGUMENT",
+	"DEADLINE_EXCEEDED",
+	"NOT_FOUND",
+	"ALREADY_EXISTS",
+	"PERMISSION_DENIED",
+	"RESOURCE_EXHAUSTED",
+	"FAILED_PRECONDITION",
+	"ABORTED",
+	"OUT_OF_RANGE",
+	"UNIMPLEMENTED",
+	"INTERNAL",
+	"UNAVAILABLE",
+	"DATA_LOSS",
+	"UNAUTHENTICATED"
+];
+/**
+* These codes are certain errors: each one tells that the server or a proxy refused the call, and did
+* not apply it. A proxy that answers 401, 403 or 404 gives UNAUTHENTICATED, PERMISSION_DENIED or UNIMPLEMENTED.
+*/
+const CERTAIN = /* @__PURE__ */ new Set([
+	3,
+	5,
+	6,
+	7,
+	9,
+	10,
+	11,
+	12,
+	16
+]);
+/**
+* These statuses of grpc-js tell that the call did not leave the client. A status with another
+* details text of the same code can come after the send, thus it is indeterminate:
+* - UNAVAILABLE "No connection established": the pick of a channel in TRANSIENT_FAILURE (picker.ts:105).
+* - UNAVAILABLE "Name resolution failed": the resolver found no address (resolver-dns.ts:119).
+* - UNAVAILABLE "Stream refused by server": RST_STREAM REFUSED_STREAM. The server did not process the stream (RFC 9113 §8.7).
+* - INTERNAL "Failed to start HTTP/2 stream": the stream did not start (load-balancing-call.ts:281).
+* - DEADLINE_EXCEEDED with "Waiting for LB pick" or "waiting for name resolution": the deadline came before a stream.
+*/
+const NOT_SENT = [
+	[14, /^No connection established/],
+	[14, /^Name resolution failed/],
+	[14, /^Stream refused by server$/],
+	[13, /^Failed to start HTTP\/2 stream/],
+	[4, /(^|,)(Waiting for LB pick|waiting for name resolution)(,|$)/]
+];
+/** This function gives the name of a status code, for example "UNAVAILABLE". */
+const codeName = (code) => GRPC_CODES[code] ?? `code ${code}`;
+/**
+* This function gives the outcome of one call from its status:
+* - OK is `ok`.
+* - A code that tells that the server refused the call is a certain error: `reply` is true.
+* - A status that tells that the call did not leave the client is a certain error with `reply` false.
+* - Each other status is indeterminate: CANCELLED, UNKNOWN, DEADLINE_EXCEEDED, RESOURCE_EXHAUSTED,
+*   INTERNAL, UNAVAILABLE and DATA_LOSS can come after the server applied the call.
+*/
+const grpcOutcome = (status, response) => {
+	if (status.code === 0) return {
+		outcome: "ok",
+		value: response ?? Buffer.alloc(0)
+	};
+	const error = `${codeName(status.code)}: ${status.details}`;
+	if (CERTAIN.has(status.code)) return {
+		outcome: "error",
+		error,
+		reply: true
+	};
+	if (NOT_SENT.some(([code, details]) => code === status.code && details.test(status.details))) return notSent(`${error} (the call did not leave the client)`);
+	return {
+		outcome: "indeterminate",
+		error
+	};
+};
+/** This method is the Check of the health service. Its request names a service, and its response gives a serving status. */
+const HEALTH_CHECK = "/grpc.health.v1.Health/Check";
+/** These operations are in each table: the Check of the health service has no side effects. */
+const GRPC_OPERATIONS = { [HEALTH_CHECK]: { idempotent: true } };
+/**
+* This function makes a table of operations from the idempotency level of each method, by its full
+* path. NO_SIDE_EFFECTS and IDEMPOTENT are idempotent. IDEMPOTENCY_UNKNOWN, the default of a proto, is not.
+*/
+const grpcOperations = (levels) => Object.fromEntries(Object.entries(levels).map(([method, level]) => [method, { idempotent: level !== "IDEMPOTENCY_UNKNOWN" }]));
+/** This function gives the bytes of a varint of protobuf. */
+const varint = (value) => {
+	const bytes = [];
+	let rest = value;
+	while (rest > 127) {
+		bytes.push(rest & 127 | 128);
+		rest = Math.floor(rest / 128);
+	}
+	bytes.push(rest);
+	return Buffer.from(bytes);
+};
+/** This function gives the bytes of a HealthCheckRequest. The service "" is the whole server, and its message is empty. */
+const healthRequest = (service) => {
+	if (service === "") return Buffer.alloc(0);
+	const name = Buffer.from(service, "utf8");
+	return Buffer.concat([
+		Buffer.from([10]),
+		varint(name.length),
+		name
+	]);
+};
+const SERVING$1 = [
+	"UNKNOWN",
+	"SERVING",
+	"NOT_SERVING",
+	"SERVICE_UNKNOWN"
+];
+/** This function gives the status of a HealthCheckResponse, or null when the bytes are not one. An empty message is UNKNOWN. */
+const healthStatus = (bytes) => {
+	let at = 0;
+	let status = 0;
+	const read = () => {
+		let value = 0;
+		for (let shift = 0; shift < 35; shift += 7) {
+			const byte = bytes[at];
+			if (byte === void 0) return null;
+			at += 1;
+			value += (byte & 127) * 2 ** shift;
+			if ((byte & 128) === 0) return value;
+		}
+		return null;
+	};
+	while (at < bytes.length) {
+		const tag = read();
+		if (tag === null) return null;
+		const wire = tag & 7;
+		if (wire === 0) {
+			const value = read();
+			if (value === null) return null;
+			if (tag >> 3 === 1) status = value;
+		} else if (wire === 2) {
+			const length = read();
+			if (length === null || at + length > bytes.length) return null;
+			at += length;
+		} else if (wire === 1 || wire === 5) {
+			at += wire === 1 ? 8 : 4;
+			if (at > bytes.length) return null;
+		} else return null;
+	}
+	return SERVING$1[status] ?? null;
+};
+/** The longest timer of Node, in milliseconds. A longer delay starts at 1 ms, thus grpc-js cannot take it. */
+const LONGEST_TIMER = 2147483647;
+/** This function gives the problems of the times that grpc-js gives to `setTimeout` with no check: each one is at most the longest timer. */
+const longestTimerProblems = (name, knobs, names) => names.flatMap((knob) => {
+	const amount = knobs[knob];
+	return amount.value !== "infinite" && ms(amount) > LONGEST_TIMER ? [`${name}'s ${knob} is above ${LONGEST_TIMER} ms, the longest timer of Node`] : [];
+});
+/** This function gives the problems of a spec: the knobs that the client cannot use. */
+const specProblems = (name, spec) => {
+	const { knobs } = spec;
+	const timers = [
+		"keepalive_time",
+		"keepalive_timeout",
+		"client_idle_timeout",
+		"retry_base",
+		"retry_cap"
+	];
+	const problems = [
+		...timeProblems(name, knobs),
+		...wrapperTimerProblems(name, knobs, {
+			connect_bound: "the wait of the startup for a ready channel",
+			request_timeout: "a call"
+		}),
+		...zeroProblems(name, "grpc-js", knobs, { open: ["keepalive_time"] }),
+		...wholeProblems(name, knobs, { millis: timers }),
+		...longestTimerProblems(name, knobs, timers),
+		...retryProblems(name, knobs),
+		...ageProblems(name, knobs, "grpc-js does not replace its connection at an age")
+	];
+	for (const knob of [
+		"keepalive_timeout",
+		"client_idle_timeout",
+		"retry_base",
+		"retry_cap"
+	]) if (finiteMs(knobs[knob]) === void 0 || !(ms(knobs[knob]) > 0)) problems.push(`${name}'s ${knob} is not a finite time above zero`);
+	if (ms(knobs.client_idle_timeout) < 1e3) problems.push(`${name}'s client_idle_timeout is below 1 s: grpc-js raises it to 1 s`);
+	if (knobs.keepalive_idle.value !== "infinite") problems.push(`${name}'s keepalive_idle is not "infinite": grpc-js sets no TCP keepalive, and the PING of keepalive_time is its keepalive`);
+	if (spec.password !== void 0) problems.push(`${name} takes no password: give the credentials in metadata, for example authorization`);
+	return problems;
+};
+/** This function gives the target of a channel from a spec: the host and the port, for the DNS resolver of grpc-js. */
+const grpcTarget = (spec) => authority(spec.host, spec.port);
+/**
+* This function gives the arguments of `new Client` from a spec. Each timer of grpc-js comes from the
+* declaration. The retries of grpc-js are off, and the resolver gives no service config.
+*/
+const grpcOptions = (spec) => {
+	const { knobs } = spec;
+	const keepalive = finiteMs(knobs.keepalive_time);
+	return {
+		target: grpcTarget(spec),
+		options: {
+			"grpc.enable_retries": 0,
+			"grpc.service_config_disable_resolution": 1,
+			...keepalive === void 0 ? {} : { "grpc.keepalive_time_ms": keepalive },
+			"grpc.keepalive_timeout_ms": ms(knobs.keepalive_timeout),
+			"grpc.keepalive_permit_without_calls": spec.keepaliveWithoutCalls ? 1 : 0,
+			"grpc.client_idle_timeout_ms": ms(knobs.client_idle_timeout),
+			"grpc.initial_reconnect_backoff_ms": ms(knobs.retry_base),
+			"grpc.max_reconnect_backoff_ms": ms(knobs.retry_cap)
+		}
+	};
+};
+/** These are the bytes of the dial: the connection preface of the client (RFC 9113 §3.4), and a SETTINGS frame with no setting. */
+const HTTP2_PREFACE = Buffer.concat([Buffer.from("PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n", "latin1"), Buffer.from([
+	0,
+	0,
+	0,
+	4,
+	0,
+	0,
+	0,
+	0,
+	0
+])]);
+/**
+* This judge reads the first frame of the server. Only a SETTINGS frame on stream 0, with no ACK,
+* passes: RFC 9113 §3.4 makes it the first frame of an HTTP/2 server. An HTTP/1.1 server answers with a status line.
+*/
+const settingsJudge = (received) => {
+	if (received.length < 9) return "more";
+	const type = received[3];
+	const flags = received[4];
+	const stream = received.readUInt32BE(5) & 2147483647;
+	return type === 4 && (flags & 1) === 0 && stream === 0 ? null : /* @__PURE__ */ new Error(`the server did not answer the HTTP/2 preface with a SETTINGS frame: its first bytes are ${received.subarray(0, 9).toString("hex")}`);
+};
+/** This dial opens a new TCP connection, sends the HTTP/2 preface, and waits for the SETTINGS frame of the server. The dial then destroys its socket. */
+const grpcDial = helloDial(HTTP2_PREFACE, settingsJudge);
+/**
+* This function makes a gRPC client, a dependency of a service over grpc-js 1.14.
+* - It has one channel for its life. Each time that the channel becomes READY is one generation.
+* - The grpc-js driver connects again by itself, after its own backoff. The client connects an IDLE channel again at once.
+* - A call is one unary call, until its status. Its deadline is the time that is left in `request_timeout`.
+* - It tells the outcome of a call in three values from its status code (C8).
+* - The retries of grpc-js are off, thus only the core sends a call again.
+* - Its keepalive is the HTTP/2 PING of grpc-js. It records the target of each generation (D1).
+*
+* These parts come from the core of the clients: the outcomes, the second try and the wait for a ready client.
+* The calls in flight, the bounded close and the checks come from the core too. This entry gives what grpc-js does in its own way.
+*/
+const grpcClient = (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 ?? nodeGrpc;
+	const dial = options.dial ?? grpcDial;
+	const operations = operationTable(GRPC_OPERATIONS, spec.operations);
+	const requestTimeout = ms(knobs.request_timeout);
+	const target = grpcTarget(spec);
+	let status = "none";
+	let channel = null;
+	let settled = null;
+	const joins = [];
+	const flight = inFlight();
+	const readied = readyWait(clock, () => status === "ready");
+	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 follows one state of the channel. The grpc-js driver ends each call in flight by itself when its transport ends. */
+	const follow = (c, state) => {
+		if (c !== channel || closing()) return;
+		if (state === "READY") {
+			if (status === "ready") return;
+			const generation = joins.length + 1;
+			joins.push({
+				generation,
+				at: clock.now(),
+				target,
+				...socketEnds(void 0)
+			});
+			record("join", "ready", `generation ${generation}, ${target}`);
+			readied.wake();
+			settled?.();
+		} else if (state === "TRANSIENT_FAILURE") {
+			if (status === "failing") return;
+			record("connect.failed", "failing", "the channel is in TRANSIENT_FAILURE: grpc-js connects again after its backoff");
+			settled?.();
+		} else if (state === "CONNECTING") {
+			if (status !== "connecting") record("channel.connecting", "connecting", target);
+		} else if (state === "IDLE") {
+			if (status === "ready") record("connection.end", "idle", "the transport ended: a GOAWAY, a reset, a FIN, the keepalive, or client_idle_timeout");
+			else if (status !== "idle") record("channel.idle", "idle", "the channel is IDLE");
+			c.state(true);
+		}
+	};
+	/** This function watches the state of the channel. It watches again before it follows, thus no change goes away. */
+	const watch = (c, current) => c.watch(current, () => {
+		if (c !== channel || closing()) return;
+		const next = c.state(false);
+		if (next !== "SHUTDOWN") watch(c, next);
+		follow(c, next);
+	});
+	/** This function gives the channel 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" || channel === 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 channel;
+	};
+	/** This function makes one try of a call: the unary call until its status, with the deadline that is left. */
+	const attempt = (method, request, metadata, timeout, signal) => {
+		const c = usable(signal);
+		if ("outcome" in c) return Promise.resolve(c);
+		if (!(timeout > 0)) return Promise.resolve(notSent("no time is left in request_timeout"));
+		let handle = null;
+		let ended = false;
+		return flight.track(signal, "the caller abandoned the call after it left the client", (settle) => {
+			try {
+				handle = c.unary(method, request, metadata, timeout, (given, response) => {
+					ended = true;
+					settle(grpcOutcome(given, response));
+				});
+			} catch (error) {
+				ended = true;
+				settle(notSent(message(error)));
+			}
+		}, () => {
+			if (!ended) handle?.cancel();
+		});
+	};
+	const call = (method, request, callOptions = {}) => {
+		const started = clock.now();
+		const metadata = {
+			...spec.metadata,
+			...callOptions.metadata
+		};
+		return sendWithReissue({
+			clock,
+			bound: requestTimeout,
+			operation: operations[method],
+			options: callOptions,
+			attempt: (signal) => attempt(method, request, metadata, requestTimeout - (clock.now() - started), signal),
+			beforeAgain: (left, signal) => readied.wait(left, signal),
+			onReissue: () => record("command.reissue", status, method)
+		});
+	};
+	const health = async (service = "", sendOptions = {}) => {
+		const sent = await call(HEALTH_CHECK, healthRequest(service), sendOptions);
+		if (sent.outcome !== "ok") return sent;
+		const serving = healthStatus(sent.value);
+		return serving === null ? {
+			outcome: "error",
+			error: "the response is not a HealthCheckResponse",
+			reply: true,
+			attempts: sent.attempts
+		} : {
+			outcome: "ok",
+			value: serving,
+			attempts: sent.attempts
+		};
+	};
+	const handle = {
+		async connect(signal) {
+			if (signal.aborted) throw new Error(`${name}: the service stopped before the connect`);
+			record("status.connecting", "connecting", target);
+			let c;
+			try {
+				c = await create(grpcOptions(spec));
+			} catch (error) {
+				record("connect.failed", "failing", message(error));
+				throw error;
+			}
+			if (closing()) {
+				c.close();
+				return;
+			}
+			channel = c;
+			const first = new Promise((resolve) => settled = resolve);
+			const now = c.state(true);
+			watch(c, now);
+			if (now !== "IDLE") follow(c, now);
+			await withinBound(clock, ms(knobs.connect_bound), first);
+			settled = null;
+		},
+		async close() {
+			if (status === "none" || closing()) return;
+			record("close.request", "closing");
+			settled?.();
+			const c = channel;
+			if (c !== null) {
+				if (!await withinBound(clock, ms(knobs.close_bound), flight.idle())) {
+					record("close.bound", "closing");
+					record("close.destroy", "closing", `${flight.size} calls in flight`);
+					flight.settleAll("the client closed with the call in flight");
+				}
+				c.close();
+			}
+			channel = null;
+			flight.settleAll("the client closed with the call in flight");
+			record("status.end", "end");
+		}
+	};
+	const keepalive = finiteMs(knobs.keepalive_time);
+	const declaration = {
+		system: spec.system,
+		knobs: {
+			connect_bound: knobs.connect_bound,
+			request_timeout: knobs.request_timeout,
+			keepalive_time: knobs.keepalive_time,
+			keepalive_timeout: knobs.keepalive_timeout,
+			heartbeat_detection_time: heartbeatDetection(knobs.keepalive_time, knobs.keepalive_timeout, 1),
+			client_idle_timeout: knobs.client_idle_timeout,
+			retry_base: knobs.retry_base,
+			retry_cap: knobs.retry_cap,
+			keepalive_idle: knobs.keepalive_idle,
+			idle_refresh_interval: spec.keepaliveWithoutCalls && keepalive !== void 0 ? knobs.keepalive_time : NEVER,
+			max_connection_age: knobs.max_connection_age,
+			close_bound: knobs.close_bound,
+			retrans_giveup_time: knobs.retrans_giveup_time
+		},
+		operations
+	};
+	/** The round-trip check passes only for SERVING: a health service that answers NOT_SERVING fails it, as a 5xx fails the HTTP check. */
+	const roundTrip = async (sendOptions) => {
+		const sent = await health(spec.healthService ?? "", sendOptions);
+		return sent.outcome === "ok" && sent.value !== "SERVING" ? {
+			outcome: "error",
+			error: `the health service answered ${sent.value}`,
+			reply: true,
+			attempts: sent.attempts
+		} : sent;
+	};
+	const checks = (checkOptions) => stepChecks(name, checkOptions, {
+		"local-state": localStateCheck(() => status === "ready"),
+		"round-trip": roundTripCheck(roundTrip),
+		dial: dialCheck(dial, spec.host, spec.port)
+	});
+	return {
+		name,
+		declaration,
+		handle,
+		meets: grpcMeetings(name, knobs, spec.keepaliveWithoutCalls),
+		get status() {
+			return status;
+		},
+		joins,
+		call,
+		health,
+		checks,
+		attach: (svc, checkOptions) => attachClient(svc, name, declaration, handle, checks(checkOptions)),
+		problems(description) {
+			const found = clientProblems(name, description, clientBounds(knobs));
+			const idle = idleCloseProblem(name, knobs.client_idle_timeout, knobs.server_idle_close, "client_idle_timeout");
+			if (idle !== null) found.push(idle);
+			if (keepalive !== void 0 && keepalive < ms(knobs.server_keepalive_min_time)) found.push(`${name}'s keepalive_time is below server_keepalive_min_time: the server answers with GOAWAY too_many_pings (O26)`);
+			return found;
+		}
+	};
+};
+//#endregion
+//#region src/grpc/machine.ts
+/** The states where the client can close, and the states where a call can start its second try. */
+const SERVING = [
+	"connecting",
+	"ready",
+	"idle",
+	"failing"
+];
+const LIVE = [...SERVING, "closing"];
+/**
+* The gRPC client of the service as a `mark1russell7.machine/1` document. It is one channel of
+* grpc-js 1.14 for the life of the client. Each READY of the channel is one generation. The states:
+* - `ready`: the channel is READY, and the client sends each call. The keepalive sends a PING each keepalive_time.
+* - `idle`: the transport ended, or the channel had no call in client_idle_timeout. The client connects again at once.
+* - `failing`: the channel is in TRANSIENT_FAILURE. The grpc-js driver connects again after its backoff.
+* - `closing`: the calls in flight, in `close_bound`. At the bound, each call gets RST_STREAM CANCEL.
+*
+* A test records the transitions of the client and replays them against this document.
+*/
+const GRPC_CLIENT_MACHINE = {
+	format: "mark1russell7.machine/1",
+	id: "service.machine.grpc-client",
+	title: "The gRPC client of the service, over grpc-js 1.14",
+	layer: "driver",
+	version: "0.1.0",
+	sources: [{
+		ref: "packages/service/src/grpc (the client implements this document)",
+		rung: "implemented"
+	}],
+	states: {
+		none: {
+			initial: true,
+			note: "the client exists, and its channel does not"
+		},
+		connecting: { note: "the channel is CONNECTING: the TCP connect and the HTTP/2 preface. The grpc-js driver has no connect timeout" },
+		ready: { note: "the channel is READY. The deadline ends a call that waits, and the keepalive finds a silent transport" },
+		idle: { note: "the channel is IDLE. The client asks it to connect at once" },
+		failing: { note: "the channel is in TRANSIENT_FAILURE. The grpc-js driver connects again after its backoff, and each call fails as not sent" },
+		closing: { note: "the calls in flight, in close_bound. At the bound, each call gets RST_STREAM CANCEL, then the channel closes" },
+		end: {
+			final: true,
+			note: "the service closed the client"
+		}
+	},
+	events: {
+		"status.connecting": { kind: "local" },
+		join: {
+			kind: "rx",
+			note: "the channel became READY: a new generation (D1)"
+		},
+		"connect.failed": {
+			kind: "rx",
+			note: "the channel went to TRANSIENT_FAILURE: a connect failed"
+		},
+		"channel.connecting": {
+			kind: "rx",
+			note: "the channel started a new connect"
+		},
+		"channel.idle": {
+			kind: "rx",
+			note: "the channel went to IDLE before it was READY"
+		},
+		"connection.end": {
+			kind: "rx",
+			note: "the transport ended: a GOAWAY, a reset, a FIN, the keepalive, or client_idle_timeout. The grpc-js driver ends each call in flight with UNAVAILABLE"
+		},
+		"command.reissue": { kind: "local" },
+		"close.request": { kind: "local" },
+		"close.bound": {
+			kind: "timer",
+			note: "the calls in flight did not end in close_bound"
+		},
+		"close.destroy": {
+			kind: "local",
+			note: "the client cancels each call in flight, then closes the channel"
+		},
+		"status.end": { kind: "local" }
+	},
+	knobs: {
+		keepalive_time: clientKnob("grpc.keepalive_time_ms"),
+		keepalive_timeout: clientKnob("grpc.keepalive_timeout_ms"),
+		client_idle_timeout: clientKnob("grpc.client_idle_timeout_ms"),
+		retry_base: clientKnob("grpc.initial_reconnect_backoff_ms"),
+		retry_cap: clientKnob("grpc.max_reconnect_backoff_ms"),
+		close_bound: clientKnob("close.bound")
+	},
+	timers: {
+		keepalive: {
+			duration: {
+				expr: "keepalive_time + keepalive_timeout",
+				unit: "s"
+			},
+			arms: ["join"],
+			cancels: ["connection.end", "close.request"],
+			fires: "connection.end",
+			note: "a timer of grpc-js: one PING each keepalive_time, and the end of the transport at keepalive_timeout with no ACK"
+		},
+		idle: {
+			duration: {
+				knob: "client_idle_timeout",
+				unit: "s"
+			},
+			arms: ["join"],
+			cancels: ["connection.end", "close.request"],
+			fires: "connection.end",
+			note: "a timer of grpc-js: client_idle_timeout with no call puts the channel in IDLE"
+		},
+		retry: {
+			duration: {
+				expr: "min(retry_cap, retry_base * pow(1.6, fired)) * 1.2",
+				unit: "s"
+			},
+			arms: ["connect.failed"],
+			cancels: ["close.request"],
+			fires: "join",
+			backoff: { resets: ["join"] },
+			note: "a timer of grpc-js, the most delay: the backoff grows by 1.6 from retry_base to retry_cap, with a jitter of 20 %. The first delay has no jitter"
+		},
+		close: closeTimer()
+	},
+	transitions: [
+		transition("connect", "none", "status.connecting", "connecting"),
+		transition("join", [
+			"connecting",
+			"idle",
+			"failing"
+		], "join", "ready"),
+		transition("connect-failed", [
+			"connecting",
+			"idle",
+			"ready"
+		], "connect.failed", "failing"),
+		transition("retry", "failing", "join", "ready", { timer: "retry" }),
+		transition("channel-connecting", ["idle", "failing"], "channel.connecting", "connecting"),
+		transition("channel-idle", ["connecting", "failing"], "channel.idle", "idle"),
+		transition("connection-end", "ready", "connection.end", "idle"),
+		transition("keepalive", "ready", "connection.end", "idle", { timer: "keepalive" }),
+		transition("idle-timeout", "ready", "connection.end", "idle", { timer: "idle" }),
+		...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/grpc/starting.ts
+/**
+* This poll is the poll of the checks that `GRPC_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 GRPC_CLIENT_STARTING_POLL = STARTING_POLL;
+/**
+* This value tells if the keepalive sends a PING with no call in flight, to start from: false. The
+* grpc-go server refuses such a PING at its defaults (`PermitWithoutStream` false). It answers with GOAWAY too_many_pings (O26).
+*/
+const GRPC_CLIENT_STARTING_WITHOUT_CALLS = false;
+/**
+* These knobs are a declaration to start from, from what the gRPC cells measured on grpc-js 1.14.6.
+* 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 grpc-js driver has no connect timeout, thus this bounds the wait of the startup.
+* - `request_timeout` 9.5 s: in the slowest poll of 10 s (O13). In DP44 a deadline of 4 s ended each
+*   call at 4.003 s to 4.004 s. The race of the two deadlines gave CANCELLED to 2 to 4 calls of 11.
+* - `keepalive_time` 300 s and `keepalive_timeout` 20 s: DP24. The PING must not come before the
+*   `MinTime` of the server, 5 min at the defaults of grpc-go (O26). The transport ended at 320.005 s.
+*   Against etcd, with a `MinTime` of 5 s, 60 s ended it at 80.012 s. A PING each 4 s against 5 s got GOAWAY at the 4th PING.
+* - `server_keepalive_min_time` 300 s: the `MinTime` of grpc-go v1.84.0 at its defaults.
+* - `client_idle_timeout` 60 s and `server_idle_close` 75 s: the proxies of the cells sent GOAWAY to an idle connection.
+*   They did that at 75 s (nginx), 180 s (Traefik), 300 s (Caddy) and 1 h (Envoy). The client closes first (O01).
+*   The default of grpc-js is 30 min.
+* - `retry_base` 1 s: the first backoff of grpc-js in T07, with no jitter. `retry_cap` 4 s: the most
+*   delay is 4.8 s with the jitter of 20 %, in the slowest poll of 10 s. The default of grpc-js is 120 s.
+* - `keepalive_idle` "infinite": grpc-js sets no TCP keepalive, and the PING is its keepalive.
+* - `max_connection_age` "infinite": the client does not replace its connection at an age.
+* - `close_bound` 2 s: the calls in flight, then RST_STREAM CANCEL for each call that stays.
+* - `retrans_giveup_time` 924.6 s: the give-up of Linux at `tcp_retries2 = 15`.
+*/
+const GRPC_CLIENT_STARTING_KNOBS = {
+	connect_bound: {
+		value: 5,
+		unit: "s"
+	},
+	request_timeout: {
+		value: 9.5,
+		unit: "s"
+	},
+	keepalive_time: {
+		value: 300,
+		unit: "s"
+	},
+	keepalive_timeout: {
+		value: 20,
+		unit: "s"
+	},
+	server_keepalive_min_time: {
+		value: 300,
+		unit: "s"
+	},
+	client_idle_timeout: {
+		value: 60,
+		unit: "s"
+	},
+	server_idle_close: {
+		value: 75,
+		unit: "s"
+	},
+	retry_base: {
+		value: 1,
+		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 { GRPC_CLIENT_MACHINE, GRPC_CLIENT_STARTING_KNOBS, GRPC_CLIENT_STARTING_POLL, GRPC_CLIENT_STARTING_WITHOUT_CALLS, GRPC_CODES, GRPC_OPERATIONS, GRPC_STATES, HEALTH_CHECK, HTTP2_PREFACE, MANIFESTATIONS, STARTING_POLL, adaptGrpc, codeName, firstDetector, grpcClient, grpcDial, grpcMeetings, grpcOperations, grpcOptions, grpcOutcome, grpcTarget, healthRequest, healthStatus, nodeGrpc, readyWait, retryProblems, settingsJudge, specProblems, unwatched };
+
+//# sourceMappingURL=grpc.js.map