@mark1russell7/harness 0.0.0-stage → 0.2.0

package/image/native/src/bin/client.rs

@@ -0,0 +1,263 @@
+//! client HOST PORT --mode idle|inflight|stream [--keepalive] [--user-timeout-ms N] [--go PATH]
+//!        [--request TEXT] [--count N] [--interval-ms N] [--sample-ms N] [--max-s N]
+//!
+//! A cell's TCP client: one connection, every event a JSON line stamped on CLOCK_MONOTONIC. It
+//! sets no per-socket TCP timer unless the cell asks, so the namespace's sysctls are what gets
+//! measured: Rust's std::net turns nothing on by itself. While it waits, it samples the kernel's
+//! view of its own socket (TCP_INFO) every --sample-ms and logs each change, a second vantage
+//! beside the prober's records. It waits in poll(), never holding its socket's lock, so it never
+//! puts off the socket's own keepalive timer.
+//!
+//! Both modes send one request and read its reply first; that reply is the last segment received.
+//! idle: then hold the connection idle until it fails.
+//! inflight: then wait for the file --go to appear, send the request again, and wait. --request
+//! names that second request, a Redis inline command: PING unless it says otherwise. BLPOP with a
+//! timeout makes the server answer only when the timeout runs out, so its reply can be the one in
+//! flight when a fault lands.
+//! stream: then wait for --go, and send the request --count times, each when the reply to the one
+//! before it has come and --interval-ms has passed: a distribution of reply times, for a fault
+//! whose outcome is one (loss, reordering). It ends with a done line.
+
+use prober::{errno_name, monotonic_ns, quantity};
+use serde_json::{json, Value};
+use std::error::Error;
+use std::io::{ErrorKind, Read, Write};
+use std::net::TcpStream;
+use std::os::fd::AsRawFd;
+use std::path::Path;
+use std::time::Duration;
+
+/// a Redis inline command; any line-based server echoes or errors on it, which is a reply too
+const REQUEST: &[u8] = b"PING\r\n";
+
+fn emit(event: &str, fields: Value) {
+    emit_at(event, monotonic_ns(), fields);
+}
+
+fn emit_at(event: &str, t: u64, fields: Value) {
+    let mut line = json!({ "ev": event, "t": t });
+    if let (Some(line), Value::Object(fields)) = (line.as_object_mut(), fields) {
+        line.extend(fields);
+    }
+    println!("{line}");
+}
+
+/// Sends the request, stamped before the write: on a bridge, the kernel can take a reset to the
+/// request before write() returns, and a stamp after it would come later than the reset's own.
+fn send(stream: &mut TcpStream, request: &[u8]) -> std::io::Result<()> {
+    let t = monotonic_ns();
+    stream.write_all(request)?;
+    emit_at("sent", t, json!({}));
+    Ok(())
+}
+
+fn set_int(fd: i32, level: i32, name: i32, value: i32) -> std::io::Result<()> {
+    // SAFETY: the option value is an int on this stack, passed with its exact size
+    let status = unsafe {
+        libc::setsockopt(
+            fd,
+            level,
+            name,
+            (&value as *const i32).cast(),
+            std::mem::size_of::<i32>() as libc::socklen_t,
+        )
+    };
+    if status == 0 { Ok(()) } else { Err(std::io::Error::last_os_error()) }
+}
+
+fn tcp_info(fd: i32) -> std::io::Result<libc::tcp_info> {
+    // SAFETY: tcp_info is plain old data, and the kernel writes at most the length it is given
+    let mut info: libc::tcp_info = unsafe { std::mem::zeroed() };
+    let mut len = std::mem::size_of::<libc::tcp_info>() as libc::socklen_t;
+    let status = unsafe {
+        libc::getsockopt(fd, libc::IPPROTO_TCP, libc::TCP_INFO, (&mut info as *mut libc::tcp_info).cast(), &mut len)
+    };
+    if status == 0 { Ok(info) } else { Err(std::io::Error::last_os_error()) }
+}
+
+/// Whether the socket has something to read, an error or an end, within `ms`: poll() asks the
+/// socket without taking its lock.
+fn readable(fd: i32, ms: i32) -> std::io::Result<bool> {
+    let mut wanted = libc::pollfd { fd, events: libc::POLLIN | libc::POLLRDHUP, revents: 0 };
+    // SAFETY: one pollfd on this stack, and its count
+    match unsafe { libc::poll(&mut wanted, 1, ms) } {
+        -1 if std::io::Error::last_os_error().kind() == ErrorKind::Interrupted => Ok(false),
+        -1 => Err(std::io::Error::last_os_error()),
+        _ => Ok(wanted.revents != 0),
+    }
+}
+
+/// what in TCP_INFO is worth a line when it changes: the timers' own state, never the ages
+fn watched(info: &libc::tcp_info) -> [u32; 7] {
+    [
+        info.tcpi_state as u32,
+        info.tcpi_retransmits as u32,
+        info.tcpi_probes as u32,
+        info.tcpi_backoff as u32,
+        info.tcpi_rto,
+        info.tcpi_unacked,
+        info.tcpi_total_retrans,
+    ]
+}
+
+struct Args {
+    host: String,
+    port: u16,
+    inflight: bool,
+    /// in stream mode, how many requests, and the pause after each reply
+    stream: Option<u32>,
+    interval: Duration,
+    keepalive: bool,
+    user_timeout_ms: Option<i32>,
+    go: String,
+    sample: Duration,
+    max: Duration,
+    /// the request sent at --go, with its line ending
+    request: Vec<u8>,
+}
+
+fn args() -> Result<Args, Box<dyn Error>> {
+    let raw: Vec<String> = std::env::args().skip(1).collect();
+    let value = |flag: &str| raw.iter().position(|arg| arg == flag).and_then(|at| raw.get(at + 1)).cloned();
+    let mode = value("--mode").ok_or("--mode idle|inflight|stream is required")?;
+    if mode != "idle" && mode != "inflight" && mode != "stream" {
+        return Err(format!("--mode is idle, inflight or stream, not {mode}").into());
+    }
+    let count: u32 = value("--count").map(|v| v.parse()).transpose()?.unwrap_or(100);
+    Ok(Args {
+        host: raw.first().ok_or("the target's host comes first")?.clone(),
+        port: raw.get(1).ok_or("then its port")?.parse()?,
+        inflight: mode != "idle",
+        stream: (mode == "stream").then_some(count),
+        interval: Duration::from_millis(value("--interval-ms").map(|v| v.parse()).transpose()?.unwrap_or(20)),
+        keepalive: raw.iter().any(|arg| arg == "--keepalive"),
+        user_timeout_ms: value("--user-timeout-ms").map(|v| v.parse()).transpose()?,
+        go: value("--go").unwrap_or_else(|| "/tmp/go".into()),
+        sample: Duration::from_micros((value("--sample-ms").map(|v| v.parse::<f64>()).transpose()?.unwrap_or(2.0) * 1000.0) as u64),
+        max: Duration::from_secs_f64(value("--max-s").map(|v| v.parse::<f64>()).transpose()?.unwrap_or(60.0)),
+        request: value("--request").map_or_else(|| REQUEST.to_vec(), |r| format!("{r}\r\n").into_bytes()),
+    })
+}
+
+fn run() -> Result<(), Box<dyn Error>> {
+    let args = args()?;
+    let boot_id = std::fs::read_to_string("/proc/sys/kernel/random/boot_id")?.trim().to_string();
+    let mode = match (args.inflight, args.stream) {
+        (_, Some(_)) => "stream",
+        (true, None) => "inflight",
+        (false, None) => "idle",
+    };
+    emit("start", json!({ "boot_id": boot_id, "mode": mode }));
+    let deadline = monotonic_ns() + args.max.as_nanos() as u64;
+
+    let mut stream = TcpStream::connect((args.host.as_str(), args.port))?;
+    stream.set_nodelay(true)?;
+    let fd = stream.as_raw_fd();
+    if args.keepalive {
+        set_int(fd, libc::SOL_SOCKET, libc::SO_KEEPALIVE, 1)?;
+    }
+    if let Some(ms) = args.user_timeout_ms {
+        set_int(fd, libc::IPPROTO_TCP, libc::TCP_USER_TIMEOUT, ms)?;
+    }
+    emit("connected", json!({ "local": stream.local_addr()?.to_string() }));
+    send(&mut stream, REQUEST)?;
+    let mut buf = [0u8; 65536];
+    let n = stream.read(&mut buf)?;
+    // the last segment received: a keepalive's idle time counts from here
+    let info = tcp_info(fd)?;
+    emit(
+        "ready",
+        json!({
+            "reply": String::from_utf8_lossy(&buf[..n.min(40)]),
+            "rtt": quantity(info.tcpi_rtt, "us"),
+            "rto": quantity(info.tcpi_rto, "us"),
+        }),
+    );
+
+    // the loop waits in poll(), which takes no lock on the socket, and reads only what is there. A
+    // read that waits takes the socket's lock each time it wakes, and a keepalive timer that finds
+    // the socket held puts itself off by HZ/20: the client would move the timer
+    // it measures
+    stream.set_nonblocking(true)?;
+    let tick = args.sample.as_millis().clamp(1, i32::MAX as u128) as i32;
+    let mut waiting = args.inflight;
+    let mut seen: Option<[u32; 7]> = None;
+    let mut age = info.tcpi_last_ack_recv;
+    // stream mode: requests sent, whether one waits for its reply, and when the next may go
+    let mut sent: u32 = 0;
+    let mut awaiting = false;
+    let mut next_at: u64 = 0;
+    loop {
+        if readable(fd, tick)? {
+            match stream.read(&mut buf) {
+                Ok(0) => {
+                    emit("eof", json!({}));
+                    return Ok(());
+                }
+                Ok(n) => {
+                    emit("data", json!({ "n": n, "text": String::from_utf8_lossy(&buf[..n.min(40)]) }));
+                    if awaiting {
+                        awaiting = false;
+                        next_at = monotonic_ns() + args.interval.as_nanos() as u64;
+                    }
+                }
+                // nothing after all; ETIMEDOUT is the connection's own end
+                Err(error) if error.kind() == ErrorKind::WouldBlock || error.kind() == ErrorKind::Interrupted => {}
+                Err(error) => {
+                    let code = error.raw_os_error().unwrap_or(0);
+                    emit("error", json!({ "errno": errno_name(code) }));
+                    return Ok(());
+                }
+            }
+        }
+        let info = tcp_info(fd)?;
+        let now = watched(&info);
+        if seen != Some(now) {
+            emit(
+                "kernel",
+                json!({
+                    "state": now[0], "retransmits": now[1], "probes": now[2], "backoff": now[3],
+                    "rto": quantity(now[4], "us"), "unacked": now[5], "total_retrans": now[6],
+                    "last_ack_recv": quantity(info.tcpi_last_ack_recv, "ms"),
+                    "last_data_recv": quantity(info.tcpi_last_data_recv, "ms"),
+                }),
+            );
+            seen = Some(now);
+        }
+        // an ACK arrived since the last sample: what a frozen process's kernel keeps sending
+        if info.tcpi_last_ack_recv < age {
+            emit("ack", json!({ "last_ack_recv": quantity(info.tcpi_last_ack_recv, "ms") }));
+        }
+        age = info.tcpi_last_ack_recv;
+        if waiting && Path::new(&args.go).exists() {
+            send(&mut stream, &args.request)?;
+            waiting = false;
+            sent = 1;
+            awaiting = args.stream.is_some();
+        }
+        if let Some(count) = args.stream {
+            if !waiting && !awaiting {
+                if sent >= count {
+                    emit("done", json!({ "requests": sent }));
+                    return Ok(());
+                }
+                if monotonic_ns() >= next_at {
+                    send(&mut stream, &args.request)?;
+                    sent += 1;
+                    awaiting = true;
+                }
+            }
+        }
+        if monotonic_ns() > deadline {
+            emit("deadline", json!({}));
+            return Ok(());
+        }
+    }
+}
+
+fn main() {
+    if let Err(error) = run() {
+        emit("fail", json!({ "why": error.to_string() }));
+        std::process::exit(1);
+    }
+}

package/image/native/src/bin/inject.rs

@@ -0,0 +1,268 @@
+//! inject ACTION ARGS... [--at NS]
+//!
+//! A cell's fault, applied inside the network namespace this sidecar shares with the target (or,
+//! for the server's side, with the client), so the target's image stays stock. Each lands in one
+//! commit, bracketed by CLOCK_MONOTONIC stamps taken in the VM: a docker exec from Windows lands
+//! 190 ms late at the median, and the bracket does not care.
+//!
+//! The actions, each with its lift:
+//!
+//! - `blackhole PEER [--direction both|in|out]` / `clear PEER [--direction …]`: the peer's
+//!   segments drop, in both directions or one. `in` drops what comes from the peer, `out` what
+//!   goes to it: a simplex partition.
+//! - `rst PEER` / `clear-rst PEER`: the peer's next segment is answered with a reset, so its next
+//!   send fails at once. A REJECT resets only the sender of the matched segment: the target's
+//!   process never hears of it.
+//! - `reject PEER --code host|net|port|admin` / `clear-reject PEER --code …`: each segment from the
+//!   peer is answered with that ICMP unreachable. On an established socket Linux keeps it as a
+//!   soft error (tcp_v4_err) and goes on retransmitting.
+//! - `mtu PEER --above N` / `clear-mtu PEER --above N`: each segment from the peer longer than N
+//!   bytes drops, as a path MTU black hole does, in the namespace that receives it. It acts on
+//!   segments only when the sender's TSO and GSO and the receiver's GRO are off (`offload`).
+//! - `netem DEV SPEC…` / `clear-netem DEV`: tc netem on the device's egress, for example
+//!   `netem eth0 delay 100ms 10ms` or `netem eth0 loss 5%`.
+//! - `offload DEV on|off`: the device's TSO, GSO and GRO, so that netem and length matches act on
+//!   segments rather than on GSO super-packets of up to 64 KB.
+//!
+//! `--at NS` holds the commit until that instant on CLOCK_MONOTONIC, the clock every stamp is on.
+//! A stall's end is timed that way, from inside the VM: the exec only has to arrive before it, and
+//! its 190 ms never reach the stall's length.
+
+use prober::monotonic_ns;
+use serde_json::json;
+use std::error::Error;
+use std::io::Write;
+use std::net::Ipv4Addr;
+use std::process::{Command, Stdio};
+
+/// sleeps until an instant on CLOCK_MONOTONIC, or returns at once if it has passed
+fn until(at: u64) -> Result<(), Box<dyn Error>> {
+    let deadline = libc::timespec {
+        // the fields' own types: musl is moving time_t to 64 bits
+        tv_sec: (at / 1_000_000_000) as _,
+        tv_nsec: (at % 1_000_000_000) as _,
+    };
+    loop {
+        // SAFETY: a valid timespec, and no remainder is asked for with an absolute time
+        let code = unsafe {
+            libc::clock_nanosleep(
+                libc::CLOCK_MONOTONIC,
+                libc::TIMER_ABSTIME,
+                &deadline,
+                std::ptr::null_mut(),
+            )
+        };
+        match code {
+            0 => return Ok(()),
+            libc::EINTR => continue,
+            other => return Err(format!("clock_nanosleep failed: {other}").into()),
+        }
+    }
+}
+
+/// The options after the positional arguments: `--at NS`, `--direction D`, `--code C`, `--above N`.
+#[derive(Default)]
+struct Options {
+    at: Option<u64>,
+    direction: Option<String>,
+    code: Option<String>,
+    above: Option<u32>,
+}
+
+fn options(args: &[String]) -> Result<Options, Box<dyn Error>> {
+    let mut out = Options::default();
+    let mut rest = args.iter();
+    while let Some(flag) = rest.next() {
+        let value = rest.next().ok_or_else(|| format!("{flag} takes a value"))?;
+        match flag.as_str() {
+            "--at" => out.at = Some(value.parse()?),
+            "--direction" => out.direction = Some(value.clone()),
+            "--code" => out.code = Some(value.clone()),
+            "--above" => out.above = Some(value.parse()?),
+            other => return Err(format!("unknown option {other}").into()),
+        }
+    }
+    Ok(out)
+}
+
+/// The iptables rules of an action that is a filter rule, or None for an action that is not.
+fn rules(action: &str, peer: Ipv4Addr, opts: &Options) -> Result<String, Box<dyn Error>> {
+    let op = |set: &str| if action == set { "-I" } else { "-D" };
+    Ok(match action {
+        "blackhole" | "clear" => {
+            let op = op("blackhole");
+            let direction = opts.direction.as_deref().unwrap_or("both");
+            let input = format!("{op} INPUT -s {peer}/32 -j DROP\n");
+            let output = format!("{op} OUTPUT -d {peer}/32 -j DROP\n");
+            match direction {
+                "both" => format!("{input}{output}"),
+                "in" => input,
+                "out" => output,
+                other => return Err(format!("unknown direction {other}").into()),
+            }
+        }
+        "rst" | "clear-rst" => {
+            let op = op("rst");
+            format!("{op} INPUT -s {peer}/32 -p tcp -j REJECT --reject-with tcp-reset\n")
+        }
+        "reject" | "clear-reject" => {
+            let op = op("reject");
+            let with = match opts.code.as_deref().ok_or("--code host|net|port|admin")? {
+                "host" => "icmp-host-unreachable",
+                "net" => "icmp-net-unreachable",
+                "port" => "icmp-port-unreachable",
+                "admin" => "icmp-admin-prohibited",
+                other => return Err(format!("unknown code {other}").into()),
+            };
+            format!("{op} INPUT -s {peer}/32 -p tcp -j REJECT --reject-with {with}\n")
+        }
+        // the long segments drop where they arrive: in the sender's own namespace, an OUTPUT drop
+        // would fail its sends with EPERM rather than lose them on the way
+        "mtu" | "clear-mtu" => {
+            let op = op("mtu");
+            let above = opts.above.ok_or("--above N")?;
+            format!("{op} INPUT -s {peer}/32 -p tcp -m length --length {}:65535 -j DROP\n", above + 1)
+        }
+        other => return Err(format!("unknown action {other}").into()),
+    })
+}
+
+/// a token of a netem specification: a word, or a number with an optional unit
+fn netem_token(token: &str) -> bool {
+    let word = !token.is_empty() && token.chars().all(|c| c.is_ascii_lowercase());
+    let number = token
+        .trim_end_matches(|c: char| c.is_ascii_alphabetic() || c == '%')
+        .parse::<f64>()
+        .is_ok()
+        && token
+            .trim_start_matches(|c: char| c.is_ascii_digit() || c == '.')
+            .chars()
+            .all(|c| c.is_ascii_alphabetic() || c == '%');
+    word || number
+}
+
+/// a device name: letters, digits, dots, dashes
+fn device(name: &str) -> Result<&str, Box<dyn Error>> {
+    if !name.is_empty() && name.chars().all(|c| c.is_ascii_alphanumeric() || c == '.' || c == '-') {
+        Ok(name)
+    } else {
+        Err(format!("not a device: {name}").into())
+    }
+}
+
+/// runs a command and fails with its stderr when it fails
+fn command(program: &str, args: &[&str]) -> Result<(), Box<dyn Error>> {
+    let out = Command::new(program).args(args).output()?;
+    if !out.status.success() {
+        return Err(format!(
+            "{program} {} exited {}: {}",
+            args.join(" "),
+            out.status,
+            String::from_utf8_lossy(&out.stderr).trim()
+        )
+        .into());
+    }
+    Ok(())
+}
+
+fn run() -> Result<(), Box<dyn Error>> {
+    let args: Vec<String> = std::env::args().skip(1).collect();
+    let action = args.first().ok_or("say an action: blackhole, clear, rst, reject, mtu, netem, offload …")?.as_str();
+    match action {
+        "netem" | "clear-netem" | "offload" => {
+            let dev = device(args.get(1).ok_or("and a device")?)?;
+            let rest: Vec<&str> = args[2..].iter().map(String::as_str).collect();
+            let (spec, at) = match rest.iter().position(|token| *token == "--at") {
+                Some(index) => (
+                    rest[..index].to_vec(),
+                    Some(rest.get(index + 1).ok_or("--at takes an instant in ns")?.parse::<u64>()?),
+                ),
+                None => (rest, None),
+            };
+            if let Some(at) = at {
+                until(at)?;
+            }
+            let t0 = monotonic_ns();
+            match action {
+                "netem" => {
+                    if spec.is_empty() || !spec.iter().all(|token| netem_token(token)) {
+                        return Err(format!("not a netem specification: {}", spec.join(" ")).into());
+                    }
+                    let mut tc = vec!["qdisc", "replace", "dev", dev, "root", "netem"];
+                    tc.extend(spec.iter().copied());
+                    command("tc", &tc)?;
+                }
+                "clear-netem" => command("tc", &["qdisc", "del", "dev", dev, "root"])?,
+                _ => {
+                    let state = match spec.as_slice() {
+                        ["on"] => "on",
+                        ["off"] => "off",
+                        _ => return Err("offload takes on or off".into()),
+                    };
+                    command("ethtool", &["-K", dev, "tso", state, "gso", state, "gro", state])?;
+                }
+            }
+            let t1 = monotonic_ns();
+            println!("{}", json!({ "action": action, "device": dev, "spec": spec, "t0": t0, "t1": t1 }));
+            Ok(())
+        }
+        _ => {
+            // parsed, never pasted: only an address reaches the rules
+            let peer: Ipv4Addr = args.get(1).ok_or("and the peer's address")?.parse()?;
+            let opts = options(&args[2..])?;
+            let script = format!("*filter\n{}COMMIT\n", rules(action, peer, &opts)?);
+            if let Some(at) = opts.at {
+                until(at)?;
+            }
+            let t0 = monotonic_ns();
+            let mut child =
+                Command::new("iptables-restore").arg("--noflush").stdin(Stdio::piped()).spawn()?;
+            child.stdin.take().ok_or("iptables-restore took no stdin")?.write_all(script.as_bytes())?;
+            let status = child.wait()?;
+            let t1 = monotonic_ns();
+            if !status.success() {
+                return Err(format!("iptables-restore exited {status}").into());
+            }
+            println!("{}", json!({ "action": action, "peer": peer.to_string(), "t0": t0, "t1": t1 }));
+            Ok(())
+        }
+    }
+}
+
+fn main() {
+    if let Err(error) = run() {
+        eprintln!("inject: {error}");
+        std::process::exit(1);
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn netem_specifications_are_words_and_numbers_with_units() {
+        for token in ["delay", "100ms", "10ms", "loss", "5%", "25.5%", "distribution", "normal", "1"] {
+            assert!(netem_token(token), "{token}");
+        }
+        for token in ["", ";", "100ms;rm", "$(x)", "-1", "a b"] {
+            assert!(!netem_token(token), "{token}");
+        }
+    }
+
+    #[test]
+    fn rules_cover_each_direction_code_and_length() {
+        let peer: Ipv4Addr = "10.0.0.2".parse().unwrap();
+        let with = |direction: &str| Options { direction: Some(direction.into()), ..Options::default() };
+        assert_eq!(rules("blackhole", peer, &with("in")).unwrap(), "-I INPUT -s 10.0.0.2/32 -j DROP\n");
+        assert_eq!(rules("clear", peer, &with("out")).unwrap(), "-D OUTPUT -d 10.0.0.2/32 -j DROP\n");
+        let code = Options { code: Some("net".into()), ..Options::default() };
+        assert!(rules("reject", peer, &code).unwrap().contains("icmp-net-unreachable"));
+        let above = Options { above: Some(1200), ..Options::default() };
+        assert_eq!(
+            rules("mtu", peer, &above).unwrap(),
+            "-I INPUT -s 10.0.0.2/32 -p tcp -m length --length 1201:65535 -j DROP\n"
+        );
+        assert!(rules("reject", peer, &Options::default()).is_err());
+    }
+}

package/image/node/Dockerfile

@@ -0,0 +1,11 @@
+# The harness's Node client: ioredis 6.0.0 on Node 24.21.0, the releases the corpus's claims about
+# ioredis and Node's keepalive name. 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.
+# lab.ts stages the build context: this folder, under harness/image/node. 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/node
+COPY harness/image/node/package.json ./
+COPY harness/image/node/npm-lock.json ./package-lock.json
+RUN npm ci --omit=dev --ignore-scripts --no-audit --no-fund
+COPY harness/image/node/client-ioredis.mjs ./

package/image/node/client-ioredis.mjs

@@ -0,0 +1,105 @@
+// client-ioredis HOST PORT --mode idle|inflight [--keepalive-ms N] [--go PATH] [--max-s N]
+//
+// A cell's client one layer up: an ioredis 6.0.0 connection, every event a JSON line stamped on
+// CLOCK_MONOTONIC (process.hrtime, which libuv reads from it), the clock the prober stamps the
+// kernel's records with. Its lines are the harness's TCP client's, so the harness reads both the
+// same way (image/native/src/bin/client.rs), with ioredis's own status changes
+// beside them as `status` lines.
+//
+// ioredis sets the socket's keepalive itself, once it connects: setKeepAlive(true, keepAlive), and
+// Node fixes the probe interval and count. It sets no other timer the kernel would see. Both modes
+// send a PING and read its reply first; that reply is the last segment received. idle: then hold
+// the connection until it fails. inflight: then wait for the file --go to appear, send a PING into
+// the fault, and wait.
+
+import { existsSync, readFileSync } from "node:fs";
+import Redis from "ioredis";
+
+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 || (mode !== "idle" && mode !== "inflight")) {
+  emit("fail", { why: "client-ioredis HOST PORT --mode idle|inflight" });
+  process.exit(1);
+}
+const keepAlive = Number(flag("--keepalive-ms") ?? 30000);
+const go = flag("--go") ?? "/tmp/go";
+const max = Number(flag("--max-s") ?? 60) * 1000;
+
+emit("start", {
+  boot_id: readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim(),
+  mode,
+  client: "ioredis",
+});
+
+// one connection, whose end is what is measured: ioredis would reconnect, so the client ends first
+const redis = new Redis({ host, port: Number(port), keepAlive, lazyConnect: true });
+for (const status of ["connect", "ready", "close", "reconnecting", "end"]) {
+  redis.on(status, () => emit("status", { status }));
+}
+
+let ended = false;
+const end = (code = 0) => {
+  if (ended) return;
+  ended = true;
+  // a moment for ioredis's own close to be written after the error that caused it
+  setTimeout(() => {
+    redis.disconnect(false);
+    process.exit(code);
+  }, 50);
+};
+redis.on("error", (error) => {
+  emit("error", { errno: error.code ?? error.errno ?? "unknown", message: error.message });
+  end();
+});
+redis.on("close", () => {
+  if (!ended) emit("eof");
+  end();
+});
+setTimeout(() => {
+  emit("deadline");
+  end();
+}, max);
+
+/** a PING, stamped before it is written: the kernel can answer before the call returns */
+const ping = () => {
+  const at = now();
+  const reply = redis.ping();
+  emit("sent", {}, at);
+  return reply;
+};
+
+redis.once("connect", () => {
+  const { localAddress, localPort } = redis.stream;
+  emit("connected", { local: `${localAddress}:${localPort}` });
+});
+
+try {
+  await redis.connect();
+  const reply = await ping();
+  emit("ready", { reply: `+${reply}\r\n` });
+} catch (error) {
+  // a connection that never became ready: what ended it was written as it happened
+  if (!ended) emit("fail", { why: error.message });
+  end(1);
+}
+
+if (mode === "inflight") {
+  const wait = setInterval(() => {
+    if (!existsSync(go)) return;
+    clearInterval(wait);
+    // into the fault: its reply never comes, or comes once the target thaws
+    ping().then(
+      (late) => emit("data", { n: late.length, text: late }),
+      () => undefined,
+    );
+  }, 2);
+}