@amritk/nish-x86_64-linux 0.18.0 → 0.20.0

package/std/net/prefork.ts

@@ -0,0 +1,412 @@
+/**
+ * `nish/net/prefork` — run a server on every core: a supervisor process that
+ * starts one worker process per core, restarts one that dies, and stops them
+ * all on SIGTERM or SIGINT (`docs/wp42-multicore-server.md` §2.3).
+ *
+ *     import { preforkWorkers } from "nish/net/prefork";
+ *
+ *     export const main = (): number => {
+ *       const worker: i32 = preforkWorkers(process.argv);
+ *       if (worker < 0) { return worker === -1 ? 0 : 1; } // the supervisor, done
+ *       const listener = tcpListenFlags("0.0.0.0", 8080, 1024, 1); // SO_REUSEPORT
+ *       // ... the single-threaded readiness loop, unchanged ...
+ *     };
+ *
+ * **One program, two roles.** `preforkWorkers(process.argv)` answers in two kinds of
+ * process. In a worker it answers the worker's index, `0` to `N - 1`, at once,
+ * and the program goes on to bind its listener and serve. In the process the
+ * user started it supervises, and answers only once every worker has exited:
+ * `-1` after a shutdown, `-2` when the workers could not be started or the
+ * supervisor could not listen for signals. Each worker binds its own listener
+ * with `tcpListenFlags`' flag 1 (`SO_REUSEPORT`), so on Linux the kernel
+ * spreads new connections across them and no state is shared:
+ * a worker is the single-threaded server it was before, `Arena.used()` flat
+ * per worker.
+ *
+ * **How a worker is told.** The supervisor runs the program again with
+ * `--nish-prefork-worker=<index>` appended to its arguments, through `spawn`;
+ * on Linux it runs `/proc/self/exe`, so a program started through `PATH` or a
+ * relative path finds itself. `preforkArgs(process.argv)` answers the
+ * arguments without that flag, for a worker that reads its own; the module
+ * takes `process.argv` from its caller because only a program with a `main`
+ * has one. The environment is inherited whole, and every descriptor the
+ * supervisor holds is close-on-exec, so a worker starts with none of them
+ * (`docs/security/runtime.md`, RT-17, RT-19).
+ *
+ * **How many.** `NISH_WORKERS` when it is a positive whole number, else
+ * `PreforkConfig.workers` when that is positive, else
+ * `availableParallelism()` on Linux and 1 elsewhere: Darwin shares a
+ * `SO_REUSEPORT` port without spreading connections across it. The count has
+ * no upper bound, so `NISH_WORKERS` is the operator's to set, not a client's.
+ *
+ * **Restarts.** A worker that exits, by a signal or with any code, is started
+ * again at the same index while the supervisor is not stopping. One that dies
+ * within `quickExitMs` of starting waits before its restart: `backoffMs` the
+ * first time, twice the last wait after that, up to `backoffCapMs`; one that
+ * ran longer starts again at once and clears its wait, so a crash loop costs a
+ * spawn every `backoffCapMs`, not a core. A restart `spawn` refuses waits on
+ * the same backoff and is tried again; only the first start of a worker that
+ * fails ends the supervisor, with `PREFORK_SPAWN_FAILED`.
+ *
+ * **Shutdown.** The supervisor listens through `signalFd()`, made before the
+ * first spawn so no signal falls between. On SIGTERM or SIGINT it stops
+ * restarting, sends every worker SIGTERM, reaps them for `graceMs`, sends what
+ * is left SIGKILL and reaps that. A second signal during the grace period sends
+ * SIGKILL at once. The workers get the default dispositions back from `exec`,
+ * so a worker that never asked for `signalFd()` ends on the SIGTERM. A
+ * supervisor that dies any other way (SIGKILL, the OOM killer, or the default
+ * action of SIGHUP or SIGQUIT, which `signalFd()` does not catch) leaves its
+ * workers running, reparented to init.
+ *
+ * Private helpers share the importing program's flat symbol namespace
+ * (`docs/wp26-stdlib.md` §3e), which is why each one carries the module's name.
+ */
+import { netClose, pollAdd, pollCreate, pollWait } from "nish:net"
+import {
+  availableParallelism,
+  getenv,
+  kill,
+  monotonicNanos,
+  platform,
+  readSignal,
+  signalFd,
+  spawn,
+  waitPid,
+} from "nish:process"
+
+/** The argument a worker is started with, its index after the `=`. */
+export const PREFORK_WORKER_FLAG: string = "--nish-prefork-worker="
+
+/** What `preforkWith` answers in the supervisor once its workers are gone. */
+export const PREFORK_STOPPED: i32 = -1
+/**
+ * What `preforkWith` answers when a worker could not be started, or when the
+ * supervisor could not listen for SIGTERM and so starts none.
+ */
+export const PREFORK_SPAWN_FAILED: i32 = -2
+
+/** The supervisor's numbers; every one is checked by `preforkWith`. */
+export class PreforkConfig {
+  /** Workers to start; 0 takes `NISH_WORKERS` or the platform's default. */
+  workers: i32 = 0
+  /** How often, in milliseconds, the supervisor reaps when nothing wakes it. */
+  tickMs: i32 = 100
+  /** The first wait before restarting a worker that died young. */
+  backoffMs: i32 = 100
+  /** The longest wait before a restart. */
+  backoffCapMs: i32 = 5000
+  /** A worker that exits within this many milliseconds of starting died young. */
+  quickExitMs: i32 = 1000
+  /** How long the workers get to exit after SIGTERM before SIGKILL. */
+  graceMs: i32 = 5000
+}
+
+/** True when `s` is one or more ASCII digits and nothing else. */
+const preforkDigits = (s: string): boolean => {
+  if (s.length === 0 || s.length > 9) {
+    return false
+  }
+  for (let i: i32 = 0; i < toI32(s.length); i++) {
+    const c: i32 = toI32(s.charCodeAt(i))
+    if (c < 48 || c > 57) {
+      return false
+    }
+  }
+  return true
+}
+
+/**
+ * How many workers to start: `env` (`NISH_WORKERS`, `null` when unset) when it
+ * is a positive whole number, else `requested` when positive, else the
+ * platform's default.
+ */
+export const preforkWorkerCount = (requested: i32, env: string | null): i32 => {
+  if (env !== null && preforkDigits(env)) {
+    const n: i32 = parseInt(env)
+    if (n > 0) {
+      return n
+    }
+  }
+  if (requested > 0) {
+    return requested
+  }
+  if (platform !== "linux") {
+    return 1
+  }
+  const cores: i32 = availableParallelism()
+  return cores > 0 ? cores : 1
+}
+
+/** The worker index `args` carries in its last element, or -1 when none. */
+export const preforkIndex = (args: string[]): i32 => {
+  if (args.length < 2) {
+    return -1
+  }
+  const last: string = args[args.length - 1]
+  if (!last.startsWith(PREFORK_WORKER_FLAG)) {
+    return -1
+  }
+  const digits: string = last.substring(PREFORK_WORKER_FLAG.length)
+  return preforkDigits(digits) ? parseInt(digits) : -1
+}
+
+/** `args` (`process.argv`) without the worker flag, the same in every process. */
+export const preforkArgs = (args: string[]): string[] => {
+  const keep: i32 = preforkIndex(args) >= 0 ? toI32(args.length) - 1 : toI32(args.length)
+  const out: string[] = []
+  for (let i: i32 = 0; i < toI32(args.length); i++) {
+    if (i < keep) {
+      out.push(args[i])
+    }
+  }
+  return out
+}
+
+/** Milliseconds on the monotonic clock. */
+const preforkNowMs = (): i64 => monotonicNanos() / 1000000
+
+/** The signals the supervisor stops its workers with. */
+const PREFORK_SIGTERM: i32 = 15
+const PREFORK_SIGKILL: i32 = 9
+
+/** One worker's slot in the supervisor. */
+class PreforkSlot {
+  /** When the running worker started, or when the waiting one may start. */
+  at: i64 = 0
+  /** The running worker's pid, 0 while it waits to be started again. */
+  pid: i32 = 0
+  /** The wait before the last restart, 0 after a worker that ran long. */
+  delay: i32 = 0
+}
+
+/** The supervisor's state while it runs. */
+class PreforkSupervisor {
+  config: PreforkConfig
+  program: string
+  args: string[]
+  slots: PreforkSlot[]
+  running: i32 = 0
+
+  constructor(config: PreforkConfig, args: string[], count: i32) {
+    this.config = config
+    this.args = preforkArgs(args)
+    const self: string | null = platform === "linux" ? realpathSync("/proc/self/exe") : null
+    this.program = self !== null ? self : this.args[0]
+    this.slots = []
+    for (let i: i32 = 0; i < count; i++) {
+      this.slots.push(new PreforkSlot())
+    }
+  }
+
+  /** Start worker `index`; false when `spawn` refused. */
+  start(index: i32): boolean {
+    const argv: string[] = [this.program]
+    for (let i: i32 = 1; i < toI32(this.args.length); i++) {
+      argv.push(this.args[i])
+    }
+    argv.push(`${PREFORK_WORKER_FLAG}${index}`)
+    const pid: i32 = spawn(argv)
+    if (pid <= 0) {
+      return false
+    }
+    const slot: PreforkSlot = this.slots[index]
+    slot.pid = pid
+    slot.at = preforkNowMs()
+    this.running = this.running + 1
+    return true
+  }
+
+  /** The slot `pid` ran in, or -1. */
+  find(pid: i32): i32 {
+    for (let i: i32 = 0; i < toI32(this.slots.length); i++) {
+      if (this.slots[i].pid === pid) {
+        return i
+      }
+    }
+    return -1
+  }
+
+  /**
+   * Give `slot` the time it may start again: at once after a worker that ran
+   * at least `quickExitMs`, else, or when `failed` (`spawn` refused it), after
+   * a wait that starts at `backoffMs` and doubles up to `backoffCapMs`.
+   */
+  backoff(slot: PreforkSlot, now: i64, failed: boolean): void {
+    if (failed || now - slot.at < toI64(this.config.quickExitMs)) {
+      const cap: i32 = this.config.backoffCapMs
+      if (slot.delay === 0) {
+        slot.delay = this.config.backoffMs
+      } else {
+        // Compared before doubling, so a cap near the i32 limit cannot overflow.
+        slot.delay = slot.delay > cap / 2 ? cap : slot.delay * 2
+      }
+    } else {
+      slot.delay = 0
+    }
+    slot.at = now + toI64(slot.delay)
+  }
+
+  /**
+   * Reap every worker that has exited. Unless `stopping`, each one's slot is
+   * given the time it may start again. A child that is not a worker (one the
+   * program spawned itself before calling `preforkWith`) is reaped too, and
+   * its status is discarded. Answers false when `waitPid` fails, which means
+   * no child is left to wait for.
+   */
+  reap(stopping: boolean): boolean {
+    while (this.running > 0) {
+      const done: i32[] = waitPid(-1, 1)
+      if (done[0] === -4) {
+        continue
+      }
+      if (done[0] <= 0) {
+        return done[0] === 0
+      }
+      const index: i32 = this.find(done[0])
+      if (index < 0) {
+        continue
+      }
+      const slot: PreforkSlot = this.slots[index]
+      this.running = this.running - 1
+      slot.pid = 0
+      if (!stopping) {
+        this.backoff(slot, preforkNowMs(), false)
+      }
+    }
+    return true
+  }
+
+  /**
+   * Start every waiting worker whose time has come. When `first`, answer false
+   * at the first `spawn` that fails; otherwise a failed start waits on the
+   * same backoff as a worker that exited at once, and the answer is true.
+   */
+  restart(first: boolean): boolean {
+    const now: i64 = preforkNowMs()
+    for (let i: i32 = 0; i < toI32(this.slots.length); i++) {
+      const slot: PreforkSlot = this.slots[i]
+      if (slot.pid === 0 && slot.at <= now && !this.start(i)) {
+        if (first) {
+          return false
+        }
+        console.error(`nish/net/prefork: cannot restart worker ${i}`)
+        this.backoff(slot, now, true)
+      }
+    }
+    return true
+  }
+
+  /** Send `sig` to every running worker. */
+  signal(sig: i32): void {
+    for (let i: i32 = 0; i < toI32(this.slots.length); i++) {
+      if (this.slots[i].pid > 0) {
+        kill(this.slots[i].pid, sig)
+      }
+    }
+  }
+
+  /**
+   * SIGTERM, reap until `graceMs` or a second signal, SIGKILL, reap until no
+   * worker is left. Two signals that arrive before the supervisor reads the
+   * first count as the second here too. Every reap goes through `reap`, so a
+   * child that is not a worker is skipped in both phases, and the SIGKILL
+   * phase ends only when the last worker is reaped or no child is left.
+   */
+  stop(loop: i32, signals: i32, ready: i32[]): void {
+    this.signal(PREFORK_SIGTERM)
+    const deadline: i64 = preforkNowMs() + toI64(this.config.graceMs)
+    this.reap(true)
+    let forced = false
+    while (this.running > 0 && !forced && preforkNowMs() < deadline) {
+      const n: i32 = pollWait(loop, ready, this.config.tickMs)
+      if (n > 0) {
+        readSignal(signals)
+        forced = true
+      }
+      this.reap(true)
+    }
+    if (this.running > 0) {
+      this.signal(PREFORK_SIGKILL)
+      while (this.reap(true) && this.running > 0) {
+        if (pollWait(loop, ready, this.config.tickMs) > 0) {
+          readSignal(signals)
+        }
+      }
+    }
+  }
+}
+
+/** The first field of `config` the supervisor cannot run with, or "" when none. */
+const preforkInvalid = (config: PreforkConfig): string => {
+  if (config.workers < 0) {
+    return "workers below 0"
+  }
+  if (config.tickMs <= 0) {
+    return "tickMs not above 0"
+  }
+  if (config.backoffMs <= 0 || config.backoffCapMs < config.backoffMs) {
+    return "backoffMs not above 0 or above backoffCapMs"
+  }
+  if (config.quickExitMs < 0 || config.graceMs < 0) {
+    return "quickExitMs or graceMs below 0"
+  }
+  return ""
+}
+
+/**
+ * In a worker, its index. In the supervisor, run the workers until SIGTERM or
+ * SIGINT and answer `PREFORK_STOPPED`, or `PREFORK_SPAWN_FAILED` when a worker's
+ * first start failed (those already started are stopped first) or no signal
+ * listener could be made (no worker is started). Panics on a config
+ * `preforkInvalid` names a field of.
+ */
+export const preforkWith = (args: string[], config: PreforkConfig): i32 => {
+  const invalid: string = preforkInvalid(config)
+  if (invalid !== "") {
+    panic(`nish/net/prefork: ${invalid}`)
+  }
+  const index: i32 = preforkIndex(args)
+  if (index >= 0) {
+    return index
+  }
+  const signals: i32 = signalFd()
+  const loop: i32 = pollCreate()
+  if (signals < 0 || loop < 0 || pollAdd(loop, signals, 1, 0) < 0) {
+    // `signals` is the process's one signal pipe, which every later
+    // `signalFd()` answers, so only the loop is closed.
+    console.error("nish/net/prefork: cannot listen for SIGTERM")
+    if (loop >= 0) {
+      netClose(loop)
+    }
+    return PREFORK_SPAWN_FAILED
+  }
+  const supervisor = new PreforkSupervisor(
+    config,
+    args,
+    preforkWorkerCount(config.workers, getenv("NISH_WORKERS"))
+  )
+  const ready: i32[] = new Array<i32>(2)
+  let result: i32 = PREFORK_STOPPED
+  if (!supervisor.restart(true)) {
+    console.error(`nish/net/prefork: cannot start ${supervisor.program}`)
+    result = PREFORK_SPAWN_FAILED
+  } else {
+    let running = true
+    while (running) {
+      const n: i32 = pollWait(loop, ready, config.tickMs)
+      if (n > 0) {
+        readSignal(signals)
+        running = false
+      } else {
+        supervisor.reap(false)
+        supervisor.restart(false)
+      }
+    }
+  }
+  supervisor.stop(loop, signals, ready)
+  netClose(loop)
+  return result
+}
+
+/** `preforkWith` with the default `PreforkConfig`. */
+export const preforkWorkers = (args: string[]): i32 => preforkWith(args, new PreforkConfig())

package/std/net/quic-listener.ts

@@ -71,6 +71,10 @@
  *     while (out !== null) { … send it … ; out = quicListenerTakePaced(conn, now); }
  *     … and wake at the earlier of conn.deadline() and quicListenerPaceTime(conn, now)
  *
+ * A carrier that sends whole flights with `quicListenerTakeFlight`, below,
+ * wakes at `quicListenerFlightTime` instead, as `Http3Server` does: a flight
+ * waits for more credit than one datagram, so the pace time can come first.
+ *
  * **GSO and GRO** (`nish:net`'s `UDP_SEGMENT` and `UDP_GRO`). A carrier that
  * sends with segmentation offload takes a whole flight at once:
  * `quicListenerTakeFlight` writes as many datagrams as the pacer has credit
@@ -79,7 +83,10 @@
  * cuts back into datagrams; each is written in place, so a flight allocates
  * nothing. The flight is paced as a whole: it is as long as the pacer's
  * credit, and charged to it datagram by datagram, so a burst is never more
- * than the initial window however the carrier sends it. On the receiving
+ * than the initial window however the carrier sends it. It starts only on a
+ * millisecond's earning, up to four datagrams, so a fast connection's pacer,
+ * which earns by the microsecond, does not let it out a datagram per send;
+ * `quicListenerFlightTime` says when. On the receiving
  * side, `quicListenerReceiveSegments` hands a connection the datagrams of
  * one GRO receive, segment by segment, in place.
  *
@@ -95,9 +102,10 @@
  * byte for byte.
  *
  * **Secrets.** The seed lives in the listener and the static keys in the
- * caller's `QuicServerConfig`, for the server's lifetime, as plain bytes,
- * since a `Secret` may not be a field (NL2430); QUIC-5 in
- * `docs/security/quic.md` records it, with #430.
+ * `QuicServerConfig`, for the server's lifetime, as plain bytes, since a
+ * `Secret` may not be a field (NL2430). `release()` wipes the listener's own,
+ * and `Http3Server.stop` the configuration's with them; QUIC-5 in
+ * `docs/security/quic.md` records what is left.
  *
  * Written from RFC 9000, in this module's own structure; nothing here is
  * ported from another implementation. Private names carry the
@@ -212,12 +220,38 @@ export class QuicListenerAnswer {
   retryScid: u8[]
   kind: i32 = 0
   retried: boolean = false
+  room: i32 = 0
 
   constructor(room: i32) {
-    this.reply = quicListenerRoom(room > 0 ? room : 0)
+    this.room = room > 0 ? room : 0
+    this.reply = quicListenerRoom(this.room)
     this.originalDcid = quicListenerRoom(QUIC_MAX_CID_LENGTH)
     this.retryScid = quicListenerRoom(QUIC_MAX_CID_LENGTH)
   }
+
+  /**
+   * Zeroes the last answer: `reply` across its whole room and each ID across
+   * its 20 bytes, so a Retry's token, a stateless reset's token and the IDs
+   * leave no copy beyond the arrays' lengths either. Each is left that long
+   * and all zero, `kind` a drop. An answer whose reply grew past its room
+   * keeps what lies beyond the longest length it is wiped at; one made with
+   * `QUIC_LISTENER_ANSWER_SIZE` never grows.
+   */
+  wipe(): void {
+    quicListenerWipeRoom(this.reply, this.room)
+    quicListenerWipeRoom(this.originalDcid, QUIC_MAX_CID_LENGTH)
+    quicListenerWipeRoom(this.retryScid, QUIC_MAX_CID_LENGTH)
+    this.kind = QUIC_LISTEN_DROP
+    this.retried = false
+  }
+}
+
+/** Grows `bytes` to at least `room` in the room it already has and zeroes all of it. */
+const quicListenerWipeRoom = (bytes: u8[], room: i32): void => {
+  if (toI32(bytes.length) < room) {
+    quicListenerResize(bytes, room)
+  }
+  secureZero(bytes)
 }
 
 /** An empty array with room for `size` bytes, so pushing up to that many allocates nothing. */
@@ -365,6 +399,30 @@ export class QuicListener {
     secureZero(entropy)
   }
 
+  /**
+   * Ends the listener: wipes the seed and the generator's unused bytes, the
+   * tag and the HMAC and HKDF scratch, the INVALID_TOKEN close's Initial
+   * secrets and key slots, and `handle`'s spare answer, which holds the last
+   * one; `handle` and `handleWindow` then drop every datagram they are
+   * handed. The other methods still run, under the zeroed seed, and are the
+   * caller's not to call. What `handle` returned is the caller's to wipe. The
+   * configuration's keys are not the listener's to wipe: `Http3Server.stop`
+   * wipes them with the rest of the server.
+   */
+  release(): void {
+    this.usable = false
+    secureZero(this.seed)
+    secureZero(this.pool)
+    this.poolHead = QUIC_LISTENER_POOL
+    secureZero(this.tag)
+    this.kdf.wipe()
+    secureZero(this.initialClient)
+    secureZero(this.initialServer)
+    this.readSlot.wipe()
+    this.writeSlot.wipe()
+    this.spare.wipe()
+  }
+
   /**
    * One unpredictable value in 0 to 255: the next byte of HMAC-SHA256 under
    * the seed of a counter, a block at a time, each byte wiped once taken.
@@ -843,6 +901,24 @@ export const quicListenerTakePaced = (conn: QuicConnection, now: i64): u8[] | nu
 export const quicListenerPaceTime = (conn: QuicConnection, now: i64): i64 =>
   now + conn.recovery.pacerDelay(now, QUIC_CONN_DATAGRAM_SIZE)
 
+/** The most credit a paced flight waits for before it starts: four datagrams. */
+export const QUIC_LISTENER_FLIGHT_QUANTUM: i32 = 4800
+
+/**
+ * The credit `quicListenerTakeFlight` waits for before `conn` starts a
+ * flight: what its pacer earns in a millisecond, from one datagram up to
+ * `QUIC_LISTENER_FLIGHT_QUANTUM`.
+ */
+const quicListenerQuantum = (conn: QuicConnection): i32 =>
+  conn.recovery.pacerQuantum(QUIC_CONN_DATAGRAM_SIZE, QUIC_LISTENER_FLIGHT_QUANTUM)
+
+/**
+ * When `quicListenerTakeFlight` next lets `conn` start a flight, in the
+ * caller's milliseconds: `now` when it may already.
+ */
+export const quicListenerFlightTime = (conn: QuicConnection, now: i64): i64 =>
+  now + conn.recovery.pacerDelay(now, quicListenerQuantum(conn))
+
 /** The most datagrams one GSO send carries: Linux's `UDP_MAX_SEGMENTS`. */
 export const QUIC_LISTENER_FLIGHT_MAX: i32 = 64
 
@@ -858,8 +934,10 @@ export class QuicFlight {
  * Writes the next flight `conn` sends at `now` into `buf[at .. at + cap)`,
  * datagram after datagram, for one GSO send, and answers its length in
  * bytes (0 for none); `flight` says how many datagrams it holds and the
- * segment size. Each datagram goes only when the pacer has credit for a full
- * one (RFC 9002 §7.7) and is charged at its real size, as
+ * segment size. A flight starts only once the pacer has the credit
+ * `quicListenerFlightTime` waits for, a millisecond's earning of one to four
+ * datagrams; then each datagram goes only when the pacer has credit for a
+ * full one (RFC 9002 §7.7) and is charged at its real size, as
  * `quicListenerTakePaced` does, so the flight is the pacer's whole credit
  * and no more. It stops at the first datagram shorter than
  * `QUIC_CONN_DATAGRAM_SIZE`, which can only be the last of a segmented send,
@@ -877,6 +955,9 @@ export const quicListenerTakeFlight = (
   flight.count = 0
   flight.segment = 0
   let length: i32 = 0
+  if (conn.recovery.pacerDelay(now, quicListenerQuantum(conn)) > 0) {
+    return length
+  }
   while (
     flight.count < QUIC_LISTENER_FLIGHT_MAX &&
     length + QUIC_CONN_DATAGRAM_SIZE <= cap &&