@threadedstack/wmd-web 0.0.0-stage → 0.1.13

package/src/host/chan-services.js

@@ -0,0 +1,689 @@
+// P-B3: the host side of the channels: one ChanHost serves every channel of a machine
+// from the service Worker (chan-service.js). It is synchronous and transport-free, so the
+// unit tests drive it directly (step()).
+//
+// Services, by the kind registered for the port (not the kind the guest passed, as in
+// chan.rs, where the port decides who answers):
+//   9p       the 9P2000.L server (src/fs/9p/server.js) over an Overlay of packs. One
+//            Overlay per port, one NinePServer per open channel (a connection). Frames are
+//            9P's own (size[4] LE). A size < 7 or > MAX_FRAME is a protocol error: the
+//            host closes the channel, as wmd's Go server drops the connection.
+//   console  raw bytes. Guest -> the page through the pipe ring (backpressure, no loss);
+//            page -> guest from consoleInput(), at most consoleInputBytes held (the
+//            page's consoleInputGate keeps under it; bytes past it are dropped, counted).
+//   control  a stub: it reads and counts the bytes (and their CRC-32, so a test can check
+//            content and order) and answers nothing. On a port listed in `yamuxPorts`
+//            (P-B11), the host side of wmd's control session instead: a yamux client
+//            (yamux.js) whose streams the page drives through controlInput() and
+//            ctlEvents (ControlSession below; the protocol on the streams is ctl.js's).
+//   net      P-B10: with a network Worker (o.netPost, src/net/net-worker.js), the guest's
+//            frame stream (4-byte big-endian length + frame) goes to that Worker, which runs
+//            the TCP/IP stack and the relay connection, and its frames come back here for
+//            the guest's ring (NetSession). Without one, a stub: frames are counted and
+//            dropped, nothing is answered.
+//
+// When the guest shuts its side down (EOF), the host closes its side too once its output
+// is out. Backpressure: a channel whose replies the guest is not reading stops being
+// read once OUT_LIMIT bytes are queued, so its guest->host ring fills and chan_send
+// blocks.
+
+import {
+  CHAN_CONSOLE, CHAN_CONTROL, CHAN_NET, CHAN_P9, CONSOLE_IN_LIMIT, G2H, H2G, H_CIN_TAKEN, H_CLOSES, H_GONE, KIND_NAMES, R_GONE, R_SHUT,
+  RTT_BUCKETS, S_GEN, S_PORT, S_STATE, ST_CLOSING, ST_FREE, ST_OPEN, chanPorts, chanView, histSummary,
+  ringAvail, ringKick, ringRead, ringSpace, ringWrite, rttBucket, stageNote,
+} from './chan.js'
+import { NinePServer } from '../fs/9p/server.js'
+import { adoptServer, dumpService, loadService } from '../fs/svc-snapshot.js'
+import { YamuxClient } from './yamux.js'
+
+export const MAX_FRAME = (1 << 20) + 64 // the guest stages T-messages in 1 MiB (p9proxy.c P9_MAX_TMSG)
+export const OUT_LIMIT = 4 << 20
+const READ_CHUNK = 1 << 18
+/** Bytes one channel may read in one step(): a guest that keeps its ring full cannot hold
+ * the service in one pass (its messages, the other channels wait for the step to end). */
+export const STEP_READ_BUDGET = 1 << 20
+
+const CRC_TABLE = (() => {
+  const t = new Int32Array(256)
+  for (let n = 0; n < 256; n++) {
+    let c = n
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1
+    t[n] = c
+  }
+  return t
+})()
+/** CRC-32 (IEEE, as zlib) of bytes, continuing from crc (0 to start). */
+export function crc32(bytes, crc = 0) {
+  let c = ~crc
+  for (let i = 0; i < bytes.length; i++) c = CRC_TABLE[(c ^ bytes[i]) & 0xff] ^ (c >>> 8)
+  return ~c >>> 0
+}
+
+/** A queue of byte chunks written into a ring as room appears. */
+class OutQueue {
+  constructor() {
+    this.chunks = []
+    this.off = 0
+    this.bytes = 0
+    this.taken = 0 // bytes written into the ring, ever
+  }
+  push(u8) {
+    if (!u8.length) return
+    this.chunks.push(u8)
+    this.bytes += u8.length
+  }
+  /** Write what fits; returns bytes written. */
+  flush(v, r) {
+    let total = 0
+    while (this.chunks.length) {
+      const c = this.chunks[0]
+      const n = ringWrite(v, r, c, this.off, c.length - this.off)
+      if (n <= 0) break
+      total += n
+      this.off += n
+      this.bytes -= n
+      this.taken += n
+      if (this.off === c.length) {
+        this.chunks.shift()
+        this.off = 0
+      }
+    }
+    return total
+  }
+}
+
+/** 9P: frames from the stream, a reply for each, in order. */
+class P9Session {
+  constructor(host, port) {
+    this.host = host
+    this.server = new NinePServer(host.fsFor(port))
+    // P-B9: the first connection after a restore carries the checkpoint's fids (the guest kernel's v9fs holds them)
+    const restored = host.restoredServers.get(port)
+    if (restored) {
+      host.restoredServers.delete(port)
+      adoptServer(this.server, restored)
+    }
+    this.buf = new Uint8Array(1 << 16)
+    this.len = 0
+  }
+  room(sess) {
+    // no more requests while the replies already made are not being read
+    return sess.out.bytes >= OUT_LIMIT ? 0 : MAX_FRAME - this.len
+  }
+  data(sess, bytes) {
+    if (this.len + bytes.length > this.buf.length) {
+      const nb = new Uint8Array(Math.max(this.buf.length * 2, this.len + bytes.length))
+      nb.set(this.buf.subarray(0, this.len))
+      this.buf = nb
+    }
+    this.buf.set(bytes, this.len)
+    this.len += bytes.length
+    this.process(sess)
+  }
+  /** Answer the whole frames buffered, until OUT_LIMIT bytes of replies wait to be read. */
+  process(sess) {
+    let at = 0
+    while (this.len - at >= 4 && sess.out.bytes < OUT_LIMIT) {
+      const b = this.buf
+      const size = (b[at] | (b[at + 1] << 8) | (b[at + 2] << 16) | (b[at + 3] << 24)) >>> 0
+      if (size < 7 || size > MAX_FRAME) {
+        this.host.protocolError(sess, `9p frame size ${size}`)
+        this.len = 0
+        return
+      }
+      if (this.len - at < size) break
+      const frame = b.slice(at, at + size) // the server may keep parts of it (Twrite data)
+      at += size
+      const v = this.host.v
+      const tag = frame[5] | (frame[6] << 8)
+      const ts = v.tagTimes[tag]
+      if (ts > 0) stageNote(v.pickup, (performance.timeOrigin + performance.now() - ts) * 1000)
+      const t0 = performance.now()
+      const reply = this.server.handle(frame)
+      this.host.noteP9(frame[4], (performance.now() - t0) * 1000)
+      sess.out.push(reply)
+      v.replyTimes[tag] = performance.timeOrigin + performance.now() // flushed right after this frame's data()
+    }
+    if (at) {
+      this.buf.copyWithin(0, at, this.len)
+      this.len -= at
+    }
+  }
+  pending() {
+    return this.len
+  }
+}
+
+class ConsoleSession {
+  constructor(host) {
+    this.host = host
+  }
+  room() {
+    return ringSpace(this.host.v, this.host.v.pipe)
+  }
+  process() {}
+  data(_sess, bytes) {
+    const n = ringWrite(this.host.v, this.host.v.pipe, bytes)
+    if (n !== bytes.length) throw new Error('console pipe overrun') // room() bounds every read
+    this.host.consoleBytes(bytes.length)
+  }
+  pending() {
+    return 0
+  }
+}
+
+/**
+ * P-B11: the control port as a yamux session (the guest init is the server). One per
+ * open of the port; the page's streams (keys k) live on the host's ctl state, so a
+ * session that ends ends them all.
+ */
+class ControlSession {
+  constructor(host, sess) {
+    this.host = host
+    const ctl = host.ctl
+    ctl.epoch++
+    this.epoch = ctl.epoch
+    this.yamux = new YamuxClient({
+      send: u8 => sess.out.push(u8),
+      keepAliveMs: host.ctlKeepAliveMs,
+      onClose: why => host.ctlSessionDown(this, why),
+    })
+    ctl.session = this
+    host.ctlEvent({ ev: 'session', up: true, epoch: this.epoch })
+  }
+  room() {
+    return Infinity // bounded by the yamux windows the guest respects, and OUT_LIMIT
+  }
+  process() {}
+  tick() {
+    this.yamux.tick()
+  }
+  data(_sess, bytes) {
+    this.yamux.feed(bytes)
+  }
+  pending() {
+    return 0
+  }
+  end(why) {
+    this.yamux.close(why, 0, false)
+  }
+}
+
+/** Bytes sent to the network Worker and not yet processed by it, at most. */
+export const NET_INFLIGHT = 1 << 20
+
+/**
+ * P-B10: the net channel with a network Worker. The guest's bytes go to the Worker as they
+ * are read (at most NET_INFLIGHT unprocessed); the Worker's frames are queued for the
+ * guest's ring, and the Worker hears how much the ring took ('wrote'), which bounds what
+ * it sends.
+ */
+class NetSession {
+  constructor(host, sess) {
+    this.host = host
+    this.sess = sess
+    this.reported = 0
+    host.net.session = this
+    host.net.opens++
+  }
+  room() {
+    return Math.max(0, NET_INFLIGHT - this.host.net.inflight)
+  }
+  process() {}
+  data(_sess, bytes) {
+    const c = bytes.slice()
+    this.host.net.inflight += c.length
+    this.host.netPost({ t: 'in', buf: c.buffer }, [c.buffer])
+  }
+  afterPump(sess) {
+    const n = sess.out.taken - this.reported
+    if (n > 0) {
+      this.reported = sess.out.taken
+      this.host.netPost({ t: 'wrote', n })
+    }
+  }
+  pending() {
+    return 0
+  }
+  end() {
+    const net = this.host.net
+    if (net.session !== this) return
+    net.session = null
+    // what was queued for this guest will not be written: the Worker must not wait for it
+    if (this.sess.out.bytes) this.host.netPost({ t: 'wrote', n: this.sess.out.bytes })
+    this.sess.out = new OutQueue()
+  }
+}
+
+class SinkSession {
+  constructor(host, kind) {
+    this.host = host
+    this.kind = kind
+    this.hdr = 0
+    this.left = 0
+    this.lenBuf = []
+  }
+  room() {
+    return Infinity
+  }
+  process() {}
+  data(_sess, bytes) {
+    const st = this.host.stats.kinds[KIND_NAMES[this.kind]]
+    st.crc32 = crc32(bytes, st.crc32) // every byte the stubs took, in order
+    if (this.kind !== CHAN_NET) return
+    // count the frames: 4-byte big-endian length, then the frame
+    let i = 0
+    while (i < bytes.length) {
+      if (this.left === 0) {
+        this.lenBuf.push(bytes[i++])
+        if (this.lenBuf.length === 4) {
+          const [a, b, c, d] = this.lenBuf
+          this.left = ((a << 24) | (b << 16) | (c << 8) | d) >>> 0
+          this.lenBuf = []
+          if (this.left === 0) continue // keepalive
+          st.frames++
+        }
+      } else {
+        const k = Math.min(this.left, bytes.length - i)
+        i += k
+        this.left -= k
+      }
+    }
+  }
+  pending() {
+    return 0
+  }
+}
+
+export class ChanHost {
+  /**
+   * @param {SharedArrayBuffer} sab the chan block
+   * @param {object} o
+   * @param {Record<number, import('../fs/overlay.js').Overlay>} [o.fs]  9P trees by port
+   * @param {(n:number)=>void} [o.onConsole]                              console bytes went into the pipe
+   * @param {number} [o.consoleInputBytes]  console input (page -> guest) held at most (CONSOLE_IN_LIMIT)
+   */
+  constructor(sab, { fs = {}, onConsole, consoleInputBytes = CONSOLE_IN_LIMIT, yamuxPorts = [], ctlKeepAliveMs = 5000, netPost = null, restore = {} } = {}) {
+    this.v = chanView(sab)
+    // P-B10: the network Worker (postMessage to it), and the net channel's session
+    this.netPost = netPost
+    this.net = { session: null, inflight: 0, opens: 0, framesDropped: 0, bytesDropped: 0 }
+    this.fs = fs
+    // P-B9: the 9P state of a checkpoint (port -> bytes): the tree is replaced now, the fid table waits for the connection
+    this.restoredServers = new Map()
+    for (const [port, bytes] of Object.entries(restore)) {
+      if (!fs[port]) throw new Error(`checkpoint has 9P state for port ${port} and this boot has no 9P service there`)
+      this.restoredServers.set(Number(port), loadService(bytes, fs[port]))
+    }
+    this.yamuxPorts = new Set(yamuxPorts)
+    this.ctlKeepAliveMs = ctlKeepAliveMs
+    // P-B11: the control session and the page's streams on it (k -> YamuxStream)
+    this.ctl = { session: null, epoch: 0, streams: new Map(), events: [], opened: 0, refusedOpens: 0 }
+    this.onConsole = onConsole
+    this.kindOfPort = new Map(chanPorts(sab).map(p => [p.port, p.kind]))
+    this.sessions = new Array(this.v.nslots).fill(null)
+    this.inbuf = new Uint8Array(READ_CHUNK)
+    this.consoleIn = [] // bytes from the page waiting for the console channel
+    this.consoleInQueued = 0 // bytes in consoleIn
+    this.consoleInLimit = consoleInputBytes
+    this.stats = {
+      // per kind; firstInAt/lastInAt: absolute ms of the first and the latest guest bytes read
+      kinds: Object.fromEntries(Object.values(KIND_NAMES).map(k => [k, { opens: 0, bytesIn: 0, bytesOut: 0, frames: 0, eofs: 0, protocolErrors: 0, firstInAt: 0, lastInAt: 0, crc32: 0 }])),
+      p9: { requests: 0, byType: {}, hist: new Array(RTT_BUCKETS).fill(0), sumUs: 0, maxUs: 0 },
+      console: { bytes: 0, firstAt: 0, lastAt: 0, inputBytes: 0, inputDropped: 0 },
+      sessionsDropped: 0,
+      errors: [],
+    }
+    this.stopped = false
+  }
+
+  /** Queue an event for the page (chan-service.js posts ctlEvents after each step). */
+  ctlEvent(e) {
+    this.ctl.events.push(e)
+  }
+
+  /** Takes the queued control events. */
+  takeCtlEvents() {
+    const e = this.ctl.events
+    if (!e.length) return null
+    this.ctl.events = []
+    return e
+  }
+
+  ctlSessionDown(cs, why) {
+    const ctl = this.ctl
+    if (ctl.session !== cs) return
+    ctl.session = null
+    ctl.lastWhy = why
+    for (const [k, st] of ctl.streams) {
+      ctl.streams.delete(k)
+      st.onClose = null
+      this.ctlEvent({ ev: 'closed', k, why: `control session ended: ${why}` })
+    }
+    this.ctlEvent({ ev: 'session', up: false, epoch: cs.epoch, why })
+  }
+
+  /**
+   * A message from the page for the control session: {op:'open'|'write'|'close'|'reset'|'ack', k, bytes?, n?}.
+   * Returns true if the session took it.
+   */
+  controlInput(m) {
+    const ctl = this.ctl
+    const cs = ctl.session
+    if (m.op === 'open') {
+      if (!cs || cs.yamux.closed) {
+        ctl.refusedOpens++
+        this.ctlEvent({
+          ev: 'closed',
+          k: m.k,
+          why: ctl.epoch
+            ? `no control session: the guest's control session ${ctl.epoch} has ended (${ctl.lastWhy || 'closed'}) and none is open`
+            : 'no control session (the guest has not opened the control port)',
+        })
+        return false
+      }
+      let st
+      try {
+        st = cs.yamux.open()
+      } catch (e) {
+        this.ctlEvent({ ev: 'closed', k: m.k, why: e.message })
+        return false
+      }
+      ctl.opened++
+      ctl.streams.set(m.k, st)
+      st.onData = u8 => this.ctlEvent({ ev: 'data', k: m.k, bytes: u8 })
+      st.onFin = () => this.ctlEvent({ ev: 'fin', k: m.k })
+      // stdin backpressure: the page counts what it posted until it hears it went out
+      st.onSent = n => {
+        const last = this.ctl.events.at(-1)
+        if (last?.ev === 'sent' && last.k === m.k) last.n += n
+        else this.ctlEvent({ ev: 'sent', k: m.k, n })
+      }
+      st.onClose = why => {
+        if (ctl.streams.get(m.k) === st) ctl.streams.delete(m.k)
+        this.ctlEvent({ ev: 'closed', k: m.k, why })
+      }
+      if (m.bytes?.length) st.write(new Uint8Array(m.bytes))
+      return true
+    }
+    const st = ctl.streams.get(m.k)
+    if (!st) return false
+    if (m.op === 'write') {
+      if (st.localFin) return false
+      st.write(new Uint8Array(m.bytes))
+    } else if (m.op === 'close') st.closeWrite()
+    else if (m.op === 'reset') st.abort()
+    else if (m.op === 'ack') st.consume(m.n)
+    return true
+  }
+
+  /** P-B10: a message from the network Worker: {t:'out', buf} frames for the guest, {t:'took', n}. */
+  netMessage(m) {
+    const net = this.net
+    if (m.t === 'took') net.inflight = Math.max(0, net.inflight - m.n)
+    else if (m.t === 'out') {
+      const u8 = new Uint8Array(m.buf)
+      const sess = net.session?.sess
+      if (!sess || sess.broken || sess.eof) {
+        // no guest to take it (not open yet, or gone): it is dropped, and the Worker is told
+        net.framesDropped++
+        net.bytesDropped += u8.length
+        this.netPost?.({ t: 'wrote', n: u8.length })
+        return
+      }
+      sess.out.push(u8)
+    }
+  }
+
+  /**
+   * P-B9: the state of every 9P service for a checkpoint: {port: {segments: Uint8Array[], bytes, fids}}. The
+   * live connection's fids go with the tree; the guest is stopped at its checkpoint point, so nothing is in flight.
+   */
+  snapshotState() {
+    const out = {}
+    for (const [port, fs] of Object.entries(this.fs)) {
+      let server = null
+      for (const sess of this.sessions) {
+        if (sess && sess.port === Number(port) && sess.impl instanceof P9Session) {
+          // The guest is stopped with its share drained: every request it made is answered, so no frame is half received. A
+          // half frame here would be lost by a restore (the guest would wait for a reply to a request the new server never saw).
+          if (sess.impl.pending()) throw new Error(`the 9P connection on port ${port} holds ${sess.impl.pending()} bytes of a half-received request at the checkpoint point; the checkpoint is refused`)
+          server = sess.impl.server
+        }
+      }
+      // no live connection: the fids a restore has not yet handed to one are still the state
+      const d = dumpService(fs, server || this.restoredServers.get(Number(port)) || null)
+      out[port] = { segments: d.segments, bytes: d.bytes, fids: d.fids }
+    }
+    return out
+  }
+
+  // What a checkpoint does not carry (docs): the channel rings and every session of the other services are rebuilt by the
+  // restoring machine: the guest's 9P channel is opened again (virtio_p9_reconnect), the console and control ports are reset
+  // and the control yamux session is a new one (the caller sends resync {now_ns, seed}, then attach). The net service is a
+  // new stack: a TCP connection the guest believed open hangs in the guest until its own timeout.
+
+  fsFor(port) {
+    const f = this.fs[port]
+    if (!f) throw new Error(`no 9P tree for port ${port}`)
+    return f
+  }
+
+  p9Requests() {
+    return this.stats.p9.requests
+  }
+
+  noteP9(type, us) {
+    const p = this.stats.p9
+    p.requests++
+    p.byType[type] = (p.byType[type] || 0) + 1
+    p.hist[rttBucket(us)]++
+    p.sumUs += us
+    if (us > p.maxUs) p.maxUs = us
+  }
+
+  consoleBytes(n) {
+    const c = this.stats.console
+    const t = performance.timeOrigin + performance.now()
+    if (!c.bytes) c.firstAt = t
+    c.lastAt = t
+    c.bytes += n
+    this.onConsole?.(n)
+  }
+
+  /** Console input held for the guest: queued, plus what a console session has not written into its ring yet. */
+  consoleInputHeld() {
+    let n = this.consoleInQueued
+    for (const sess of this.sessions) if (sess && sess.kind === CHAN_CONSOLE) n += sess.out.bytes
+    return n
+  }
+
+  /**
+   * Bytes for the guest's console (page -> guest), queued until the channel is open.
+   * Holds at most consoleInputBytes: the rest is dropped and counted (the page's
+   * consoleInputGate never sends more than that). Returns the bytes kept.
+   */
+  consoleInput(u8) {
+    const c = this.stats.console
+    const keep = Math.max(0, Math.min(u8.length, this.consoleInLimit - this.consoleInputHeld()))
+    if (keep < u8.length) {
+      const drop = u8.length - keep
+      c.inputDropped += drop
+      Atomics.add(this.v.i32, H_CIN_TAKEN, drop) // never coming: the page's gate must not wait for it
+      if (c.inputDropped === drop) this.#error(`console input over ${this.consoleInLimit} bytes not read by the guest: ${drop} bytes dropped`)
+    }
+    if (keep) {
+      this.consoleIn.push(keep < u8.length ? u8.subarray(0, keep) : u8)
+      this.consoleInQueued += keep
+      c.inputBytes += keep
+    }
+    return keep
+  }
+
+  #error(msg) {
+    this.stats.errors.push(msg)
+    if (this.stats.errors.length > 32) this.stats.errors.shift()
+  }
+
+  protocolError(sess, why) {
+    this.stats.kinds[KIND_NAMES[sess.kind]].protocolErrors++
+    this.#error(`handle ${sess.slot}: ${why}; closing the channel`)
+    const v = this.v
+    // as a server dropping the connection: the guest's sends fail, its receives see EOF
+    const g = v.ring(sess.slot, G2H)
+    const h = v.ring(sess.slot, H2G)
+    Atomics.store(v.i32, g.c + R_GONE, 1)
+    ringKick(v, g)
+    sess.broken = true
+    sess.out = new OutQueue()
+    Atomics.store(v.i32, h.c + R_SHUT, 1)
+    ringKick(v, h)
+  }
+
+  #open(slot, gen) {
+    const v = this.v
+    const port = Atomics.load(v.i32, v.slotBase(slot) + S_PORT)
+    const kind = this.kindOfPort.get(port)
+    const sess = { slot, gen, port, kind, out: new OutQueue(), eof: false, closedOut: false, broken: false, impl: null }
+    this.stats.kinds[KIND_NAMES[kind]].opens++
+    if (kind === CHAN_P9) sess.impl = new P9Session(this, port)
+    else if (kind === CHAN_CONSOLE) sess.impl = new ConsoleSession(this)
+    else if (kind === CHAN_CONTROL && this.yamuxPorts.has(port)) sess.impl = new ControlSession(this, sess)
+    else if (kind === CHAN_NET && this.netPost) sess.impl = new NetSession(this, sess)
+    else sess.impl = new SinkSession(this, kind)
+    return sess
+  }
+
+  /** One pass over every channel. Returns true if anything moved. */
+  step() {
+    const v = this.v
+    const i32 = v.i32
+    if (Atomics.load(i32, H_GONE)) {
+      if (!this.stopped) {
+        this.stopped = true
+        for (let s = 0; s < v.nslots; s++) if (this.sessions[s]) this.#drop(s)
+      }
+      return false
+    }
+    let work = false
+    for (let s = 0; s < v.nslots; s++) {
+      const b = v.slotBase(s)
+      const st = Atomics.load(i32, b + S_STATE)
+      let sess = this.sessions[s]
+      if (st === ST_CLOSING) {
+        if (sess) this.#drop(s)
+        Atomics.store(i32, b + S_STATE, ST_FREE)
+        work = true
+        continue
+      }
+      if (st !== ST_OPEN) {
+        if (sess) this.#drop(s)
+        continue
+      }
+      const gen = Atomics.load(i32, b + S_GEN)
+      if (!sess || sess.gen !== gen) {
+        if (sess) this.#drop(s)
+        sess = this.sessions[s] = this.#open(s, gen)
+        work = true
+      }
+      if (this.#pump(sess)) work = true
+    }
+    return work
+  }
+
+  #drop(s) {
+    const sess = this.sessions[s]
+    this.sessions[s] = null
+    if (!sess) return
+    if (sess.impl?.pending()) this.stats.sessionsDropped++ // a message was cut off
+    sess.impl?.end?.('the guest closed the control channel')
+    // console input the session still held will never reach a guest ring
+    if (sess.kind === CHAN_CONSOLE && sess.out.bytes) Atomics.add(this.v.i32, H_CIN_TAKEN, sess.out.bytes)
+  }
+
+  #pump(sess) {
+    const v = this.v
+    const g = v.ring(sess.slot, G2H)
+    const h = v.ring(sess.slot, H2G)
+    const ks = this.stats.kinds[KIND_NAMES[sess.kind]]
+    let work = false
+    if (sess.kind === CHAN_CONSOLE && this.consoleIn.length && !sess.broken) {
+      for (const c of this.consoleIn) sess.out.push(c)
+      this.consoleIn = []
+      this.consoleInQueued = 0
+    }
+    sess.impl.tick?.()
+    const before = sess.out.bytes
+    let wrote = sess.out.flush(v, h)
+    if (sess.kind === CHAN_CONSOLE && wrote) Atomics.add(v.i32, H_CIN_TAKEN, wrote) // console input taken by the ring
+    if (!sess.broken && sess.impl.pending() && sess.out.bytes < OUT_LIMIT) {
+      // requests held back while the replies were not read
+      const n = sess.impl.pending()
+      sess.impl.process(sess)
+      if (sess.impl.pending() !== n) work = true
+      wrote += sess.out.flush(v, h)
+    }
+    if (wrote) {
+      ks.bytesOut += wrote
+      work = true
+    }
+    if (before && !sess.out.bytes) work = true
+    // read, as much as the service can take, up to STEP_READ_BUDGET this step
+    let budget = STEP_READ_BUDGET
+    while (!sess.broken && sess.out.bytes < OUT_LIMIT && budget > 0) {
+      const room = Math.min(sess.impl.room(sess), this.inbuf.length)
+      if (room <= 0) break
+      const n = ringRead(v, g, this.inbuf, 0, Math.min(room, budget))
+      if (!n) break
+      budget -= n
+      const t = performance.timeOrigin + performance.now()
+      if (!ks.bytesIn) ks.firstInAt = t
+      ks.lastInAt = t
+      ks.bytesIn += n
+      work = true
+      sess.impl.data(sess, this.inbuf.subarray(0, n))
+      const w2 = sess.out.flush(v, h)
+      if (sess.kind === CHAN_CONSOLE && w2) Atomics.add(v.i32, H_CIN_TAKEN, w2)
+      ks.bytesOut += w2
+    }
+    sess.impl.afterPump?.(sess)
+    // EOF from the guest: close our side once the output is out
+    if (!sess.eof && Atomics.load(v.i32, g.c + R_SHUT) && ringAvail(v, g) === 0) {
+      sess.eof = true
+      ks.eofs++
+      sess.impl.end?.('the guest closed the control channel')
+      if (sess.impl.pending()) this.stats.sessionsDropped++
+      work = true
+    }
+    if (sess.eof && !sess.closedOut && !sess.out.bytes) {
+      sess.closedOut = true
+      Atomics.store(v.i32, h.c + R_SHUT, 1)
+      ringKick(v, h)
+    }
+    return work
+  }
+
+  /** Stats for the page (JSON-safe). */
+  snapshot() {
+    const p = this.stats.p9
+    return {
+      kinds: this.stats.kinds,
+      p9: {
+        requests: p.requests,
+        byType: p.byType,
+        service: histSummary(p.hist, { meanUs: p.requests ? p.sumUs / p.requests : 0, maxUs: p.maxUs }),
+      },
+      console: { ...this.stats.console, inputHeld: this.consoleInputHeld() },
+      uppers: Object.fromEntries(
+        Object.entries(this.fs).map(([port, f]) => [port, { used: f.used, max: Number.isFinite(f.maxUpperBytes) ? f.maxUpperBytes : null, fullHits: f.fullHits || 0 }]),
+      ),
+      sessionsDropped: this.stats.sessionsDropped,
+      net: this.netPost ? { open: !!this.net.session, inflight: this.net.inflight, opens: this.net.opens, framesDropped: this.net.framesDropped, bytesDropped: this.net.bytesDropped, queued: this.net.session?.sess.out.bytes ?? 0 } : undefined,
+      control: this.yamuxPorts.size
+        ? { epoch: this.ctl.epoch, up: !!this.ctl.session, streams: this.ctl.streams.size, opened: this.ctl.opened, refusedOpens: this.ctl.refusedOpens, yamux: this.ctl.session ? { ...this.ctl.session.yamux.stats, pingRttMs: this.ctl.session.yamux.stats.pingRttMs.slice(-8) } : null }
+        : undefined,
+      errors: [...this.stats.errors],
+      closes: Atomics.load(this.v.i32, H_CLOSES),
+    }
+  }
+}