@mark1russell7/machines 0.3.9 → 0.3.11

package/build/index.js

@@ -7824,6 +7824,10 @@ const PGBOUNCER_SERVER = machineSchema.parse({
 			ref: `${PB} src/janitor.c:558-570 the janitor closes a server in SV_LOGIN that is older than server_connect_timeout, from its launch: 'connect timeout'`,
 			rung: "implemented"
 		},
+		{
+			ref: "run 39160356281 of mark1russell7/systems: with server_connect_timeout 128 s, the connect timer closed the socket 127.998993 s after its SYN in 1 of 11 runs, 1.007 ms before 128 s. libevent 2.1 counts a timeout from its cached time of the pass (event.c event_add_nolock, gettime with tv_cache)",
+			rung: "observed"
+		},
 		{
 			ref: `${PB} src/objects.c:1385-1393, :1246-1248 a server in a login that closes marks the pool as failing, with the reason. A login that ends clears it`,
 			rung: "implemented"
@@ -8044,6 +8048,10 @@ const PGBOUNCER_SERVER = machineSchema.parse({
 				knob: "slack",
 				unit: "ms"
 			},
+			early: {
+				knob: "slack",
+				unit: "ms"
+			},
 			arms: ["enter:connecting"],
 			cancels: [
 				"socket.connect",
@@ -8051,7 +8059,7 @@ const PGBOUNCER_SERVER = machineSchema.parse({
 				"peer.rst"
 			],
 			fires: "timer.connect-timeout",
-			note: "src/objects.c:1640-1641, src/sbuf.c:163-203: a timeout of libevent on the wait for EV_WRITE, in whole seconds. Which clock libevent reads is an assumption of this document: the monotonic one"
+			note: "src/objects.c:1640-1641, src/sbuf.c:163-203: a timeout of libevent on the wait for EV_WRITE, in whole seconds. Which clock libevent reads is an assumption of this document: the monotonic one. libevent counts the timeout from the time that it caches for the callbacks of one pass of its loop, thus from up to one pass before the connect: the timer can fire up to that pass early"
 		},
 		login_timeout: {
 			duration: {
@@ -9592,6 +9600,775 @@ const POSTGRES_SESSION = machineSchema.parse({
 	}
 });
 //#endregion
+//#region src/pg/supavisor-client.ts
+const SV = "v2.9.13";
+/**
+* This document is Supavisor 2.9.13 in transaction mode, for one client connection. It gives the
+* states of the client handler (a gen_statem) from the accept to the close, and the timers that act
+* on it.
+*
+* Between two transactions the client holds no server connection. A message of the client checks one
+* out of the pool of the tenant, and ReadyForQuery of the server checks it in. Thus a fault of the
+* server reaches an idle client only through the pool. Its next query meets the pool, or the pool
+* shuts down and closes it, as after 57P03 at a login of the pool.
+*
+* At the defaults the handler writes a heartbeat to an idle client each 60 s: a ParameterStatus of
+* application_name. A failed write ends the client. client_idle_timeout does not end a session in
+* 2.9.13: its timer fires an event that no clause handles. Each client socket has SO_KEEPALIVE.
+*/
+const SUPAVISOR_CLIENT = machineSchema.parse({
+	format: "mark1russell7.machine/1",
+	id: "supavisor-client",
+	title: "Supavisor 2.9.13 in transaction mode: one client connection, its checkout of a server and its heartbeat",
+	layer: "proxy",
+	version: "2.9.13",
+	conditions: {
+		supavisor: "2.9.13",
+		mode: "transaction, the mode of the user of the tenant",
+		client: "a PostgreSQL client over TCP, with no TLS, as the user <db_user>.<tenant>",
+		tenant: "one tenant with one user and one server, client_heartbeat_interval 60 s and client_idle_timeout 0 at the defaults"
+	},
+	sources: [
+		{
+			ref: `${SV} lib/supavisor/tenants/tenant.ex:28-32 the defaults of a tenant: default_pool_size 15, default_max_clients 1000, client_idle_timeout 0, client_heartbeat_interval 60 s`,
+			rung: "implemented"
+		},
+		{
+			ref: `${SV} lib/supavisor/tenants/user.ex:16-19 a user: mode_type transaction or session, pool_size, pool_checkout_timeout 60_000 ms, max_clients`,
+			rung: "implemented"
+		},
+		{
+			ref: `${SV} lib/supavisor/application.ex:71-83 each listener is ranch_tcp with keepalive true: each client socket has SO_KEEPALIVE`,
+			rung: "implemented"
+		},
+		{
+			ref: `${SV} lib/supavisor/client_handler.ex:21-23, :123, :198 a state_timeout of 5_000 ms in :handshake, and 2_500 ms for a TLS handshake`,
+			rung: "implemented"
+		},
+		{
+			ref: `${SV} lib/supavisor/client_handler.ex:315, :600, :627 an event timeout of 15_000 ms on each wait of the authentication`,
+			rung: "implemented"
+		},
+		{
+			ref: `${SV} lib/supavisor/client_handler.ex:901-911 handle_actions arms the event timeout of client_idle_timeout, then the event timeout of the heartbeat. A gen_statem has one event timeout: the second action replaces the first`,
+			rung: "implemented"
+		},
+		{
+			ref: `${SV} lib/supavisor/client_handler.ex:430-433, :734-744 the timer of client_idle_timeout fires :idle_timeout, but the clause matches :idle_terminate. The catch-all clause logs 'Undefined msg' and keeps the state`,
+			rung: "implemented"
+		},
+		{
+			ref: `${SV} lib/supavisor/client_handler.ex:435-445, :1006 the heartbeat writes the ParameterStatus application_name each client_heartbeat_interval, and a failed write ends the client`,
+			rung: "implemented"
+		},
+		{
+			ref: `${SV} lib/supavisor/client_handler.ex:705-716, :836-870, :966-971 a message in :idle checks out a server: poolboy with pool_checkout_timeout, then DbHandler.checkout with its call timeout of 15 s (lib/supavisor/db_handler.ex:101-110). A server connection that connects postpones the call (db_handler.ex:500-516)`,
+			rung: "implemented"
+		},
+		{
+			ref: `${SV} lib/supavisor/errors/checkout_timeout_error.ex and lib/supavisor/error.ex:83-84 a checkout timeout reaches the client as FATAL XX000 'unable to check out connection from the pool after <ms>ms in Transaction mode'`,
+			rung: "implemented"
+		},
+		{
+			ref: `${SV} lib/supavisor/client_handler.ex:523-537, :872-876 ReadyForQuery of the server: the client checks the server in and goes to :idle, and handle_actions arms the heartbeat`,
+			rung: "implemented"
+		},
+		{
+			ref: `${SV} lib/supavisor/client_handler.ex:697-703 a Sync of the client in :busy goes to the server, and handle_actions arms the heartbeat in :busy too`,
+			rung: "implemented"
+		},
+		{
+			ref: `${SV} lib/supavisor/client_handler.ex:90, :485-497 and lib/supavisor/errors/db_handler_exited_error.ex:15-25 the handler traps exits. The exit of its server connection ends the client: after a fatal error of the server that the client got, or with no ErrorResponse for the close of the server (db_termination)`,
+			rung: "implemented"
+		},
+		{
+			ref: `${SV} lib/supavisor/client_handler.ex:556-566, :1016-1022 a close or an error of the client socket ends the client`,
+			rung: "implemented"
+		},
+		{
+			ref: `${SV} lib/supavisor/client_handler.ex:545-556 and lib/supavisor/protocol/server.ex:183-190 the graceful shutdown of the pool: a client outside a transaction gets FATAL 57P01 'terminating connection due to administrator command' and its close, and a client in a transaction waits for its end (postpone)`,
+			rung: "implemented"
+		}
+	],
+	states: {
+		"[none]": {
+			initial: true,
+			pseudo: true,
+			note: "Before ranch accepts the connection"
+		},
+		handshake: { note: "The startup packet, with a state timeout of 5 s" },
+		auth: { note: "The authentication of the client by the password of its user, with a timeout of 15 s on each wait" },
+		idle: { note: "Between two transactions: no server connection. The heartbeat runs" },
+		checkout: { note: "A message of the client waits for a server connection of the pool. The handler does nothing else in this wait" },
+		busy: { note: "A transaction: the client holds a server connection, and the server connection sends the replies to the client" },
+		ended: {
+			final: true,
+			note: "The handler closed the client, with an ErrorResponse when it has one"
+		}
+	},
+	events: {
+		"local.accept": {
+			kind: "local",
+			note: "ranch accepts the TCP connection"
+		},
+		"rx.startup": {
+			kind: "rx",
+			note: "The startup packet of the client"
+		},
+		"local.authenticated": {
+			kind: "local",
+			note: "The password of the client matches, and the pool of the tenant serves"
+		},
+		"rx.query": {
+			kind: "rx",
+			note: "A message of the client between two transactions"
+		},
+		"local.checked-out": {
+			kind: "local",
+			note: "The pool gives a server connection, and it takes the client"
+		},
+		"server.ready": {
+			kind: "local",
+			note: "The server connection reads ReadyForQuery: the end of the transaction"
+		},
+		"server.exit": {
+			kind: "peer",
+			note: "The server connection of the client ends: the server closed it, reset it, or sent a fatal error"
+		},
+		"client.gone": {
+			kind: "peer",
+			note: "The client closes its connection, or a read or a write of its socket fails"
+		},
+		"pool.shutdown": {
+			kind: "local",
+			note: "The pool of the tenant shuts down gracefully, for example after 57P03 at a login of the pool"
+		},
+		"timer.handshake": {
+			kind: "timer",
+			note: "The state timeout of the handshake"
+		},
+		"timer.auth": {
+			kind: "timer",
+			note: "The timeout of a wait of the authentication"
+		},
+		"timer.heartbeat": {
+			kind: "timer",
+			note: "client_heartbeat_interval with no event of the handler"
+		},
+		"timer.checkout": {
+			kind: "timer",
+			note: "The pool gives no server connection in pool_checkout_timeout, or the server connection does not take the client in 15 s"
+		},
+		"tx.heartbeat": {
+			kind: "tx",
+			note: "The ParameterStatus application_name to the client"
+		},
+		"tx.error": {
+			kind: "tx",
+			note: "An ErrorResponse: FATAL with the SQLSTATE of the error, XX000 for an error of Supavisor"
+		}
+	},
+	knobs: {
+		client_heartbeat_interval: {
+			key: "supavisor client_heartbeat_interval of the tenant",
+			scope: "proxy",
+			unit: "s",
+			default: 60,
+			off: 0,
+			note: "lib/supavisor/tenants/tenant.ex:32"
+		},
+		client_idle_timeout: {
+			key: "supavisor client_idle_timeout of the tenant",
+			scope: "proxy",
+			unit: "s",
+			default: 0,
+			off: 0,
+			note: "lib/supavisor/tenants/tenant.ex:31. It ends no session in 2.9.13, thus this document gives it no timer. Its event timeout is armed only when the heartbeat is off, and it fires :idle_timeout, which goes to the catch-all clause (lib/supavisor/client_handler.ex:430-433, :734-744, :901-911)"
+		},
+		pool_checkout_timeout: {
+			key: "supavisor pool_checkout_timeout of the user",
+			scope: "proxy",
+			unit: "ms",
+			default: 6e4,
+			note: "lib/supavisor/tenants/user.ex:18"
+		},
+		handshake: {
+			key: "the state timeout of the handshake",
+			scope: "process",
+			unit: "ms",
+			default: 5e3,
+			note: "lib/supavisor/client_handler.ex:23: a constant of the source"
+		},
+		auth: {
+			key: "the timeout of a wait of the authentication",
+			scope: "process",
+			unit: "ms",
+			default: 15e3,
+			note: "lib/supavisor/client_handler.ex:315: a constant of the source"
+		},
+		checkout_call: {
+			key: "the call timeout of DbHandler.checkout",
+			scope: "process",
+			unit: "ms",
+			default: 15e3,
+			note: "lib/supavisor/db_handler.ex:106: a constant of the source"
+		},
+		slack: {
+			key: "the lateness of the scheduler of the BEAM for one timer of a gen_statem",
+			scope: "process",
+			unit: "ms",
+			default: 10,
+			note: "An assumption of this document, not a value of Supavisor"
+		}
+	},
+	timers: {
+		handshake_timeout: {
+			duration: {
+				knob: "handshake",
+				unit: "ms"
+			},
+			lateness: {
+				knob: "slack",
+				unit: "ms"
+			},
+			arms: ["enter:handshake"],
+			cancels: ["rx.startup"],
+			fires: "timer.handshake",
+			note: "lib/supavisor/client_handler.ex:123, :198: a state timeout"
+		},
+		auth_timeout: {
+			duration: {
+				knob: "auth",
+				unit: "ms"
+			},
+			lateness: {
+				knob: "slack",
+				unit: "ms"
+			},
+			arms: ["enter:auth"],
+			cancels: ["local.authenticated"],
+			fires: "timer.auth",
+			note: "lib/supavisor/client_handler.ex:315, :600, :627"
+		},
+		heartbeat: {
+			duration: {
+				knob: "client_heartbeat_interval",
+				unit: "s"
+			},
+			lateness: {
+				knob: "slack",
+				unit: "ms"
+			},
+			arms: ["enter:idle"],
+			cancels: ["rx.query"],
+			fires: "timer.heartbeat",
+			backoff: { resets: ["enter:idle"] },
+			note: "lib/supavisor/client_handler.ex:435-445, :901-911: an event timeout, thus any event of the handler cancels it. Each heartbeat arms the next, the same each time. A Sync in a transaction arms it too"
+		},
+		checkout_timeout: {
+			duration: {
+				knob: "checkout_call",
+				unit: "ms"
+			},
+			lateness: {
+				knob: "slack",
+				unit: "ms"
+			},
+			arms: ["enter:checkout"],
+			cancels: ["local.checked-out"],
+			fires: "timer.checkout",
+			note: "lib/supavisor/client_handler.ex:848-851, lib/supavisor/db_handler.ex:101-110: poolboy gives a worker of the pool at once while the pool has one, and the call to that worker waits up to 15 s while it connects. With each worker checked out, poolboy waits up to pool_checkout_timeout"
+		}
+	},
+	transitions: [
+		{
+			id: "scl.accept",
+			from: "[none]",
+			to: "handshake",
+			on: "local.accept",
+			timer: "handshake_timeout",
+			source: "lib/supavisor/client_handler.ex:89-125"
+		},
+		{
+			id: "scl.startup",
+			from: "handshake",
+			to: "auth",
+			on: "rx.startup",
+			timer: "auth_timeout",
+			source: "lib/supavisor/client_handler.ex:211-315"
+		},
+		{
+			id: "scl.handshake-timed-out",
+			from: "handshake",
+			to: "ended",
+			on: "timer.handshake",
+			source: "lib/supavisor/client_handler.ex:198-200"
+		},
+		{
+			id: "scl.auth-timed-out",
+			from: "auth",
+			to: "ended",
+			on: "timer.auth",
+			errno: "XX000",
+			emits: ["tx.error"],
+			source: "lib/supavisor/client_handler.ex:627-635"
+		},
+		{
+			id: "scl.authenticated",
+			from: "auth",
+			to: "idle",
+			on: "local.authenticated",
+			timer: "heartbeat",
+			source: "lib/supavisor/client_handler.ex:340-410"
+		},
+		{
+			id: "scl.heartbeat",
+			from: ["idle", "busy"],
+			to: "idle",
+			on: "timer.heartbeat",
+			guard: "the write of the heartbeat succeeds",
+			timer: "heartbeat",
+			emits: ["tx.heartbeat"],
+			source: "lib/supavisor/client_handler.ex:435-440"
+		},
+		{
+			id: "scl.query",
+			from: "idle",
+			to: "checkout",
+			on: "rx.query",
+			timer: "checkout_timeout",
+			source: "lib/supavisor/client_handler.ex:705-716"
+		},
+		{
+			id: "scl.checked-out",
+			from: "checkout",
+			to: "busy",
+			on: "local.checked-out",
+			source: "lib/supavisor/client_handler.ex:708-711, :851-856"
+		},
+		{
+			id: "scl.checkout-timed-out",
+			from: "checkout",
+			to: "ended",
+			on: "timer.checkout",
+			errno: "XX000",
+			emits: ["tx.error"],
+			note: "FATAL 'unable to check out connection from the pool after <ms>ms in Transaction mode'",
+			source: "lib/supavisor/client_handler.ex:712-714, :966-971, lib/supavisor/errors/checkout_timeout_error.ex"
+		},
+		{
+			id: "scl.ready",
+			from: "busy",
+			to: "idle",
+			on: "server.ready",
+			timer: "heartbeat",
+			source: "lib/supavisor/client_handler.ex:523-537"
+		},
+		{
+			id: "scl.server-gone",
+			from: "busy",
+			to: "ended",
+			on: "server.exit",
+			note: "A fatal error of the server reaches the client first. A close or a reset of the server has no ErrorResponse: the client gets the close only",
+			source: "lib/supavisor/client_handler.ex:485-497, lib/supavisor/errors/db_handler_exited_error.ex:15-25"
+		},
+		{
+			id: "scl.gone",
+			from: [
+				"handshake",
+				"auth",
+				"idle",
+				"checkout",
+				"busy"
+			],
+			to: "ended",
+			on: "client.gone",
+			source: "lib/supavisor/client_handler.ex:556-566, :1016-1022"
+		},
+		{
+			id: "scl.pool-shutdown",
+			from: "idle",
+			to: "ended",
+			on: "pool.shutdown",
+			errno: "57P01",
+			emits: ["tx.error"],
+			note: "FATAL 57P01 'terminating connection due to administrator command', then the close. A client in a transaction gets it at the end of the transaction",
+			source: "lib/supavisor/client_handler.ex:545-556, lib/supavisor/protocol/server.ex:183-190"
+		}
+	],
+	over: {
+		machine: "systems.machine.linux-tcp",
+		states: {
+			handshake: "ESTABLISHED",
+			auth: "ESTABLISHED",
+			idle: "ESTABLISHED",
+			checkout: "ESTABLISHED",
+			busy: "ESTABLISHED"
+		},
+		sets: {},
+		ends: "client.gone",
+		note: "The socket of the client. ranch sets SO_KEEPALIVE and no other keepalive option, thus the three keepalive sysctls of the namespace apply"
+	}
+});
+//#endregion
+//#region src/pg/supavisor-server.ts
+/**
+* This document is Supavisor 2.9.13 in transaction mode, for one server connection of the pool of a
+* tenant. It is one DbHandler, a gen_statem, from its start by the pool to its end.
+*
+* The connect to the server has a timeout of 5 s, and the authentication 15 s. A failed connect ends the
+* DbHandler with FATAL 08006 'Failed to connect to database'. A client that waits for this connection gets
+* that error at once. The pool then starts a new DbHandler, which waits the rest of 2.5 s from the last
+* failure before it connects.
+*
+* The DbHandler reads its socket in each state. Thus a close or a reset of the server ends it at once, idle
+* or with a client. A client that holds the connection then gets the close. The server socket has
+* TCP_NODELAY and no keepalive, and no timer of Supavisor bounds a query.
+*/
+const SUPAVISOR_SERVER = machineSchema.parse({
+	format: "mark1russell7.machine/1",
+	id: "supavisor-server",
+	title: "Supavisor 2.9.13 in transaction mode: one server connection of the pool of a tenant",
+	layer: "proxy",
+	version: "2.9.13",
+	conditions: {
+		supavisor: "2.9.13",
+		mode: "transaction, the mode of the user of the tenant",
+		server: "one PostgreSQL server over TCP, with no TLS, at the address of the tenant"
+	},
+	sources: [
+		{
+			ref: `${SV} lib/supavisor/tenant_supervisor.ex:72-80 the pool of a tenant: poolboy, worker DbHandler, size min_size, max_overflow pool_size, lifo, an overflow worker stops after 5 min idle`,
+			rung: "implemented"
+		},
+		{
+			ref: `${SV} lib/supavisor/db_handler.ex:66, :205-224, :1111-1119 a new DbHandler waits the rest of 2.5 s from the last failed connect of its pool (connect_cooldown)`,
+			rung: "implemented"
+		},
+		{
+			ref: `${SV} lib/supavisor/db_handler.ex:226-289 the connect: gen_tcp with nodelay and no keepalive, and a timeout of 5_000 ms (1_000 ms in proxy mode). Then the startup message, and a state timeout of 15_000 ms on the authentication`,
+			rung: "implemented"
+		},
+		{
+			ref: `${SV} lib/supavisor/db_handler.ex:1072-1085, :292-321 a failed connect: the circuit breaker and the backoff of the pool record it, FATAL 08006 'Failed to connect to database', and the DbHandler goes to terminating_with_error, then stops`,
+			rung: "implemented"
+		},
+		{
+			ref: `${SV} lib/supavisor/db_handler.ex:480-516 a checkout in :idle or :busy links the client and gives it the socket. In another state the call waits (postpone), and in terminating_with_error it gets the error`,
+			rung: "implemented"
+		},
+		{
+			ref: `${SV} lib/supavisor/db_handler.ex:551-574 a close of the server socket: in the authentication a failed connect, else the DbHandler stops with db_termination`,
+			rung: "implemented"
+		},
+		{
+			ref: `${SV} lib/supavisor/db_handler.ex:575-585 the exit of the client that holds the connection: Terminate to the server, close, stop`,
+			rung: "implemented"
+		},
+		{
+			ref: `${SV} lib/supavisor/circuit_breaker.ex:28-35 100 failed connects of a tenant in 150 s block its new connections for 30 s`,
+			rung: "implemented"
+		},
+		{
+			ref: `${SV} lib/supavisor/db_handler.ex:69-76, :362-372, :297-301 an ErrorResponse at the authentication: 57P03 (the server shuts down) shuts the pool down gracefully, 3D000, 42501 and 22023 shut it down, and 28P01 and 28000 keep it`,
+			rung: "implemented"
+		},
+		{
+			ref: `${SV} lib/supavisor/manager.ex:107-118, lib/supavisor/client_handler.ex:545-556 the graceful shutdown of a pool: each client outside a transaction gets FATAL 57P01 'terminating connection due to administrator command' and its close. A client in a transaction gets it after the transaction`,
+			rung: "implemented"
+		},
+		{
+			ref: `${SV} run 39164922565 of mark1russell7/systems: the server stopped, and the next connect of the pool got 57P03 in 6 of 11 runs. Each idle client then got FATAL 57P01 and its close, 8 to 10 ms after the server closed its connections. In 5 runs the connect came after the server, and the pool stayed`,
+			rung: "observed"
+		}
+	],
+	states: {
+		"[none]": {
+			initial: true,
+			pseudo: true,
+			note: "The pool starts a DbHandler"
+		},
+		cooldown: { note: "The pool had a failed connect in the last 2.5 s: the DbHandler waits for the rest" },
+		connecting: { note: "The TCP connect, with its timeout of 5 s" },
+		authentication: { note: "The startup message and the authentication, with a state timeout of 15 s" },
+		idle: { note: "In the pool, ready for a client. The DbHandler reads the socket" },
+		busy: { note: "Checked out by a client for a transaction: the DbHandler sends each message of the server to the client" },
+		ended: {
+			final: true,
+			note: "The DbHandler stopped, and the pool starts a new one"
+		}
+	},
+	events: {
+		"local.start": {
+			kind: "local",
+			note: "The pool starts the DbHandler"
+		},
+		"socket.connect": {
+			kind: "local",
+			note: "The TCP connect ends"
+		},
+		"rx.ready-for-query": {
+			kind: "rx",
+			note: "ReadyForQuery of the server: the end of the authentication or of a transaction"
+		},
+		"local.checkout": {
+			kind: "local",
+			note: "A client checks the connection out of the pool"
+		},
+		"client.gone": {
+			kind: "peer",
+			note: "The client that holds the connection ends"
+		},
+		"peer.fin": {
+			kind: "peer",
+			note: "The server closes the connection"
+		},
+		"peer.rst": {
+			kind: "peer",
+			note: "A reset of the connection of the server"
+		},
+		"socket.error": {
+			kind: "local",
+			note: "The socket of the server fails with its own error"
+		},
+		"rx.shutting-down": {
+			kind: "rx",
+			note: "An ErrorResponse 57P03 at the authentication: the server shuts down"
+		},
+		"timer.cooldown": {
+			kind: "timer",
+			note: "The rest of 2.5 s from the last failed connect of the pool"
+		},
+		"timer.connect": {
+			kind: "timer",
+			note: "The timeout of gen_tcp.connect"
+		},
+		"timer.auth": {
+			kind: "timer",
+			note: "The state timeout of the authentication"
+		},
+		"tx.terminate": {
+			kind: "tx",
+			note: "The Terminate message, then the close of the socket"
+		},
+		"tx.error": {
+			kind: "tx",
+			note: "FATAL 08006 'Failed to connect to database' to the client that waits for the connection"
+		},
+		"tx.pool-shutdown": {
+			kind: "local",
+			note: "The graceful shutdown of the pool: FATAL 57P01 and the close of each client outside a transaction"
+		}
+	},
+	knobs: {
+		cooldown: {
+			key: "the cooldown of the pool after a failed connect",
+			scope: "process",
+			unit: "ms",
+			default: 2500,
+			note: "lib/supavisor/db_handler.ex:66: a constant of the source"
+		},
+		connect: {
+			key: "the timeout of the TCP connect to the server",
+			scope: "process",
+			unit: "ms",
+			default: 5e3,
+			note: "lib/supavisor/db_handler.ex:240: a constant of the source, 1_000 ms in proxy mode"
+		},
+		auth: {
+			key: "the state timeout of the authentication to the server",
+			scope: "process",
+			unit: "ms",
+			default: 15e3,
+			note: "lib/supavisor/db_handler.ex:67: a constant of the source"
+		},
+		keepalive_idle: {
+			key: "the keepalive idle time of the server socket of Supavisor",
+			scope: "proxy",
+			unit: "s",
+			default: 0,
+			off: 0,
+			note: "lib/supavisor/db_handler.ex:229-236: Supavisor sets no SO_KEEPALIVE on a server socket, thus no bound"
+		},
+		slack: {
+			key: "the lateness of the scheduler of the BEAM for one timer of a gen_statem",
+			scope: "process",
+			unit: "ms",
+			default: 10,
+			note: "An assumption of this document, not a value of Supavisor"
+		}
+	},
+	timers: {
+		cooldown: {
+			duration: {
+				knob: "cooldown",
+				unit: "ms"
+			},
+			lateness: {
+				knob: "slack",
+				unit: "ms"
+			},
+			arms: ["enter:cooldown"],
+			fires: "timer.cooldown",
+			note: "lib/supavisor/db_handler.ex:205-224, :1111-1119: the rest of 2.5 s from the last failure, thus at most 2.5 s"
+		},
+		connect_timeout: {
+			duration: {
+				knob: "connect",
+				unit: "ms"
+			},
+			lateness: {
+				knob: "slack",
+				unit: "ms"
+			},
+			arms: ["enter:connecting"],
+			cancels: [
+				"socket.connect",
+				"socket.error",
+				"peer.rst"
+			],
+			fires: "timer.connect",
+			note: "lib/supavisor/db_handler.ex:240-248: the timeout of gen_tcp.connect. Its end closes the socket in SYN_SENT"
+		},
+		authentication_timeout: {
+			duration: {
+				knob: "auth",
+				unit: "ms"
+			},
+			lateness: {
+				knob: "slack",
+				unit: "ms"
+			},
+			arms: ["enter:authentication"],
+			cancels: [
+				"rx.ready-for-query",
+				"peer.fin",
+				"peer.rst",
+				"socket.error"
+			],
+			fires: "timer.auth",
+			note: "lib/supavisor/db_handler.ex:272, :329-331"
+		}
+	},
+	transitions: [
+		{
+			id: "ssv.start",
+			from: "[none]",
+			to: "connecting",
+			on: "local.start",
+			guard: "no failed connect of the pool in the last 2.5 s",
+			timer: "connect_timeout",
+			source: "lib/supavisor/db_handler.ex:205-228"
+		},
+		{
+			id: "ssv.start-late",
+			from: "[none]",
+			to: "cooldown",
+			on: "local.start",
+			guard: "a failed connect of the pool in the last 2.5 s",
+			timer: "cooldown",
+			source: "lib/supavisor/db_handler.ex:205-211"
+		},
+		{
+			id: "ssv.cooldown-over",
+			from: "cooldown",
+			to: "connecting",
+			on: "timer.cooldown",
+			timer: "connect_timeout",
+			source: "lib/supavisor/db_handler.ex:222-224"
+		},
+		{
+			id: "ssv.connected",
+			from: "connecting",
+			to: "authentication",
+			on: "socket.connect",
+			timer: "authentication_timeout",
+			source: "lib/supavisor/db_handler.ex:248-273"
+		},
+		{
+			id: "ssv.connect-failed",
+			from: ["connecting", "authentication"],
+			to: "ended",
+			on: [
+				"timer.connect",
+				"socket.error",
+				"peer.rst",
+				"peer.fin",
+				"timer.auth"
+			],
+			errno: "08006",
+			emits: ["tx.error"],
+			note: "FATAL 'Failed to connect to database: <reason>' to a client that waits for the connection, then the DbHandler stops",
+			source: "lib/supavisor/db_handler.ex:282-289, :329-331, :551-555, :1072-1085, :292-321"
+		},
+		{
+			id: "ssv.authenticated",
+			from: "authentication",
+			to: "idle",
+			on: "rx.ready-for-query",
+			source: "lib/supavisor/db_handler.ex:380-390"
+		},
+		{
+			id: "ssv.server-shutting-down",
+			from: "authentication",
+			to: "ended",
+			on: "rx.shutting-down",
+			emits: ["tx.pool-shutdown"],
+			note: "57P03 at the login: Supavisor shuts the whole pool down gracefully, thus a server that shuts down can end each idle client of the tenant",
+			source: "lib/supavisor/db_handler.ex:69-76, :362-372, :297-301"
+		},
+		{
+			id: "ssv.checkout",
+			from: "idle",
+			to: "busy",
+			on: "local.checkout",
+			source: "lib/supavisor/db_handler.ex:500-512"
+		},
+		{
+			id: "ssv.release",
+			from: "busy",
+			to: "idle",
+			on: "rx.ready-for-query",
+			source: "lib/supavisor/db_handler.ex:415-425"
+		},
+		{
+			id: "ssv.closed",
+			from: ["idle", "busy"],
+			to: "ended",
+			on: [
+				"peer.fin",
+				"peer.rst",
+				"socket.error"
+			],
+			note: "db_termination: a client that holds the connection gets the close, with no ErrorResponse",
+			source: "lib/supavisor/db_handler.ex:557-574"
+		},
+		{
+			id: "ssv.client-gone",
+			from: "busy",
+			to: "ended",
+			on: "client.gone",
+			emits: ["tx.terminate"],
+			source: "lib/supavisor/db_handler.ex:575-585"
+		}
+	],
+	over: {
+		machine: "systems.machine.linux-tcp",
+		states: {
+			connecting: "SYN_SENT",
+			authentication: "ESTABLISHED",
+			idle: "ESTABLISHED",
+			busy: "ESTABLISHED"
+		},
+		sets: { keepidle: {
+			knob: "keepalive_idle",
+			unit: "s"
+		} },
+		ends: "socket.error",
+		note: "The server socket, with TCP_NODELAY and no SO_KEEPALIVE. The DbHandler reads it in each state, thus the end of the socket reaches it at once"
+	}
+});
+//#endregion
 //#region src/procedures-ws.ts
 /**
 * This module holds the machine documents of the WebSocket transport of `@procedures/client`
@@ -10842,9 +11619,11 @@ const MACHINES = byId([
 	HIKARICP_PGJDBC,
 	PGBOUNCER_CLIENT,
 	PGBOUNCER_SERVER,
-	PGPOOL_SESSION
+	PGPOOL_SESSION,
+	SUPAVISOR_CLIENT,
+	SUPAVISOR_SERVER
 ]);
 //#endregion
-export { 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, REDIS_CLIENT, SENTINEL, UNDICI_CLIENT, UNDICI_TICK_MS, goLateSeconds, goTimerLateness, nodeEarlySeconds, nodeLateSeconds, nodeTimerLateness, undiciFastEarly, undiciFastLateness };
+export { 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, REDIS_CLIENT, SENTINEL, SUPAVISOR_CLIENT, SUPAVISOR_SERVER, UNDICI_CLIENT, UNDICI_TICK_MS, goLateSeconds, goTimerLateness, nodeEarlySeconds, nodeLateSeconds, nodeTimerLateness, undiciFastEarly, undiciFastLateness };
 
 //# sourceMappingURL=index.js.map