@threadedstack/wmd-web 0.0.0-stage → 0.1.12

package/src/net/net-worker.js

@@ -0,0 +1,172 @@
+// P-B10: the guest network's Worker. It runs the TCP/IP stack (stack.js) and the relay's
+// WebSocket (relay-client.js), off the page and off the channel service.
+//
+// The channel service (chan-service.js, NetSession in chan-services.js) owns the net
+// channel's rings and talks to this Worker over a MessagePort:
+//   service -> here  {t:'in', buf}     bytes the guest's virtio-net wrote: 4-byte BE length + frame, as a stream
+//                    {t:'wrote', n}    n of the bytes we sent were written into the guest's ring
+//   here -> service  {t:'out', buf}    frames for the guest, length-prefixed the same way
+//                    {t:'took', n}     n input bytes were processed (the service reads more only then)
+// The page: {t:'init', port, relay?: {url, protocol?, token?, tokenUrl?, key?}, instance?, names?, switchPort?, config?, maxConns?}, {t:'stats'},
+//           (W59: protocol 'wisp' uses wisp-client.js; instance is the machine's id, names its placeholder
+//           map [[name, ip]], kept by the page across restores; {t:'names', id} asks for the whole map)
+//           (W56: switchPort is the guest's port on an in-page switch, switch.js; with no relay only
+//           the guests on the switch are reachable)
+//           {t:'drop-relay'} (test hook: drop the WebSocket).
+// Messages out to the page: {t:'stats', stats}, {t:'log', line}, W59: {t:'name', name, ip} (a new placeholder),
+//           {t:'status', status} (vm.net.onStatus), {t:'names', id, names}.
+
+import { NetStack } from './stack.js'
+import { RelayClient } from './relay-client.js'
+import { WispClient } from './wisp-client.js'
+import { PeerNet } from './peer.js'
+
+const RING_INFLIGHT = 1 << 20 // bytes sent to the service not yet in the guest's ring, at most
+const MAX_FRAME = 65536
+
+let stack = null
+let relay = null
+let peers = null
+let port = null
+let inflight = 0 // bytes posted to the service, not yet written into the ring
+let pending = [] // output frames of this turn
+let pendingBytes = 0
+let flushQueued = false
+// the input stream's partial frame
+let hdr = new Uint8Array(4)
+let hdrN = 0
+let frame = null
+let frameN = 0
+
+const log = line => self.postMessage({ t: 'log', line })
+
+self.onmessage = e => {
+  const m = e.data
+  if (m.t === 'init') init(m)
+  else if (m.t === 'stats') self.postMessage({ t: 'stats', id: m.id, stats: snapshot() })
+  else if (m.t === 'drop-relay') relay?.drop()
+  else if (m.t === 'names') self.postMessage({ t: 'names', id: m.id, names: relay?.nameList?.() ?? [] })
+}
+
+function snapshot() {
+  return stack ? { stack: stack.snapshot(), relay: relay?.snapshot() ?? null, peers: peers?.snapshot() ?? null, ringInflight: inflight } : null
+}
+
+function init(m) {
+  port = m.port
+  if (m.relay?.protocol === 'wisp') {
+    relay = new WispClient({
+      url: m.relay.url, token: m.relay.token, tokenUrl: m.relay.tokenUrl, key: m.relay.key, instance: m.instance, names: m.names, log,
+      onName: (name, ip) => self.postMessage({ t: 'name', name, ip }),
+      onStatus: status => self.postMessage({ t: 'status', status }),
+    })
+  } else if (m.relay) relay = new RelayClient({ url: m.relay.url, token: m.relay.token, tokenUrl: m.relay.tokenUrl, instance: m.instance, log })
+  if (m.switchPort) peers = new PeerNet({ port: m.switchPort, log })
+  stack = new NetStack({ send: queueOut, relay, peers, config: m.config, maxConns: m.maxConns, log, txRoom: () => RING_INFLIGHT - inflight - pendingBytes })
+  relay?.attach(stack)
+  peers?.attach(stack)
+  wrapCallbacks()
+  port.onmessage = ev => {
+    const x = ev.data
+    if (x.t === 'in') {
+      const u8 = new Uint8Array(x.buf)
+      feed(u8)
+      stack.flushAcks()
+      port.postMessage({ t: 'took', n: u8.length })
+    } else if (x.t === 'wrote') {
+      inflight -= x.n
+      stack.pump()
+    }
+    flushOut()
+  }
+  setInterval(() => {
+    stack.tick()
+    flushOut()
+  }, 100)
+  // stats for the page while the guest runs
+  let last = ''
+  setInterval(() => {
+    const s = JSON.stringify(snapshot())
+    if (s !== last) self.postMessage({ t: 'stats', stats: JSON.parse(s) })
+    last = s
+  }, 1000)
+  self.postMessage({ t: 'ready' })
+}
+
+/** After relay callbacks (they run outside our port handler), send what they produced. */
+function wrapCallbacks() {
+  for (const k of ['onRelayDown', 'onConnected', 'onRelayData', 'onRelayEnd', 'onRelayAbort', 'onRelayCredit', 'onDnsReply', 'peerOpen']) {
+    const g = stack[k].bind(stack)
+    stack[k] = (...a) => {
+      const r = g(...a)
+      scheduleFlush()
+      return r
+    }
+  }
+}
+
+function scheduleFlush() {
+  if (flushQueued) return
+  flushQueued = true
+  queueMicrotask(() => {
+    flushQueued = false
+    flushOut()
+  })
+}
+
+function feed(u8) {
+  let i = 0
+  while (i < u8.length) {
+    if (!frame) {
+      const k = Math.min(4 - hdrN, u8.length - i)
+      hdr.set(u8.subarray(i, i + k), hdrN)
+      hdrN += k
+      i += k
+      if (hdrN < 4) break
+      hdrN = 0
+      const len = ((hdr[0] << 24) | (hdr[1] << 16) | (hdr[2] << 8) | hdr[3]) >>> 0
+      if (len === 0) continue // keepalive
+      if (len > MAX_FRAME) {
+        log(`net: a frame of ${len} bytes from the guest; the stream is out of step, dropping the input`)
+        return
+      }
+      frame = new Uint8Array(len)
+      frameN = 0
+      continue
+    }
+    const k = Math.min(frame.length - frameN, u8.length - i)
+    frame.set(u8.subarray(i, i + k), frameN)
+    frameN += k
+    i += k
+    if (frameN === frame.length) {
+      const f = frame
+      frame = null
+      stack.input(f)
+    }
+  }
+}
+
+function queueOut(f) {
+  pending.push(f)
+  pendingBytes += 4 + f.length
+}
+
+function flushOut() {
+  stack.flushAcks()
+  if (!pending.length) return
+  const buf = new Uint8Array(pendingBytes)
+  let o = 0
+  for (const f of pending) {
+    const n = f.length
+    buf[o] = n >>> 24
+    buf[o + 1] = (n >>> 16) & 255
+    buf[o + 2] = (n >>> 8) & 255
+    buf[o + 3] = n & 255
+    buf.set(f, o + 4)
+    o += 4 + n
+  }
+  inflight += pendingBytes
+  pending = []
+  pendingBytes = 0
+  port.postMessage({ t: 'out', buf: buf.buffer }, [buf.buffer])
+}

package/src/net/packet.js

@@ -0,0 +1,227 @@
+// P-B10: Ethernet, ARP, IPv4, ICMP, UDP and TCP framing for the guest's virtual network.
+// Pure functions over Uint8Arrays; the stack (stack.js) builds and reads every frame here.
+
+export const ETH_IPV4 = 0x0800
+export const ETH_ARP = 0x0806
+export const ETH_HLEN = 14
+export const IP_ICMP = 1
+export const IP_TCP = 6
+export const IP_UDP = 17
+
+export const TCP_FIN = 0x01
+export const TCP_SYN = 0x02
+export const TCP_RST = 0x04
+export const TCP_PSH = 0x08
+export const TCP_ACK = 0x10
+
+export function ipToU32(s) {
+  const p = s.split('.').map(Number)
+  return ((p[0] << 24) | (p[1] << 16) | (p[2] << 8) | p[3]) >>> 0
+}
+export function u32ToIp(n) {
+  return `${n >>> 24}.${(n >>> 16) & 255}.${(n >>> 8) & 255}.${n & 255}`
+}
+export function macBytes(s) {
+  return Uint8Array.from(s.split(':').map(x => parseInt(x, 16)))
+}
+export function macStr(b) {
+  return Array.from(b, x => x.toString(16).padStart(2, '0')).join(':')
+}
+
+/** The Internet checksum's running 32-bit sum over bytes [start, end). */
+export function sum16(u8, start, end, acc = 0) {
+  let i = start
+  for (; i + 1 < end; i += 2) acc += (u8[i] << 8) | u8[i + 1]
+  if (i < end) acc += u8[i] << 8
+  return acc
+}
+export function fold(acc) {
+  while (acc > 0xffff) acc = (acc & 0xffff) + Math.floor(acc / 0x10000)
+  return ~acc & 0xffff
+}
+
+const rd16 = (b, o) => (b[o] << 8) | b[o + 1]
+const rd32 = (b, o) => ((b[o] << 24) | (b[o + 1] << 16) | (b[o + 2] << 8) | b[o + 3]) >>> 0
+const wr16 = (b, o, v) => {
+  b[o] = (v >>> 8) & 255
+  b[o + 1] = v & 255
+}
+const wr32 = (b, o, v) => {
+  b[o] = (v >>> 24) & 255
+  b[o + 1] = (v >>> 16) & 255
+  b[o + 2] = (v >>> 8) & 255
+  b[o + 3] = v & 255
+}
+export { rd16, rd32, wr16, wr32 }
+
+/** Parse an Ethernet frame (no VLAN tags). */
+export function parseEth(f) {
+  if (f.length < ETH_HLEN) return null
+  return { dst: f.subarray(0, 6), src: f.subarray(6, 12), type: rd16(f, 12), payload: f.subarray(ETH_HLEN) }
+}
+
+/** ARP request/reply (Ethernet + IPv4 only). */
+export function parseArp(p) {
+  if (p.length < 28 || rd16(p, 0) !== 1 || rd16(p, 2) !== ETH_IPV4 || p[4] !== 6 || p[5] !== 4) return null
+  return { op: rd16(p, 6), sha: p.subarray(8, 14), spa: rd32(p, 14), tha: p.subarray(18, 24), tpa: rd32(p, 24) }
+}
+
+export function arpReply(myMac, myIp, toMac, toIp) {
+  const f = new Uint8Array(ETH_HLEN + 28)
+  f.set(toMac, 0)
+  f.set(myMac, 6)
+  wr16(f, 12, ETH_ARP)
+  const o = ETH_HLEN
+  wr16(f, o, 1)
+  wr16(f, o + 2, ETH_IPV4)
+  f[o + 4] = 6
+  f[o + 5] = 4
+  wr16(f, o + 6, 2)
+  f.set(myMac, o + 8)
+  wr32(f, o + 14, myIp)
+  f.set(toMac, o + 18)
+  wr32(f, o + 24, toIp)
+  return f
+}
+
+/** Parse an IPv4 packet. Fragments and bad headers return null. */
+export function parseIp(p) {
+  if (p.length < 20 || p[0] >> 4 !== 4) return null
+  const ihl = (p[0] & 15) * 4
+  const total = rd16(p, 2)
+  if (ihl < 20 || total < ihl || total > p.length) return null
+  const frag = rd16(p, 6)
+  if (frag & 0x2000 || frag & 0x1fff) return { fragment: true } // MF or an offset: not supported
+  return { proto: p[9], src: rd32(p, 12), dst: rd32(p, 16), ttl: p[8], header: p.subarray(0, ihl), payload: p.subarray(ihl, total) }
+}
+
+let ipId = 1
+/**
+ * A whole Ethernet + IPv4 frame with an l4len-byte transport part; fill(frame, offset)
+ * writes the transport bytes, then the IPv4 checksum (and the TCP/UDP checksum) is set.
+ */
+export function ipFrame(srcMac, dstMac, src, dst, proto, l4len, fill) {
+  const f = new Uint8Array(ETH_HLEN + 20 + l4len)
+  f.set(dstMac, 0)
+  f.set(srcMac, 6)
+  wr16(f, 12, ETH_IPV4)
+  const o = ETH_HLEN
+  f[o] = 0x45
+  wr16(f, o + 2, 20 + l4len)
+  wr16(f, o + 4, ipId)
+  ipId = (ipId + 1) & 0xffff
+  wr16(f, o + 6, 0x4000) // DF
+  f[o + 8] = 64
+  f[o + 9] = proto
+  wr32(f, o + 12, src)
+  wr32(f, o + 16, dst)
+  wr16(f, o + 10, fold(sum16(f, o, o + 20)))
+  const t = o + 20
+  fill(f, t)
+  if (proto === IP_TCP || proto === IP_UDP) {
+    const ck = proto === IP_TCP ? t + 16 : t + 6
+    f[ck] = f[ck + 1] = 0
+    let acc = sum16(f, o + 12, o + 20) + proto + l4len // pseudo-header
+    acc = sum16(f, t, t + l4len, acc)
+    let c = fold(acc)
+    if (proto === IP_UDP && c === 0) c = 0xffff
+    wr16(f, ck, c)
+  } else if (proto === IP_ICMP) {
+    f[t + 2] = f[t + 3] = 0
+    wr16(f, t + 2, fold(sum16(f, t, t + l4len)))
+  }
+  return f
+}
+
+export function parseUdp(p) {
+  if (p.length < 8) return null
+  const len = rd16(p, 4)
+  if (len < 8 || len > p.length) return null
+  return { sport: rd16(p, 0), dport: rd16(p, 2), payload: p.subarray(8, len) }
+}
+
+export function udpFrame(srcMac, dstMac, src, dst, sport, dport, data) {
+  return ipFrame(srcMac, dstMac, src, dst, IP_UDP, 8 + data.length, (f, t) => {
+    wr16(f, t, sport)
+    wr16(f, t + 2, dport)
+    wr16(f, t + 4, 8 + data.length)
+    f.set(data, t + 8)
+  })
+}
+
+/** Parse a TCP segment with its options (MSS, window scale). */
+export function parseTcp(p) {
+  if (p.length < 20) return null
+  const off = (p[12] >> 4) * 4
+  if (off < 20 || off > p.length) return null
+  const s = {
+    sport: rd16(p, 0), dport: rd16(p, 2), seq: rd32(p, 4), ack: rd32(p, 8), flags: p[13] & 0x3f, win: rd16(p, 14),
+    mss: 0, wscale: -1, payload: p.subarray(off),
+  }
+  if (s.flags & TCP_SYN) {
+    for (let i = 20; i < off; ) {
+      const kind = p[i]
+      if (kind === 0) break
+      if (kind === 1) {
+        i++
+        continue
+      }
+      const len = p[i + 1]
+      if (len < 2 || i + len > off) break
+      if (kind === 2 && len === 4) s.mss = rd16(p, i + 2)
+      else if (kind === 3 && len === 3) s.wscale = Math.min(p[i + 2], 14)
+      i += len
+    }
+  }
+  return s
+}
+
+/** A TCP segment frame. opts: {mss, wscale} only on SYN. */
+export function tcpFrame(srcMac, dstMac, src, dst, sport, dport, seq, ack, flags, win, data, opts) {
+  const olen = opts ? 8 : 0 // MSS (4) + NOP + window scale (3)
+  const dlen = data ? data.length : 0
+  return ipFrame(srcMac, dstMac, src, dst, IP_TCP, 20 + olen + dlen, (f, t) => {
+    wr16(f, t, sport)
+    wr16(f, t + 2, dport)
+    wr32(f, t + 4, seq)
+    wr32(f, t + 8, ack)
+    f[t + 12] = ((20 + olen) / 4) << 4
+    f[t + 13] = flags
+    wr16(f, t + 14, Math.min(win, 0xffff))
+    if (opts) {
+      f[t + 20] = 2
+      f[t + 21] = 4
+      wr16(f, t + 22, opts.mss)
+      f[t + 24] = 1
+      f[t + 25] = 3
+      f[t + 26] = 3
+      f[t + 27] = opts.wscale
+    }
+    if (dlen) f.set(data, t + 20 + olen)
+  })
+}
+
+/** ICMP destination unreachable (type 3) quoting the original IP header + 8 bytes. */
+export function icmpUnreachable(srcMac, dstMac, src, dst, code, origIp) {
+  const quote = origIp.subarray(0, Math.min(origIp.length, ((origIp[0] & 15) * 4) + 8))
+  return ipFrame(srcMac, dstMac, src, dst, IP_ICMP, 8 + quote.length, (f, t) => {
+    f[t] = 3
+    f[t + 1] = code
+    f.set(quote, t + 8)
+  })
+}
+
+/** ICMP echo reply for an echo request payload p (type 8). */
+export function icmpEchoReply(srcMac, dstMac, src, dst, p) {
+  return ipFrame(srcMac, dstMac, src, dst, IP_ICMP, p.length, (f, t) => {
+    f.set(p, t)
+    f[t] = 0
+    f[t + 1] = 0
+  })
+}
+
+/** Sequence-number comparisons (mod 2^32). */
+export const seqLt = (a, b) => ((a - b) | 0) < 0
+export const seqLe = (a, b) => ((a - b) | 0) <= 0
+export const seqDiff = (a, b) => (a - b) | 0 // a - b as a signed 32-bit number
+export const seqAdd = (a, n) => (a + n) >>> 0

package/src/net/peer.js

@@ -0,0 +1,230 @@
+// W56: the network Worker's side of an in-page switch (switch.js). It is the stack's transport for
+// connections between guests on the switch, as relay-client.js is for connections to the internet:
+// the stack calls connect / data / end / abort / credit and is called back (onConnected,
+// onRelayData, onRelayEnd, onRelayAbort, onRelayCredit) with the same stream ids. A connection a
+// peer opens to this guest comes in as stack.peerOpen(); the stack answers with accepted().
+//
+// Between two Workers (one MessagePort each way, from the switch), a stream is named by the id its
+// opener gave it and who opened it ("mine" is said by the sender):
+//   {t:'open', sid, sport, dport}     open a connection to this guest's dport, from the opener's guest
+//                                      port sport; the opener may be sent WINDOW bytes
+//   {t:'opened', sid, code, credit}   code 0: open, the opener may send `credit` bytes; else refused
+//   {t:'data', sid, mine, buf}        bytes (an ArrayBuffer), within the credit the other side gave
+//   {t:'end', sid, mine}              no more data (FIN)
+//   {t:'abort', sid, mine, code, reason}  reset
+//   {t:'credit', sid, mine, n}        the other side may send n more bytes
+// The flow control is the relay's (proto.js): each side has at most the credit the other gave in
+// flight, and gives credit back as its guest takes the bytes.
+
+import { E, WINDOW } from './proto.js'
+
+export class PeerNet {
+  /**
+   * @param {object} o
+   * @param {MessagePort} o.port  the switch's port (switch.js attach())
+   * @param {(line: string) => void} [o.log]
+   */
+  constructor(o) {
+    this.port = o.port
+    this.log = o.log || (() => {})
+    this.stack = null
+    this.names = new Map() // name -> ip (u32)
+    this.ips = new Set()
+    this.links = new Map() // peer ip -> {port, ip}
+    this.waiting = new Map() // peer ip -> [fn(link|null)] connects waiting for the switch's port
+    this.streams = new Map() // stack id -> {link, sid, mine}
+    this.remote = new Map() // `${ip}:${sid}` of streams a peer opened -> stack id
+    this.stats = { opened: 0, accepted: 0, refused: 0, linked: 0, gone: 0, sent: 0, received: 0 }
+    this.port.onmessage = e => this.#fromSwitch(e.data)
+  }
+
+  attach(stack) {
+    this.stack = stack
+  }
+
+  /** A guest on the switch has this address. */
+  has(ip) {
+    return this.ips.has(ip >>> 0)
+  }
+
+  /** The address of a guest's name on the switch (undefined if none). */
+  lookup(name) {
+    return this.names.get(name)
+  }
+
+  #fromSwitch(x) {
+    if (x.t === 'table') {
+      this.names = new Map(x.members.map(m => [m.name, m.ip >>> 0]))
+      this.ips = new Set(x.members.map(m => m.ip >>> 0))
+    } else if (x.t === 'link') this.#linked(x.ip >>> 0, x.port)
+    else if (x.t === 'nolink') this.#ready(x.ip >>> 0, null)
+    else if (x.t === 'gone') this.#gone(x.ip >>> 0)
+  }
+
+  #linked(ip, port) {
+    const old = this.links.get(ip)
+    if (old) this.#gone(ip) // a new link replaces a stale one (the peer left and came back)
+    const link = { ip, port }
+    this.links.set(ip, link)
+    this.stats.linked++
+    port.onmessage = e => this.#fromPeer(link, e.data)
+    this.#ready(ip, link)
+  }
+
+  #ready(ip, link) {
+    const w = this.waiting.get(ip)
+    if (!w) return
+    this.waiting.delete(ip)
+    for (const f of w) f(link)
+  }
+
+  #gone(ip) {
+    const link = this.links.get(ip)
+    this.#ready(ip, null)
+    if (!link) return
+    this.links.delete(ip)
+    this.stats.gone++
+    link.port.onmessage = null
+    link.port.close()
+    for (const [id, s] of [...this.streams]) {
+      if (s.link !== link) continue
+      this.#forget(id)
+      this.stack.onRelayAbort(id, E.GONE, 'the peer left the network')
+    }
+  }
+
+  #forget(id) {
+    const s = this.streams.get(id)
+    if (!s) return
+    this.streams.delete(id)
+    if (!s.mine) this.remote.delete(`${s.link.ip}:${s.sid}`)
+  }
+
+  #withLink(ip, f) {
+    const link = this.links.get(ip)
+    if (link) return f(link)
+    let w = this.waiting.get(ip)
+    if (!w) {
+      w = []
+      this.waiting.set(ip, w)
+      this.port.postMessage({ t: 'link', ip })
+    }
+    w.push(f)
+  }
+
+  #send(s, m, transfer) {
+    s.link.port.postMessage(m, transfer)
+  }
+
+  // ---- the stack's transport (outbound streams and both directions' data) ----
+
+  /** Open stream id to the peer at host (a u32 or dotted string), from this guest's port sport. */
+  connect(id, host, port, sport) {
+    const ip = typeof host === 'number' ? host >>> 0 : ipU32(host)
+    this.#withLink(ip, link => {
+      if (!this.stack.hasConn(id)) return // given up meanwhile
+      if (!link) return this.stack.onConnected(id, E.UNREACHABLE, 0, 'no guest has that address')
+      const s = { link, sid: id, mine: true }
+      this.streams.set(id, s)
+      this.stats.opened++
+      this.#send(s, { t: 'open', sid: id, sport, dport: port })
+    })
+  }
+
+  data(id, u8) {
+    const s = this.streams.get(id)
+    if (!s) return
+    const buf = u8.slice().buffer
+    this.stats.sent += u8.length
+    this.#send(s, { t: 'data', sid: s.sid, mine: s.mine, buf }, [buf])
+  }
+
+  end(id) {
+    const s = this.streams.get(id)
+    if (s) this.#send(s, { t: 'end', sid: s.sid, mine: s.mine })
+  }
+
+  abort(id, code = E.RESET, reason = '') {
+    const s = this.streams.get(id)
+    if (!s) return
+    this.#forget(id)
+    this.#send(s, { t: 'abort', sid: s.sid, mine: s.mine, code, reason })
+  }
+
+  credit(id, n) {
+    const s = this.streams.get(id)
+    if (s) this.#send(s, { t: 'credit', sid: s.sid, mine: s.mine, n })
+  }
+
+  /** The stack's answer to an inbound open (stack.peerOpen): E.OK once the guest accepted, else why not. */
+  accepted(id, code, reason = '') {
+    const s = this.streams.get(id)
+    if (!s) return
+    if (code === E.OK) this.stats.accepted++
+    else {
+      this.stats.refused++
+      this.#forget(id)
+    }
+    this.#send(s, { t: 'opened', sid: s.sid, code, credit: code === E.OK ? WINDOW : 0, reason })
+  }
+
+  // ---- from a peer ----
+
+  #fromPeer(link, x) {
+    if (this.links.get(link.ip) !== link) return
+    if (x.t === 'open') {
+      const key = `${link.ip}:${x.sid}`
+      if (this.remote.has(key)) return
+      const id = this.stack.peerOpen(link.ip, x.sport, x.dport, this)
+      if (id === null) {
+        link.port.postMessage({ t: 'opened', sid: x.sid, code: E.REFUSED, credit: 0 })
+        return
+      }
+      this.remote.set(key, id)
+      this.streams.set(id, { link, sid: x.sid, mine: false })
+      return
+    }
+    // the sender's "mine" is from its side: its stream is one a peer opened here
+    const id = x.t === 'opened' || !x.mine ? x.sid : this.remote.get(`${link.ip}:${x.sid}`)
+    const s = id === undefined ? null : this.streams.get(id)
+    if (!s || s.link !== link) return
+    switch (x.t) {
+      case 'opened':
+        if (x.code !== E.OK) this.#forget(id)
+        this.stack.onConnected(id, x.code, x.credit, x.reason || '')
+        break
+      case 'data':
+        this.stats.received += x.buf.byteLength
+        this.stack.onRelayData(id, new Uint8Array(x.buf))
+        break
+      case 'end':
+        this.stack.onRelayEnd(id)
+        break
+      case 'abort':
+        this.#forget(id)
+        this.stack.onRelayAbort(id, x.code ?? E.RESET, x.reason || '')
+        break
+      case 'credit':
+        this.stack.onRelayCredit(id, x.n)
+        break
+    }
+  }
+
+  /** The stack forgot a stream (it ended cleanly): drop its record. */
+  closed(id) {
+    this.#forget(id)
+  }
+
+  snapshot() {
+    return { ...this.stats, links: this.links.size, streams: this.streams.size, names: Object.fromEntries([...this.names].map(([n, ip]) => [n, ipStr(ip)])) }
+  }
+}
+
+function ipU32(s) {
+  const p = String(s).split('.').map(Number)
+  return (((p[0] << 24) | (p[1] << 16) | (p[2] << 8) | p[3]) >>> 0)
+}
+
+function ipStr(v) {
+  return `${v >>> 24}.${(v >>> 16) & 255}.${(v >>> 8) & 255}.${v & 255}`
+}