@threadedstack/wmd-web 0.0.0-stage → 0.1.13

package/src/host/ctl.js

@@ -0,0 +1,778 @@
+// P-B11 (ROADMAP 2.2b): wmd's control protocol, the page's half
+// (internal/engine/ctlproto.go, control.go; the guest's guest/container2wasm/cmd/init
+// control.go, procs.go).
+//
+// One yamux stream per operation (the yamux client runs in the channel service Worker,
+// yamux.js; this module sees each stream as bytes in and out):
+//  1. The host writes one JSON request line: {"op":"run"|"exec"|"kill"|"attach"|"procs"|
+//     "pause"|"resume"|"ps"|"stats"|"step"|"resync", "id", "args", "env", "cwd", "user",
+//     "tty", "sig", "all", "ps_args", "now", "seed" (base64 of 32 bytes, Go's []byte),
+//     "p9tag", "p9opts", "ckpt", ...}; empty fields are left out (Go's omitempty).
+//  2. run / exec / step: frames both ways, id[1] | length[4] big-endian | payload; ids 0
+//     control (JSON {"resize":[rows,cols]} or {"close_stdin":true}), 1 stdin, 2 stdout,
+//     3 stderr, 4 exit (4-byte BE code, optionally 4 more bytes of flags, bit 0 "synced").
+//     The host sends close_stdin at once when there is no stdin (control.go).
+//  3. attach: one JSON line ({"ok","error","state","code","buffered","dropped"}), then the
+//     frames of the process (the ring it kept while detached first), as for run/exec.
+//  4. Other ops: one JSON response line {"ok","error","exit_code","titles","rows","stats","ids"}.
+// A stream that ends without an exit frame is exit 125 (control.go runProcessExit).
+
+export const STREAM_CONTROL = 0
+export const STREAM_STDIN = 1
+export const STREAM_STDOUT = 2
+export const STREAM_STDERR = 3
+export const STREAM_EXIT = 4
+export const EXIT_SYNCED = 1
+/** readFrame's sanity limit (ctlproto.go). */
+export const MAX_CTL_FRAME = 10 * 1024 * 1024
+export const MAIN_PROC_ID = 'main'
+
+const enc = new TextEncoder()
+
+/** One frame: id | len BE | payload. */
+export function encodeFrame(id, payload = new Uint8Array(0)) {
+  const p = typeof payload === 'string' ? enc.encode(payload) : payload
+  const f = new Uint8Array(5 + p.length)
+  f[0] = id
+  new DataView(f.buffer).setUint32(1, p.length)
+  f.set(p, 5)
+  return f
+}
+
+/** The exit frame's payload: {code, synced} (ctlproto.go parseExitFrame). */
+export function parseExitFrame(p) {
+  if (p.length < 4) return { code: 125, synced: false }
+  const dv = new DataView(p.buffer, p.byteOffset, p.length)
+  return { code: dv.getInt32(0), synced: p.length >= 8 && (dv.getUint32(4) & EXIT_SYNCED) !== 0 }
+}
+
+/** base64 of bytes (Go encodes []byte in JSON as standard base64). */
+export function base64(u8) {
+  let s = ''
+  for (let i = 0; i < u8.length; i++) s += String.fromCharCode(u8[i])
+  return btoa(s)
+}
+
+/** The request line, with Go's omitempty: empty strings, false, 0 and empty lists are left out. */
+export function requestLine(req) {
+  const o = {}
+  for (const [k, v] of Object.entries(req)) {
+    if (v === undefined || v === null || v === '' || v === false || v === 0) continue
+    if (Array.isArray(v) && !v.length) continue
+    o[k] = v instanceof Uint8Array ? base64(v) : v
+  }
+  if (!o.op) throw new Error('control request without op')
+  return enc.encode(JSON.stringify(o) + '\n')
+}
+
+/**
+ * What the engine adds to a run request (run.go fillRunRequest): the host clock, 32 bytes
+ * of entropy (crypto.getRandomValues: the guest has no entropy device, P-B3 problem 2),
+ * the share's 9P tag and the guest's mount options. The browser mounts with cache=mmap
+ * (p9mount.js), not the native engine's cache=loose.
+ */
+export function fillRunRequest(req, { p9opts, now = Date.now(), random = globalThis.crypto } = {}) {
+  if (!p9opts) throw new Error('fillRunRequest: p9opts is required (the init refuses a first run without it)')
+  const seed = new Uint8Array(32)
+  random.getRandomValues(seed)
+  return { ...req, now: Math.floor(now / 1000), seed, p9tag: 'wmdroot', p9opts }
+}
+
+function cat(a, b) {
+  const o = new Uint8Array(a.length + b.length)
+  o.set(a)
+  o.set(b, a.length)
+  return o
+}
+
+/** Bytes kept as chunks: appending costs no copy, only taking does (no O(n^2) on small pieces). */
+class ByteQueue {
+  constructor() {
+    this.chunks = []
+    this.off = 0 // into chunks[0]
+    this.length = 0
+  }
+  push(u8) {
+    if (u8.length) {
+      this.chunks.push(u8)
+      this.length += u8.length
+    }
+  }
+  /** The first n bytes (n <= length), copied; removed when take is true. */
+  read(n, take) {
+    const out = new Uint8Array(n)
+    let got = 0
+    let i = 0
+    let off = this.off
+    while (got < n) {
+      const c = this.chunks[i]
+      const k = Math.min(n - got, c.length - off)
+      out.set(c.subarray(off, off + k), got)
+      got += k
+      off += k
+      if (off === c.length) {
+        i++
+        off = 0
+      }
+    }
+    if (take) {
+      this.chunks.splice(0, i)
+      this.off = off
+      this.length -= n
+    }
+    return out
+  }
+}
+
+/** Splits a byte stream into frames. Throws on a frame over MAX_CTL_FRAME. */
+export class FrameReader {
+  constructor() {
+    this.q = new ByteQueue()
+    this.need = -1 // payload length of the frame whose header is read, or -1
+    this.id = 0
+  }
+  /** Returns the whole frames now available: [{id, payload}]. */
+  push(u8) {
+    this.q.push(u8)
+    const out = []
+    for (;;) {
+      if (this.need < 0) {
+        if (this.q.length < 5) break
+        const h = this.q.read(5, true)
+        const n = new DataView(h.buffer).getUint32(1)
+        if (n > MAX_CTL_FRAME) throw new Error(`control frame too large: ${n} bytes`)
+        this.id = h[0]
+        this.need = n
+      }
+      if (this.q.length < this.need) break
+      out.push({ id: this.id, payload: this.q.read(this.need, true) })
+      this.need = -1
+    }
+    return out
+  }
+}
+
+/** Splits off the first line (for response and attach lines). */
+export class LineReader {
+  constructor(max = 1 << 20) {
+    this.buf = new Uint8Array(0)
+    this.max = max
+  }
+  /** Returns {line, rest} once a newline came, else null. */
+  push(u8) {
+    this.buf = this.buf.length ? cat(this.buf, u8) : u8
+    const nl = this.buf.indexOf(10)
+    if (nl < 0) {
+      if (this.buf.length > this.max) throw new Error('control: response line too long')
+      return null
+    }
+    const line = new TextDecoder().decode(this.buf.subarray(0, nl))
+    const rest = this.buf.slice(nl + 1)
+    this.buf = new Uint8Array(0)
+    return { line, rest }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// The client. transport: {post(msg)}; the boot wires post() to the channel service
+// Worker and calls client.onEvents(evs) with what the service sends:
+//   {ev:'session', up, epoch, why?}          the guest opened (or lost) the control port
+//   {ev:'data', k, bytes}                     bytes on stream k (the page acks them)
+//   {ev:'fin', k}                             the guest closed its side of stream k
+//   {ev:'closed', k, why}                     stream k is gone (why null: both sides closed)
+// Messages to the service ({t:'ctl', ...}):
+//   {op:'open', k, bytes}  {op:'write', k, bytes}  {op:'close', k} (FIN)
+//   {op:'reset', k}        {op:'ack', k, n}
+// ---------------------------------------------------------------------------
+
+/** Bytes the page may have posted to a stream that the service has not sent on yet
+ * (stdin backpressure): past it, CtlProcess.write refuses and writeAsync waits. 4 MiB of
+ * data plus room for the request line and frame headers, so one write of up to 4 MiB
+ * goes whole to an idle stream. */
+export const STREAM_CREDIT = (4 << 20) + (64 << 10)
+/** Streams the page has open at once; more wait their turn. The guest's yamux server
+ * resets streams it cannot queue for accept (AcceptBacklog 256). */
+export const MAX_OPEN_STREAMS = 128
+
+export class CtlStream {
+  constructor(client, k) {
+    this.client = client
+    this.k = k
+    this.onBytes = null
+    this.onFin = null
+    this.ended = false // closed (both sides) or reset
+    this.why = null
+    this.opened = false // the open has been posted (MAX_OPEN_STREAMS)
+    this.queued = [] // messages before the open went out
+    this.inflight = 0 // bytes posted and not yet sent on by the service
+    this.gotBytes = 0
+    this.creditWaiters = []
+    let resolve
+    this.closed = new Promise(r => (resolve = r))
+    this._resolve = resolve
+  }
+  _post(m) {
+    if (this.opened) this.client.transport.post(m)
+    else this.queued.push(m)
+  }
+  /** Posts u8 (counted against STREAM_CREDIT). False once the stream has ended. */
+  write(u8) {
+    if (this.ended) return false
+    this.inflight += u8.length
+    this._post({ t: 'ctl', op: 'write', k: this.k, bytes: u8 })
+    return true
+  }
+  /** Bytes that may be posted now without passing STREAM_CREDIT. */
+  credit() {
+    return Math.max(0, STREAM_CREDIT - this.inflight)
+  }
+  /** Resolves when credit() >= n (or at once if the stream ended). */
+  waitCredit(n) {
+    if (this.ended || this.credit() >= Math.min(n, STREAM_CREDIT)) return Promise.resolve()
+    return new Promise(r => this.creditWaiters.push({ n: Math.min(n, STREAM_CREDIT), r }))
+  }
+  _sent(n) {
+    this.inflight = Math.max(0, this.inflight - n)
+    this._wake()
+  }
+  _wake() {
+    const w = this.creditWaiters
+    this.creditWaiters = []
+    for (const x of w) {
+      if (this.ended || this.credit() >= x.n) x.r()
+      else this.creditWaiters.push(x)
+    }
+  }
+  closeWrite() {
+    if (!this.ended) this._post({ t: 'ctl', op: 'close', k: this.k })
+  }
+  reset() {
+    if (!this.ended) this._post({ t: 'ctl', op: 'reset', k: this.k })
+  }
+}
+
+/**
+ * A run, exec or attach: stdout/stderr callbacks, stdin, and `exited`
+ * ({code, synced, error?}). As control.go runProcessExit: a stream that ends without an
+ * exit frame gives 125 and the error.
+ *
+ * stdin: write() takes bytes only while the stream's credit allows (STREAM_CREDIT posted
+ * and not yet sent on to the guest) and returns false otherwise, sending nothing;
+ * writeAsync() queues and resolves once its bytes are posted, waiting for credit as the
+ * guest's yamux window lets the service send. Nothing is queued without bound.
+ */
+export class CtlProcess {
+  constructor(stream, { onStdout, onStderr, onControl, op = '', mapExec = false } = {}) {
+    this.stream = stream
+    this.onStdout = onStdout
+    this.onStderr = onStderr
+    this.onControl = onControl
+    this.op = op
+    this.mapExec = mapExec
+    this.frames = new FrameReader()
+    this.exit = null
+    this.stdinClosed = false
+    this.closeAfterQueue = false
+    this.queue = [] // writeAsync data waiting for credit, in order
+    this.pumping = false
+    this.bytes = { stdout: 0, stderr: 0, stdin: 0 }
+    this.errTail = '' // the last stderr text, for exec failures crun reports (mapExec)
+    this.sawStdout = false
+    let resolve
+    this.exited = new Promise(r => (resolve = r))
+    this._resolve = resolve
+  }
+  _frames(u8) {
+    let frames
+    try {
+      frames = this.frames.push(u8)
+    } catch (e) {
+      this.stream.reset()
+      this._end(e.message)
+      return
+    }
+    for (const f of frames) {
+      if (f.id === STREAM_STDOUT) {
+        this.bytes.stdout += f.payload.length
+        this.sawStdout = true
+        this.onStdout?.(f.payload)
+      } else if (f.id === STREAM_STDERR) {
+        this.bytes.stderr += f.payload.length
+        let p = f.payload
+        if (this.mapExec && !this.sawStdout) {
+          const text = new TextDecoder().decode(p)
+          this.errTail = (this.errTail + text).slice(-8192)
+          const clean = cleanRuntimeText(text)
+          if (clean !== text) p = enc.encode(clean)
+        }
+        this.onStderr?.(p)
+      } else if (f.id === STREAM_EXIT) {
+        if (!this.exit) {
+          this.exit = parseExitFrame(f.payload)
+          if (this.mapExec && this.exit.code === 1 && !this.sawStdout) {
+            // as the init does for run (control.go crunExecStatus), which it does not for exec
+            const code = crunExecStatus(this.errTail)
+            if (code) {
+              this.exit.code = code
+              this.exit.error = cleanRuntimeText(this.errTail.trim().split('\n').at(-1) || '')
+            }
+          }
+          this.stream.closeWrite() // nothing more to say; the guest closes its side
+          this._resolve({ ...this.exit })
+        }
+      } else if (f.id === STREAM_CONTROL) this.onControl?.(f.payload)
+    }
+  }
+  _end(why) {
+    if (this.exit) return
+    this.exit = { code: 125, synced: false, error: why || 'process stream closed' }
+    this._resolve({ ...this.exit })
+    this.stream._wake()
+  }
+  #frame(p) {
+    return encodeFrame(STREAM_STDIN, p)
+  }
+  /**
+   * Bytes (or text) for stdin, now: true when all of it was posted (in frames of at most
+   * 1 MiB), false (nothing sent) when the credit does not allow it, writeAsync data is
+   * still waiting, stdin is closed or the process has ended.
+   */
+  write(data) {
+    if (this.stdinClosed || this.closeAfterQueue || this.exit || this.queue.length) return false
+    const p = typeof data === 'string' ? enc.encode(data) : data
+    const need = p.length + 5 * Math.ceil(p.length / (1 << 20))
+    if (need > this.stream.credit()) return false
+    this.bytes.stdin += p.length
+    for (let o = 0; o < p.length; o += 1 << 20) this.stream.write(this.#frame(p.subarray(o, Math.min(p.length, o + (1 << 20)))))
+    return true
+  }
+  /** Queues bytes (or text) for stdin; resolves true once all are posted, false if the process ended first. */
+  writeAsync(data) {
+    const p = typeof data === 'string' ? enc.encode(data) : data
+    if (this.stdinClosed || this.closeAfterQueue || this.exit) return Promise.resolve(false)
+    return new Promise(resolve => {
+      this.queue.push({ p, off: 0, resolve })
+      this.#pump()
+    })
+  }
+  async #pump() {
+    if (this.pumping) return
+    this.pumping = true
+    while (this.queue.length) {
+      const item = this.queue[0]
+      if (this.exit || this.stream.ended) {
+        for (const q of this.queue.splice(0)) q.resolve(false)
+        break
+      }
+      const chunk = Math.min(item.p.length - item.off, 1 << 20)
+      await this.stream.waitCredit(chunk + 5)
+      if (this.exit || this.stream.ended) continue
+      const n = Math.min(chunk, Math.max(1, this.stream.credit() - 5))
+      this.stream.write(this.#frame(item.p.subarray(item.off, item.off + n)))
+      this.bytes.stdin += n
+      item.off += n
+      if (item.off >= item.p.length) {
+        this.queue.shift()
+        item.resolve(true)
+      }
+    }
+    this.pumping = false
+    if (this.closeAfterQueue && !this.queue.length) {
+      this.closeAfterQueue = false
+      this.#closeNow()
+    }
+  }
+  /** Resolves when every writeAsync byte has been posted. */
+  drained() {
+    if (!this.queue.length) return Promise.resolve()
+    return new Promise(r => this.queue[this.queue.length - 1].resolve = (orig => v => (orig(v), r()))(this.queue[this.queue.length - 1].resolve))
+  }
+  /** close_stdin, after any writeAsync data still queued. */
+  closeStdin() {
+    if (this.stdinClosed || this.exit) return
+    if (this.queue.length) {
+      this.closeAfterQueue = true
+      return
+    }
+    this.#closeNow()
+  }
+  #closeNow() {
+    if (this.stdinClosed || this.exit) return
+    this.stdinClosed = true
+    this.stream.write(encodeFrame(STREAM_CONTROL, JSON.stringify({ close_stdin: true })))
+  }
+  resize(rows, cols) {
+    if (!this.exit) this.stream.write(encodeFrame(STREAM_CONTROL, JSON.stringify({ resize: [rows, cols] })))
+  }
+}
+
+/** The init's name for the container (crun's id); never shown to the user. */
+const CRUN_ID = 'foo'
+
+/** crun's messages with the internal container id taken out. */
+export function cleanRuntimeText(t) {
+  return t
+    .replaceAll(`the container \`${CRUN_ID}\``, 'the container')
+    .replaceAll(`container \`${CRUN_ID}\``, 'the container')
+    .replaceAll(`\`/run/crun/${CRUN_ID}/config.json\``, "the container's state")
+    .replaceAll(`/run/crun/${CRUN_ID}/`, '')
+}
+
+/** The init's crunExecStatus (control.go): 127 not found, 126 not executable, else 0. */
+export function crunExecStatus(log) {
+  for (const line of log.split('\n')) {
+    const l = line.replace(/^[^:]*crun: /, '').replace(/^Error: /, '')
+    if (/executable file `.*` not found/.test(l)) return 127
+    if (/the path `.*` exists but it is not executable/.test(l)) return 126
+    if (/exec container process `.*`: Permission denied$/.test(l)) return 126
+    if (/exec container process `.*`: No such file or directory$/.test(l)) return 127
+  }
+  return 0
+}
+
+export class ControlClient {
+  constructor(transport) {
+    this.transport = transport
+    this.streams = new Map()
+    this.nextK = 1
+    this.session = { up: false, epoch: 0, why: null }
+    this.waiters = []
+    this.acks = new Map()
+    this.waitingOpens = [] // streams past MAX_OPEN_STREAMS, in order
+    this.openNow = 0
+    this.ids = new Set() // run/exec ids of this page's processes that have not exited
+    this.stats = { opened: 0, bytesIn: 0, sessionUpAt: 0, queuedOpens: 0 }
+  }
+
+  onEvents(evs) {
+    for (const e of evs) this.#event(e)
+    this.#flushAcks()
+  }
+
+  #event(e) {
+    if (e.ev === 'session') {
+      this.session = { up: e.up, epoch: e.epoch, why: e.why || null }
+      if (e.up) {
+        if (!this.stats.sessionUpAt) this.stats.sessionUpAt = performance.now()
+        const w = this.waiters
+        this.waiters = []
+        for (const x of w) {
+          clearTimeout(x.timer)
+          x.resolve()
+        }
+      }
+      return
+    }
+    const s = this.streams.get(e.k)
+    if (!s) return
+    if (e.ev === 'data') {
+      const u8 = new Uint8Array(e.bytes)
+      this.stats.bytesIn += u8.length
+      s.gotBytes += u8.length
+      s.onBytes?.(u8)
+      // acked once delivered: a page that stops serving events stops the guest (backpressure)
+      this.acks.set(e.k, (this.acks.get(e.k) || 0) + u8.length)
+    } else if (e.ev === 'sent') s._sent(e.n)
+    else if (e.ev === 'fin') s.onFin?.()
+    else if (e.ev === 'closed') {
+      s.ended = true
+      s.why = e.why === 'reset by the guest' && !s.gotBytes
+        ? 'the guest refused the stream before any reply (reset: its yamux server queues at most 256 streams waiting to be accepted)'
+        : e.why
+      this.streams.delete(e.k)
+      this.acks.delete(e.k)
+      if (s.opened) {
+        this.openNow--
+        this.#openNext()
+      }
+      s._wake()
+      s._resolve(s.why)
+    }
+  }
+
+  #openNext() {
+    while (this.waitingOpens.length && this.openNow < MAX_OPEN_STREAMS) this.#postOpen(this.waitingOpens.shift())
+  }
+
+  #postOpen({ s, line }) {
+    this.openNow++
+    s.opened = true
+    s.inflight += line.length
+    this.transport.post({ t: 'ctl', op: 'open', k: s.k, bytes: line })
+    for (const m of s.queued.splice(0)) this.transport.post(m)
+  }
+
+  #flushAcks() {
+    for (const [k, n] of this.acks) this.transport.post({ t: 'ctl', op: 'ack', k, n })
+    this.acks.clear()
+  }
+
+  /**
+   * Resolves once the guest has opened the control port (the yamux session is up). Rejects at once, with the
+   * reason, when the machine has ended or its channel service has died (fail()): a wait on a machine that is
+   * gone must not run out its timeout.
+   */
+  waitSession(timeoutMs = 600_000) {
+    if (this.session.up) return Promise.resolve()
+    if (this.failure) return Promise.reject(new Error(this.failure))
+    return new Promise((resolve, reject) => {
+      const t = setTimeout(() => {
+        this.waiters = this.waiters.filter(w => w.timer !== t)
+        reject(new Error(`the guest did not open the control channel within ${timeoutMs} ms`))
+      }, timeoutMs)
+      this.waiters.push({ timer: t, resolve, reject })
+    })
+  }
+
+  /** The machine is over (it exited, trapped, or the channel service died): every wait rejects with `message` now. */
+  fail(message) {
+    if (this.failure) return
+    this.failure = message
+    const w = this.waiters
+    this.waiters = []
+    for (const x of w) {
+      clearTimeout(x.timer)
+      x.reject(new Error(message))
+    }
+  }
+
+  /** A stream with the request line sent. */
+  openStream(req) {
+    const line = requestLine(req)
+    const k = this.nextK++
+    const s = new CtlStream(this, k)
+    this.streams.set(k, s)
+    this.stats.opened++
+    if (this.openNow < MAX_OPEN_STREAMS) this.#postOpen({ s, line })
+    else {
+      this.stats.queuedOpens++
+      this.waitingOpens.push({ s, line })
+    }
+    return s
+  }
+
+  /** A stream that ends at once with `why` (a request refused on the page). */
+  #refused(why) {
+    const s = new CtlStream(this, this.nextK++)
+    s.ended = true
+    s.why = why
+    queueMicrotask(() => s._resolve(why))
+    return s
+  }
+
+  /** run / exec / step: a CtlProcess. stdin: false sends close_stdin at once (control.go). */
+  process(req, { stdin = false, ...handlers } = {}) {
+    const bad = checkProcessRequest(req, this.ids)
+    const s = bad ? this.#refused(bad) : this.openStream(req)
+    const p = new CtlProcess(s, { ...handlers, op: req.op, mapExec: req.op === 'exec' })
+    if (!bad && req.id && (req.op === 'exec' || req.op === 'run')) {
+      this.ids.add(req.id)
+      p.exited.then(() => this.ids.delete(req.id))
+    }
+    s.onBytes = u8 => p._frames(u8)
+    s.closed.then(why => p._end(why || 'process stream closed'))
+    if (!stdin && !bad) p.closeStdin()
+    return p
+  }
+
+  run(req, o) {
+    return this.process({ ...req, op: 'run' }, o)
+  }
+
+  /** op "exec" (runc exec in the container). */
+  startExec(req, o) {
+    return this.process({ ...req, op: 'exec' }, o)
+  }
+
+  /** attach (W3.4): {reply, proc}; proc is null when the reply is an error. */
+  attach(id, handlers = {}) {
+    const s = this.openStream({ op: 'attach', id })
+    const lines = new LineReader()
+    return new Promise((resolve, reject) => {
+      let proc = null
+      s.onBytes = u8 => {
+        if (proc) return proc._frames(u8)
+        let got
+        try {
+          got = lines.push(u8)
+        } catch (e) {
+          s.reset()
+          return reject(e)
+        }
+        if (!got) return
+        let reply
+        try {
+          reply = JSON.parse(got.line)
+        } catch {
+          s.reset()
+          return reject(new Error(`attach ${id}: bad reply ${JSON.stringify(got.line.slice(0, 200))}`))
+        }
+        if (!reply.ok) {
+          s.closeWrite()
+          return resolve({ reply, proc: null })
+        }
+        proc = new CtlProcess(s, handlers)
+        s.closed.then(why => proc._end(why || 'process stream closed'))
+        resolve({ reply, proc })
+        if (got.rest.length) proc._frames(got.rest)
+      }
+      s.closed.then(why => {
+        if (!proc) reject(new Error(`attach ${id}: the stream closed before the reply${why ? `: ${why}` : ''}`))
+      })
+    })
+  }
+
+  /** kill / procs / pause / resume / ps / stats: the JSON response. */
+  simple(req) {
+    const s = this.openStream(req)
+    const lines = new LineReader()
+    return new Promise((resolve, reject) => {
+      let done = false
+      s.onBytes = u8 => {
+        if (done) return
+        let got
+        try {
+          got = lines.push(u8)
+        } catch (e) {
+          done = true
+          s.reset()
+          return reject(e)
+        }
+        if (!got) return
+        done = true
+        s.closeWrite()
+        try {
+          resolve(JSON.parse(got.line))
+        } catch {
+          reject(new Error(`control ${req.op}: bad response ${JSON.stringify(got.line.slice(0, 200))}`))
+        }
+      }
+      s.closed.then(why => {
+        if (!done) reject(new Error(`control ${req.op}: the stream closed before a response${why ? `: ${why}` : ''}`))
+      })
+    })
+  }
+
+  kill({ id, sig = '', all = false } = {}) {
+    return this.simple({ op: 'kill', id, sig, all })
+  }
+
+  procs() {
+    return this.simple({ op: 'procs' })
+  }
+}
+
+/**
+ * Why a run/exec request cannot go to the guest, or null. The init would answer some of
+ * these with a bare 125 (a NUL in an argument or env entry: Go's exec refuses it) or run
+ * them anyway (an id already in use by a process of this page).
+ */
+export function checkProcessRequest(req, liveIds = new Set()) {
+  if ((req.op === 'exec' || req.op === 'run') && (!Array.isArray(req.args) || !req.args.length) && req.op === 'exec') {
+    return 'exec: no command (args is empty)'
+  }
+  for (const [what, list] of [['argument', req.args || []], ['environment entry', req.env || []]]) {
+    for (let i = 0; i < list.length; i++) {
+      if (typeof list[i] !== 'string') return `${req.op}: ${what} ${i} is not a string`
+      if (list[i].includes('\0')) return `${req.op}: ${what} ${i} contains a NUL byte, which a process cannot be given (${JSON.stringify(list[i].slice(0, 40))})`
+    }
+  }
+  if (req.cwd && req.cwd.includes('\0')) return `${req.op}: the working directory contains a NUL byte`
+  if (req.id && liveIds.has(req.id)) return `${req.op}: the process id ${JSON.stringify(req.id)} is already in use by a running process`
+  return null
+}
+
+// ---------------------------------------------------------------------------
+// The bundle: the OCI runtime spec as the engine writes it (internal/engine/ocispec.go
+// buildSpec, bundle.go writeBundle), for the guest init's config/config.json.
+// ---------------------------------------------------------------------------
+
+export const GUEST_9P_MOUNT = '/run/wmd9p'
+export const DEFAULT_CAPS = [
+  'CAP_CHOWN', 'CAP_DAC_OVERRIDE', 'CAP_FSETID', 'CAP_FOWNER', 'CAP_MKNOD', 'CAP_NET_RAW', 'CAP_SETGID',
+  'CAP_SETUID', 'CAP_SETFCAP', 'CAP_SETPCAP', 'CAP_NET_BIND_SERVICE', 'CAP_SYS_CHROOT', 'CAP_KILL', 'CAP_AUDIT_WRITE',
+]
+const MASKED = ['/proc/acpi', '/proc/asound', '/proc/kcore', '/proc/keys', '/proc/latency_stats', '/proc/timer_list', '/proc/timer_stats', '/proc/sched_debug', '/proc/scsi', '/sys/firmware']
+const READONLY = ['/proc/bus', '/proc/fs', '/proc/irq', '/proc/sys', '/proc/sysrq-trigger']
+const ETC_FILES = ['hosts', 'resolv.conf', 'hostname']
+
+function defaultMounts() {
+  return [
+    { destination: '/proc', type: 'proc', source: 'proc', options: ['nosuid', 'noexec', 'nodev'] },
+    { destination: '/dev', type: 'tmpfs', source: 'tmpfs', options: ['nosuid', 'strictatime', 'mode=755', 'size=65536k'] },
+    { destination: '/dev/pts', type: 'devpts', source: 'devpts', options: ['nosuid', 'noexec', 'newinstance', 'ptmxmode=0666', 'mode=0620', 'gid=5'] },
+    { destination: '/dev/shm', type: 'tmpfs', source: 'shm', options: ['nosuid', 'noexec', 'nodev', 'mode=1777', 'size=65536k'] },
+    { destination: '/dev/mqueue', type: 'mqueue', source: 'mqueue', options: ['nosuid', 'noexec', 'nodev'] },
+    { destination: '/sys', type: 'sysfs', source: 'sysfs', options: ['nosuid', 'noexec', 'nodev', 'ro'] },
+  ]
+}
+
+/**
+ * The 9P tree's files for a container (paths relative to the share root, beside the
+ * rootfs/ the packs give): bundle/config/config.json, bundle/config/imageconfig.json,
+ * bundle/etc/{hosts,resolv.conf,hostname}, and one share per mount (vol0, vol1, ...)
+ * holding the mount's files.
+ *
+ * @param {object} o
+ * @param {string[]} o.args          process args
+ * @param {string[]} [o.env]
+ * @param {string} [o.cwd]           default "/"
+ * @param {{uid:number, gid:number, additionalGids?:number[]}} [o.user]  numeric (the engine resolves names on the host)
+ * @param {boolean} [o.terminal]
+ * @param {string} [o.hostname]      default "localhost"
+ * @param {boolean} [o.networkDisabled]  no address line in /etc/hosts, empty resolv.conf (default true: no network yet)
+ * @param {{destination:string, files:Record<string,{data:Uint8Array|string, mode?:number}|string>, file?:string, readOnly?:boolean}[]} [o.mounts]
+ *        each mount is a share vol<i> with these files; `file` binds only that file of the share
+ * @param {string} [o.arch]          for imageconfig.json (default arm64)
+ * @returns {{files: Record<string, string|Uint8Array|{data, mode}>, spec: object}}
+ */
+export function containerBundle(o) {
+  const cwd = o.cwd || '/'
+  const user = o.user || { uid: 0, gid: 0 }
+  const hostname = o.hostname || 'localhost'
+  const spec = {
+    ociVersion: '1.0.2',
+    process: {
+      terminal: !!o.terminal,
+      user: { uid: user.uid, gid: user.gid, ...(user.additionalGids?.length ? { additionalGids: user.additionalGids } : {}) },
+      args: [...o.args],
+      env: [...(o.env || [])],
+      cwd,
+      capabilities: { bounding: DEFAULT_CAPS, effective: DEFAULT_CAPS, permitted: DEFAULT_CAPS },
+      rlimits: [{ type: 'RLIMIT_NOFILE', hard: 1 << 20, soft: 1 << 20 }],
+      oomScoreAdj: 0,
+    },
+    root: { path: `${GUEST_9P_MOUNT}/rootfs`, readonly: false },
+    hostname,
+    mounts: defaultMounts(),
+    linux: {
+      namespaces: [{ type: 'pid' }, { type: 'ipc' }, { type: 'uts' }, { type: 'mount' }],
+      maskedPaths: MASKED,
+      readonlyPaths: READONLY,
+      resources: { devices: [{ allow: false, access: 'rwm' }] },
+    },
+  }
+  for (const name of ETC_FILES) {
+    spec.mounts.push({ destination: `/etc/${name}`, type: 'bind', source: `${GUEST_9P_MOUNT}/bundle/etc/${name}`, options: ['rbind', 'rprivate', 'rw'] })
+  }
+  const files = {}
+  ;(o.mounts || []).forEach((m, i) => {
+    const share = `vol${i}`
+    const entries = Object.entries(m.files || {})
+    for (const [rel, f] of entries) files[`${share}/${rel}`] = f
+    if (!entries.length) files[`${share}/.keep`] = '' // the share's directory
+    let src = `${GUEST_9P_MOUNT}/${share}`
+    if (m.file) src += `/${m.file}`
+    spec.mounts.push({ destination: m.destination, type: 'bind', source: src, options: ['rbind', 'rprivate', m.readOnly ? 'ro' : 'rw'] })
+  })
+  const networkDisabled = o.networkDisabled ?? true
+  let hosts = '127.0.0.1\tlocalhost\n::1\tlocalhost ip6-localhost ip6-loopback\nfe00::\tip6-localnet\nff00::\tip6-mcastprefix\nff02::1\tip6-allnodes\nff02::2\tip6-allrouters\n'
+  if (!networkDisabled) hosts += `${o.ip || '10.88.0.2'}\t${hostname}\n`
+  files['bundle/etc/hosts'] = hosts
+  files['bundle/etc/resolv.conf'] = networkDisabled ? '' : `nameserver ${o.gateway || '10.88.0.1'}\n`
+  files['bundle/etc/hostname'] = `${hostname}\n`
+  files['bundle/config/config.json'] = JSON.stringify(spec, null, 2) + '\n'
+  files['bundle/config/imageconfig.json'] =
+    JSON.stringify({ architecture: o.arch || 'arm64', os: 'linux', config: { Env: [...(o.env || [])], Cmd: [...o.args], WorkingDir: cwd }, rootfs: { type: 'layers', diff_ids: null } }, null, 2) + '\n'
+  return { files, spec }
+}