@mark1russell7/harness 0.5.0 → 0.7.0

package/image/go-http/Dockerfile

@@ -0,0 +1,14 @@
+# The Go HTTP client of the harness: the http.Transport of Go 1.27.2 at its defaults, with the
+# settings of a cell over them. It runs as a container in the client's network namespace, as the
+# harness's own TCP client does, and prints the same JSON lines. The program uses the standard
+# library only, thus the digest of the builder pins all of its code.
+# lab.ts stages the build context: this folder, under harness/image/go-http.
+FROM golang:1.27.2-alpine@sha256:f92b6ef800e499660581efdabdf25d9d817a9d124eaf900924f0504e7e27e12d AS build
+WORKDIR /src
+COPY harness/image/go-http/go.mod harness/image/go-http/main.go ./
+# the format and the vet of the source come first, as the cargo test of the harness image does
+RUN test -z "$(gofmt -l .)" || { gofmt -d .; exit 1; }
+RUN CGO_ENABLED=0 go vet ./... && CGO_ENABLED=0 go build -trimpath -o /client-go .
+
+FROM alpine:3.22@sha256:5291449c3df73caf6ed85e649dec1b9e818b39a5d8c871e97afc13e9cd5e8fa8
+COPY --from=build /client-go /opt/harness/client-go

package/image/go-http/go.mod

@@ -0,0 +1,3 @@
+module client-go
+
+go 1.27

package/image/go-http/main.go

@@ -0,0 +1,324 @@
+// Command client-go is the Go client of the HTTP cells: the http.Transport of Go 1.27.2 at its
+// defaults, with each setting that a cell gives over them. Each event is a JSON line with `ev` and
+// `t`, the CLOCK_MONOTONIC time in nanoseconds, as the TCP client of the harness writes them.
+//
+//	client-go HOST PORT --mode idle|inflight|gap [--gap-ms N] [--method GET|POST] [--hold-ms N]
+//	          [--bytes N] [--go PATH] [--max-s N] [--linger-ms N]
+//	          [--idle-conn-timeout-ms N] [--max-idle-per-host N] [--dial-timeout-ms N]
+//	          [--keepalive-ms N] [--keepalive-interval-ms N] [--keepalive-count N] [--timeout-ms N]
+//
+// The first request is GET /, and the end of its reply is the ready line. Then the client holds
+// the connection idle (idle), sends the second request when the file --go appears (inflight), or
+// sends it after the gap (gap).
+//
+// A wrapper on each connection writes what the read loop of the transport reads: an end of file,
+// or an error. The trace of the transport writes which connection each request goes on, whether
+// the transport reused it, and each new try of a request on a new connection.
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"flag"
+	"fmt"
+	"io"
+	"net"
+	"net/http"
+	"net/http/httptrace"
+	"os"
+	"runtime"
+	"strings"
+	"sync"
+	"syscall"
+	"time"
+	"unsafe"
+)
+
+var out sync.Mutex
+
+// now gives the time on CLOCK_MONOTONIC in nanoseconds: the clock of the prober.
+func now() int64 {
+	var ts syscall.Timespec
+	syscall.Syscall(syscall.SYS_CLOCK_GETTIME, 1, uintptr(unsafe.Pointer(&ts)), 0)
+	return ts.Nano()
+}
+
+// emitAt writes one line with the time t.
+func emitAt(ev string, t int64, fields map[string]any) {
+	line := map[string]any{"ev": ev, "t": t}
+	for key, value := range fields {
+		line[key] = value
+	}
+	bytes, _ := json.Marshal(line)
+	out.Lock()
+	os.Stdout.Write(append(bytes, '\n'))
+	out.Unlock()
+}
+
+// emit writes one line with the time now.
+func emit(ev string, fields map[string]any) { emitAt(ev, now(), fields) }
+
+var names = map[syscall.Errno]string{
+	syscall.ECONNRESET:   "ECONNRESET",
+	syscall.ECONNREFUSED: "ECONNREFUSED",
+	syscall.ETIMEDOUT:    "ETIMEDOUT",
+	syscall.EHOSTUNREACH: "EHOSTUNREACH",
+	syscall.ENETUNREACH:  "ENETUNREACH",
+	syscall.EPIPE:        "EPIPE",
+	syscall.ECONNABORTED: "ECONNABORTED",
+}
+
+// errnoOf gives the name of the error of a socket, EOF for an end of file, or TIMEOUT for a
+// deadline of Go.
+func errnoOf(err error) string {
+	var errno syscall.Errno
+	if errors.As(err, &errno) {
+		if name, ok := names[errno]; ok {
+			return name
+		}
+		return fmt.Sprintf("E%d", int(errno))
+	}
+	if errors.Is(err, io.EOF) || errors.Is(err, io.ErrUnexpectedEOF) {
+		return "EOF"
+	}
+	var timeout interface{ Timeout() bool }
+	if errors.As(err, &timeout) && timeout.Timeout() {
+		return "TIMEOUT"
+	}
+	return "ERROR"
+}
+
+// traced is a connection that writes what its reads end with, and its close.
+type traced struct {
+	net.Conn
+	local  string
+	mu     sync.Mutex
+	closed bool
+}
+
+func (c *traced) Read(p []byte) (int, error) {
+	n, err := c.Conn.Read(p)
+	if err != nil {
+		c.mu.Lock()
+		closed := c.closed
+		c.mu.Unlock()
+		// a read after the close of the client itself is not an event of the peer
+		if !closed {
+			if errors.Is(err, io.EOF) {
+				emit("eof", map[string]any{"local": c.local})
+			} else {
+				emit("conn-error", map[string]any{"local": c.local, "errno": errnoOf(err), "message": err.Error()})
+			}
+		}
+	}
+	return n, err
+}
+
+func (c *traced) Close() error {
+	c.mu.Lock()
+	first := !c.closed
+	c.closed = true
+	c.mu.Unlock()
+	if first {
+		emit("closed", map[string]any{"local": c.local})
+	}
+	return c.Conn.Close()
+}
+
+// dial gives the DialContext of the transport: the dialer, and a wrapper on each connection.
+func dial(d *net.Dialer) func(ctx context.Context, network, addr string) (net.Conn, error) {
+	var mu sync.Mutex
+	count := 0
+	return func(ctx context.Context, network, addr string) (net.Conn, error) {
+		start := now()
+		conn, err := d.DialContext(ctx, network, addr)
+		if err != nil {
+			emit("dial-error", map[string]any{"errno": errnoOf(err), "message": err.Error(), "ns": now() - start})
+			return nil, err
+		}
+		mu.Lock()
+		count++
+		n := count
+		mu.Unlock()
+		local := conn.LocalAddr().String()
+		emit("conn", map[string]any{"n": n, "local": local})
+		if n == 1 {
+			emit("connected", map[string]any{"local": local})
+		}
+		return &traced{Conn: conn, local: local}, nil
+	}
+}
+
+// request sends request i and waits for its outcome. It tells whether a reply came.
+func request(client *http.Client, base string, i int, method, path string) bool {
+	attempts := 0
+	trace := &httptrace.ClientTrace{
+		GotConn: func(info httptrace.GotConnInfo) {
+			attempts++
+			ev := "request"
+			if attempts > 1 {
+				ev = "retry"
+			}
+			emit(ev, map[string]any{
+				"i":       i,
+				"local":   info.Conn.LocalAddr().String(),
+				"reused":  info.Reused,
+				"idle_ns": info.IdleTime.Nanoseconds(),
+			})
+		},
+		WroteRequest: func(info httptrace.WroteRequestInfo) {
+			fields := map[string]any{"i": i}
+			if info.Err != nil {
+				fields["errno"] = errnoOf(info.Err)
+			}
+			emit("wrote", fields)
+		},
+		GotFirstResponseByte: func() { emit("first-byte", map[string]any{"i": i}) },
+	}
+	var body io.Reader
+	if method == "POST" {
+		body = strings.NewReader("x")
+	}
+	req, err := http.NewRequestWithContext(httptrace.WithClientTrace(context.Background(), trace), method, base+path, body)
+	if err != nil {
+		emit("fail", map[string]any{"why": err.Error()})
+		os.Exit(1)
+	}
+	// the stamp comes before the call: the transport writes the request after it
+	at := now()
+	emitAt("sent", at, map[string]any{"i": i})
+	resp, err := client.Do(req)
+	if err != nil {
+		emit("error", map[string]any{"i": i, "errno": errnoOf(err), "message": err.Error()})
+		return false
+	}
+	emit("response", map[string]any{"i": i, "status": resp.StatusCode})
+	n, err := io.Copy(io.Discard, resp.Body)
+	resp.Body.Close()
+	if err != nil {
+		emit("error", map[string]any{"i": i, "errno": errnoOf(err), "message": err.Error()})
+		return false
+	}
+	if i == 1 {
+		emit("ready", map[string]any{"reply": resp.Status})
+	} else {
+		emit("data", map[string]any{"i": i, "n": n})
+		emit("replied", map[string]any{"i": i, "n": map[string]any{"value": n, "unit": "B"}})
+	}
+	return true
+}
+
+func milliseconds(ms float64) time.Duration { return time.Duration(ms * float64(time.Millisecond)) }
+
+func main() {
+	usage := "client-go HOST PORT --mode idle|inflight|gap"
+	if len(os.Args) < 3 {
+		emit("fail", map[string]any{"why": usage})
+		os.Exit(1)
+	}
+	host, port := os.Args[1], os.Args[2]
+	flags := flag.NewFlagSet("client-go", flag.ExitOnError)
+	mode := flags.String("mode", "", "idle, inflight or gap")
+	gapMs := flags.Float64("gap-ms", 0, "the gap after the first reply, in gap mode")
+	method := flags.String("method", "GET", "the method of the second request")
+	holdMs := flags.Int("hold-ms", 0, "the second request asks the server to hold its reply")
+	size := flags.Int("bytes", 0, "the second request asks for a body of this length")
+	goPath := flags.String("go", "/tmp/go", "the file that starts the second request, in inflight mode")
+	maxS := flags.Float64("max-s", 60, "the deadline of the client")
+	lingerMs := flags.Float64("linger-ms", 500, "the wait after the second request, before the exit")
+	idleMs := flags.Float64("idle-conn-timeout-ms", 0, "Transport.IdleConnTimeout")
+	maxIdle := flags.Int("max-idle-per-host", 0, "Transport.MaxIdleConnsPerHost")
+	dialMs := flags.Float64("dial-timeout-ms", 0, "Dialer.Timeout")
+	keepAliveMs := flags.Float64("keepalive-ms", 0, "Dialer.KeepAlive, negative for off")
+	intervalMs := flags.Float64("keepalive-interval-ms", 0, "KeepAliveConfig.Interval")
+	probes := flags.Int("keepalive-count", 0, "KeepAliveConfig.Count")
+	timeoutMs := flags.Float64("timeout-ms", 0, "Client.Timeout")
+	flags.Parse(os.Args[3:])
+	given := map[string]bool{}
+	flags.Visit(func(f *flag.Flag) { given[f.Name] = true })
+	if *mode != "idle" && *mode != "inflight" && *mode != "gap" {
+		emit("fail", map[string]any{"why": usage})
+		os.Exit(1)
+	}
+
+	// the dialer of http.DefaultTransport (src/net/http/transport.go:47-53), with the settings of the cell
+	dialer := &net.Dialer{Timeout: 30 * time.Second, KeepAlive: 30 * time.Second}
+	if given["dial-timeout-ms"] {
+		dialer.Timeout = milliseconds(*dialMs)
+	}
+	if given["keepalive-ms"] {
+		dialer.KeepAlive = milliseconds(*keepAliveMs)
+	}
+	if given["keepalive-interval-ms"] || given["keepalive-count"] {
+		dialer.KeepAliveConfig = net.KeepAliveConfig{
+			Enable:   dialer.KeepAlive >= 0,
+			Idle:     dialer.KeepAlive,
+			Interval: milliseconds(*intervalMs),
+			Count:    *probes,
+		}
+	}
+	transport := http.DefaultTransport.(*http.Transport).Clone()
+	transport.DialContext = dial(dialer)
+	if given["idle-conn-timeout-ms"] {
+		transport.IdleConnTimeout = milliseconds(*idleMs)
+	}
+	if given["max-idle-per-host"] {
+		transport.MaxIdleConnsPerHost = *maxIdle
+	}
+	client := &http.Client{Transport: transport}
+	if given["timeout-ms"] {
+		client.Timeout = milliseconds(*timeoutMs)
+	}
+
+	bootID, _ := os.ReadFile("/proc/sys/kernel/random/boot_id")
+	settings := map[string]any{}
+	settings["IdleConnTimeout_ms"] = transport.IdleConnTimeout.Milliseconds()
+	settings["MaxIdleConnsPerHost"] = transport.MaxIdleConnsPerHost
+	settings["DialTimeout_ms"] = dialer.Timeout.Milliseconds()
+	settings["KeepAlive_ms"] = dialer.KeepAlive.Milliseconds()
+	settings["KeepAliveInterval_ms"] = dialer.KeepAliveConfig.Interval.Milliseconds()
+	settings["KeepAliveCount"] = dialer.KeepAliveConfig.Count
+	settings["ClientTimeout_ms"] = client.Timeout.Milliseconds()
+	start := map[string]any{}
+	start["boot_id"] = strings.TrimSpace(string(bootID))
+	start["mode"] = *mode
+	start["client"] = "go-nethttp"
+	start["go"] = runtime.Version()
+	start["settings"] = settings
+	emit("start", start)
+	go func() {
+		time.Sleep(time.Duration(*maxS * float64(time.Second)))
+		emit("deadline", nil)
+		os.Exit(0)
+	}()
+
+	base := "http://" + net.JoinHostPort(host, port)
+	second := "/"
+	if *holdMs > 0 {
+		second = fmt.Sprintf("/hold?ms=%d", *holdMs)
+	} else if *size > 0 {
+		second = fmt.Sprintf("/big?bytes=%d", *size)
+	}
+	if !request(client, base, 1, "GET", "/") {
+		os.Exit(1)
+	}
+	switch *mode {
+	case "idle":
+		// the connection stays in the pool until it ends, or until the deadline
+		select {}
+	case "inflight":
+		for {
+			if _, err := os.Stat(*goPath); err == nil {
+				break
+			}
+			time.Sleep(2 * time.Millisecond)
+		}
+	case "gap":
+		time.Sleep(milliseconds(*gapMs))
+	}
+	request(client, base, 2, *method, second)
+	emit("done", map[string]any{"i": 2})
+	time.Sleep(milliseconds(*lingerMs))
+	os.Exit(0)
+}

package/image/mongo/Dockerfile

@@ -0,0 +1,11 @@
+# The harness's MongoDB client: the driver mongodb 7.7.0 on Node 24.21.0. It runs as a container
+# in the client's network namespace, as the harness's own TCP client does, and prints the same JSON
+# lines, with the driver's own events beside them. The same image sends a planned step-down.
+# lab.ts stages the build context: this folder, under harness/image/mongo. The lockfile is
+# npm-lock.json here, because npm leaves each package-lock.json out of a published tarball.
+FROM node:24.21.0-alpine@sha256:ebfe2f90462722a7a4de65e91990e97fe0d401c70e0e762c5b53302f905ec1c1
+WORKDIR /opt/harness/mongo
+COPY harness/image/mongo/package.json ./
+COPY harness/image/mongo/npm-lock.json ./package-lock.json
+RUN npm ci --omit=dev --ignore-scripts --no-audit --no-fund
+COPY harness/image/mongo/client-mongo.mjs harness/image/mongo/stepdown-mongo.mjs ./

package/image/mongo/client-mongo.mjs

@@ -0,0 +1,273 @@
+// client-mongo HOST PORT --mode idle|inflight|stream [--hosts H:P,H:P] [--set NAME] [--op write|read-long]
+//              [--interval-ms N] [--max-s N] [--go PATH] [--w majority|1] [--before] [--options JSON]
+//
+// The client of a MongoDB cell: the driver mongodb 7.7.0 on Node 24.21.0, against a replica set.
+// Each event is a JSON line with `ev` and `t`, the time on CLOCK_MONOTONIC in nanoseconds
+// (process.hrtime, which libuv reads from it). The prober stamps the records of the kernel on the
+// same clock, and the injector stamps each fault on it.
+//
+// The lines:
+// - start: the version of the driver and of Node, the mode and the options.
+// - clocks: the wall clock in ms beside the monotonic clock, each second. The log of mongod is on
+//   the wall clock, and these lines put it on the monotonic clock.
+// - socket, socket-end, socket-error: each socket of the driver by its role (monitor, rtt, pool),
+//   with its local address. The role comes from the stack of the call that makes the socket.
+// - connected: the first socket of the pool. The TCP client of the harness names its own socket so.
+// - sdam: each heartbeat, each change of the description of a server, and each change of the topology.
+// - cmap: each event of a connection pool, and each clear with its interruption of connections in use.
+// - command: each try of an operation, with its server. A retry is a second try with the same number.
+// - connecting: the start of the selection of the first server.
+// - ready: the reply to the first write once the monitor streams (idle, inflight), or the
+//   connection of the client (stream).
+// - sent, ack, fail: each operation by its sequence number, with its server or its error and labels.
+// - data, error: the end of the operation in flight, as the TCP client of the harness tells it.
+//   In idle mode, an error of the socket of the first pool connection is an error line too.
+// - done, deadline: the end of the client.
+//
+// The modes: idle sends one write, then holds the connections until --max-s. inflight sends one
+// write, waits for the file --go, sends one more operation into the fault, and holds the
+// connections after its end. stream sends a write each --interval-ms after the reply before, until
+// --max-s or SIGTERM. --before starts the client into a fault that holds already: its first
+// selection meets it.
+
+import { randomUUID } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import net from "node:net";
+
+const now = () => process.hrtime.bigint();
+const emit = (ev, fields = {}, at = now()) => process.stdout.write(`${JSON.stringify({ ev, t: Number(at), ...fields })}\n`);
+
+const argv = process.argv.slice(2);
+const flag = (name) => {
+  const at = argv.indexOf(name);
+  return at === -1 ? undefined : argv[at + 1];
+};
+const [host, port] = argv;
+const mode = flag("--mode");
+if (host === undefined || port === undefined || !["idle", "inflight", "stream"].includes(mode)) {
+  emit("fail", { why: "client-mongo HOST PORT --mode idle|inflight|stream" });
+  process.exit(1);
+}
+const first = `${host}:${port}`;
+const hosts = [first, ...(flag("--hosts") ?? "").split(",").filter((each) => each !== "" && each !== first)];
+const set = flag("--set") ?? "rs0";
+const op = flag("--op") ?? "write";
+const interval = Number(flag("--interval-ms") ?? 50);
+const max = Number(flag("--max-s") ?? 120) * 1000;
+const go = flag("--go") ?? "/tmp/go";
+const w = flag("--w") === "1" ? 1 : "majority";
+const before = argv.includes("--before");
+const options = JSON.parse(flag("--options") ?? "{}");
+
+// ---- the two clocks: the wall clock of a log line of mongod goes onto the monotonic clock by them
+const clocks = () => {
+  const t = now();
+  emit("clocks", { real: Date.now() }, t);
+};
+clocks();
+setInterval(clocks, 1000).unref();
+
+// ---- each socket of the driver, by its role: the stack of the call that makes it names the caller
+const roleOf = (stack) => {
+  if (/measureRoundTripTime/.test(stack)) return "rtt";
+  if (/sdam[\\/]monitor\.js/.test(stack)) return "monitor";
+  if (/cmap[\\/]connection_pool\.js/.test(stack)) return "pool";
+  return "other";
+};
+let connected = null;
+const createConnection = net.createConnection;
+Error.stackTraceLimit = 50;
+net.createConnection = function (...args) {
+  const role = roleOf(new Error().stack ?? "");
+  const socket = createConnection.apply(this, args);
+  const server = `${args[0]?.host}:${args[0]?.port}`;
+  socket.once("connect", () => {
+    const local = `${socket.localAddress}:${socket.localPort}`;
+    emit("socket", { role, server, local });
+    if (role === "pool" && connected === null) {
+      connected = local;
+      emit("connected", { local });
+    }
+    socket.once("close", (hadError) => emit("socket-end", { role, server, local, error: hadError }));
+  });
+  socket.once("error", (error) => {
+    const local = socket.localPort === undefined ? null : `${socket.localAddress}:${socket.localPort}`;
+    const errno = error.code ?? error.errno ?? null;
+    emit("socket-error", { role, server, local, errno, message: error.message });
+    // the socket of the client in idle mode: its error is the detection, as for the TCP client
+    if (mode === "idle" && local !== null && local === connected) emit("error", { errno });
+  });
+  return socket;
+};
+
+// the driver loads after the patch, thus each of its sockets goes through it
+const { MongoClient } = await import("mongodb");
+const version = JSON.parse(readFileSync(new URL("./node_modules/mongodb/package.json", import.meta.url), "utf8")).version;
+
+const bootId = () => {
+  try {
+    return readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim();
+  } catch {
+    return null;
+  }
+};
+emit("start", { boot_id: bootId(), client: "mongodb", driver: version, node: process.versions.node, mode, op, w, hosts, options });
+
+const uri = `mongodb://${hosts.join(",")}/?replicaSet=${set}`;
+const client = new MongoClient(uri, { ...options, writeConcern: { w }, monitorCommands: true });
+
+// ---- the driver's own events, each stamped as the driver emits it
+const failure = (error) =>
+  error === undefined || error === null
+    ? null
+    : { name: error.name, code: error.code ?? null, labels: [...(error.errorLabelSet ?? [])], message: error.message };
+const describe = (d) =>
+  d === undefined ? null : { type: d.type, setName: d.setName ?? null, electionId: d.electionId?.toHexString?.() ?? null, error: failure(d.error) };
+/** This promise resolves at the first awaited hello of a monitor: the stream of the monitor has begun. */
+let streamed = () => undefined;
+const streaming = new Promise((resolve) => {
+  streamed = resolve;
+});
+client.on("serverHeartbeatStarted", (e) => {
+  emit("sdam", { event: "heartbeat-started", address: e.connectionId, awaited: e.awaited });
+  if (e.awaited) streamed();
+});
+client.on("serverHeartbeatSucceeded", (e) =>
+  emit("sdam", { event: "heartbeat-succeeded", address: e.connectionId, awaited: e.awaited, duration: e.duration, primary: e.reply?.isWritablePrimary ?? null }),
+);
+client.on("serverHeartbeatFailed", (e) =>
+  emit("sdam", { event: "heartbeat-failed", address: e.connectionId, awaited: e.awaited, duration: e.duration, failure: failure(e.failure) }),
+);
+client.on("serverDescriptionChanged", (e) =>
+  emit("sdam", { event: "server-changed", address: e.address, previous: describe(e.previousDescription), next: describe(e.newDescription) }),
+);
+client.on("topologyDescriptionChanged", (e) => {
+  const primary = [...e.newDescription.servers.values()].find((d) => d.type === "RSPrimary")?.address ?? null;
+  emit("sdam", { event: "topology-changed", type: e.newDescription.type, primary });
+});
+client.on("serverOpening", (e) => emit("sdam", { event: "server-opening", address: e.address }));
+client.on("serverClosed", (e) => emit("sdam", { event: "server-closed", address: e.address }));
+for (const [event, name] of [
+  ["connectionPoolCreated", "pool-created"],
+  ["connectionPoolReady", "pool-ready"],
+  ["connectionPoolClosed", "pool-closed"],
+  ["connectionCreated", "created"],
+  ["connectionReady", "connection-ready"],
+  ["connectionCheckOutStarted", "checkout-started"],
+  ["connectionCheckedOut", "checked-out"],
+  ["connectionCheckedIn", "checked-in"],
+]) {
+  client.on(event, (e) => emit("cmap", { event: name, address: e.address, connectionId: e.connectionId ?? null }));
+}
+client.on("connectionPoolCleared", (e) => emit("cmap", { event: "pool-cleared", address: e.address, interruptInUseConnections: e.interruptInUseConnections ?? false }));
+client.on("connectionClosed", (e) => emit("cmap", { event: "closed", address: e.address, connectionId: e.connectionId, reason: e.reason, failure: failure(e.error) }));
+client.on("connectionCheckOutFailed", (e) => emit("cmap", { event: "checkout-failed", address: e.address, reason: e.reason, failure: failure(e.error) }));
+
+/** This function gives the sequence number of an operation from its comment. */
+const numberOf = (command) => {
+  const match = /^[wr]:(\d+)$/.exec(String(command?.comment ?? ""));
+  return match === null ? null : Number(match[1]);
+};
+const started = new Map();
+/** This map holds the server of the last try of each operation that succeeded, by its sequence number. */
+const lastServer = new Map();
+client.on("commandStarted", (e) => {
+  const n = numberOf(e.command);
+  if (n === null) return;
+  started.set(e.requestId, n);
+  emit("command", { event: "started", name: e.commandName, n, address: e.address, connectionId: e.connectionId, requestId: e.requestId });
+});
+client.on("commandSucceeded", (e) => {
+  if (!started.has(e.requestId)) return;
+  const n = started.get(e.requestId);
+  started.delete(e.requestId);
+  lastServer.set(n, e.address);
+  emit("command", { event: "succeeded", name: e.commandName, n, address: e.address, requestId: e.requestId, duration: e.duration });
+});
+client.on("commandFailed", (e) => {
+  if (!started.has(e.requestId)) return;
+  const n = started.get(e.requestId);
+  started.delete(e.requestId);
+  emit("command", { event: "failed", name: e.commandName, n, address: e.address, requestId: e.requestId, duration: e.duration, failure: failure(e.failure) });
+});
+
+// ---- the end of the client
+let stopped = false;
+const stop = (code = 0) => {
+  if (stopped) return;
+  stopped = true;
+  emit("done");
+  client.close().finally(() => setTimeout(() => process.exit(code), 50));
+};
+process.on("SIGTERM", () => stop(0));
+setTimeout(() => {
+  emit("deadline");
+  stop(0);
+}, max);
+
+const collection = client.db("cells").collection("w");
+// the writes of one client: each run starts its numbers at 1, and the field `run` keeps them apart
+const run = randomUUID();
+
+/**
+ * This function sends operation n: a write of its sequence number, or the read of the long
+ * document. Its stamp is before the call. It gives null for a reply, or the error.
+ */
+const operate = async (n) => {
+  const at = now();
+  const kind = op === "read-long" && mode === "inflight" && n > 1 ? "read" : "write";
+  const reply = kind === "read" ? collection.findOne({ _id: "long" }, { comment: `r:${n}` }) : collection.insertOne({ n, run }, { comment: `w:${n}` });
+  emit("sent", { n, kind }, at);
+  try {
+    const answer = await reply;
+    emit("ack", { n, kind, at: lastServer.get(n) ?? null, bytes: kind === "read" ? JSON.stringify(answer ?? {}).length : 0 });
+    return null;
+  } catch (error) {
+    emit("fail", { n, kind, ...failure(error) });
+    return error;
+  }
+};
+
+emit("connecting", { hosts });
+try {
+  await client.connect();
+} catch (error) {
+  emit("fail", { why: "connect", ...failure(error) });
+  emit("error", { errno: error.name, message: error.message });
+  stop(before ? 0 : 1);
+}
+if (stopped) await new Promise(() => undefined);
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+if (mode === "stream") {
+  emit("ready", { at: first });
+  for (let n = 1; !stopped; n += 1) {
+    await operate(n);
+    await sleep(interval);
+  }
+} else {
+  // the first write makes the connection of the pool. Its reply is the last data before the fault
+  const failed = await operate(1);
+  if (failed !== null) {
+    emit("error", { errno: failed.name, message: failed.message });
+    stop(1);
+  } else {
+    // the monitor sends its first awaited hello minHeartbeatFrequencyMS after its first check. A
+    // fault before that hello meets the start of the stream, not the stream that a cell measures
+    const awaited = await Promise.race([streaming.then(() => true), sleep(5000).then(() => false)]);
+    emit("ready", { reply: "ack", streaming: awaited });
+    if (mode === "inflight") {
+      await new Promise((resolve) => {
+        const wait = setInterval(() => {
+          if (!existsSync(go)) return;
+          clearInterval(wait);
+          resolve();
+        }, 2);
+      });
+      const error = await operate(2);
+      if (error === null) emit("data", { n: 1 });
+      else emit("error", { errno: error.name, message: error.message });
+    }
+  }
+}