@threadedstack/wmd-web 0.1.13 → 0.1.14

package/relay/wisp.ts

@@ -5,8 +5,9 @@
 //   - open: no key (the standalone relay's default); identity = the client's instance id (0xE7)
 //     plus its address group, bandwidth shared per address
 //   - keys (optional): Wisp password auth, scrypt hashes; a relay with keys refuses keyless clients
-// Pre-auth limits: sockets in their handshake per address, a handshake deadline, failed keys
-// throttled per address.
+// Pre-auth: wrong keys are throttled per address, and at most `preAuthPerAddr` key checks (a scrypt each) run at once
+// per address. A handshake deadline, an idle-stream close and the per-address identity rate are off unless set
+// (plan §16). A hosted relay refuses after the handshake, so the page hears why (wmd-reason, 0xE9).
 //
 // Flow control: upload is Wisp's CONTINUE (packets), released as the bytes reach the remote and
 // the up bucket allows (so the bucket delays CONTINUE); download is wmd-credit (0xE1) bytes when
@@ -15,11 +16,11 @@
 import { randomBytes } from 'node:crypto'
 import { E } from '../src/net/proto.js'
 import {
-  CLOSE, EXT, PT, STREAM, SUBPROTOCOL, ServerHandshake, answerPacket, closePacket, closeWords, continuePacket,
-  dataPacket, ext, parse, shutdownPacket,
+  CLOSE, EXT, PT, REASON_KIND, STREAM, SUBPROTOCOL, ServerHandshake, answerPacket, closePacket, closeWords, continuePacket,
+  dataPacket, ext, parse, reasonPacket, shutdownPacket,
 } from '../src/net/wisp.js'
 import { type AllowEntry, type Engine, type Principal, type Session, type Shared, type Stream, Window, type Wire, compileAllow, newShared } from './engine.ts'
-import { type Governor, resolveClient } from './hosted.ts'
+import { type Governor, type Why, resolveClient } from './hosted.ts'
 import { type OwnerKey, verifySecret } from './keys.ts'
 import type { Cidr } from './policy.ts'
 import { clientKey, verifyToken } from './token.ts'
@@ -43,11 +44,11 @@ export type WispOptions = {
   //                              so one stream that keeps the packet rule never reaches it); past it the stream that sent more gets 0x49
   maxHeldTotal?: number // upload bytes held by the whole relay (512 MiB); past it, DATA from a group over its fair share gets 0x49
   maxGroupHeldBytes?: number // upload bytes held by one address group or key, all its sessions (2 x the session cap)
-  instancesPerHour?: number // new identities per address (or key) an hour (120)
-  maxPrincipals?: number // identities remembered (10000)
-  preAuthPerAddr?: number // sockets in their handshake per address (8)
-  handshakeMs?: number // (10000)
-  streamIdleMs?: number // a stream with no bytes either way this long is closed, 0x47 (30 min)
+  instancesPerHour?: number // new identities per address (or key) an hour (no limit)
+  maxPrincipals?: number // identities remembered (no limit)
+  preAuthPerAddr?: number // key checks (scrypt) at once per address (8)
+  handshakeMs?: number // a socket that has not finished its handshake this long is closed (no limit)
+  streamIdleMs?: number // a stream with no bytes either way this long is closed, 0x47 (no limit)
   version?: string // the relay's version, in the MOTD
 }
 
@@ -81,6 +82,7 @@ type SessionW = {
   engine: Engine
   v2: boolean
   confirm: boolean
+  reason: boolean
   credit: boolean
   halfclose: boolean
   dns: boolean
@@ -118,11 +120,12 @@ export function createWisp(engine: Engine, o: { secret?: string; port: () => num
     heldSwept = n
     groupHeld = g
   }, 1000)
-  const handshakeMs = w.handshakeMs ?? 10_000
-  const streamIdleMs = w.streamIdleMs ?? 30 * 60_000
+  const handshakeMs = w.handshakeMs ?? 0
+  const streamIdleMs = w.streamIdleMs ?? 0
   const preAuth = w.preAuthPerAddr ?? 8
-  const maxPrincipals = w.maxPrincipals ?? 10_000
-  const instancesPerHour = w.instancesPerHour ?? 120
+  const maxPrincipals = w.maxPrincipals ?? Infinity
+  const instancesPerHour = w.instancesPerHour ?? Infinity
+  const handshaking = new Set<any>() // sockets that have not finished their handshake (rule G closes the oldest first)
   const inHandshake = new Map<string, number>()
   const failed = new Map<string, { fails: number; until: number; at: number }>()
   const newIds = new Map<string, Window>() // per address or key: new identities this hour
@@ -138,16 +141,22 @@ export function createWisp(engine: Engine, o: { secret?: string; port: () => num
   const log = engine.log
   const stats = engine.stats
 
-  const motd = () =>
-    w.hosted
-      ? `wmd hosted relay${w.version ? ` ${w.version}` : ''}: the operator sees destination names, DNS names and plain-http content (TLS traffic is not visible); ` +
-        `abuse contact ${w.hosted.contact}; ${w.hosted.limitsLine()}; blocked ports: ${(o.blockedPorts ?? [25]).join(', ') || 'none'}`
-      :
-    `wmd-relay${w.version ? ` ${w.version}` : ''}: up to ${o.maxConns ?? 64} streams per guest; ${o.rateDown ?? 16 << 20} B/s down and ` +
-    `${o.rateUp ?? 4 << 20} B/s up; blocked ports: ${(o.blockedPorts ?? [25]).join(', ') || 'none'}; private, loopback and metadata addresses are refused`
+  const motd = () => {
+    const ports = `blocked ports: ${(o.blockedPorts ?? []).join(', ') || 'none'}`
+    if (w.hosted) {
+      return `wmd hosted relay${w.version ? ` ${w.version}` : ''}: the operator sees destination names, DNS names and plain-http content (TLS traffic is not visible); ` +
+        `abuse contact ${w.hosted.contact}; ${w.hosted.limitsLine()}; ${ports}`
+    }
+    const set = [
+      o.maxConns !== undefined && `up to ${o.maxConns} streams per guest`,
+      o.rateDown !== undefined && `${o.rateDown} B/s down`,
+      o.rateUp !== undefined && `${o.rateUp} B/s up`,
+    ].filter(Boolean)
+    return `wmd-relay${w.version ? ` ${w.version}` : ''}: ${set.length ? `${set.join('; ')}; ` : ''}${ports}; private, loopback and metadata addresses are refused`
+  }
 
   function serverExts(mode: Mode) {
-    const e = [ext.confirm(), ext.motd(motd()), ext.wmdCredit(0), ext.wmdHalfclose(), ext.wmdDns(), ext.wmdInstance()]
+    const e = [ext.confirm(), ext.motd(motd()), ext.wmdCredit(0), ext.wmdHalfclose(), ext.wmdDns(), ext.wmdInstance(), ext.wmdReason()]
     if (mode === 'key-pending') e.push(ext.passwordServer(true))
     return e
   }
@@ -182,12 +191,6 @@ export function createWisp(engine: Engine, o: { secret?: string; port: () => num
     const origin = req.headers.get('origin') || ''
     // before any table or the log sees it: no real page origin is this long
     if (origin.length > 256) return refuse(400, 'the Origin header is longer than 256 characters\n', 'origin too long', { addr })
-    if (w.hosted) {
-      const denied = w.hosted.deniedClient(ip, origin)
-      if (denied) return refuse(403, `${denied}\n`, 'denied', { addr, origin })
-      const closed = w.hosted.notAccepting()
-      if (closed) return refuse(503, `${closed}\n`, 'not accepting', { addr })
-    }
     const t = failed.get(addr)
     if (t && t.until > Date.now()) return refuse(429, 'too many wrong keys from this address; wait\n', 'key throttle', { addr }) // set only after ADDR_FAILS
     if (open && w.checkHost && !LOOPBACK_HOST.test(req.headers.get('host') || '')) {
@@ -257,15 +260,22 @@ export function createWisp(engine: Engine, o: { secret?: string; port: () => num
     } else {
       return refuse(401, 'no token\n', 'no token', { origin })
     }
-    const n = inHandshake.get(addr) || 0
-    if (n >= preAuth) return refuse(429, 'too many connections opening from this address; wait\n', 'pre-auth limit', { addr })
-    inHandshake.set(addr, n + 1)
+    let pre = false
+    if (mode === 'key-pending') {
+      const n = inHandshake.get(addr) || 0
+      if (n >= preAuth) return refuse(429, 'too many connections opening from this address; wait\n', 'pre-auth limit', { addr })
+      inHandshake.set(addr, n + 1)
+      pre = true
+    }
+    // hosted: the socket counts from now (rule E); a refusal waits for the handshake, so the page hears why (rule I)
+    const full = w.hosted?.claimHandshake() ?? null
     const headers: Record<string, string> = {}
     if (v2 && protos.length) headers['Sec-WebSocket-Protocol'] = protos.includes(SUBPROTOCOL) ? SUBPROTOCOL : protos[0]
-    const data = { kind: 'wisp', v2, mode, addr, ip, sid, uid, grp, exp, p, key, origin, hs: null as any, hsTimer: null as any, pre: true }
+    const data = { kind: 'wisp', v2, mode, addr, ip, sid, uid, grp, exp, p, key, origin, hs: null as any, hsTimer: null as any, pre, claimed: !!w.hosted && !full, refuse: full as Why | null, at: performance.now() }
     const ok = srv.upgrade(req, Object.keys(headers).length ? { data, headers } : { data }) // Bun refuses an empty headers object
     if (!ok) {
       release(data)
+      unclaim(data)
       return reply('upgrade failed\n', 400)
     }
     return undefined
@@ -291,6 +301,13 @@ export function createWisp(engine: Engine, o: { secret?: string; port: () => num
   }
   const keyThrottled = (addr: string, id: string) => (failed.get(`${addr}|${id}`)?.until ?? 0) > Date.now()
 
+  /** A hosted socket's count, given back when it closes before a session took it over. */
+  function unclaim(d: any) {
+    if (!d.claimed) return
+    d.claimed = false
+    w.hosted?.unclaim()
+  }
+
   /** The socket left its handshake (done or gone): it no longer counts against the pre-auth cap. */
   function release(d: any) {
     if (!d.pre) return
@@ -310,24 +327,40 @@ export function createWisp(engine: Engine, o: { secret?: string; port: () => num
     const r = d.hs.start()
     sendAll(ws, r.send)
     if (r.done) return finish(ws, null)
-    d.hsTimer = setTimeout(() => {
-      if (d.session) return
-      log({ ev: 'session-refused', proto: 'wisp', why: 'handshake timeout', addr: d.addr })
-      ws.close(1008, 'handshake timeout')
-    }, handshakeMs)
+    handshaking.add(ws)
+    if (handshakeMs > 0) {
+      d.hsTimer = setTimeout(() => {
+        if (d.session) return
+        log({ ev: 'session-refused', proto: 'wisp', why: 'handshake timeout', addr: d.addr })
+        ws.close(1008, 'handshake timeout')
+      }, handshakeMs)
+    }
   }
 
-  function rejectHs(ws: any, reason: number, why: string) {
+  function rejectHs(ws: any, reason: number, why: string, rule?: string) {
     const d = ws.data
-    log({ ev: 'session-refused', proto: 'wisp', why, addr: d.addr })
+    log({ ev: 'session-refused', proto: 'wisp', why, addr: d.addr, ...(rule ? { rule } : {}) })
     stats.refusedSessions++
     sendAll(ws, d.hs.reject(reason))
     ws.close(1008, closeWords(reason).slice(0, 120))
   }
 
+  /** A rule refused the session (hosted): REASON when the client lists wmd-reason, then CLOSE on stream 0, then 4011 in words. */
+  function refuseHs(ws: any, client: any, why: Why) {
+    const d = ws.data
+    log({ ev: 'session-refused', proto: 'wisp', why: why.words, rule: why.rule, addr: d.addr, origin: d.origin })
+    stats.refusedSessions++
+    const code = /^(denied-|not-allowed-site)/.test(why.rule) ? CLOSE.BLOCKED : CLOSE.THROTTLED
+    if (client?.common?.has(EXT.WMD_REASON)) ws.send(reasonPacket(0, REASON_KIND.REFUSED, why.rule, why.until ?? 0, why.words))
+    if (d.v2) sendAll(ws, d.hs.reject(code))
+    ws.close(4011, why.words.slice(0, 120))
+  }
+
   async function finish(ws: any, client: any) {
     const d = ws.data
+    handshaking.delete(ws)
     if (d.hsTimer) clearTimeout(d.hsTimer)
+    if (d.refuse) return refuseHs(ws, client, d.refuse)
     let share: Shared | undefined
     let allow: AllowEntry[] | undefined
     let fresh = false
@@ -363,23 +396,30 @@ export function createWisp(engine: Engine, o: { secret?: string; port: () => num
       if (fresh && engine.principals.size >= maxPrincipals) {
         // least recently admitted identity with no live session goes first (plan 5: LRU); refuse only when all are live
         for (const [k, q] of engine.principals) if (!q.live) { engine.principals.delete(k); break }
-        if (engine.principals.size >= maxPrincipals) return rejectHs(ws, CLOSE.THROTTLED, 'too many identities remembered')
+        if (engine.principals.size >= maxPrincipals) return rejectHs(ws, CLOSE.THROTTLED, 'too many identities remembered', 'maxPrincipals')
       }
-      if (fresh) {
+      if (fresh && instancesPerHour !== Infinity) {
         let win = newIds.get(d.grp)
         if (!win) newIds.set(d.grp, (win = new Window(instancesPerHour, 60 * 60_000)))
-        if (!win.hit()) return rejectHs(ws, CLOSE.THROTTLED, `more than ${instancesPerHour} new instances this hour from ${d.grp}`)
+        if (!win.hit()) return rejectHs(ws, CLOSE.THROTTLED, `more than ${instancesPerHour} new instances this hour from ${d.grp}`, 'instancesPerHour')
       }
       const a = engine.admit(d.uid, d.grp, Date.now(), { proto: 'wisp' }, share)
-      if (!a.ok) return rejectHs(ws, CLOSE.THROTTLED, a.body.trim())
+      if (!a.ok) return rejectHs(ws, CLOSE.THROTTLED, a.body.trim(), a.rule)
       d.p = a.p
     }
     let adm: ReturnType<Governor['admitSession']> | null = null
     if (w.hosted) {
-      const closed = w.hosted.notAccepting()
-      if (closed) return rejectHs(ws, CLOSE.THROTTLED, closed)
-      adm = w.hosted.admitSession({ ip: d.ip, grp: d.grp, origin: d.origin, fresh, end: words => ws.close(4011, words.slice(0, 120)) })
-      if (!adm.ok) return rejectHs(ws, CLOSE.THROTTLED, adm.why)
+      const reason = !!client?.common?.has(EXT.WMD_REASON)
+      const tell = (kind: number, rule: string, until: number, words: string) => {
+        if (reason && ws.readyState === 1) ws.send(reasonPacket(0, kind, rule, until, words))
+      }
+      const end = (why: Why) => {
+        tell(REASON_KIND.REFUSED, why.rule, why.until ?? 0, why.words)
+        ws.close(4011, why.words.slice(0, 120))
+      }
+      adm = w.hosted.admitSession({ ip: d.ip, grp: d.grp, origin: d.origin, end, tell, claimed: d.claimed })
+      if (!adm.ok) return refuseHs(ws, client, adm)
+      d.claimed = false // the session holds the socket's count now
       d.rel = adm.adm.release
     }
     const common: Set<number> = client?.common ?? new Set()
@@ -390,7 +430,7 @@ export function createWisp(engine: Engine, o: { secret?: string; port: () => num
     if (adm?.ok) s.hx = adm.adm
     s.allow = allow
     const sw: SessionW = {
-      engine, v2: d.v2, confirm: common.has(EXT.CONFIRM), credit: common.has(EXT.WMD_CREDIT), halfclose: common.has(EXT.WMD_HALFCLOSE),
+      engine, v2: d.v2, confirm: common.has(EXT.CONFIRM), reason: common.has(EXT.WMD_REASON), credit: common.has(EXT.WMD_CREDIT), halfclose: common.has(EXT.WMD_HALFCLOSE),
       dns: common.has(EXT.WMD_DNS), buffer, idleTimer: null, unknownLogged: false,
     }
     s.w = sw
@@ -437,7 +477,10 @@ export function createWisp(engine: Engine, o: { secret?: string; port: () => num
       if (q) for (const b of q) writeUp(s, st, x, b)
       if (x.shutPending && !st.closed) engine.clientEnd(s, st.id)
     },
-    refused: (s, id, code) => send(s, closePacket(id, reasonFor(code))),
+    refused(s, id, code, why, rule, until) {
+      if (rule && (s.w as SessionW)?.reason) send(s, reasonPacket(id, REASON_KIND.REFUSED, rule, until ?? 0, why))
+      send(s, closePacket(id, reasonFor(code)))
+    },
     data(s, st, bytes) {
       sw(st).last = performance.now()
       send(s, dataPacket(st.id, bytes))
@@ -446,7 +489,10 @@ export function createWisp(engine: Engine, o: { secret?: string; port: () => num
       if ((s.w as SessionW).halfclose) send(s, shutdownPacket(st.id))
       else engine.clientEnd(s, st.id) // no half-close: the stream is over once the remote's bytes are all sent
     },
-    abort: (s, st, code) => send(s, closePacket(st.id, st.w?.idle ? CLOSE.DATA_TIMEOUT : reasonFor(code))),
+    abort(s, st, code, why, rule, until) {
+      if (rule && (s.w as SessionW)?.reason) send(s, reasonPacket(st.id, REASON_KIND.REFUSED, rule, until ?? 0, why))
+      send(s, closePacket(st.id, st.w?.idle ? CLOSE.DATA_TIMEOUT : reasonFor(code)))
+    },
     grant(s, st, n) {
       const x = sw(st)
       x.released += n
@@ -584,8 +630,10 @@ export function createWisp(engine: Engine, o: { secret?: string; port: () => num
 
   function close(ws: any, code: number, reason: string) {
     const d = ws.data
+    handshaking.delete(ws)
     if (d.hsTimer) clearTimeout(d.hsTimer)
     release(d)
+    unclaim(d)
     d.rel?.()
     const s: Session | undefined = d.session
     if (!s) return
@@ -600,9 +648,21 @@ export function createWisp(engine: Engine, o: { secret?: string; port: () => num
     /** Maintenance: every stream gets CLOSE 0x01 (the spec has no maintenance code), then the socket closes 1001 in words. */
     drain(ws: any) {
       const s: Session | undefined = ws.data.session
-      if (s && !s.closed) for (const st of s.streams.values()) ws.send(closePacket(st.id, CLOSE.UNKNOWN))
+      if (s && !s.closed) {
+        if ((s.w as SessionW)?.reason) ws.send(reasonPacket(0, REASON_KIND.REFUSED, 'draining', 0, DRAIN_WORDS))
+        for (const st of s.streams.values()) ws.send(closePacket(st.id, CLOSE.UNKNOWN))
+      }
       ws.close(1001, DRAIN_WORDS)
     },
+    /** Rule G: the sockets still in their handshake, oldest first. */
+    handshakes: () => [...handshaking],
+    /** Rule G: close one, at once; its count is given back now. */
+    closeHandshake(ws: any) {
+      handshaking.delete(ws)
+      unclaim(ws.data)
+      log({ ev: 'session-refused', proto: 'wisp', why: 'closed unfinished to free a socket', rule: 'busy', addr: ws.data.addr })
+      ws.close(1013, 'the relay is full')
+    },
     fetch,
     open: open_,
     message,

package/src/host/ctl.js

@@ -22,6 +22,8 @@ export const STREAM_STDIN = 1
 export const STREAM_STDOUT = 2
 export const STREAM_STDERR = 3
 export const STREAM_EXIT = 4
+/** A keep-running container's command: {state: 'running'|'exited'|'none', code} (control.go streamCommand). */
+export const STREAM_COMMAND = 5
 export const EXIT_SYNCED = 1
 /** readFrame's sanity limit (ctlproto.go). */
 export const MAX_CTL_FRAME = 10 * 1024 * 1024
@@ -262,8 +264,11 @@ export class CtlStream {
  * guest's yamux window lets the service send. Nothing is queued without bound.
  */
 export class CtlProcess {
-  constructor(stream, { onStdout, onStderr, onControl, op = '', mapExec = false } = {}) {
+  constructor(stream, { onStdout, onStderr, onControl, onCommand, op = '', mapExec = false } = {}) {
     this.stream = stream
+    this.onCommand = onCommand
+    /** The last report of a keep-running container's command ({state, code}), or null. */
+    this.command = null
     this.onStdout = onStdout
     this.onStderr = onStderr
     this.onControl = onControl
@@ -320,6 +325,17 @@ export class CtlProcess {
           this.stream.closeWrite() // nothing more to say; the guest closes its side
           this._resolve({ ...this.exit })
         }
+      } else if (f.id === STREAM_COMMAND) {
+        let st
+        try {
+          st = JSON.parse(new TextDecoder().decode(f.payload))
+        } catch {
+          continue
+        }
+        // the guest sends the last state again after every attach (a rewind lands here): report changes only
+        if (this.command && this.command.state === st.state && this.command.code === st.code) continue
+        this.command = { state: st.state, code: st.code | 0 }
+        this.onCommand?.({ ...this.command })
       } else if (f.id === STREAM_CONTROL) this.onControl?.(f.payload)
     }
   }
@@ -653,6 +669,17 @@ export class ControlClient {
     })
   }
 
+  /**
+   * Starts the command of a keep-running container whose init has none running (browser only:
+   * a base snapshot is made with args [] and the page's command is started after the restore).
+   * user is "uid:gid" or a name from the image. Resolves to the guest's reply ({ok} or {error}).
+   */
+  startCommand({ args, env = [], cwd = '', user = '' } = {}) {
+    const bad = checkProcessRequest({ op: 'exec', args, env, cwd })
+    if (bad) return Promise.resolve({ ok: false, error: bad.replace(/^exec:/, 'command:') })
+    return this.simple({ op: 'command', args, env, cwd, user })
+  }
+
   kill({ id, sig = '', all = false } = {}) {
     return this.simple({ op: 'kill', id, sig, all })
   }
@@ -724,7 +751,13 @@ function defaultMounts() {
  * @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}}
+ * @param {boolean} [o.init]         docker run --init: tini at /sbin/docker-init runs the command
+ * @param {boolean} [o.keepRunning]  wmd's keep-running init at /sbin/docker-init: the container stays up
+ *        after its command ends; args may be [] (nothing runs until ControlClient.startCommand). Send the
+ *        run request with command: true and stop_signal (see runOptions).
+ * @param {string} [o.stopSignal]    the image's STOPSIGNAL (default SIGTERM), for runOptions
+ * @returns {{files: Record<string, string|Uint8Array|{data, mode}>, spec: object, run: object}}  run: fields to add to
+ *        the run request ({command, stop_signal} for keepRunning, else {})
  */
 export function containerBundle(o) {
   const cwd = o.cwd || '/'
@@ -735,7 +768,7 @@ export function containerBundle(o) {
     process: {
       terminal: !!o.terminal,
       user: { uid: user.uid, gid: user.gid, ...(user.additionalGids?.length ? { additionalGids: user.additionalGids } : {}) },
-      args: [...o.args],
+      args: o.init || o.keepRunning ? [DOCKER_INIT, '--', ...o.args] : [...o.args],
       env: [...(o.env || [])],
       cwd,
       capabilities: { bounding: DEFAULT_CAPS, effective: DEFAULT_CAPS, permitted: DEFAULT_CAPS },
@@ -752,6 +785,10 @@ export function containerBundle(o) {
       resources: { devices: [{ allow: false, access: 'rwm' }] },
     },
   }
+  if (o.init || o.keepRunning) {
+    // as dockerd binds its docker-init (internal/engine/ocispec.go): the guest's tini, or its own init for keep-running
+    spec.mounts.push({ destination: DOCKER_INIT, type: 'bind', source: o.keepRunning ? '/sbin/init' : '/sbin/tini', options: ['bind', 'ro'] })
+  }
   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'] })
   }
@@ -774,5 +811,9 @@ export function containerBundle(o) {
   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 }
+  const run = o.keepRunning ? { command: true, stop_signal: o.stopSignal || 'SIGTERM' } : {}
+  return { files, spec, run }
 }
+
+/** Where dockerd puts the init of docker run --init. */
+export const DOCKER_INIT = '/sbin/docker-init'

package/src/net/wisp-client.js

@@ -15,13 +15,15 @@
 //   - 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).
+//   - status: onStatus({state, relay, reason, words, rule?, until?}) for the page (plan §6). With wmd-reason (0xE9) a
+//     relay says which rule refused or slowed the page and when it lifts (until: ms since 1970, 0 = no time): state
+//     'limited' for a refusal, 'slowed' for a slowdown (plan §16, rule I).
 //
 // 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,
+  CLOSE, EXT, PT, RCODE, REASON_KIND, SUBPROTOCOL, ClientHandshake, answerAddrs, closePacket, closeWords, connectPacket, creditPacket,
   dataPacket, ext, lookupPacket, parse, shutdownPacket,
 } from './wisp.js'
 
@@ -141,6 +143,10 @@ export class WispClient {
     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.readyStatus = null // the status the open connection had before a 'limited' or 'slowed' one
+    this.whys = new Map() // stream id -> {rule, until, words}: the REASON before its CLOSE
+    this.closeWhy = null // the REASON on stream 0 before the relay closes the session
+    this.liftTimer = 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')
   }
@@ -149,15 +155,33 @@ export class WispClient {
     this.stack = stack
   }
 
-  #status(state, reason, words) {
+  #status(state, reason, words, why) {
     let relay = ''
     try {
       relay = this.url ? new URL(this.url).origin.replace(/^http/, 'ws') : ''
     } catch {}
     this.status = { state, relay, reason: reason ?? 0, words: words || '' }
+    if (why) Object.assign(this.status, { rule: why.rule, until: why.until || 0 })
     this.onStatus(this.status)
   }
 
+  /** A rule refused or slowed this page while the connection stays up; the ready status comes back when it lifts. */
+  #limited(state, why) {
+    clearTimeout(this.liftTimer)
+    this.#status(state, 0, why.words, why)
+    const wait = why.until ? why.until - Date.now() : 0
+    if (wait > 0) this.liftTimer = setTimeout(() => this.#lift(), wait)
+  }
+
+  #lift() {
+    clearTimeout(this.liftTimer)
+    this.liftTimer = null
+    if (this.up && this.readyStatus && (this.status?.state === 'limited' || this.status?.state === 'slowed')) {
+      const r = this.readyStatus
+      this.#status(r.state, r.reason, r.words)
+    }
+  }
+
   #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
@@ -242,7 +266,7 @@ export class WispClient {
     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))],
+      exts: [ext.confirm(), ext.wmdCredit(WINDOW), ext.wmdHalfclose(), ext.wmdDns(), ext.wmdInstance(hexBytes(this.instance)), ext.wmdReason()],
       password: this.key ? { user: this.key.id, pass: this.key.secret } : null,
     })
     const openTimer = setTimeout(() => !this.up && this.ws === ws && ws.close(), this.openTimeoutMs)
@@ -281,14 +305,20 @@ export class WispClient {
       if (wasUp) {
         this.stats.drops++
         this.streams.clear()
+        this.whys.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)
+        clearTimeout(this.liftTimer)
+        const told = this.closeWhy
+        this.closeWhy = null
+        // a relay that closed us on purpose (maintenance, 1001; a rule or its operator, 4011) is not back in a moment: wait
+        // until the rule lifts, or the longest
+        this.backoff = e.code === CLOSE_MAINTENANCE || e.code === CLOSE_DENIED || told ? BACKOFF_MAX_MS : BACKOFF_MIN_MS
+        this.nextAt = this.now() + Math.max(this.backoff, told?.until ? told.until - Date.now() : 0)
+        const why = told?.words || `relay connection closed (${e.code}${e.reason ? ` ${e.reason}` : ''})`
+        this.log(`net: the relay connection closed (${e.code}${e.reason ? ` ${e.reason}` : ''}${told ? `; ${told.rule}` : ''}): every connection is reset`)
+        if (told) this.#status('limited', 0, why, told)
+        else this.#status('down', 0, why)
         this.stack?.onRelayDown(why)
         return
       }
@@ -298,9 +328,10 @@ export class WispClient {
         return this.#socket([], false)
       }
       if (authFail) {
-        const st = ['auth-required', 'auth-refused', 'version'].includes(authFail.state) ? authFail.state : 'unreachable'
+        const st = ['auth-required', 'auth-refused', 'version', 'limited'].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)
+        const why = authFail.rule ? { rule: authFail.rule, until: authFail.until, words: authFail.words } : null
+        return this.#failed(authFail.words, st, authFail.reason, why)
       }
       this.#failed(`could not connect to the relay (${e.code}${e.reason ? ` ${e.reason}` : ''})`)
     }
@@ -320,6 +351,7 @@ export class WispClient {
       this.log(`net: ${words}`)
       this.#status('degraded', 0, words)
     } else this.#status('connected', 0, motd)
+    this.readyStatus = this.status
     const q = this.queue
     this.queue = []
     for (const x of q) {
@@ -328,15 +360,16 @@ export class WispClient {
     }
   }
 
-  #failed(why, state = 'unreachable', reason = 0) {
+  #failed(why, state = 'unreachable', reason = 0, rule = null) {
     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 wait = Math.max(this.backoff, rule?.until ? rule.until - Date.now() : 0) // a rule that names its end: not before it
+    this.nextAt = this.now() + wait
+    this.log(`net: ${why}${rule ? ` (${rule.rule})` : ''}; next try in ${Math.round(wait)} ms`)
+    this.#status(state, reason, why, rule)
     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
@@ -351,7 +384,21 @@ export class WispClient {
 
   // ---- packets from the relay ----
 
+  /** Rule I: a REASON. On a stream it gives that stream's CLOSE its words; on 0 it is the whole session's state. */
+  #reason(m) {
+    if (!this.server?.has(EXT.WMD_REASON)) return
+    const why = { rule: m.rule, until: m.until, words: m.words }
+    if (m.id !== 0) {
+      if (m.kind === REASON_KIND.REFUSED && this.streams.has(m.id)) this.whys.set(m.id, why)
+      return
+    }
+    if (m.kind === REASON_KIND.SLOWED) return this.#limited('slowed', why)
+    if (m.kind === REASON_KIND.CLEARED) return this.status?.state === 'slowed' && this.status.rule === m.rule && this.#lift()
+    if (m.kind === REASON_KIND.REFUSED) this.closeWhy = why // the relay closes the session next
+  }
+
   #dispatch(m) {
+    if (!m.error && m.type === PT.REASON) return this.#reason(m) // about the session too, so not tied to an attached stack
     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)`)
@@ -364,6 +411,7 @@ export class WispClient {
         st.counter = m.n
         if (!st.confirmed) {
           st.confirmed = true
+          if (this.status?.state === 'limited' && !(this.status.until > Date.now())) this.#lift()
           s.onConnected(m.id, E.OK, WINDOW, '')
         }
         this.#flush(m.id, st)
@@ -403,7 +451,13 @@ export class WispClient {
         const st = this.streams.get(m.id)
         if (!st) return
         this.#forget(m.id, st)
-        const words = closeWords(m.reason)
+        const told = this.whys.get(m.id)
+        this.whys.delete(m.id)
+        if (told) {
+          this.log(`net: stream ${m.id}: ${told.rule}: ${told.words}`)
+          this.#limited('limited', told)
+        }
+        const words = told?.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)