@mark1russell7/harness 0.12.4 → 0.13.0

package/build/schema.d.ts

@@ -1,4 +1,4 @@
-import { $ as Subject, S as ImageSource, i as ClientImage, r as Client } from "./cell-jEkGFgGL.js";
+import { S as ImageSource, et as Subject, i as ClientImage, r as Client } from "./cell-D2QNOxE8.js";
 import { z } from "zod";
 //#region src/schema.d.ts
 /**

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

@@ -8,7 +8,7 @@
 //! 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.
+//! Each mode sends one request and reads 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
@@ -29,7 +29,7 @@ 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
+/// a Redis inline command. Any line-based server echoes it or gives an error, and that is a reply too
 const REQUEST: &[u8] = b"PING\r\n";
 
 fn emit(event: &str, fields: Value) {
@@ -45,7 +45,7 @@ fn emit_at(event: &str, t: u64, fields: Value) {
 }
 
 /// 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.
+/// request before write() returns, and a stamp after it comes later than the reset's own.
 fn send(stream: &mut TcpStream, request: &[u8]) -> std::io::Result<()> {
     let t = monotonic_ns();
     stream.write_all(request)?;
@@ -211,15 +211,14 @@ fn run() -> Result<(), Box<dyn Error>> {
     );
 
     // 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
+    // read that waits takes the socket's lock each time it wakes. A keepalive timer that finds the
+    // socket held puts itself off by HZ/20. Thus such a read moves the timer that the client 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
+    // stream mode: requests sent, whether one waits for its reply, and when the next can go
     let mut sent: u32 = 0;
     let mut awaiting = false;
     let mut reply = Reply::default();
@@ -240,7 +239,7 @@ fn run() -> Result<(), Box<dyn Error>> {
                         next_at = monotonic_ns() + args.interval.as_nanos() as u64;
                     }
                 }
-                // nothing after all; ETIMEDOUT is the connection's own end
+                // 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);

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

@@ -1,9 +1,10 @@
 //! 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.
+//! This sidecar applies the fault of a cell. It applies the fault inside the network namespace
+//! that it shares with the target (or, for the side of the server, with the client). Thus the
+//! image of the target stays stock. Each fault lands in one commit, between two CLOCK_MONOTONIC
+//! stamps that the sidecar takes in the VM. A docker exec from Windows lands 190 ms late at the
+//! median, and this delay has no effect on the two stamps.
 //!
 //! The actions, each with its lift:
 //!
@@ -29,8 +30,8 @@
 //!
 //! - `signal NAME SIGNAL`: SIGNAL (KILL, STOP, CONT, TERM or HUP) to each process whose name is
 //!   NAME, in the process namespace this sidecar shares with a member of a group or a hop. STOP and
-//!   CONT freeze a server and thaw it while its kernel stays up; KILL stops it, and its kernel
-//!   closes its sockets; HUP asks a pooler to read its configuration again. The stamps bracket the
+//!   CONT freeze a server and thaw it while its kernel stays up. KILL stops it, and its kernel
+//!   closes its sockets. HUP asks a pooler to read its configuration again. The stamps bracket the
 //!   kill(2) calls.
 //! - `write NAME PATH CONTENT`: CONTENT to the file PATH in the root of the process NAME, through
 //!   /proc/PID/root, by a rename in one step. A proxy that watches its configuration file reloads
@@ -119,7 +120,7 @@ fn options(args: &[String]) -> Result<Options, Box<dyn Error>> {
 fn rules(action: &str, peer: Ipv4Addr, opts: &Options) -> Result<String, Box<dyn Error>> {
     let op = |set: &str| if action == set { "-I" } else { "-D" };
     // what comes from the peer, and what goes to it: at an end, the INPUT and OUTPUT of its own
-    // sockets; at a router, what it forwards in and out of the device toward the peer
+    // sockets. At a router, what it forwards in and out of the device toward the peer
     let (from, to) = match opts.via.as_deref() {
         None => (format!("INPUT -s {peer}/32"), format!("OUTPUT -d {peer}/32")),
         Some(dev) => (format!("FORWARD -i {dev} -s {peer}/32"), format!("FORWARD -o {dev} -d {peer}/32")),
@@ -152,8 +153,8 @@ fn rules(action: &str, peer: Ipv4Addr, opts: &Options) -> Result<String, Box<dyn
             };
             format!("{op} {from} -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
+        // the long segments drop where they arrive. In the namespace of the sender, an OUTPUT drop
+        // fails its sends with EPERM, and it does not lose them on the way
         "mtu" | "clear-mtu" => {
             let op = op("mtu");
             let above = opts.above.ok_or("--above N")?;
@@ -291,7 +292,7 @@ fn processes(name: &str) -> Result<Vec<libc::pid_t>, Box<dyn Error>> {
             continue;
         };
         // a process can end between the listing and the read. A zombie keeps its name until its
-        // parent reaps it: a server that a fin killed is one, and no signal reaches it
+        // parent reaps it: a server that a fin stopped is one, and no signal reaches it
         let Ok(comm) = std::fs::read_to_string(entry.path().join("comm")) else { continue };
         let Ok(stat) = std::fs::read_to_string(entry.path().join("stat")) else { continue };
         if comm.trim_end() == name && !zombie(&stat) {

package/image/node/client-ioredis.mjs

@@ -7,8 +7,8 @@
 // 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
+// Node fixes the probe interval and count. It sets no other timer that the kernel sees. Each mode
+// sends a PING and reads 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.
 
@@ -40,7 +40,7 @@ emit("start", {
   client: "ioredis",
 });
 
-// one connection, whose end is what is measured: ioredis would reconnect, so the client ends first
+// one connection, whose end is what is measured: ioredis reconnects by itself, thus 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 }));
@@ -69,7 +69,7 @@ setTimeout(() => {
   end();
 }, max);
 
-/** a PING, stamped before it is written: the kernel can answer before the call returns */
+/** This function sends a PING. It stamps the PING before the write, because the kernel can answer before the call ends. */
 const ping = () => {
   const at = now();
   const reply = redis.ping();

package/image/node/client-sentinel.mjs

@@ -49,7 +49,7 @@ emit("start", {
 });
 
 const redis = new Redis({ ...options, sentinels, name, lazyConnect: true });
-/** the server that the connection is on now, or null between connections */
+/** This function gives the server that the connection is on at this time, or null between connections. */
 const remote = () => {
   const stream = redis.stream;
   return stream?.remoteAddress === undefined ? null : `${stream.remoteAddress}:${stream.remotePort}`;

package/image/node-http/lines.mjs

@@ -6,10 +6,10 @@
 
 import { existsSync, readFileSync } from "node:fs";
 
-/** This function gives the time now, in nanoseconds on CLOCK_MONOTONIC. */
+/** This function gives the current time, in nanoseconds on CLOCK_MONOTONIC. */
 export const now = () => process.hrtime.bigint();
 
-/** This function writes one line, with the time `at` (the time now when none is given). */
+/** This function writes one line, with the time `at` (the current time when none is given). */
 export const emit = (ev, fields = {}, at = now()) =>
   process.stdout.write(`${JSON.stringify({ ev, t: Number(at), ...fields })}\n`);
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@mark1russell7/harness",
-  "version": "0.12.4",
+  "version": "0.13.0",
   "description": "A fault-injection harness for connection timers: a cell runs a client against a stock target in Docker, through a topology of routers and proxies, a replicated group under Sentinels or a replica set, injects a fault, measures the kernel's own records and judges a prediction. HTTP clients of Go, Node and undici race the keep-alive of a Node server, and the MongoDB driver meets the faults of a replica set. The WebSocket client of @procedures/client drops a silent connection on its own heartbeat, and the harness times that detection and the reconnect from the program's lines and the kernel's stamps.",
   "keywords": [
     "fault-injection",