@threadedstack/wmd-web 0.0.0-stage → 0.1.12

package/src/net/wisp-client.js

@@ -0,0 +1,570 @@
+// W59: the browser side of Wisp (wisp.js), a transport for the network Worker with the same
+// interface as RelayClient (relay-client.js): the stack (stack.js) calls connect / data / end /
+// abort / credit / dns and is called back with onConnected, onRelayData, onRelayEnd,
+// onRelayAbort, onRelayCredit, onDnsReply, onRelayDown. NetStack does not change; the Wisp
+// specifics live here:
+//
+//   - upload: Wisp counts packets, not bytes. The stack gets WINDOW bytes of credit when a stream
+//     opens and gets back each packet's bytes when the packet leaves here; packets past the
+//     stream's counter wait in its queue until a CONTINUE resets the counter (plan §3).
+//   - download: with wmd-credit (0xE1) the stack's credit goes to the relay as CREDIT; without it
+//     the relay sends as fast as it reads and a stream holding more than DOWN_CAP undelivered
+//     bytes (or the session, SESSION_CAP) is reset with a log line.
+//   - half-close: with wmd-halfclose (0xE2) a guest FIN is SHUTDOWN; without it the FIN is held
+//     until the remote closes. A remote SHUTDOWN, or CLOSE 0x02, is a FIN; every other CLOSE is a reset.
+//   - names: the guest's lookups get placeholder addresses from 198.18.0.0/15; a connect to one
+//     is a CONNECT to the name (plan §4). With wmd-dns (0xE4) the relay answers first, so
+//     NXDOMAIN and refusals reach the guest; without it every valid name gets a placeholder.
+//   - status: onStatus({state, relay, reason, words}) for the page (plan §6).
+//
+// A drop of the WebSocket fails every stream (onRelayDown), as with v1.
+
+import { E, RCODE as V1_RCODE, WINDOW } from './proto.js'
+import {
+  CLOSE, EXT, PT, RCODE, SUBPROTOCOL, ClientHandshake, answerAddrs, closePacket, closeWords, connectPacket, creditPacket,
+  dataPacket, ext, lookupPacket, parse, shutdownPacket,
+} from './wisp.js'
+
+/** `relay: {url: 'local'}`: a `wmd-relay` started with no arguments on this computer. */
+export const LOCAL_RELAY_URL = 'ws://127.0.0.1:8780/wisp/'
+/** `relay: {url: 'hosted'}`: the public relay we run (`wmd-relay --hosted`, docs/relay-hosted.md). A page that uses it
+    needs `wss://relay.threadedstack.com` in its CSP connect-src. Set to '' and 'hosted' is unreachable, in words. */
+export const HOSTED_RELAY_URL = 'wss://relay.threadedstack.com/wisp/'
+
+const BACKOFF_MIN_MS = 250
+const BACKOFF_MAX_MS = 8000
+const CLOSE_MAINTENANCE = 1001 // a hosted relay's drain (WebSocket 1001 "the relay is closed for maintenance")
+const CLOSE_DENIED = 4011 // a hosted relay's operator denied this address or page origin
+const OPEN_TIMEOUT_MS = 10_000
+const QUEUE_MAX_MS = 8000
+export const DOWN_CAP = 64 << 20 // bytes delivered and not yet taken by the guest, per stream, without wmd-credit
+export const SESSION_CAP = 256 << 20 // the same, for every stream together
+export const NAME_CAP = 65536 // placeholder addresses per machine; never recycled
+const PH_BASE = (198 << 24) | (18 << 16) // 198.18.0.0/15
+const PH_MASK = 0xfffe0000
+const NAME_TTL = 60
+const CREDIT_SLACK = 64 << 10 // bytes a relay with wmd-credit may run past the credit it was given before it is cut off
+const LOOKUPS_MAX = 1024 // lookups waiting for the relay's answer
+const MOTD_MAX = 400 // characters of the relay's message shown in the status
+const MALFORMED_LOGGED = 8 // malformed packets logged in full; after that every 1000th
+const DEGRADED = { [EXT.CONFIRM]: 'open confirmation', [EXT.WMD_CREDIT]: 'download flow control', [EXT.WMD_HALFCLOSE]: 'half-close', [EXT.WMD_DNS]: 'name lookups' }
+
+/** The URL a relay config names ('local', 'hosted', or a ws(s) URL); '' when none is configured. */
+export function relayUrl(url) {
+  if (url === 'local') return LOCAL_RELAY_URL
+  if (url === 'hosted') return HOSTED_RELAY_URL
+  return url || ''
+}
+
+const ipU32 = (s) => {
+  const p = s.split('.')
+  if (p.length !== 4) return -1
+  let v = 0
+  for (const x of p) {
+    if (!/^\d{1,3}$/.test(x) || +x > 255) return -1
+    v = v * 256 + +x
+  }
+  return v >>> 0
+}
+const u32Ip = (v) => `${v >>> 24}.${(v >>> 16) & 255}.${(v >>> 8) & 255}.${v & 255}`
+export const isPlaceholder = (ip) => {
+  const v = ipU32(ip)
+  return v >= 0 && ((v & PH_MASK) >>> 0) === PH_BASE >>> 0
+}
+
+/** A host name the guest could look up (RFC 1123 labels); a bad one is NXDOMAIN without asking anyone. */
+export function validName(n) {
+  if (!n || n.length > 253 || n.includes('..')) return false
+  return n.split('.').every((l) => /^[a-z0-9_]([a-z0-9_-]{0,61}[a-z0-9_])?$/i.test(l))
+}
+
+/** A Wisp CLOSE reason as the stack's E code. */
+function eCode(reason) {
+  switch (reason) {
+    case CLOSE.INVALID: return E.BAD
+    case CLOSE.UNREACHABLE: return E.UNREACHABLE
+    case CLOSE.TIMEOUT: case CLOSE.DATA_TIMEOUT: return E.TIMEOUT
+    case CLOSE.REFUSED: return E.REFUSED
+    case CLOSE.BLOCKED: return E.BLOCKED
+    case CLOSE.THROTTLED: return E.LIMIT
+    case CLOSE.AUTH_BAD_PASSWORD: case CLOSE.AUTH_BAD_SIGNATURE: case CLOSE.AUTH_REQUIRED: return E.GONE
+    default: return E.RESET
+  }
+}
+
+const KNOWN_RCODES = new Set([RCODE.SERVFAIL, RCODE.NXDOMAIN, RCODE.REFUSED]) // any other rcode from a relay is a failure of the lookup
+
+const hexBytes = (h) => Uint8Array.from(h.match(/../g) || [], (x) => parseInt(x, 16))
+
+export class WispClient {
+  /**
+   * @param {object} o
+   * @param {string} o.url                 ws(s)://host:port/wisp/, 'local' or 'hosted'
+   * @param {string} [o.token]             bundled relay: the session token (subprotocol "t.<token>")
+   * @param {string} [o.tokenUrl]          fetch a fresh token before each open (JSON {token}), with ?instance=
+   * @param {{id: string, secret: string}} [o.key]  an owner key (Wisp password auth)
+   * @param {string} [o.instance]          this machine's id, 32 hex digits (kept across restores; plan §3)
+   * @param {[string, string][]} [o.names] the placeholder map so far (name, address), from the page
+   * @param {(name: string, ip: string) => void} [o.onName]   a new placeholder (the page keeps the map)
+   * @param {(s: object) => void} [o.onStatus]
+   * @param {typeof WebSocket} [o.WebSocket]
+   * @param {(line: string) => void} [o.log]
+   */
+  constructor(o) {
+    this.url = relayUrl(o.url)
+    this.configured = o.url
+    this.token = o.token || ''
+    this.tokenUrl = o.tokenUrl || ''
+    this.key = o.key || null
+    this.instance = /^[0-9a-f]{32}$/.test(o.instance || '') ? o.instance : Array.from(crypto.getRandomValues(new Uint8Array(16)), (b) => b.toString(16).padStart(2, '0')).join('')
+    this.WS = o.WebSocket || globalThis.WebSocket
+    this.log = o.log || (() => {})
+    this.now = o.now || (() => performance.now())
+    this.openTimeoutMs = o.openTimeoutMs || OPEN_TIMEOUT_MS
+    this.onName = o.onName || (() => {})
+    this.onStatus = o.onStatus || (() => {})
+    this.stack = null
+    this.ws = null
+    this.up = false
+    this.connecting = false
+    this.queue = [] // {kind: 'connect' | 'dns', id, ..., at} waiting for the socket
+    this.backoff = 0
+    this.nextAt = 0
+    this.timer = null
+    this.hs = null // the handshake's result: {version, buffer, server, common, motd}
+    this.server = null // the last relay's extensions (known after a first handshake)
+    this.streams = new Map() // id -> {confirmed, counter, held: [], ended, shut, owed}
+    this.held = 0 // bytes delivered without wmd-credit and not yet taken, all streams
+    this.names = new Map() // name -> ip
+    this.ips = new Map() // ip -> name
+    this.nextName = 1
+    this.lookups = new Map() // id -> {name, at} sent to the relay, not yet answered
+    for (const [n, ip] of o.names || []) if (this.names.size < NAME_CAP) this.#learn(n, ip)
+    this.status = null
+    this.stats = { opens: 0, openFailures: 0, drops: 0, sent: 0, received: 0, lastClose: null, lastError: null, v1Fallbacks: 0, downCapResets: 0, creditViolations: 0, malformed: 0, unknownPlaceholders: 0 }
+    if (!this.url) this.#status('unreachable', CLOSE.UNKNOWN, o.url === 'hosted' ? 'no hosted relay is configured' : 'no relay URL is configured')
+  }
+
+  attach(stack) {
+    this.stack = stack
+  }
+
+  #status(state, reason, words) {
+    let relay = ''
+    try {
+      relay = this.url ? new URL(this.url).origin.replace(/^http/, 'ws') : ''
+    } catch {}
+    this.status = { state, relay, reason: reason ?? 0, words: words || '' }
+    this.onStatus(this.status)
+  }
+
+  #learn(name, ip) {
+    // only an address of 198.18.0.0/15 that no other name has is a placeholder (a bad entry would move nextName out of range)
+    if (typeof name !== 'string' || typeof ip !== 'string' || !isPlaceholder(ip) || this.ips.has(ip) || this.names.has(name)) return
+    this.names.set(name, ip)
+    this.ips.set(ip, name)
+    const v = ipU32(ip)
+    if (v >= 0) this.nextName = Math.max(this.nextName, ((v - PH_BASE) >>> 0) + 1)
+  }
+
+  /** The placeholder for a name (made now if new); null when every address is used. */
+  #placeholder(name) {
+    let ip = this.names.get(name)
+    if (ip) return ip
+    if (this.names.size >= NAME_CAP || this.nextName >= 1 << 17) {
+      if (!this.namesFull) {
+        this.namesFull = true
+        this.log(`net: ${NAME_CAP} names looked up: no addresses left for new names until the machine restarts`)
+        this.#status('degraded', 0, `${NAME_CAP} names looked up: new names fail until the machine restarts`)
+      }
+      return null
+    }
+    ip = u32Ip((PH_BASE + this.nextName++) >>> 0)
+    this.#learn(name, ip)
+    this.onName(name, ip)
+    return ip
+  }
+
+  /** The placeholder map, for a checkpoint. */
+  nameList() {
+    return [...this.names]
+  }
+
+  #raw(b) {
+    this.stats.sent += b.length
+    this.ws.send(b)
+  }
+
+  /** Open the socket if it is not open (now, or when the backoff allows). */
+  wake() {
+    if (!this.url || this.up || this.connecting || this.timer) return
+    const wait = this.nextAt - this.now()
+    if (wait > 0) {
+      this.timer = setTimeout(() => {
+        this.timer = null
+        this.#open()
+      }, wait)
+      return
+    }
+    this.#open()
+  }
+
+  async #open() {
+    if (this.up || this.connecting) return
+    this.connecting = true
+    this.#status('connecting')
+    let token = this.token
+    try {
+      if (this.tokenUrl) {
+        const u = new URL(this.tokenUrl, globalThis.location?.href)
+        u.searchParams.set('instance', this.instance)
+        const r = await fetch(u, { cache: 'no-store', signal: AbortSignal.timeout(this.openTimeoutMs) })
+        if (!r.ok) throw new Error(`token: GET ${this.tokenUrl}: ${r.status}`)
+        token = (await r.json()).token
+        if (token !== undefined && typeof token !== 'string') throw new Error(`token: GET ${this.tokenUrl}: the answer has no text token`)
+      }
+    } catch (e) {
+      return this.#failed(e.message)
+    }
+    // B8: offer wisp-v2; a server that fails the WebSocket handshake for it gets one retry as
+    // Wisp v1 (no subprotocol). A token needs its subprotocol, so there is no retry with one.
+    this.#socket(token ? [SUBPROTOCOL, `t.${token}`] : [SUBPROTOCOL], !token)
+  }
+
+  #socket(protocols, mayRetry) {
+    let ws
+    try {
+      ws = protocols.length ? new this.WS(this.url, protocols) : new this.WS(this.url)
+    } catch (e) {
+      return this.#failed(e.message)
+    }
+    ws.binaryType = 'arraybuffer'
+    this.ws = ws
+    let opened = false
+    const hs = new ClientHandshake({
+      exts: [ext.confirm(), ext.wmdCredit(WINDOW), ext.wmdHalfclose(), ext.wmdDns(), ext.wmdInstance(hexBytes(this.instance))],
+      password: this.key ? { user: this.key.id, pass: this.key.secret } : null,
+    })
+    const openTimer = setTimeout(() => !this.up && this.ws === ws && ws.close(), this.openTimeoutMs)
+    let authFail = null
+    ws.onopen = () => {
+      if (this.ws === ws) opened = true
+    }
+    ws.onmessage = (e) => {
+      if (this.ws !== ws || typeof e.data === 'string') return
+      const u8 = new Uint8Array(e.data)
+      this.stats.received += u8.length
+      if (!this.up) {
+        const r = hs.step(parse(u8))
+        for (const b of r.send) this.#raw(b)
+        if (r.fail) {
+          authFail = r.fail
+          ws.close(1000, 'handshake failed')
+        } else if (r.done) {
+          clearTimeout(openTimer)
+          this.#ready(r.done)
+        }
+        return
+      }
+      this.#dispatch(parse(u8))
+    }
+    ws.onerror = () => {
+      this.stats.lastError = 'websocket error'
+    }
+    ws.onclose = (e) => {
+      clearTimeout(openTimer)
+      if (this.ws !== ws) return
+      const wasUp = this.up
+      this.ws = null
+      this.up = false
+      this.stats.lastClose = { code: e.code, reason: e.reason, at: Math.round(this.now()) }
+      if (wasUp) {
+        this.stats.drops++
+        this.streams.clear()
+        this.lookups.clear() // the stack fails its lookups in onRelayDown
+        this.held = 0
+        // a relay that closed us on purpose (maintenance, 1001; denied by its operator, 4011) is not back in a moment: wait the longest
+        this.backoff = e.code === CLOSE_MAINTENANCE || e.code === CLOSE_DENIED ? BACKOFF_MAX_MS : BACKOFF_MIN_MS
+        this.nextAt = this.now() + this.backoff
+        const why = `relay connection closed (${e.code}${e.reason ? ` ${e.reason}` : ''})`
+        this.log(`net: the relay connection closed (${e.code}${e.reason ? ` ${e.reason}` : ''}): every connection is reset`)
+        this.#status('down', 0, why)
+        this.stack?.onRelayDown(why)
+        return
+      }
+      if (!opened && mayRetry) {
+        this.stats.v1Fallbacks++
+        this.log('net: the relay refused the wisp-v2 subprotocol; trying Wisp v1')
+        return this.#socket([], false)
+      }
+      if (authFail) {
+        const st = ['auth-required', 'auth-refused', 'version'].includes(authFail.state) ? authFail.state : 'unreachable'
+        this.backoff = BACKOFF_MAX_MS // a wrong or missing key does not fix itself: no tight loop
+        return this.#failed(authFail.words, st, authFail.reason)
+      }
+      this.#failed(`could not connect to the relay (${e.code}${e.reason ? ` ${e.reason}` : ''})`)
+    }
+  }
+
+  #ready(done) {
+    this.connecting = false
+    this.up = true
+    this.backoff = 0
+    this.stats.opens++
+    this.hs = done
+    this.server = done.common
+    const motd = (done.motd || '').slice(0, MOTD_MAX)
+    const missing = Object.keys(DEGRADED).map(Number).filter((id) => !done.common.has(id))
+    if (missing.length) {
+      const words = `this relay does not support ${missing.map((id) => DEGRADED[id]).join(', ')} (Wisp ${done.version}${motd ? `; ${motd}` : ''})`
+      this.log(`net: ${words}`)
+      this.#status('degraded', 0, words)
+    } else this.#status('connected', 0, motd)
+    const q = this.queue
+    this.queue = []
+    for (const x of q) {
+      if (x.kind === 'connect') this.#connectNow(x.id, x.host, x.port)
+      else this.#dnsNow(x.id, x.name)
+    }
+  }
+
+  #failed(why, state = 'unreachable', reason = 0) {
+    this.connecting = false
+    this.ws = null
+    this.stats.openFailures++
+    this.stats.lastError = why
+    this.backoff = Math.min(Math.max(this.backoff * 2, BACKOFF_MIN_MS), BACKOFF_MAX_MS)
+    this.nextAt = this.now() + this.backoff
+    this.log(`net: ${why}; next try in ${this.backoff} ms`)
+    this.#status(state, reason, why)
+    const t = this.now()
+    const keep = []
+    const hopeless = state !== 'unreachable' // a missing or wrong key, or another protocol version, does not fix itself by waiting
+    for (const x of this.queue) {
+      if (!hopeless && t - x.at < QUEUE_MAX_MS) keep.push(x)
+      else if (x.kind === 'connect') this.stack?.onConnected(x.id, E.GONE, 0, why)
+      else this.stack?.onDnsReply(x.id, V1_RCODE.SERVFAIL, 0, [], why)
+    }
+    this.queue = keep
+    if (keep.length) this.wake()
+  }
+
+  // ---- packets from the relay ----
+
+  #dispatch(m) {
+    const s = this.stack
+    if (!s || m.error) {
+      if (m.error && (this.stats.malformed++ < MALFORMED_LOGGED || this.stats.malformed % 1000 === 0)) this.log(`net: a malformed packet from the relay (${m.error}); ignored (${this.stats.malformed} so far)`)
+      return
+    }
+    switch (m.type) {
+      case PT.CONTINUE: {
+        const st = this.streams.get(m.id)
+        if (!st) return
+        st.counter = m.n
+        if (!st.confirmed) {
+          st.confirmed = true
+          s.onConnected(m.id, E.OK, WINDOW, '')
+        }
+        this.#flush(m.id, st)
+        break
+      }
+      case PT.DATA: {
+        const st = this.streams.get(m.id)
+        if (!st || !m.payload.length) return
+        if (!st.confirmed) return this.#violation(m.id, st, E.BAD, 'data before the connection was confirmed')
+        if (this.server.has(EXT.WMD_CREDIT)) {
+          st.allow -= m.payload.length // the relay may send what the guest has taken so far, plus the window it was given
+          if (st.allow < -CREDIT_SLACK) return this.#violation(m.id, st, E.LIMIT, 'it sent more than the credit it was given')
+        } else {
+          st.owed += m.payload.length
+          this.held += m.payload.length
+          if (st.owed > DOWN_CAP || this.held > SESSION_CAP) {
+            this.stats.downCapResets++
+            const why = st.owed > DOWN_CAP ? `more than ${DOWN_CAP >> 20} MiB waiting for the guest on one connection` : `more than ${SESSION_CAP >> 20} MiB waiting for the guest`
+            this.log(`net: stream ${m.id}: ${why} (this relay has no download flow control): reset`)
+            this.#forget(m.id, st)
+            this.#raw(closePacket(m.id, CLOSE.CLIENT_ERROR))
+            s.onRelayAbort(m.id, E.LIMIT, why)
+            return
+          }
+        }
+        s.onRelayData(m.id, m.payload.slice())
+        break
+      }
+      case PT.SHUTDOWN: {
+        const st = this.streams.get(m.id)
+        if (!st || st.ended) return
+        st.ended = true
+        s.onRelayEnd(m.id)
+        break
+      }
+      case PT.CLOSE: {
+        const st = this.streams.get(m.id)
+        if (!st) return
+        this.#forget(m.id, st)
+        const words = closeWords(m.reason)
+        if (!st.confirmed) {
+          // unconfirmed (open confirmation) or opened on trust (no confirmation): a refused SYN either way
+          if (this.server.has(EXT.CONFIRM)) return s.onConnected(m.id, m.reason === CLOSE.VOLUNTARY ? E.RESET : eCode(m.reason), 0, words)
+        }
+        if (m.reason === CLOSE.VOLUNTARY) {
+          if (!st.ended) s.onRelayEnd(m.id) // the remote's FIN after its last byte
+          return
+        }
+        s.onRelayAbort(m.id, eCode(m.reason), words)
+        break
+      }
+      case PT.ANSWER: {
+        const d = this.lookups.get(m.id)
+        if (!d) return
+        this.lookups.delete(m.id)
+        const { addrs, reason } = answerAddrs(m, 1)
+        if (m.rcode !== RCODE.NOERROR) return s.onDnsReply(m.id, KNOWN_RCODES.has(m.rcode) ? m.rcode : RCODE.SERVFAIL, m.ttl, [], reason)
+        if (!addrs.length) return s.onDnsReply(m.id, RCODE.NOERROR, m.ttl, [], reason)
+        this.#answer(m.id, d.name, Math.min(m.ttl, NAME_TTL))
+        break
+      }
+    }
+  }
+
+  #answer(id, name, ttl) {
+    const ip = this.#placeholder(name)
+    if (!ip) return this.stack.onDnsReply(id, V1_RCODE.SERVFAIL, 0, [], 'no addresses left for new names')
+    const v = ipU32(ip)
+    this.stack.onDnsReply(id, RCODE.NOERROR, ttl, [Uint8Array.of(v >>> 24, (v >>> 16) & 255, (v >>> 8) & 255, v & 255)], '')
+  }
+
+  /** The relay broke the flow rules for a stream: reset it, in words. */
+  #violation(id, st, code, what) {
+    this.stats.creditViolations++
+    const why = `the relay broke the flow rules: ${what}`
+    this.log(`net: stream ${id}: ${why}: reset`)
+    this.#forget(id, st)
+    this.#raw(closePacket(id, CLOSE.CLIENT_ERROR))
+    this.stack.onRelayAbort(id, code, why)
+  }
+
+  #forget(id, st) {
+    this.streams.delete(id)
+    this.held -= st.owed
+  }
+
+  /** Send a stream's held packets while its counter allows; the stack gets their bytes back as credit. */
+  #flush(id, st) {
+    while (st.held.length && st.counter > 0) {
+      const b = st.held.shift()
+      st.counter--
+      this.#raw(dataPacket(id, b))
+      this.stack.onRelayCredit(id, b.length)
+    }
+    if (!st.held.length && st.shut && !st.shutSent) {
+      st.shutSent = true
+      this.#raw(shutdownPacket(id))
+    }
+  }
+
+  #connectNow(id, host, port) {
+    if (this.streams.has(id)) return
+    const st = { confirmed: false, counter: this.server.has(EXT.CONFIRM) ? 0 : this.hs.buffer, allow: WINDOW, held: [], ended: false, shut: false, shutSent: false, owed: 0 }
+    this.streams.set(id, st)
+    this.#raw(connectPacket(id, host, port))
+    if (!this.server.has(EXT.CONFIRM)) {
+      // no open confirmation: the stream is open on trust; a failure comes as a CLOSE (a RST after open)
+      st.confirmed = true
+      queueMicrotask(() => this.streams.get(id) === st && this.stack?.onConnected(id, E.OK, WINDOW, ''))
+    }
+  }
+
+  #dnsNow(id, name) {
+    if (!this.server.has(EXT.WMD_DNS)) return this.#answer(id, name, NAME_TTL)
+    if (this.lookups.size >= LOOKUPS_MAX) this.lookups.delete(this.lookups.keys().next().value) // the oldest: the stack gave up on it long ago
+    this.lookups.set(id, { name, at: this.now() })
+    this.#raw(lookupPacket(id, name, 1))
+  }
+
+  // ---- the stack's interface ----
+
+  connect(id, host, port) {
+    if (isPlaceholder(host)) {
+      const name = this.ips.get(host)
+      if (!name) {
+        this.stats.unknownPlaceholders++
+        const why = `${host} is a name placeholder this machine does not know (from before a restore without its names?)`
+        this.log(`net: ${why}: reset`)
+        return queueMicrotask(() => this.stack?.onConnected(id, E.UNREACHABLE, 0, why))
+      }
+      host = name
+    }
+    if (this.up) return this.#connectNow(id, host, port)
+    if (!this.url) return queueMicrotask(() => this.stack?.onConnected(id, E.UNREACHABLE, 0, this.status.words))
+    this.queue.push({ kind: 'connect', id, host, port, at: this.now() })
+    this.wake()
+  }
+
+  data(id, u8) {
+    const st = this.up && this.streams.get(id)
+    if (!st) return
+    st.held.push(u8)
+    this.#flush(id, st)
+  }
+
+  end(id) {
+    const st = this.up && this.streams.get(id)
+    if (!st || st.shut) return
+    if (!this.server.has(EXT.WMD_HALFCLOSE)) return // held until the remote closes (stated, plan §3)
+    st.shut = true
+    this.#flush(id, st)
+  }
+
+  abort(id) {
+    const st = this.up && this.streams.get(id)
+    if (!st) return
+    this.#forget(id, st)
+    this.#raw(closePacket(id, CLOSE.VOLUNTARY))
+  }
+
+  /** The guest took n bytes: the relay may send n more (wmd-credit), or they are no longer held here. */
+  credit(id, n) {
+    const st = this.up && this.streams.get(id)
+    if (!st || n <= 0) return
+    if (this.server.has(EXT.WMD_CREDIT)) {
+      st.allow += n
+      return this.#raw(creditPacket(id, n))
+    }
+    const k = Math.min(n, st.owed)
+    st.owed -= k
+    this.held -= k
+  }
+
+  /** A stream that ended cleanly on both sides (the stack's FIN exchange is done). */
+  closed(id) {
+    const st = this.streams.get(id)
+    if (st) this.#forget(id, st)
+  }
+
+  dns(id, name) {
+    name = String(name).toLowerCase().replace(/\.$/, '')
+    if (!validName(name)) return queueMicrotask(() => this.stack?.onDnsReply(id, RCODE.NXDOMAIN, 0, [], 'not a valid host name'))
+    if (this.names.has(name)) return queueMicrotask(() => this.stack && this.#answer(id, name, NAME_TTL))
+    if (this.up) return this.#dnsNow(id, name)
+    // a relay known to lack wmd-dns: answer without waking it (plan §4)
+    if (this.server && !this.server.has(EXT.WMD_DNS)) return queueMicrotask(() => this.stack && this.#answer(id, name, NAME_TTL))
+    if (!this.url) return queueMicrotask(() => this.stack?.onDnsReply(id, V1_RCODE.SERVFAIL, 0, [], this.status.words))
+    this.queue.push({ kind: 'dns', id, name, at: this.now() })
+    this.wake()
+  }
+
+  /** Test hook: drop the WebSocket as a network failure would. */
+  drop() {
+    this.ws?.close(4000, 'dropped by the page (test hook)')
+  }
+
+  snapshot() {
+    return {
+      protocol: 'wisp', url: this.url, up: this.up, connecting: this.connecting, status: this.status,
+      version: this.hs?.version ?? null, extensions: this.server ? [...this.server] : null, motd: this.hs?.motd ?? '',
+      streams: this.streams.size, names: this.names.size, ...this.stats,
+    }
+  }
+}