@threadedstack/wmd-web 0.0.0-stage → 0.1.12

package/src/net/proto.js

@@ -0,0 +1,189 @@
+// P-B10: the relay protocol, shared by the browser's network Worker (net-worker.js) and the
+// relay server (web/relay/relay.ts).
+//
+// One WebSocket per guest machine carries every TCP stream of that guest and its DNS
+// lookups. Binary messages only (the relay's first message is a JSON text "hello"):
+//
+//   type u8 | id u32 BE | payload
+//
+// Client -> relay
+//   CONNECT  port u16 BE | host utf8        open stream `id` to host:port (an IP literal; a name
+//                                           is resolved by the relay and checked after resolution)
+//   DATA     bytes                          at most the credit the relay granted for the stream
+//   END      -                              half-close (the guest sent FIN)
+//   ABORT    -                              reset (the guest sent RST, or the stream is gone)
+//   CREDIT   n u32 BE                       the relay may send n more bytes on the stream
+//   DNS      qtype u16 BE | name utf8       look up `name` (qtype 1 = A, 28 = AAAA); `id` is the query's
+//
+// Relay -> client
+//   CONNECTED code u8 | credit u32 BE | detail utf8   code 0: open, the client may send `credit` bytes;
+//                                                      else refused (detail says why)
+//   DATA      bytes                         at most the credit the client granted (WINDOW at first)
+//   END       -                             the remote closed cleanly (FIN): no more data
+//   ABORT     code u8 | reason utf8         the stream failed (remote reset, relay limit, ...):
+//                                           NOT a clean end; data may be missing
+//   CREDIT    n u32 BE                      the client may send n more bytes
+//   DNSREPLY  rcode u8 | ttl u32 BE | count u8 | addresses (4 or 16 bytes each) | reason utf8
+//
+// Flow control: each side may have at most the credit the other granted in flight per
+// stream; a stream starts with WINDOW bytes of credit for the relay (the client grants it
+// by sending CONNECT) and the credit in CONNECTED for the client. Credit comes back as the
+// receiver passes the bytes on.
+
+export const PROTOCOL = 'wmd-relay.v1'
+export const WINDOW = 256 << 10
+export const MAX_DATA = 64 << 10 // largest DATA payload either side sends
+
+export const T = {
+  CONNECT: 0x01, DATA: 0x02, END: 0x03, ABORT: 0x04, CREDIT: 0x05, DNS: 0x06,
+  CONNECTED: 0x81, RDATA: 0x82, REND: 0x83, RABORT: 0x84, RCREDIT: 0x85, DNSREPLY: 0x86,
+}
+
+/** Why a connect or a stream failed (CONNECTED code, ABORT code). */
+export const E = {
+  OK: 0,
+  BLOCKED: 1, // the address is private, loopback, link-local, metadata, reserved or the relay's own
+  NOT_ALLOWED: 2, // not on the relay's allowlist
+  REFUSED: 3, // the remote refused (ECONNREFUSED)
+  TIMEOUT: 4,
+  DNS: 5, // the name did not resolve
+  LIMIT: 6, // a relay limit (connections, rate, bytes)
+  BAD: 7, // malformed request
+  UNREACHABLE: 8,
+  PORT: 9, // the port is blocked by policy
+  RESET: 10, // the remote reset or failed mid-stream
+  GONE: 11, // the session is closing
+}
+export const E_NAMES = Object.fromEntries(Object.entries(E).map(([k, v]) => [v, k.toLowerCase()]))
+
+/** DNS rcodes used in DNSREPLY (RFC 1035). */
+export const RCODE = { NOERROR: 0, SERVFAIL: 2, NXDOMAIN: 3, REFUSED: 5 }
+
+const enc = new TextEncoder()
+const dec = new TextDecoder()
+
+export function msg(type, id, payload) {
+  const n = payload ? payload.length : 0
+  const b = new Uint8Array(5 + n)
+  b[0] = type
+  new DataView(b.buffer).setUint32(1, id >>> 0)
+  if (n) b.set(payload, 5)
+  return b
+}
+
+export function connectMsg(id, host, port) {
+  const h = enc.encode(host)
+  const p = new Uint8Array(2 + h.length)
+  p[0] = port >> 8
+  p[1] = port & 255
+  p.set(h, 2)
+  return msg(T.CONNECT, id, p)
+}
+
+export function u32Msg(type, id, n) {
+  const p = new Uint8Array(4)
+  new DataView(p.buffer).setUint32(0, n >>> 0)
+  return msg(type, id, p)
+}
+
+export function dnsMsg(id, name, qtype) {
+  const h = enc.encode(name)
+  const p = new Uint8Array(2 + h.length)
+  p[0] = qtype >> 8
+  p[1] = qtype & 255
+  p.set(h, 2)
+  return msg(T.DNS, id, p)
+}
+
+export function connectedMsg(id, code, credit, detail = '') {
+  const d = enc.encode(detail)
+  const p = new Uint8Array(5 + d.length)
+  p[0] = code
+  new DataView(p.buffer).setUint32(1, credit >>> 0)
+  p.set(d, 5)
+  return msg(T.CONNECTED, id, p)
+}
+
+export function abortMsg(id, code, reason = '') {
+  const d = enc.encode(reason)
+  const p = new Uint8Array(1 + d.length)
+  p[0] = code
+  p.set(d, 1)
+  return msg(T.RABORT, id, p)
+}
+
+/** addrs: arrays of 4 (A) or 16 (AAAA) bytes. */
+export function dnsReplyMsg(id, rcode, ttl, addrs = [], reason = '') {
+  const d = enc.encode(reason)
+  const alen = addrs.reduce((s, a) => s + a.length, 0)
+  const p = new Uint8Array(6 + alen + d.length)
+  p[0] = rcode
+  new DataView(p.buffer).setUint32(1, ttl >>> 0)
+  p[5] = addrs.length
+  let o = 6
+  for (const a of addrs) {
+    p.set(a, o)
+    o += a.length
+  }
+  p.set(d, o)
+  return msg(T.DNSREPLY, id, p)
+}
+
+/** Parse one message; returns null when it is too short. */
+export function parse(u8) {
+  if (u8.length < 5) return null
+  const dv = new DataView(u8.buffer, u8.byteOffset, u8.byteLength)
+  const type = u8[0]
+  const id = dv.getUint32(1)
+  const p = u8.subarray(5)
+  const m = { type, id, payload: p }
+  switch (type) {
+    case T.CONNECT:
+      if (p.length < 3) return null
+      m.port = (p[0] << 8) | p[1]
+      m.host = dec.decode(p.subarray(2))
+      break
+    case T.DNS:
+      if (p.length < 3) return null
+      m.qtype = (p[0] << 8) | p[1]
+      m.name = dec.decode(p.subarray(2))
+      break
+    case T.CREDIT:
+    case T.RCREDIT:
+      if (p.length !== 4) return null
+      m.n = dv.getUint32(5)
+      break
+    case T.CONNECTED:
+      if (p.length < 5) return null
+      m.code = p[0]
+      m.credit = dv.getUint32(6)
+      m.detail = dec.decode(p.subarray(5))
+      break
+    case T.RABORT:
+      if (p.length < 1) return null
+      m.code = p[0]
+      m.reason = dec.decode(p.subarray(1))
+      break
+    case T.DNSREPLY: {
+      if (p.length < 6) return null
+      m.rcode = p[0]
+      m.ttl = dv.getUint32(6)
+      m.count = p[5]
+      m.rest = p.subarray(6) // the addresses (their size depends on the query), then the reason
+      break
+    }
+  }
+  return m
+}
+
+/** The addresses of a DNSREPLY for a query of qtype (1: 4 bytes each, 28: 16). */
+export function dnsReplyAddrs(m, qtype) {
+  const size = qtype === 28 ? 16 : 4
+  const addrs = []
+  for (let i = 0; i < m.count; i++) {
+    const a = m.rest.subarray(i * size, (i + 1) * size)
+    if (a.length !== size) return { addrs, reason: 'short reply' }
+    addrs.push(a)
+  }
+  return { addrs, reason: dec.decode(m.rest.subarray(m.count * size)) }
+}

package/src/net/relay-client.js

@@ -0,0 +1,226 @@
+// P-B10: the browser side of the relay protocol (proto.js): one WebSocket to the relay
+// server for the whole guest, opened when the guest first needs it and again after a drop
+// (with a backoff), never in a loop on its own. The stack (stack.js) calls connect / data /
+// end / abort / credit / dns; the client calls the stack back (onConnected, onRelayData,
+// onRelayEnd, onRelayAbort, onRelayCredit, onDnsReply, onRelayDown).
+//
+// A drop of the WebSocket fails every stream (onRelayDown: the stack resets them; the
+// relay forgets them too), so nothing resumes half-way and nothing ends as if complete.
+
+import { E, PROTOCOL, RCODE, T, connectMsg, dnsMsg, dnsReplyAddrs, msg, parse, u32Msg } from './proto.js'
+
+const BACKOFF_MIN_MS = 250
+const BACKOFF_MAX_MS = 8000
+const OPEN_TIMEOUT_MS = 10_000
+const QUEUE_MAX_MS = 8000 // a connect or lookup waits this long for the relay to come back
+
+export class RelayClient {
+  /**
+   * @param {object} o
+   * @param {string} o.url            ws(s)://host:port/relay
+   * @param {string} [o.token]        the session token (sent as a WebSocket subprotocol "t.<token>")
+   * @param {string} [o.tokenUrl]     fetch a fresh token from here before each open (JSON {token}),
+   *                                  with ?instance=<this guest's id>: the relay keeps this guest's caps
+   *                                  across its tokens and reconnects
+   * @param {string} [o.instance]     this guest's id (default: a random one per client)
+   * @param {typeof WebSocket} [o.WebSocket]
+   * @param {(line: string) => void} [o.log]
+   */
+  constructor(o) {
+    this.url = o.url
+    this.token = o.token || ''
+    this.tokenUrl = o.tokenUrl || ''
+    this.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.stack = null
+    this.ws = null
+    this.up = false
+    this.connecting = false
+    this.queue = [] // messages waiting for the socket
+    this.backoff = 0
+    this.nextAt = 0
+    this.timer = null
+    this.hello = null
+    this.stats = { opens: 0, openFailures: 0, drops: 0, sent: 0, received: 0, lastClose: null, lastError: null }
+  }
+
+  attach(stack) {
+    this.stack = stack
+  }
+
+  #send(m) {
+    if (this.up) {
+      this.stats.sent += m.length
+      this.ws.send(m)
+      return
+    }
+    this.queue.push({ m, at: this.now() })
+    this.wake()
+  }
+
+  /** Open the socket if it is not open (now, or when the backoff allows). */
+  wake() {
+    if (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
+    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' })
+        if (!r.ok) throw new Error(`token: GET ${this.tokenUrl}: ${r.status}`)
+        token = (await r.json()).token
+      }
+    } catch (e) {
+      return this.#failed(e.message)
+    }
+    let ws
+    try {
+      ws = new this.WS(this.url, token ? [PROTOCOL, `t.${token}`] : [PROTOCOL])
+    } catch (e) {
+      return this.#failed(e.message)
+    }
+    ws.binaryType = 'arraybuffer'
+    this.ws = ws
+    const openTimer = setTimeout(() => ws.readyState !== 1 && ws.close(), OPEN_TIMEOUT_MS)
+    ws.onopen = () => {
+      clearTimeout(openTimer)
+      if (this.ws !== ws) return
+      this.connecting = false
+      this.up = true
+      this.backoff = 0
+      this.stats.opens++
+      const q = this.queue
+      this.queue = []
+      for (const x of q) this.#send(x.m)
+    }
+    ws.onmessage = e => {
+      if (this.ws !== ws) return
+      if (typeof e.data === 'string') {
+        try {
+          this.hello = JSON.parse(e.data)
+        } catch {}
+        return
+      }
+      const u8 = new Uint8Array(e.data)
+      this.stats.received += u8.length
+      this.#dispatch(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.backoff = BACKOFF_MIN_MS
+        this.nextAt = this.now() + this.backoff
+        this.log(`net: the relay connection closed (${e.code}${e.reason ? ` ${e.reason}` : ''}): every connection is reset`)
+        this.stack?.onRelayDown(`relay connection closed (${e.code}${e.reason ? ` ${e.reason}` : ''})`)
+      } else this.#failed(`could not connect to the relay (${e.code}${e.reason ? ` ${e.reason}` : ''})`)
+    }
+  }
+
+  #failed(why) {
+    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`)
+    // what waited for this open keeps waiting (the relay may be restarting) for up to
+    // QUEUE_MAX_MS; older connects are refused (RST) and older lookups get SERVFAIL
+    const t = this.now()
+    const keep = []
+    for (const x of this.queue) {
+      if (t - x.at < QUEUE_MAX_MS) keep.push(x)
+      else {
+        const id = new DataView(x.m.buffer, x.m.byteOffset).getUint32(1)
+        if (x.m[0] === T.CONNECT) this.stack?.onConnected(id, E.GONE, 0, why)
+        else if (x.m[0] === T.DNS) this.stack?.onDnsReply(id, RCODE.SERVFAIL, 0, [], why)
+      }
+    }
+    this.queue = keep
+    if (keep.length) this.wake()
+  }
+
+  #dispatch(u8) {
+    const m = parse(u8)
+    const s = this.stack
+    if (!m || !s) return
+    switch (m.type) {
+      case T.CONNECTED:
+        s.onConnected(m.id, m.code, m.credit, m.detail)
+        break
+      case T.RDATA:
+        if (m.payload.length) s.onRelayData(m.id, m.payload.slice())
+        break
+      case T.REND:
+        s.onRelayEnd(m.id)
+        break
+      case T.RABORT:
+        s.onRelayAbort(m.id, m.code, m.reason)
+        break
+      case T.RCREDIT:
+        s.onRelayCredit(m.id, m.n)
+        break
+      case T.DNSREPLY: {
+        const { addrs, reason } = dnsReplyAddrs(m, 1)
+        s.onDnsReply(m.id, m.rcode, m.ttl, addrs, reason)
+        break
+      }
+    }
+  }
+
+  // ---- the stack's interface ----
+  connect(id, host, port) {
+    this.#send(connectMsg(id, host, port))
+  }
+  data(id, u8) {
+    if (this.up) this.#send(msg(T.DATA, id, u8))
+  }
+  end(id) {
+    if (this.up) this.#send(msg(T.END, id))
+  }
+  abort(id) {
+    if (this.up) this.#send(msg(T.ABORT, id))
+  }
+  credit(id, n) {
+    if (this.up && n > 0) this.#send(u32Msg(T.CREDIT, id, n))
+  }
+  dns(id, name, qtype) {
+    this.#send(dnsMsg(id, name, qtype))
+  }
+
+  /** Test hook: drop the WebSocket as a network failure would. */
+  drop() {
+    this.ws?.close(4000, 'dropped by the page (test hook)')
+  }
+
+  snapshot() {
+    return { url: this.url, up: this.up, connecting: this.connecting, hello: this.hello, ...this.stats }
+  }
+}
+
+export { E, RCODE }