@mark1russell7/machines 0.3.15 → 0.3.16

package/build/index.js

@@ -1,5 +1,1238 @@
 import { machineSchema } from "@mark1russell7/algebra";
 import { z } from "zod";
+//#region src/grpc/grpc-go-server.ts
+const AT$9 = "grpc-go v1.84.0";
+const GO = "go1.27.2 src/net";
+const ETCD = "etcd v3.6.15";
+/** These are the facts of the transport of grpc-go, for each server on it. */
+const TRANSPORT = [
+	{
+		ref: `${AT$9} internal/transport/defaults.go:31-40 the server keepalive: Time 2 h, Timeout 20 s. MinTime of the policy 5 min. MaxConnectionIdle, Age and AgeGrace infinite`,
+		rung: "implemented"
+	},
+	{
+		ref: `${AT$9} internal/transport/http2_server.go:226-253 the defaults of the parameters, a jitter of 10 % on MaxConnectionAge, and TCP_USER_TIMEOUT = Timeout when Time is not infinite`,
+		rung: "implemented"
+	},
+	{
+		ref: `${AT$9} internal/syscall/syscall_linux.go:71-90 SetTCPUserTimeout acts only on a *net.TCPConn. On any other net.Conn it does nothing`,
+		rung: "implemented"
+	},
+	{
+		ref: `${AT$9} internal/transport/http2_server.go:1197-1286 keepalive(): a PING after Time with no read, and Close when no read comes for Timeout after it. MaxConnectionIdle and MaxConnectionAge drain with GOAWAY, and AgeGrace closes`,
+		rung: "implemented"
+	},
+	{
+		ref: `${AT$9} internal/transport/http2_server.go:881-933 handlePing: a PING less than MinTime after the last one is a strike, and with no stream open and PermitWithoutStream false, less than 2 h. The third strike sends GOAWAY ENHANCE_YOUR_CALM too_many_pings and closes the connection`,
+		rung: "implemented"
+	},
+	{
+		ref: `${AT$9} internal/transport/http2_server.go:279-281, :1064, :1132, :1176 each write of headers, a status or data by the server clears the strikes`,
+		rung: "implemented"
+	},
+	{
+		ref: `${AT$9} internal/transport/http2_server.go:1291-1310 Close closes the net.Conn: a FIN, or a reset when bytes are unread`,
+		rung: "implemented"
+	},
+	{
+		ref: `${AT$9} internal/transport/http2_server.go:536-537, :603-615 a call with the header grpc-timeout gets a timer of that timeout from the read of its headers. Its end closes the stream with RST_STREAM CANCEL, and the context of the handler ends`,
+		rung: "implemented"
+	},
+	{
+		ref: `${AT$9} server.go:192, :1000-1009 a deadline of 120 s for the handshake of each new connection (ConnectionTimeout)`,
+		rung: "implemented"
+	},
+	{
+		ref: `${AT$9} server.go:894-905 the comment of grpc-go: Go sets a TCP keepalive of 15 s on each accepted connection`,
+		rung: "documented"
+	},
+	{
+		ref: `${GO}/dial.go:20-27 the defaults of the TCP keepalive of Go: 15 s idle, 15 s between probes, 9 probes`,
+		rung: "implemented"
+	},
+	{
+		ref: `${GO}/tcpsock_posix.go:158-164 and tcpsock.go:289-305 each accepted connection gets the KeepAlive of its ListenConfig: on, with the defaults of Go, when the caller gives none`,
+		rung: "implemented"
+	},
+	{
+		ref: `${GO}/tcpsock_unix.go:12-31 and tcpsockopt_unix.go:15-53 SetKeepAliveConfig sets SO_KEEPALIVE, TCP_KEEPIDLE, TCP_KEEPINTVL and TCP_KEEPCNT`,
+		rung: "implemented"
+	},
+	{
+		ref: "linux v6.6 net/ipv4/tcp_timer.c tcp_keepalive_timer: with TCP_USER_TIMEOUT set, the keepalive aborts at its first firing that is U after the last received segment, with a probe out. Thus at K + k·I, k = max(1, ceil((U − K) / I)), and TCP_KEEPCNT is not read",
+		rung: "implemented"
+	}
+];
+/** This function gives the document of a server of grpc-go for one variant. */
+const serverOf = (variant) => machineSchema.parse({
+	format: "mark1russell7.machine/1",
+	id: variant.id,
+	title: variant.title,
+	layer: "server",
+	version: variant.version,
+	conditions: variant.conditions,
+	sources: [...TRANSPORT, ...variant.sources],
+	states: {
+		"[none]": {
+			initial: true,
+			pseudo: true,
+			note: "Before the accept of the connection"
+		},
+		handshake: { note: "The accepted connection, until the preface and the SETTINGS of the client, with the deadline of ConnectionTimeout" },
+		idle: { note: "A ready transport with no stream open. The keepalive of the server runs" },
+		active: { note: "One or more streams open, for example a call that the handler holds" },
+		draining: { note: "After a GOAWAY of the server: no new stream, and the open streams end" },
+		ended: {
+			final: true,
+			note: "The connection closed"
+		}
+	},
+	events: {
+		"local.accept": {
+			kind: "local",
+			note: "The listener accepts the connection, with the TCP keepalive of Go, and TCP_USER_TIMEOUT where it applies"
+		},
+		"rx.settings": {
+			kind: "rx",
+			note: "The preface and the first SETTINGS of the client"
+		},
+		"rx.frame": {
+			kind: "rx",
+			note: "Any frame of the client. The server keeps the time of its last read"
+		},
+		"rx.headers": {
+			kind: "rx",
+			note: "The headers of a new stream: a call"
+		},
+		"rx.ping": {
+			kind: "rx",
+			note: "A PING of the client. The server answers it, and checks it against its policy"
+		},
+		"rx.ping-strike-3": {
+			kind: "rx",
+			note: "The third PING that breaks the policy, with no write of the server since the first one"
+		},
+		"rx.ping-ack": {
+			kind: "rx",
+			note: "The ACK of a PING of the server"
+		},
+		"local.stream-end": {
+			kind: "local",
+			note: "The last open stream ends: its status goes out"
+		},
+		"timer.call-deadline": {
+			kind: "timer",
+			note: "The timeout of the header grpc-timeout of a call ends"
+		},
+		"tx.rst-stream": {
+			kind: "tx",
+			note: "RST_STREAM CANCEL of a stream, at the deadline of its call"
+		},
+		"app.stop": {
+			kind: "app",
+			note: "GracefulStop: a GOAWAY on each connection"
+		},
+		"peer.fin": {
+			kind: "peer",
+			note: "The client ends the connection: an end of file for the reader of the server"
+		},
+		"peer.rst": {
+			kind: "peer",
+			note: "A reset of the connection"
+		},
+		"socket.error": {
+			kind: "local",
+			note: "The socket fails with its own error: a reset, or a give-up of the kernel (ETIMEDOUT)"
+		},
+		"timer.connection-timeout": {
+			kind: "timer",
+			note: "No preface came before the deadline of the handshake"
+		},
+		"timer.keepalive": {
+			kind: "timer",
+			note: "No read for Time: the server sends a PING"
+		},
+		"timer.ping-timeout": {
+			kind: "timer",
+			note: "No read for Timeout after the PING"
+		},
+		"timer.max-idle": {
+			kind: "timer",
+			note: "No stream open for MaxConnectionIdle"
+		},
+		"timer.max-age": {
+			kind: "timer",
+			note: "The connection is MaxConnectionAge old"
+		},
+		"timer.grace": {
+			kind: "timer",
+			note: "AgeGrace after the GOAWAY of the age"
+		},
+		"tx.ping": {
+			kind: "tx",
+			note: "A PING of the keepalive of the server"
+		},
+		"tx.goaway": {
+			kind: "tx",
+			note: "A GOAWAY of the server"
+		},
+		"tx.fin": {
+			kind: "tx",
+			note: "The close of the net.Conn: a FIN"
+		}
+	},
+	knobs: {
+		keepalive_time: {
+			key: "keepalive.ServerParameters.Time",
+			scope: "server",
+			unit: "s",
+			default: 7200,
+			note: "defaults.go:38: 2 h. 0 is the default"
+		},
+		keepalive_timeout: {
+			key: "keepalive.ServerParameters.Timeout",
+			scope: "server",
+			unit: "s",
+			default: 20,
+			note: "defaults.go:39: the wait after the PING, and TCP_USER_TIMEOUT where it applies"
+		},
+		min_time: {
+			key: "keepalive.EnforcementPolicy.MinTime",
+			scope: "server",
+			unit: "s",
+			default: variant.minTime,
+			note: "the shortest interval between two PINGs of a client with a stream open"
+		},
+		permit_without_stream: {
+			key: "keepalive.EnforcementPolicy.PermitWithoutStream",
+			scope: "server",
+			unit: null,
+			default: 0,
+			note: "false: with no stream open, the shortest interval is 2 h"
+		},
+		no_stream_ping_interval: {
+			key: "defaultPingTimeout",
+			scope: "server",
+			unit: "s",
+			default: 7200,
+			note: "http2_server.go:883: a constant of grpc-go"
+		},
+		max_ping_strikes: {
+			key: "maxPingStrikes",
+			scope: "server",
+			unit: "count",
+			default: 2,
+			note: "http2_server.go:882: the GOAWAY comes at the strike after it"
+		},
+		max_connection_idle: {
+			key: "keepalive.ServerParameters.MaxConnectionIdle",
+			scope: "server",
+			unit: "s",
+			default: 0,
+			off: 0,
+			note: "defaults.go:35: infinite, and 0 is the default"
+		},
+		max_connection_age: {
+			key: "keepalive.ServerParameters.MaxConnectionAge",
+			scope: "server",
+			unit: "s",
+			default: 0,
+			off: 0,
+			note: "defaults.go:36: infinite. When set, a jitter of ±10 %"
+		},
+		max_connection_age_grace: {
+			key: "keepalive.ServerParameters.MaxConnectionAgeGrace",
+			scope: "server",
+			unit: "s",
+			default: 0,
+			off: 0,
+			note: "defaults.go:37: infinite"
+		},
+		connection_timeout: {
+			key: "grpc.ConnectionTimeout",
+			scope: "server",
+			unit: "s",
+			default: 120,
+			note: "server.go:192"
+		},
+		call_timeout: {
+			key: "the header grpc-timeout of a call",
+			scope: "call",
+			unit: "s",
+			default: 0,
+			off: 0,
+			note: "The client gives it: the time left to its deadline when it sends the headers. No timeout when the call has no deadline"
+		},
+		listener_keepidle: {
+			key: "the TCP keepalive idle of an accepted connection",
+			scope: "server",
+			unit: "s",
+			default: variant.listenerIdle,
+			note: variant.note
+		},
+		listener_keepintvl: {
+			key: "the TCP keepalive interval of an accepted connection",
+			scope: "server",
+			unit: "s",
+			default: 15,
+			note: "dial.go:24: the default of Go"
+		},
+		listener_keepcnt: {
+			key: "the TCP keepalive count of an accepted connection",
+			scope: "server",
+			unit: "count",
+			default: 9,
+			note: "dial.go:27: the default of Go"
+		},
+		sets_user_timeout: {
+			key: "TCP_USER_TIMEOUT reaches the socket",
+			scope: "server",
+			unit: "count",
+			default: variant.setsUserTimeout,
+			note: "1 when grpc-go gets the *net.TCPConn of the listener, else 0. A wrapper of the conn, as cmux, makes it 0 (syscall_linux.go:71-77). A count, thus the sets of the socket can read it"
+		},
+		slack: {
+			key: "the lateness of the scheduler of Go for one step",
+			scope: "process",
+			unit: "s",
+			default: .01,
+			note: "An assumption of this document, not a value of grpc-go"
+		},
+		hz: {
+			key: "CONFIG_HZ",
+			scope: "global",
+			unit: "Hz",
+			default: null,
+			note: "The build option of the kernel"
+		}
+	},
+	timers: {
+		connection_timeout: {
+			duration: {
+				knob: "connection_timeout",
+				unit: "s"
+			},
+			lateness: {
+				knob: "slack",
+				unit: "s"
+			},
+			arms: ["local.accept"],
+			cancels: ["rx.settings"],
+			fires: "timer.connection-timeout",
+			note: "server.go:1005-1009: a deadline of the conn for the handshake"
+		},
+		keepalive: {
+			duration: {
+				knob: "keepalive_time",
+				unit: "s"
+			},
+			lateness: {
+				knob: "slack",
+				unit: "s"
+			},
+			arms: [
+				"rx.settings",
+				"rx.frame",
+				"rx.ping-ack"
+			],
+			fires: "timer.keepalive",
+			note: "http2_server.go:1252-1262: from the last read. The timer fires at Time and finds the last read, thus it sets itself again to Time after that read"
+		},
+		ping_timeout: {
+			duration: {
+				knob: "keepalive_timeout",
+				unit: "s"
+			},
+			lateness: {
+				knob: "slack",
+				unit: "s"
+			},
+			arms: ["tx.ping"],
+			cancels: ["rx.frame", "rx.ping-ack"],
+			fires: "timer.ping-timeout",
+			note: "http2_server.go:1263-1281: any read since the PING cancels the close"
+		},
+		call_deadline: {
+			duration: {
+				knob: "call_timeout",
+				unit: "s"
+			},
+			lateness: {
+				knob: "slack",
+				unit: "s"
+			},
+			arms: ["rx.headers"],
+			cancels: [
+				"local.stream-end",
+				"peer.rst",
+				"peer.fin",
+				"socket.error"
+			],
+			fires: "timer.call-deadline",
+			note: "http2_server.go:603-615: from the read of the headers of the call. Its end resets the stream, and it does not end the connection"
+		},
+		max_idle: {
+			duration: {
+				knob: "max_connection_idle",
+				unit: "s"
+			},
+			lateness: {
+				knob: "slack",
+				unit: "s"
+			},
+			arms: ["enter:idle"],
+			cancels: ["rx.headers"],
+			fires: "timer.max-idle",
+			note: "http2_server.go:1222-1238: off at the defaults"
+		},
+		max_age: {
+			duration: {
+				knob: "max_connection_age",
+				unit: "s"
+			},
+			early: {
+				expr: "0.1 * max_connection_age",
+				unit: "s"
+			},
+			lateness: {
+				expr: "0.1 * max_connection_age + slack",
+				unit: "s"
+			},
+			arms: ["local.accept"],
+			fires: "timer.max-age",
+			note: "http2_server.go:231-232, :1239-1241: with a jitter of ±10 %. Off at the defaults"
+		},
+		grace: {
+			duration: {
+				knob: "max_connection_age_grace",
+				unit: "s"
+			},
+			lateness: {
+				knob: "slack",
+				unit: "s"
+			},
+			arms: ["timer.max-age"],
+			fires: "timer.grace",
+			note: "http2_server.go:1240-1251: the close after the GOAWAY of the age"
+		}
+	},
+	realizes: {
+		"systems.mechanism.heartbeat-interval": { timer: "keepalive" },
+		"systems.mechanism.heartbeat-detection-time": {
+			duration: {
+				expr: "keepalive_time + keepalive_timeout",
+				unit: "s"
+			},
+			lateness: {
+				expr: "2 * slack",
+				unit: "s"
+			},
+			note: "The PING after Time with no read, and the close Timeout after it"
+		},
+		"systems.mechanism.idle-refresh-interval": {
+			duration: {
+				knob: "listener_keepidle",
+				unit: "s"
+			},
+			lateness: {
+				model: "linux.wheel",
+				knobs: ["listener_keepidle", "hz"],
+				unit: "s"
+			},
+			early: {
+				model: "linux.jiffy",
+				knobs: ["hz"],
+				unit: "s"
+			},
+			note: "The first probe of the TCP keepalive of the accepted connection, rounded up on the wheel: no other segment goes out on an idle connection for 2 h"
+		}
+	},
+	transitions: [
+		{
+			id: "gs.accept",
+			from: "[none]",
+			to: "handshake",
+			on: "local.accept",
+			timer: "connection_timeout",
+			source: "server.go:1000-1009"
+		},
+		{
+			id: "gs.ready",
+			from: "handshake",
+			to: "idle",
+			on: "rx.settings",
+			source: "http2_server.go:205-300"
+		},
+		{
+			id: "gs.handshake-timeout",
+			from: "handshake",
+			to: "ended",
+			on: "timer.connection-timeout",
+			timer: "connection_timeout",
+			emits: ["tx.fin"],
+			source: "server.go:1005-1013"
+		},
+		{
+			id: "gs.stream",
+			from: "idle",
+			to: "active",
+			on: "rx.headers",
+			source: "http2_server.go"
+		},
+		{
+			id: "gs.stream-end",
+			from: "active",
+			to: "idle",
+			on: "local.stream-end",
+			source: "http2_server.go"
+		},
+		{
+			id: "gs.call-deadline",
+			from: "active",
+			to: "active",
+			on: "timer.call-deadline",
+			timer: "call_deadline",
+			emits: ["tx.rst-stream"],
+			note: "The stream of the call ends with RST_STREAM CANCEL. The connection stays, and another open stream goes on",
+			source: "http2_server.go:603-615"
+		},
+		{
+			id: "gs.ping-idle",
+			from: "idle",
+			to: "idle",
+			on: "timer.keepalive",
+			timer: "keepalive",
+			emits: ["tx.ping"],
+			source: "http2_server.go:1267-1274"
+		},
+		{
+			id: "gs.ping-active",
+			from: "active",
+			to: "active",
+			on: "timer.keepalive",
+			timer: "keepalive",
+			emits: ["tx.ping"],
+			source: "http2_server.go:1267-1274"
+		},
+		{
+			id: "gs.ping-timeout",
+			from: ["idle", "active"],
+			to: "ended",
+			on: "timer.ping-timeout",
+			timer: "ping_timeout",
+			errno: "keepalive ping not acked within timeout",
+			emits: ["tx.fin"],
+			source: "http2_server.go:1263-1266, :1291-1310"
+		},
+		{
+			id: "gs.too-many-pings",
+			from: ["idle", "active"],
+			to: "ended",
+			on: "rx.ping-strike-3",
+			errno: "too_many_pings",
+			emits: ["tx.goaway", "tx.fin"],
+			note: "GOAWAY ENHANCE_YOUR_CALM with the data too_many_pings, then the close of the connection",
+			source: "http2_server.go:929-932"
+		},
+		{
+			id: "gs.max-idle",
+			from: "idle",
+			to: "draining",
+			on: "timer.max-idle",
+			timer: "max_idle",
+			emits: ["tx.goaway"],
+			source: "http2_server.go:1232-1236"
+		},
+		{
+			id: "gs.max-age",
+			from: ["idle", "active"],
+			to: "draining",
+			on: "timer.max-age",
+			timer: "max_age",
+			emits: ["tx.goaway"],
+			source: "http2_server.go:1239-1241"
+		},
+		{
+			id: "gs.stop",
+			from: ["idle", "active"],
+			to: "draining",
+			on: "app.stop",
+			emits: ["tx.goaway"],
+			source: "server.go:1683"
+		},
+		{
+			id: "gs.drained",
+			from: "draining",
+			to: "ended",
+			on: ["timer.grace", "local.stream-end"],
+			emits: ["tx.fin"],
+			source: "http2_server.go:1242-1251"
+		},
+		{
+			id: "gs.reset",
+			from: [
+				"handshake",
+				"idle",
+				"active",
+				"draining"
+			],
+			to: "ended",
+			on: ["socket.error", "peer.rst"],
+			errno: "ECONNRESET",
+			note: "The error of the socket, with its own code: ETIMEDOUT for an abort of the keepalive or a give-up of the kernel",
+			source: "http2_server.go"
+		},
+		{
+			id: "gs.closed",
+			from: [
+				"handshake",
+				"idle",
+				"active",
+				"draining"
+			],
+			to: "ended",
+			on: "peer.fin",
+			errno: "EOF",
+			emits: ["tx.fin"],
+			source: "http2_server.go"
+		}
+	],
+	over: {
+		machine: "systems.machine.linux-tcp",
+		states: {
+			handshake: "ESTABLISHED",
+			idle: "ESTABLISHED",
+			active: "ESTABLISHED",
+			draining: "ESTABLISHED"
+		},
+		sets: {
+			keepidle: {
+				expr: "ceil(listener_keepidle)",
+				unit: "s"
+			},
+			keepintvl: {
+				expr: "ceil(listener_keepintvl)",
+				unit: "s"
+			},
+			keepcnt: {
+				expr: "sets_user_timeout * max(1, ceil((keepalive_timeout - ceil(listener_keepidle)) / ceil(listener_keepintvl))) + (1 - sets_user_timeout) * listener_keepcnt",
+				unit: "count"
+			},
+			tcp_user_timeout: {
+				expr: "1000 * sets_user_timeout * keepalive_timeout",
+				unit: "ms"
+			}
+		},
+		ends: "socket.error",
+		note: "The accepted socket: a Linux TCP socket with the keepalive of Go. Where TCP_USER_TIMEOUT reaches it, the keepalive aborts at its first firing that is U after the last received segment, with a probe out: a keepalive of count k, k = max(1, ceil((U − K) / I)). U also ends a send with no ACK, U after its first retransmission"
+	}
+});
+/**
+* This document is a server of grpc-go v1.84.0 on its own listener: grpc.NewServer on net.Listen, at the
+* defaults, as in the server of the harness. Its keepalive is on (a PING after 2 h with no read). Thus the
+* transport gives each accepted connection a TCP_USER_TIMEOUT of 20 s. With the TCP keepalive of Go
+* (15 s, 15 s, 9), an idle connection to a client that is gone ends 30 s after the last data. A client
+* that pings more often than 5 min with a stream open, or than 2 h with none, gets GOAWAY
+* too_many_pings at its third strike.
+*/
+const GRPC_GO_SERVER = serverOf({
+	id: "grpc-go-server",
+	title: "A server of grpc-go v1.84.0: one HTTP/2 connection, its keepalive, its policy for the PINGs of a client and its TCP socket",
+	version: "1.84.0",
+	conditions: {
+		"grpc-go": "v1.84.0",
+		go: "1.27.2",
+		server: "grpc.NewServer with the server options of the caller, on net.Listen",
+		transport: "HTTP/2 over TCP, with no TLS"
+	},
+	sources: [],
+	minTime: 300,
+	listenerIdle: 15,
+	setsUserTimeout: 1,
+	note: "dial.go:20: the default of Go, on net.Listen. A ListenConfig with its own KeepAlive changes it"
+});
+/**
+* This document is the server of etcd v3.6.15, on grpc-go v1.83.2, at the defaults: one client URL with no
+* TLS. The keepalive of the server is 2 h and 20 s, and a client can ping each 5 s with a stream open.
+* The server serves gRPC and HTTP on one port through cmux. Thus the transport gets a wrapper of the conn,
+* and it sets no TCP_USER_TIMEOUT. The listener sets the keepalive idle to 30 s. The interval and the
+* count of Go stay. Thus an idle connection to a gone client ends 165 s after the last data: 30 + 9 × 15.
+*/
+const ETCD_SERVER = serverOf({
+	id: "etcd-server",
+	title: "The server of etcd v3.6.15 on grpc-go v1.83.2: one gRPC connection of a client, its keepalive, its policy for PINGs and its TCP socket",
+	version: "3.6.15",
+	conditions: {
+		etcd: "v3.6.15",
+		"grpc-go": "v1.83.2",
+		go: "1.26.8",
+		server: "etcd with one member at its defaults, one client URL of http: and no TLS",
+		transport: "HTTP/2 over TCP through cmux, with no TLS"
+	},
+	sources: [
+		{
+			ref: `${ETCD} server/embed/config.go:69-71 --grpc-keepalive-min-time 5 s, --grpc-keepalive-interval 2 h, --grpc-keepalive-timeout 20 s`,
+			rung: "implemented"
+		},
+		{
+			ref: `${ETCD} server/embed/etcd.go:780-793 the policy (MinTime, PermitWithoutStream false) and the parameters (Time, Timeout) of the gRPC server`,
+			rung: "implemented"
+		},
+		{
+			ref: `${ETCD} server/embed/etcd.go:707-712 and client/pkg/transport/listener.go:48-116 a client URL with no socket options gets net.Listen in a keepalive listener`,
+			rung: "implemented"
+		},
+		{
+			ref: `${ETCD} client/pkg/transport/keepalive_listener.go:52-71 each accepted connection: SetKeepAlive(true) and SetKeepAlivePeriod(30 s), which sets the idle only (${GO}/tcpsock.go:249-257)`,
+			rung: "implemented"
+		},
+		{
+			ref: `${ETCD} server/embed/serve.go:141, :214-216 the gRPC server serves the HTTP/2 connections of cmux, a MuxConn (github.com/soheilhy/cmux v0.1.5 cmux.go:274-277), not a *net.TCPConn`,
+			rung: "implemented"
+		},
+		{
+			ref: `${ETCD} server/etcdserver/api/v3rpc/grpc.go:86-88 the server registers the health service of gRPC`,
+			rung: "implemented"
+		}
+	],
+	minTime: 5,
+	listenerIdle: 30,
+	setsUserTimeout: 0,
+	note: "keepalive_listener.go:68: SetKeepAlivePeriod(30 s) on each accepted connection"
+});
+//#endregion
+//#region src/grpc/grpc-js.ts
+const AT$8 = "@grpc/grpc-js 1.14.6 src";
+/**
+* This document is grpc-js 1.14.6 on Node, for one channel to one server with no TLS, its transport
+* (one HTTP/2 session on one TCP connection) and one unary call on it. It gives the states of the
+* transport, from its connect to its end, and the timers that act on it.
+*
+* At the defaults the keepalive of grpc-js is off: it sends no PING. It sets TCP_NODELAY and no TCP
+* keepalive, and its connect has no timeout. A call has no deadline. Thus nothing in grpc-js ends a
+* call on a silent connection: only the kernel can, or the server.
+*
+* When the transport ends, each call in flight on it ends with UNAVAILABLE. The client does not retry such
+* a call, because the call reached the server (PROCESSED). It retries only a call that did not start, and
+* once a stream that the server refused. The channel then goes IDLE, and the next call connects again. A call
+* that finds the channel in TRANSIENT_FAILURE fails at once, unless it asks to wait for the channel.
+*/
+const GRPC_JS = machineSchema.parse({
+	format: "mark1russell7.machine/1",
+	id: "grpc-js",
+	title: "grpc-js 1.14.6: one channel to a gRPC server, its HTTP/2 transport, its keepalive and a unary call",
+	layer: "driver",
+	version: "1.14.6",
+	conditions: {
+		"grpc-js": "1.14.6",
+		node: "24.21.0",
+		client: "a Client of grpc-js with the channel options of the caller, and unary calls with no deadline and no waitForReady",
+		transport: "HTTP/2 over TCP to a host and port, with no TLS (createInsecure), and the load balancer pick_first",
+		server: "any gRPC server"
+	},
+	sources: [
+		{
+			ref: `${AT$8}/transport.ts:70 KEEPALIVE_TIMEOUT_MS is 20000`,
+			rung: "implemented"
+		},
+		{
+			ref: `${AT$8}/transport.ts:183-198 grpc.keepalive_time_ms is -1 when the caller gives none, grpc.keepalive_timeout_ms is 20000, and grpc.keepalive_permit_without_calls is false`,
+			rung: "implemented"
+		},
+		{
+			ref: `${AT$8}/transport.ts:447-453 a PING goes out only with a keepalive time above 0, and with a call in flight or permit_without_calls`,
+			rung: "implemented"
+		},
+		{
+			ref: `${AT$8}/transport.ts:455-507 each PING starts a timer of keepalive_timeout_ms, and its end with no ACK ends the transport (handleDisconnect). A failed send of the PING ends it too`,
+			rung: "implemented"
+		},
+		{
+			ref: `${AT$8}/transport.ts:515-534 and :553-561 the keepalive timer starts with the first call in flight, and after each ACK. It is not reset by data. When it ends with no call in flight, the PING goes out at the start of the next call`,
+			rung: "implemented"
+		},
+		{
+			ref: `${AT$8}/transport.ts:200-242 a close or an error of the session, or a close of its socket, ends the transport. A GOAWAY makes it unusable (reportDisconnectToOwner)`,
+			rung: "implemented"
+		},
+		{
+			ref: `${AT$8}/transport.ts:205-227 a GOAWAY ENHANCE_YOUR_CALM with the data too_many_pings tells the subchannel that the server refused the pings`,
+			rung: "implemented"
+		},
+		{
+			ref: `${AT$8}/transport.ts:431-441 handleDisconnect: each call in flight gets onDisconnect, and the session is destroyed in the next turn of the event loop`,
+			rung: "implemented"
+		},
+		{
+			ref: `${AT$8}/transport.ts:684-687 shutdown closes the session: a GOAWAY, then the end of the socket after the last stream`,
+			rung: "implemented"
+		},
+		{
+			ref: `${AT$8}/transport.ts:792-810 the transport is ready at the first SETTINGS of the server (remoteSettings)`,
+			rung: "implemented"
+		},
+		{
+			ref: `${AT$8}/transport.ts:818-840 the TCP connect is net.connect with no timeout`,
+			rung: "implemented"
+		},
+		{
+			ref: `${AT$8}/transport.ts:862 setNoDelay on each connection: TCP_NODELAY, thus no Nagle. No setKeepAlive anywhere in the package`,
+			rung: "implemented"
+		},
+		{
+			ref: `${AT$8}/subchannel-call.ts:360-371 onDisconnect ends the call with UNAVAILABLE 'Connection dropped' in the next turn of the event loop, unless the stream ends first`,
+			rung: "implemented"
+		},
+		{
+			ref: `${AT$8}/subchannel-call.ts:230-329 the end of a stream with no status: REFUSED_STREAM is UNAVAILABLE, CANCEL after a dropped connection is UNAVAILABLE, and an internal error of ECONNRESET or ETIMEDOUT is UNAVAILABLE`,
+			rung: "implemented"
+		},
+		{
+			ref: `${AT$8}/load-balancing-call.ts:257-261 a stream that the server refused has the progress REFUSED, and any other started stream PROCESSED`,
+			rung: "implemented"
+		},
+		{
+			ref: `${AT$8}/retrying-call.ts:631-652 a transparent retry for NOT_STARTED, and one for REFUSED. A PROCESSED call is retried only by a retry policy of the service config, which the defaults do not have`,
+			rung: "implemented"
+		},
+		{
+			ref: `${AT$8}/load-balancing-call.ts:338-345 a pick in TRANSIENT_FAILURE fails the call at once, unless it asks for waitForReady`,
+			rung: "implemented"
+		},
+		{
+			ref: `${AT$8}/resolving-call.ts:118-180 the deadline of a call is a timer from the start of the call. Its end cancels the call with DEADLINE_EXCEEDED`,
+			rung: "implemented"
+		},
+		{
+			ref: `${AT$8}/deadline.ts:39-52 the header grpc-timeout is the time left to the deadline when the call sends its headers, rounded up to whole milliseconds. A server can start a timer of it`,
+			rung: "implemented"
+		},
+		{
+			ref: `${AT$8}/subchannel-call.ts:269-279 a RST_STREAM CANCEL of the server ends the call with CANCELLED 'Call cancelled'`,
+			rung: "implemented"
+		},
+		{
+			ref: "run 39272272260 (T01.array.206): a deadline of 4 s against a server of grpc-go ended 4 of 11 calls with CANCELLED, each in the band of the deadline. In each of the 4, the handler at the server ended 1.1 ms before the end of the call. In 7 runs with DEADLINE_EXCEEDED it ended later, or at most 1.5 ms before",
+			rung: "observed"
+		},
+		{
+			ref: `${AT$8}/subchannel.ts:275-291 the end of the transport takes the subchannel from READY to IDLE. After too_many_pings the keepalive time doubles`,
+			rung: "implemented"
+		},
+		{
+			ref: `${AT$8}/subchannel.ts:298-304 a failed connect takes the subchannel to TRANSIENT_FAILURE`,
+			rung: "implemented"
+		},
+		{
+			ref: `${AT$8}/backoff-timeout.ts:23-26 the reconnect waits 1000 ms first, each next wait 1.6 times longer, up to 120000 ms, with a jitter of 0.2`,
+			rung: "implemented"
+		},
+		{
+			ref: `${AT$8}/internal-channel.ts:74-77 and :324-325 a channel with no call for grpc.client_idle_timeout_ms goes IDLE: 30 min at the defaults, 1 s at least`,
+			rung: "implemented"
+		},
+		{
+			ref: "node v24.21.0 lib/net.js:589 (a socket has no timeout until setTimeout), :828-843 (setNoDelay)",
+			rung: "implemented"
+		},
+		{
+			ref: "node v24.21.0 lib/internal/http2/core.js: no PING of its own, and no timeout of the session at the defaults",
+			rung: "implemented"
+		}
+	],
+	states: {
+		"[none]": {
+			initial: true,
+			pseudo: true,
+			note: "Before the first call: the channel is IDLE"
+		},
+		connecting: { note: "The TCP connect, with TCP_NODELAY, no keepalive and no timeout (transport.ts:818-862). The call waits in the queue of the channel" },
+		opening: { note: "The HTTP/2 preface and the SETTINGS of the client, until the first SETTINGS of the server (transport.ts:792-810)" },
+		idle: { note: "A ready transport with no call in flight. At the defaults no timer runs on it" },
+		waiting: { note: "A unary call in flight: the call waits for its status, with no timer at the defaults" },
+		ended: {
+			final: true,
+			note: "The transport ended. Each call in flight ended with UNAVAILABLE, and the channel is IDLE until the next call"
+		}
+	},
+	events: {
+		"app.call": {
+			kind: "app",
+			note: "The application starts a unary call, for example grpc.health.v1.Health/Check"
+		},
+		"socket.connect": {
+			kind: "local",
+			note: "The TCP connect ends, and the session sends its preface and its SETTINGS"
+		},
+		"rx.settings": {
+			kind: "rx",
+			note: "The first SETTINGS of the server: the transport is ready, and the queued call goes out"
+		},
+		"rx.reply": {
+			kind: "rx",
+			note: "The status of the call, in the trailers of its stream"
+		},
+		"rx.ping-ack": {
+			kind: "rx",
+			note: "The ACK of a PING of the keepalive"
+		},
+		"rx.goaway": {
+			kind: "rx",
+			note: "A GOAWAY of the server. The transport takes no new call"
+		},
+		"peer.fin": {
+			kind: "peer",
+			note: "The server or a middlebox ends the connection: an end of the socket"
+		},
+		"peer.rst": {
+			kind: "peer",
+			note: "A reset of the connection: the socket fails with ECONNRESET"
+		},
+		"socket.error": {
+			kind: "local",
+			note: "The socket fails with its own error: a reset, or a give-up of the kernel (ETIMEDOUT, EHOSTUNREACH)"
+		},
+		"timer.keepalive": {
+			kind: "timer",
+			note: "The keepalive timer ends: the transport sends a PING"
+		},
+		"timer.ping-timeout": {
+			kind: "timer",
+			note: "No ACK came for the PING in keepalive_timeout_ms"
+		},
+		"timer.deadline": {
+			kind: "timer",
+			note: "The deadline of the call ends: DEADLINE_EXCEEDED"
+		},
+		"timer.idle": {
+			kind: "timer",
+			note: "The channel had no call for client_idle_timeout_ms"
+		},
+		"timer.reconnect": {
+			kind: "timer",
+			note: "The backoff of the subchannel ends: the next connect can start"
+		},
+		"tx.ping": {
+			kind: "tx",
+			note: "A PING frame of the keepalive"
+		},
+		"tx.goaway": {
+			kind: "tx",
+			note: "The GOAWAY of a session that the client closes (shutdown)"
+		},
+		"tx.fin": {
+			kind: "tx",
+			note: "The end of the socket of grpc-js, when the session is destroyed: its FIN"
+		}
+	},
+	knobs: {
+		keepalive_time: {
+			key: "grpc.keepalive_time_ms",
+			scope: "client",
+			unit: "ms",
+			default: 0,
+			off: 0,
+			note: "transport.ts:183-187, :447-453: -1 when the caller gives none, and the keepalive sends no PING unless the value is above 0. 0 here is that state: off"
+		},
+		keepalive_timeout: {
+			key: "grpc.keepalive_timeout_ms",
+			scope: "client",
+			unit: "ms",
+			default: 2e4,
+			note: "transport.ts:70, :188-192: the wait for the ACK of each PING"
+		},
+		keepalive_permit_without_calls: {
+			key: "grpc.keepalive_permit_without_calls",
+			scope: "client",
+			unit: null,
+			default: 0,
+			note: "transport.ts:193-198: 1 sends the PINGs with no call in flight too"
+		},
+		deadline: {
+			key: "the deadline of a call",
+			scope: "client",
+			unit: "ms",
+			default: 0,
+			off: 0,
+			note: "client.ts:72: no deadline unless the caller gives one"
+		},
+		initial_reconnect_backoff: {
+			key: "grpc.initial_reconnect_backoff_ms",
+			scope: "client",
+			unit: "ms",
+			default: 1e3,
+			note: "backoff-timeout.ts:23"
+		},
+		max_reconnect_backoff: {
+			key: "grpc.max_reconnect_backoff_ms",
+			scope: "client",
+			unit: "ms",
+			default: 12e4,
+			note: "backoff-timeout.ts:25"
+		},
+		client_idle_timeout: {
+			key: "grpc.client_idle_timeout_ms",
+			scope: "client",
+			unit: "ms",
+			default: 18e5,
+			note: "internal-channel.ts:77: 30 min"
+		},
+		slack: {
+			key: "the lateness of the event loop of Node for one step",
+			scope: "process",
+			unit: "s",
+			default: .01,
+			note: "An assumption of this document, not a value of grpc-js: a timer or a callback of Node that comes late"
+		},
+		hz: {
+			key: "CONFIG_HZ",
+			scope: "global",
+			unit: "Hz",
+			default: null,
+			note: "The build option of the kernel"
+		}
+	},
+	timers: {
+		keepalive: {
+			duration: {
+				knob: "keepalive_time",
+				unit: "ms"
+			},
+			lateness: {
+				knob: "slack",
+				unit: "s"
+			},
+			arms: ["enter:waiting", "rx.ping-ack"],
+			fires: "timer.keepalive",
+			note: "transport.ts:515-534, :553-561: from the first call in flight and from each ACK, not from data. Off at the defaults"
+		},
+		ping_timeout: {
+			duration: {
+				knob: "keepalive_timeout",
+				unit: "ms"
+			},
+			lateness: {
+				knob: "slack",
+				unit: "s"
+			},
+			arms: ["tx.ping"],
+			cancels: [
+				"rx.ping-ack",
+				"socket.error",
+				"peer.rst",
+				"peer.fin"
+			],
+			fires: "timer.ping-timeout",
+			note: "transport.ts:472-477: the end of the wait for the ACK ends the transport. Only a PING arms it, thus it does not run at the defaults"
+		},
+		deadline: {
+			duration: {
+				knob: "deadline",
+				unit: "ms"
+			},
+			lateness: {
+				knob: "slack",
+				unit: "s"
+			},
+			arms: ["app.call", "enter:waiting"],
+			cancels: [
+				"rx.reply",
+				"socket.error",
+				"peer.rst",
+				"peer.fin"
+			],
+			fires: "timer.deadline",
+			note: "resolving-call.ts:118-180: the deadline of the call, DEADLINE_EXCEEDED. No bound at the defaults. A server of grpc-go starts a timer of the same time from the header grpc-timeout, and its RST_STREAM CANCEL can reach the call first: then the call ends with CANCELLED"
+		},
+		idle_timeout: {
+			duration: {
+				knob: "client_idle_timeout",
+				unit: "ms"
+			},
+			lateness: {
+				knob: "slack",
+				unit: "s"
+			},
+			arms: ["enter:idle"],
+			cancels: ["app.call"],
+			fires: "timer.idle",
+			note: "internal-channel.ts:324-325, :655: the channel goes IDLE and closes its transport"
+		},
+		reconnect: {
+			duration: {
+				expr: "min(initial_reconnect_backoff * pow(1.6, fired), max_reconnect_backoff)",
+				unit: "ms"
+			},
+			early: {
+				expr: "0.2 * min(initial_reconnect_backoff * pow(1.6, fired), max_reconnect_backoff)",
+				unit: "ms"
+			},
+			lateness: {
+				expr: "0.2 * min(initial_reconnect_backoff * pow(1.6, fired), max_reconnect_backoff) + 1000 * slack",
+				unit: "ms"
+			},
+			arms: ["enter:connecting"],
+			cancels: ["rx.settings"],
+			fires: "timer.reconnect",
+			backoff: { resets: ["rx.settings"] },
+			note: "backoff-timeout.ts:23-26, subchannel.ts:349-372: the backoff starts with each connect. A connect that fails before it ends waits for it. A ready transport stops it and starts it again from 1 s"
+		}
+	},
+	realizes: {
+		"systems.mechanism.heartbeat-interval": { timer: "keepalive" },
+		"systems.mechanism.heartbeat-detection-time": {
+			duration: {
+				expr: "keepalive_time + keepalive_timeout",
+				unit: "ms"
+			},
+			lateness: {
+				expr: "2000 * slack",
+				unit: "ms"
+			},
+			note: "With the keepalive on: the PING after keepalive_time, and the end of the transport keepalive_timeout after it. Off at the defaults"
+		}
+	},
+	transitions: [
+		{
+			id: "gj.call",
+			from: "[none]",
+			to: "connecting",
+			on: "app.call",
+			note: "The first call takes the channel from IDLE to CONNECTING. The call waits in its queue",
+			source: "internal-channel.ts, subchannel.ts:252-262"
+		},
+		{
+			id: "gj.connected",
+			from: "connecting",
+			to: "opening",
+			on: "socket.connect",
+			note: "TCP_NODELAY, then the preface of HTTP/2",
+			source: "transport.ts:842-870"
+		},
+		{
+			id: "gj.ready",
+			from: "opening",
+			to: "waiting",
+			on: "rx.settings",
+			note: "The transport is ready, and the queued call goes out",
+			source: "transport.ts:792-810, subchannel.ts:264-275"
+		},
+		{
+			id: "gj.connect-failed",
+			from: ["connecting", "opening"],
+			to: "ended",
+			on: [
+				"socket.error",
+				"peer.rst",
+				"peer.fin"
+			],
+			errno: "UNAVAILABLE",
+			note: "The subchannel goes to TRANSIENT_FAILURE, and the queued call fails at once with UNAVAILABLE and the error of the connect (ECONNREFUSED for a reset of the SYN)",
+			source: "subchannel.ts:298-304, load-balancing-call.ts:338-345"
+		},
+		{
+			id: "gj.call-idle",
+			from: "idle",
+			to: "waiting",
+			on: "app.call",
+			source: "transport.ts:563-666"
+		},
+		{
+			id: "gj.replied",
+			from: "waiting",
+			to: "idle",
+			on: "rx.reply",
+			source: "subchannel-call.ts:166-180"
+		},
+		{
+			id: "gj.deadline",
+			from: "waiting",
+			to: "idle",
+			on: "timer.deadline",
+			timer: "deadline",
+			errno: "DEADLINE_EXCEEDED",
+			note: "The call ends, and the transport stays",
+			source: "client.ts:72"
+		},
+		{
+			id: "gj.ping",
+			from: "waiting",
+			to: "waiting",
+			on: "timer.keepalive",
+			timer: "keepalive",
+			emits: ["tx.ping"],
+			source: "transport.ts:455-507"
+		},
+		{
+			id: "gj.ping-ack",
+			from: "waiting",
+			to: "waiting",
+			on: "rx.ping-ack",
+			source: "transport.ts:488-491"
+		},
+		{
+			id: "gj.ping-timeout",
+			from: ["idle", "waiting"],
+			to: "ended",
+			on: "timer.ping-timeout",
+			timer: "ping_timeout",
+			errno: "CLOSED",
+			emits: ["tx.fin"],
+			note: "The transport ends by itself and destroys its session. A call in flight ends with UNAVAILABLE 'Connection dropped'",
+			source: "transport.ts:472-476, :431-441, subchannel-call.ts:360-371"
+		},
+		{
+			id: "gj.reset",
+			from: ["idle", "waiting"],
+			to: "ended",
+			on: ["socket.error", "peer.rst"],
+			errno: "ECONNRESET",
+			note: "The error of the socket, with its own code: ECONNRESET for a reset, ETIMEDOUT or EHOSTUNREACH for a give-up of the kernel. A call in flight ends with UNAVAILABLE",
+			source: "transport.ts:230-242, :431-441, subchannel-call.ts:289-313"
+		},
+		{
+			id: "gj.closed",
+			from: ["idle", "waiting"],
+			to: "ended",
+			on: "peer.fin",
+			errno: "EOF",
+			emits: ["tx.fin"],
+			note: "The end of the socket ends the session, and grpc-js destroys its side. A call in flight ends with UNAVAILABLE",
+			source: "transport.ts:200-203, :237-242, :431-441"
+		},
+		{
+			id: "gj.goaway",
+			from: ["idle", "waiting"],
+			to: "ended",
+			on: "rx.goaway",
+			errno: "GOAWAY",
+			note: "The transport takes no new call, and the subchannel goes IDLE. A stream above the last stream id of the GOAWAY is refused and retried once. The server then ends the connection",
+			source: "transport.ts:205-227, subchannel.ts:275-291"
+		},
+		{
+			id: "gj.idle-timeout",
+			from: "idle",
+			to: "ended",
+			on: "timer.idle",
+			timer: "idle_timeout",
+			emits: ["tx.goaway", "tx.fin"],
+			source: "internal-channel.ts:655, transport.ts:684-687"
+		}
+	],
+	over: {
+		machine: "systems.machine.linux-tcp",
+		states: {
+			connecting: "SYN_SENT",
+			opening: "ESTABLISHED",
+			idle: "ESTABLISHED",
+			waiting: "ESTABLISHED"
+		},
+		sets: {},
+		ends: "socket.error",
+		note: "The socket of the transport: a Linux TCP socket with TCP_NODELAY and no keepalive. Thus the kernel ends a send with no ACK only at the give-up of its retransmissions, and an idle socket to a peer that is gone stays open"
+	}
+});
+//#endregion
 //#region src/http/timers.ts
 /**
 * This module gives the lateness of a timer in user space on Linux 6.6. A Node timer and a Go timer
@@ -13103,9 +14336,12 @@ const MACHINES = byId([
 	AMQPLIB,
 	RABBITMQ_CONNECTION,
 	ATEN_DETECTOR,
-	RA_MEMBER
+	RA_MEMBER,
+	GRPC_JS,
+	GRPC_GO_SERVER,
+	ETCD_SERVER
 ]);
 //#endregion
-export { AMQPLIB, ATEN_DETECTOR, GO_TRANSPORT, HIKARICP_PGJDBC, IOREDIS_SENTINEL, IOREDIS_STATUS, LINUX_TCP, MACHINES, MANIFESTATIONS, MONGODB_NODE, MONGOD_REPL, MONGOD_SESSION, NF_CONNTRACK_TCP, NODE_HTTP_AGENT, NODE_HTTP_SERVER, NODE_POSTGRES, NODE_TIMER_EARLY, PGBOUNCER_CLIENT, PGBOUNCER_SERVER, PGPOOL_SESSION, POSTGRES_SESSION, PROCEDURES_WS_CLIENT, PROCEDURES_WS_SERVER, RABBITMQ_CONNECTION, RA_MEMBER, REDIS_CLIENT, SENTINEL, SUPAVISOR_CLIENT, SUPAVISOR_SERVER, UNDICI_CLIENT, UNDICI_TICK_MS, goLateSeconds, goTimerLateness, nodeEarlySeconds, nodeLateSeconds, nodeTimerLateness, undiciFastEarly, undiciFastLateness };
+export { AMQPLIB, ATEN_DETECTOR, ETCD_SERVER, GO_TRANSPORT, GRPC_GO_SERVER, GRPC_JS, HIKARICP_PGJDBC, IOREDIS_SENTINEL, IOREDIS_STATUS, LINUX_TCP, MACHINES, MANIFESTATIONS, MONGODB_NODE, MONGOD_REPL, MONGOD_SESSION, NF_CONNTRACK_TCP, NODE_HTTP_AGENT, NODE_HTTP_SERVER, NODE_POSTGRES, NODE_TIMER_EARLY, PGBOUNCER_CLIENT, PGBOUNCER_SERVER, PGPOOL_SESSION, POSTGRES_SESSION, PROCEDURES_WS_CLIENT, PROCEDURES_WS_SERVER, RABBITMQ_CONNECTION, RA_MEMBER, REDIS_CLIENT, SENTINEL, SUPAVISOR_CLIENT, SUPAVISOR_SERVER, UNDICI_CLIENT, UNDICI_TICK_MS, goLateSeconds, goTimerLateness, nodeEarlySeconds, nodeLateSeconds, nodeTimerLateness, undiciFastEarly, undiciFastLateness };
 
 //# sourceMappingURL=index.js.map