@mark1russell7/kind 0.11.6 → 0.11.7

package/image/agent.mjs

@@ -1,4 +1,4 @@
-// The agent of a kind node. It runs in a privileged container in the PID namespace of the node
+// The agent of a kind node. It operates in a privileged container in the PID namespace of the node
 // container, thus it sees the processes of each pod of the node, and PID 1 is the init of the node.
 //
 //   node agent.mjs serve       polls the rules of kube-proxy in the namespaces of the node, as
@@ -37,7 +37,7 @@ const node = process.env.NODE_NAME ?? "";
 const say = (line) => process.stdout.write(`${JSON.stringify({ ...line, node })}\n`);
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
-/** the backends of a Service in each mode of kube-proxy, as "ip:port" (with the weight for IPVS) */
+/** These commands give the backends of a Service in each mode of kube-proxy, as "ip:port" (with the weight for IPVS). */
 const DUMP = {
   iptables: ["nsenter", "-t", "1", "-m", "-n", "--", "iptables-save", "-t", "nat"],
   nftables: ["nsenter", "-t", "1", "-m", "-n", "--", "nft", "list", "table", "ip", "kube-proxy"],
@@ -45,15 +45,15 @@ const DUMP = {
 };
 
 /**
- * the TCP lines of the conntrack table of the node's network namespace: those of the ClusterIP and
- * those of a handshake. A kernel without CONFIG_NF_CONNTRACK_PROCFS has no /proc/net/nf_conntrack
- * (the kernel of GitHub's runner, 6.17), thus the agent then asks netlink with the conntrack tool of
+ * This function reads the TCP lines of the conntrack table in the node's network namespace: those
+ * of the ClusterIP and those of a handshake. A kernel without CONFIG_NF_CONNTRACK_PROCFS has no
+ * /proc/net/nf_conntrack (the kernel of GitHub's runner, 6.17), thus the agent then asks netlink with the conntrack tool of
  * the node. Both give the same form of line. The first read decides the source. `text` is null when
  * no source answers, and `why` tells why.
  *
  * A dump through netlink walks each bucket of the table of the whole kernel with the softirqs off,
  * whatever its filter. A segment that comes in that walk waits for its end. Thus each read is one
- * dump of TCP, and the agent filters it. The workflow makes the table small (kind.yml)
+ * dump of TCP, and the agent filters it. The workflow makes the table small (kind.yml).
  */
 const SOURCES = {
   procfs: (ip) => [["nsenter", "-t", "1", "-n", "--", "grep", "-F", "-e", ` dst=${ip} `, "-e", "[UNREPLIED]", "-e", " SYN_RECV ", "/proc/net/nf_conntrack"]],
@@ -67,7 +67,7 @@ const conntrackOf = (ip) => {
     let ok = true;
     for (const [command, ...args] of SOURCES[name](ip)) {
       const run = spawnSync(command, args, { encoding: "utf8", maxBuffer: 64 << 20 });
-      // grep exits 1 when no line matches; conntrack exits 0 with no entry
+      // grep exits 1 when no line matches, and conntrack exits 0 with no entry
       if (run.status === 0 || (name === "procfs" && run.status === 1)) {
         for (const line of (run.stdout ?? "").split("\n")) if (line.trim() !== "") lines.add(line);
       } else {
@@ -83,7 +83,7 @@ const conntrackOf = (ip) => {
   }
   return { text: null, why: why.join("; ") };
 };
-/** the PIDs of the clients of the node: the agent is in the PID namespace of the node, thus /proc holds each pod */
+/** This function gives the PIDs of the clients of the node. The agent is in the PID namespace of the node, thus /proc holds each pod. */
 const clientsOf = () => {
   const out = [];
   for (const name of readdirSync("/proc")) {
@@ -98,10 +98,11 @@ const clientsOf = () => {
 };
 
 /**
- * the counters of dropped packets, by name. For the node: the drops of the backlogs and the squeezes
- * of the softirqs (the kernel, all CPUs), and the drops of each veth. For each client pod, through
- * /proc/<pid>/net: the IP discards and the sends with no route, the failed connects, the ICMP
- * errors of an unreachable destination, the drops of each interface, and the neighbors with no address yet
+ * This function gives the counters of dropped packets, by name. For the node, it gives the drops of
+ * the backlogs and the squeezes of the softirqs (the kernel, all CPUs), and the drops of each veth.
+ * For each client pod, it reads /proc/<pid>/net. There it gives the IP discards and the sends with
+ * no route, and the failed connects. It also gives the ICMP errors of an unreachable destination,
+ * the drops of each interface, and the neighbors with no address yet.
  */
 const countersOf = () => {
   const values = {};
@@ -136,7 +137,7 @@ const countersOf = () => {
     values[`client.${pid}.ip-out-discards`] = ip["OutDiscards"] ?? 0;
     values[`client.${pid}.ip-out-no-routes`] = ip["OutNoRoutes"] ?? 0;
     values[`client.${pid}.tcp-attempt-fails`] = tcp["AttemptFails"] ?? 0;
-    // a refused connect is a reset, or an ICMP error such as the port unreachable of a reject rule
+    // a refused connect is a reset, or an ICMP error, for example the port unreachable of a reject rule
     values[`client.${pid}.icmp-in-unreachable`] = snmpOf(snmp, "Icmp")["InDestUnreachs"] ?? 0;
     for (const [name, drops] of Object.entries(devOf(own))) {
       if (name === "lo") continue;
@@ -149,9 +150,9 @@ const countersOf = () => {
 };
 
 /**
- * how often the agent reads the conntrack table, in ms. Three dumps each 250 ms on each node took
- * three quarters of the CPUs of a runner (run 39066066532), and the lab waited for an idle VM until
- * the end. An entry of a SYN with no reply lives 120 s, thus a read each second sees it
+ * This value tells how often the agent reads the conntrack table, in ms. Three dumps each 250 ms on
+ * each node took three quarters of the CPUs of a runner (CI 39066066532). Then the lab waited for an
+ * idle VM until the end. An entry of a SYN with no reply lives 120 s, thus a read each second sees it.
  */
 const CONNTRACK_EVERY = 1000;
 
@@ -266,12 +267,14 @@ const serve = async () => {
 };
 
 /**
- * the pollers of the sidecars of the node, of one kind: `eds` or `lds`. /tmp/<kind>.json gives the
- * interval and each pod of the node with a PID in it, and for `eds` the server cluster. The agent
- * starts one poller for each pod in the network namespace of that PID, and stops each one when the
- * file changes or goes. nsenter -n keeps the mount namespace of the agent, thus the poller is this
- * file, and its clock is the one of the VM. The EDS pollers read the client pods, and the LDS
- * pollers read the server pods
+ * This function controls the pollers of the sidecars of the node, of one kind: `eds` or `lds`.
+ * The file /tmp/<kind>.json gives the interval and each pod of the node with a PID in it. For
+ * `eds`, it also gives the server cluster. The agent starts one poller for each pod in the network
+ * namespace of that PID. It stops each poller when the file changes or goes.
+ *
+ * The command nsenter -n keeps the mount namespace of the agent. Thus the poller is this file, and
+ * its clock is the one of the VM. The EDS pollers read the client pods, and the LDS pollers read the
+ * server pods.
  */
 const pollers = async (kind) => {
   const file = `/tmp/${kind}.json`;
@@ -312,10 +315,10 @@ const pollers = async (kind) => {
 };
 
 /**
- * one poll loop of the admin endpoint of a sidecar, 127.0.0.1:15000 in the namespace of the pod
- * (envoy_bootstrap.json of Istio 1.31.3), each `every` ms. `read` gives the state of one answer, and
- * a line comes at each change of that state, with the start of the poll before it (`prev`), as a rules
- * line. Each second, a line `<kind>-alive` counts the polls
+ * This function is one poll loop of the admin endpoint of a sidecar, each `every` ms. The endpoint
+ * is 127.0.0.1:15000 in the namespace of the pod (envoy_bootstrap.json of Istio 1.31.3). `read`
+ * gives the state of one answer. A line comes at each change of that state, with the start of the
+ * poll before it (`prev`), as a rules line. Each second, a line `<kind>-alive` counts the polls.
  */
 const poll = async (kind, url, every, pod, read) => {
   let last = null;
@@ -359,8 +362,9 @@ const poll = async (kind, url, every, pod, read) => {
 };
 
 /**
- * one EDS poller. The filter of /clusters keeps the server cluster only (clusters_handler.cc of Envoy
- * v1.39.4). A line `eds` gives the healthy hosts (`b`), and each other host with its flags (`u`)
+ * This function is one EDS poller. The filter of /clusters keeps the server cluster only
+ * (clusters_handler.cc of Envoy v1.39.4). A line `eds` gives the healthy hosts (`b`), and each
+ * other host with its flags (`u`).
  */
 const eds = ({ cluster, every, pod }) =>
   poll("eds", `http://127.0.0.1:15000/clusters?filter=${encodeURIComponent(clusterFilter(cluster))}`, every, pod, (text) => {
@@ -369,8 +373,9 @@ const eds = ({ cluster, every, pod }) =>
   });
 
 /**
- * one LDS poller, in a server pod. The filter of /stats keeps the two counters of the listener
- * manager. A line `lds` gives each update of a listener (`mod`) and each update in place (`inPlace`)
+ * This function is one LDS poller, in a server pod. The filter of /stats keeps the two counters of
+ * the listener manager. A line `lds` gives each update of a listener (`mod`) and each update in
+ * place (`inPlace`).
  */
 const lds = ({ every, pod }) =>
   poll("lds", `http://127.0.0.1:15000/stats?filter=${encodeURIComponent(LDS_FILTER)}`, every, pod, (text) => {

package/image/client.mjs

@@ -6,6 +6,7 @@
 // unreachable, or another error) and its local port (`lp`). With PROTOCOL h2c, each connection is a
 // session of HTTP/2, and each request is a stream on the next session in turn. With SESSION_CHECK,
 // each session has the session check of the service: a stream timeout or a PING with no ACK closes it.
+// Each second, one line counts the PINGs of the checks and their ACKs (`pings`).
 import http from "node:http";
 import http2 from "node:http2";
 import net from "node:net";
@@ -32,7 +33,8 @@ let turn = 0;
 // each slot of HTTP/2 holds one session on its own socket, thus the client knows its local port. A
 // GOAWAY, a close or an error of the session makes the slot open a new session at its next stream.
 // kube-proxy picks a backend for that new connection. The old session ends the streams that it has.
-// The check of a session hears each frame of the peer: its SETTINGS, its PINGs, and each response
+// The check of a session hears each frame of the peer: its SETTINGS, its PINGs, and each response.
+// It sends each PING through `counted`, thus the client counts each PING and each ACK
 const sessionOf = () => {
   const socket = net.connect({ host, port: Number(port) });
   const session = http2.connect(`http://${host}:${port}`, { createConnection: () => socket });
@@ -42,7 +44,23 @@ const sessionOf = () => {
     held.check?.stop();
   };
   if (checkKnobs !== null) {
-    held.check = sessionCheck(session, {
+    const counted = {
+      get connecting() {
+        return session.connecting;
+      },
+      ping(callback) {
+        const sent = session.ping((error) => {
+          if (error === null) pings.acked += 1;
+          callback(error);
+        });
+        if (sent) pings.sent += 1;
+        return sent;
+      },
+      destroy(error) {
+        session.destroy(error);
+      },
+    };
+    held.check = sessionCheck(counted, {
       knobs: checkKnobs,
       onClose: (cause) => {
         held.usable = false;
@@ -77,6 +95,15 @@ process.on("SIGHUP", () => {
   }, timeout + 100);
 });
 
+// the PINGs of the session checks of this client. Each second, one line gives the PINGs that the client
+// sent and the ACKs that it got in that second. A client with no check writes zeros, thus each record
+// shows that the client counted
+let pings = { sent: 0, acked: 0 };
+setInterval(() => {
+  say({ ev: "pings", t: now(), sent: pings.sent, acked: pings.acked });
+  pings = { sent: 0, acked: 0 };
+}, 1000);
+
 let pending = [];
 const flush = () => {
   if (pending.length === 0) return;

package/image/watch.mjs

@@ -1,11 +1,11 @@
-// The watcher of a kind cell. It runs in a container on the Docker network of the cluster, thus in
+// The watcher of a kind cell. It operates in a container on the Docker network of the cluster, thus in
 // the VM, and it stamps each event on CLOCK_MONOTONIC when it arrives. It watches the pods, the
 // EndpointSlices and the events of one namespace through the API, and it follows the log of each
 // pod with the label lab.systems/log=1. A log line is JSON with its own stamp, and the watcher
 // passes it on as it is.
 //
 // The sidecar of Istio (the container istio-proxy) is a native sidecar: an init container that
-// runs beside the app. The watcher follows it too. Its lines are the access log of Envoy (JSON, a
+// operates beside the app. The watcher follows it too. Its lines are the access log of Envoy (JSON, a
 // stamp of the wall clock) and the text of pilot-agent. Each one becomes a line `proxy` with the
 // stamp of its arrival: evidence, not a time that a band reads. An access line of a call that
 // succeeded at its first attempt is only counted (`proxy-ok`, each second), thus the record keeps
@@ -43,10 +43,10 @@ const say = (line) => pending.push(`${JSON.stringify(line)}\n`);
  * opens again with no resource version, and the API gives each object again as ADDED.
  */
 const GONE = Symbol("gone");
-/** the result of a handler for an ERROR event: GONE for an expired resource version, else null */
+/** This function gives the result of a handler for an ERROR event: GONE for an expired resource version, else null. */
 const errorOf = (status) => (status?.code === 410 ? GONE : null);
 
-/** a stream of lines from the API, again after each end, from the last resource version it saw */
+/** This function opens a stream of lines from the API. After each end, it opens it again from the last resource version that it saw. */
 const stream = (path, query, onLine, again = true) => {
   let version = null;
   const open = () => {
@@ -104,9 +104,9 @@ const stateOf = (state) => {
   return "none";
 };
 
-/** the container of the sidecar of Istio */
+/** This is the container of the sidecar of Istio. */
 const PROXY = "istio-proxy";
-/** the access lines of each sidecar that the watcher only counted, by pod, since the last count */
+/** This map holds the access lines of each sidecar that the watcher only counted, by pod, since the last count. */
 const counted = new Map();
 setInterval(() => {
   const t = now();
@@ -114,11 +114,11 @@ setInterval(() => {
   counted.clear();
 }, 1000);
 
-/** an access line of Envoy that tells nothing more than its call: status 200, no flag, gRPC status 0, one attempt */
+/** This function tells if an access line of Envoy tells nothing more than its call: status 200, no flag, gRPC status 0, one try. */
 const plain = (log) =>
   String(log.code) === "200" && (log.flags === "-" || log.flags === "" || log.flags === undefined) && String(log.grpc) === "0" && Number(log.attempts ?? 1) <= 1;
 
-/** a line of the sidecar: an access line of Envoy as JSON, or a text line of pilot-agent */
+/** This function takes a line of the sidecar: an access line of Envoy as JSON, or a text line of pilot-agent. */
 const proxyLine = (pod, text) => {
   if (text.startsWith("{")) {
     try {
@@ -136,7 +136,7 @@ const proxyLine = (pod, text) => {
   say({ ev: "proxy", t: now(), p: pod, text: text.slice(0, 500) });
 };
 
-/** the namespace of the mesh, with the ztunnel pods */
+/** This is the namespace of the mesh, with the ztunnel pods. */
 const MESH_NS = "istio-system";
 
 const following = new Set();
@@ -146,7 +146,7 @@ const follow = (ns, pod, container, id) => {
   following.add(key);
   stream(
     `/api/v1/namespaces/${ns}/pods/${pod}/log`,
-    // a ztunnel ran before the cell: only its lines from the start of the watcher
+    // a ztunnel started before the cell: only its lines from the start of the watcher
     ns === MESH_NS ? { container, follow: "true", sinceSeconds: "5" } : { container, follow: "true" },
     (text) => {
       if (ns === MESH_NS) say({ ev: "ztunnel", t: now(), p: pod, text: text.slice(0, 500) });
@@ -176,7 +176,7 @@ for (const ns of namespaces) {
       last: stateOf(status.lastState),
       id: status.containerID ?? null,
     }));
-    // the native sidecar of Istio is a running init container: its state, apart from the containers
+    // the native sidecar of Istio is an init container that operates: its state, apart from the containers
     const sidecars = (pod.status?.initContainerStatuses ?? [])
       .filter((status) => status.name === PROXY)
       .map((status) => ({ n: status.name, r: status.ready, rc: status.restartCount, st: stateOf(status.state), id: status.containerID ?? null }));

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@mark1russell7/kind",
-  "version": "0.11.6",
+  "version": "0.11.7",
   "description": "Kubernetes in Docker as a lab for connection timers: a kind cluster from a scenario, faults in the namespaces of its pods, observations on the one monotonic clock of the VM, and predictions from the ordering law. Its judge entry reads and judges a raw record without Docker.",
   "keywords": [
     "kubernetes",