@preventive/triage 1.0.0-alpha.0 → 1.0.0-alpha.10

package/server-e2e/ws-server.ts

@@ -0,0 +1,276 @@
+// WebSocket runtime: the per-connection handler (Peer setup, message
+// dispatch, close/error) and the server-driven heartbeat sweep. Wired
+// once at boot onto the shared `wss` with the protocol handlers +
+// lifecycle hooks it dispatches to. Kept out of index.ts so the WS
+// message loop — the most concurrency-sensitive surface — is one unit.
+//
+// `setupPeerConnection` is the per-connection handler in isolation; the
+// SSE+POST fallback (./sse-server.ts) calls it with an `SseSession`
+// adapter so both transports share one dispatcher and one Peer
+// lifecycle. The adapter is structurally compatible — `setupPeerConnection`
+// only touches the `EventEmitter` + `readyState`/`OPEN`/`send`/`close`
+// subset that both real WSs and the adapter expose.
+
+import type { WebSocket, WebSocketServer } from 'ws'
+import { Buffer } from 'node:buffer'
+import type { IncomingMessage as HttpRequest } from 'node:http'
+import { decodeUtf8 } from '../common/utf8.js'
+import type { SaveErrorReason } from '../common/save-error-reason.ts'
+import type { ServerInfo } from '../common/server-info.ts'
+import { Peer, type PeerRegistry } from './peer.ts'
+import { errMsg, errStack, randomId } from './util.ts'
+import type { SaveMsg, SubscribeMsg } from './sign.ts'
+import type { AuthenticateMsg } from './auth.ts'
+import type { ObjstoreHandlers } from './objstore/handlers.ts'
+import type { ObjstoreDeleteMsg, ObjstoreFetchMsg, ObjstorePutBeginMsg } from './objstore/sign.ts'
+
+// Wire-message envelope as it lands post-`JSON.parse`. Every field is
+// `unknown` until a handler narrows it; the type just documents the
+// dispatch surface so call sites can pattern-match on `msg.type`.
+type IncomingMessage = {
+  type?: unknown
+  [k: string]: unknown
+}
+
+// Subset of `WsServerDeps` consumed by `setupPeerConnection`. The
+// heartbeat sweep + the `wss` reference stay in `WsServerDeps`; the
+// SSE path doesn't need them.
+export type PeerConnectionDeps = {
+  peers: PeerRegistry
+  // The mode this server advertises, emitted as the first `server-info`
+  // frame on every connection (see setupPeerConnection).
+  serverInfo: ServerInfo
+  send: (socket: WebSocket, msg: object) => void
+  unsubscribeAll: (socket: WebSocket) => void
+  handleSave: (socket: WebSocket, msg: SaveMsg) => Promise<void>
+  handleSubscribe: (socket: WebSocket, msg: SubscribeMsg) => Promise<void>
+  handleAuthenticate: (socket: WebSocket, msg: AuthenticateMsg) => void
+  sendSaveError: (socket: WebSocket, workspaceTag: string, base: string | null, reason: SaveErrorReason) => void
+  objstore: ObjstoreHandlers
+  track: (promise: Promise<unknown>) => void
+  isShuttingDown: () => boolean
+  maxInflightPerSocket: number
+  debug: boolean
+}
+
+export type WsServerDeps = PeerConnectionDeps & {
+  wss: WebSocketServer
+  heartbeatIntervalMs: number
+}
+
+// Per-connection setup: create Peer, send challenge, wire message /
+// close / error / pong listeners. `socket` is the WebSocket-shaped
+// surface — a real `ws` `WebSocket`, or an `SseSession` cast through
+// `as unknown as WebSocket`; only the subset both expose is used.
+export function setupPeerConnection(socket: WebSocket, req: HttpRequest, deps: PeerConnectionDeps): void {
+  const {
+    peers, serverInfo, send, unsubscribeAll, handleSave, handleSubscribe, handleAuthenticate,
+    sendSaveError, objstore, track, isShuttingDown, maxInflightPerSocket, debug,
+  } = deps
+  if (debug) console.log(`connect from ${req.socket.remoteAddress}`)
+  // One Peer holds this connection's state, created before any client
+  // frame can arrive (`socket.on('message')` is wired below). The
+  // heartbeat sweep's two-tick liveness check (see below) is the only
+  // thing closing FDs for an otherwise-idle peer.
+  const peer = new Peer(randomId())
+  peers.set(socket, peer)
+  socket.on('pong', () => { peer.alive = true })
+  // Issue the per-connection challenge nonce FIRST — before the client can
+  // send anything that needs it, AND as frame #0 so clients/tests that
+  // positionally read the first frame as the challenge keep working. The
+  // client signs it into every `workspace-subscribe` (see canonicalSubscribe
+  // in server-e2e/sign.ts); a captured subscribe frame can't be replayed from
+  // a different connection because that connection's nonce differs and the
+  // signature won't verify against the new canonical bytes. Round-9 H2.
+  send(socket, { type: 'challenge', nonce: peer.challenge })
+  // Then advertise the sync protocol (the mode probe), right after the
+  // challenge — the WS plane and the SSE fallback share this path. A client
+  // uses it to detect the mode, cache it, and refuse a cross-mode switch.
+  // Unauthenticated + mode-agnostic; an older client ignores it (predicate
+  // readers skip it; the workspaceTag demux drops it).
+  send(socket, { type: 'server-info', ...serverInfo })
+  // Per-socket handlers are DELIBERATELY NOT serialized (vs the
+  // client-side `messageQueue = messageQueue.then(...)` Promise
+  // chain inside `client/triage-sync.ts:onTransportMessage`).
+  // Each inbound frame spawns its own tracked async IIFE; two
+  // frames from the same socket can interleave across `await`
+  // boundaries inside the handlers. Per-resource correctness needs
+  // no in-process lock: `commitRevision` resolves concurrent saves
+  // via its single gated INSERT (one snapshot + the
+  // `UNIQUE(workspace_tag, seq)` PK — see `server-e2e/db.ts`), and the
+  // objstore handlers (`commitPut` / `beginPut` / `deleteObject`)
+  // via the version compare-and-set + content-addressing (see
+  // `server-e2e/objstore/store.ts`), backed by post-await
+  // `readyState === OPEN` rechecks in every objstore handler. The
+  // unbounded fan-out is capped by `maxInflightPerSocket` (see
+  // also the `'busy'` NACK at the cap below). Concurrent dispatch
+  // is intentional: it lets multi-workspace clients multiplex
+  // saves + subscribes over one socket without HOL blocking.
+  // Audit follow-up to round-15 concurrency review.
+  socket.on('message', (data: Buffer, isBinary: boolean) => {
+    // Drop new work once shutdown started — `wss.close()` stops new
+    // CONNECTIONS but already-open sockets can still send messages.
+    // Without this gate a message arriving between `wss.close()`
+    // resolving and the `inFlight` snapshot would spawn a handler
+    // that's NOT in the snapshot, then resume against the just-
+    // closed DB and throw inside the commit's gated INSERT. Audit
+    // round-9.
+    if (isShuttingDown()) return
+    // Wire protocol is JSON over text frames. A binary frame is
+    // either a buggy client or someone probing — drop without
+    // attempting to interpret it as text.
+    if (isBinary) return
+    let msg: IncomingMessage | null = null
+    try {
+      // `decodeUtf8` is fatal on invalid UTF-8 (vs `Buffer.toString`
+      // which silently substitutes U+FFFD). The substitution path
+      // would let mangled bytes pass JSON.parse only to fail
+      // signature verification deeper in the handler — wasted work
+      // and noisier logs. Fail at the gate.
+      msg = JSON.parse(decodeUtf8(data)) as IncomingMessage
+    } catch { return }
+    if (!msg || typeof msg !== 'object') return
+    const parsed: IncomingMessage = msg
+    // Per-socket inflight cap. Each tracked handler keeps the socket
+    // alive in `inFlight`, and a peer who keeps firing valid frames
+    // can spawn unbounded handlers — growing SIGTERM drain time and
+    // memory. Drop new work above the cap. Heartbeat ping is the
+    // exception: it's stateless, synchronous, and we want to KEEP
+    // responding so the peer doesn't drop the socket while we're
+    // shedding load. Pings go through a fast inline `send(pong)`
+    // path BELOW that doesn't bump the per-socket inflight counter,
+    // so a ping-spam at the cap can't outrun the gate. Transport
+    // audit `server-e2e/index.ts:590` + post-#58 audit follow-up.
+    if (parsed.type === 'ping') {
+      send(socket, { type: 'pong' })
+      return
+    }
+    // `authenticate` runs synchronously (constant-time bytes compare
+    // — no DB, no I/O), so it shares the same fast-inline path as
+    // `ping` and bypasses the per-socket inflight counter. Keeping
+    // it out of the IIFE pool means an unauthenticated client can
+    // still complete the handshake when the socket is otherwise
+    // saturated (matching the philosophy of the `busy` NACK path
+    // for `workspace-save`: don't strand a recoverable handshake
+    // behind the cap).
+    if (parsed.type === 'authenticate') {
+      handleAuthenticate(socket, parsed as AuthenticateMsg)
+      return
+    }
+    if (peer.inflight >= maxInflightPerSocket) {
+      if (debug) console.warn(`drop message: socket inflight ${peer.inflight} >= ${maxInflightPerSocket}`)
+      // For workspace-save specifically, send a typed NACK so the
+      // client's `pending` slot clears IMMEDIATELY instead of
+      // hanging until the next heartbeat (~15–30s). Reason `busy`
+      // is server-side overload; safe to retry. Same wire envelope
+      // as the existing `too-large` save-error path.
+      //
+      // Wire-order interaction with `'stale-base'`: the cap-path
+      // send is SYNCHRONOUS in this message callback and lands on
+      // the wire BEFORE any handler IIFE's `await`-completed reply.
+      // If an earlier in-flight `workspace-save` (frame F1) ends up
+      // emitting a catch-up `workspace-state` + `'stale-base'` while
+      // a later frame F2 hits the cap, the order is `'busy'`(F2) →
+      // `workspace-state`(F1) → `'stale-base'`(F1). The client's
+      // `handleSaveError` correlates on `base`, and the wire-order
+      // trick documented in `common/save-error-reason.ts` (catch-up
+      // clears `pending` before the stale-base frame's
+      // `handleSaveError` runs) still holds.
+      const rawBase = (parsed as SaveMsg).base
+      const baseField: string | null = typeof rawBase === 'string' ? rawBase : null
+      const rawTag = (parsed as SaveMsg).workspaceTag
+      const tagField = typeof rawTag === 'string' ? rawTag : null
+      if (parsed.type === 'workspace-save' && tagField != null) {
+        // `sendSaveError` runs its taxonomy-guard before the wire
+        // send and throws on an unknown reason. Every OTHER emit
+        // site lives inside the `handler` IIFE's try/catch — this
+        // cap path is the only one outside it. Mirror the same
+        // forensic envelope so a future bad reason here surfaces
+        // as `Handler error (type=workspace-save): …` rather than
+        // escaping to ws's emitter as an uncaught.
+        try {
+          sendSaveError(socket, tagField, baseField, 'busy')
+        } catch (err) {
+          console.warn('Handler error (type=workspace-save):', errStack(err))
+        }
+      }
+      return
+    }
+    peer.inflight += 1
+    const handler = (async () => {
+      try {
+        if (parsed.type === 'workspace-save') await handleSave(socket, parsed as SaveMsg)
+        else if (parsed.type === 'workspace-subscribe') await handleSubscribe(socket, parsed as SubscribeMsg)
+        // Objstore control plane — bytes ride the REST plane via
+        // tokens these handlers mint. The Objstore*Msg types are
+        // weak shapes (every field `unknown`); the handlers narrow
+        // each field through their own validators on entry.
+        else if (parsed.type === 'objstore-put-begin') await objstore.handlePutBegin(socket, parsed as ObjstorePutBeginMsg)
+        else if (parsed.type === 'objstore-delete') await objstore.handleDelete(socket, parsed as ObjstoreDeleteMsg)
+        else if (parsed.type === 'objstore-fetch') await objstore.handleFetch(socket, parsed as ObjstoreFetchMsg)
+      } catch (err) {
+        // Forensic logging for unexpected throws — the handlers all
+        // have internal narrow catches (e.g. signature reject paths);
+        // anything reaching here is unexpected. Include the wire
+        // `type` so an operator can correlate to a specific code
+        // path, and prefer `.stack` over `.message` so the post-
+        // mortem has the throw site.
+        const typeStr = typeof parsed.type === 'string' ? parsed.type : '<unknown>'
+        console.warn(`Handler error (type=${typeStr}):`, errStack(err))
+      } finally {
+        peer.inflight -= 1
+      }
+    })()
+    track(handler)
+  })
+  socket.on('close', () => {
+    // `unsubscribeAll` reads `peer.tags` (peer still registered), then
+    // we drop the Peer. The Peer's state would GC once the socket is
+    // unreachable, but `wss.clients` / `ws` internals hold the socket
+    // strongly well past `close`, so the explicit delete frees it
+    // immediately. Audit round-10 + round-13.
+    unsubscribeAll(socket)
+    peers.delete(socket)
+  })
+  // Surface socket-level errors instead of swallowing — these are
+  // the signals operators want under abuse / network flakiness
+  // (TLS handshake failures, frame-decode errors, ws-protocol
+  // violations). `close` fires after `error` and runs the unsubscribe
+  // cleanup, so logging here doesn't risk leaking.
+  socket.on('error', (err: Error) => { console.warn('Socket error:', errMsg(err)) })
+}
+
+// Wires `wss.on('connection')` + starts the heartbeat. Returns the
+// timer so shutdown can clear it.
+export function installWsServer(deps: WsServerDeps): { heartbeatTimer: ReturnType<typeof setInterval> } {
+  const { wss, peers, heartbeatIntervalMs } = deps
+
+  wss.on('connection', (socket: WebSocket, req) => {
+    setupPeerConnection(socket, req, deps)
+  })
+
+  // Periodic heartbeat sweep. Two-tick liveness window: a socket that
+  // doesn't `pong` within `heartbeatIntervalMs` of our `ping` sees its
+  // tracker flip to `false`; on the NEXT tick we terminate. `try/catch`
+  // shrugs at any peer that races us into CLOSING / CLOSED (`ws.ping` /
+  // `ws.terminate` throw in that state) — the close event handles
+  // cleanup either way.
+  //
+  // `unref` so the timer alone doesn't keep the event loop alive
+  // (parity with `terminateTimer` in shutdown). Cleared in shutdown so
+  // a graceful SIGTERM doesn't fire one last ping race after wss.close.
+  const heartbeatTimer = setInterval(() => {
+    for (const ws of wss.clients) {
+      const peer = peers.get(ws)
+      if (peer?.alive === false) {
+        try { ws.terminate() } catch {}
+        continue
+      }
+      if (peer) peer.alive = false
+      try { ws.ping() } catch {}
+    }
+  }, heartbeatIntervalMs)
+  heartbeatTimer.unref?.()
+
+  return { heartbeatTimer }
+}

package/strip-types-loader.js

@@ -0,0 +1,94 @@
+// Module customization hook that erases TypeScript types using Node's
+// built-in `module.stripTypeScriptTypes()` — the same eraser that powers
+// Node's unflagged `.ts` execution, exposed here as an explicit loader so
+// this package can run its own `.ts` source after it's installed as a
+// dependency. Built on Node's bundled eraser, it needs no third-party dep
+// (cf. `amaro`, which is just the library Node already bundles for this).
+//
+// Why this is needed at all — Node DISABLES built-in `.ts` stripping for
+// any file under `node_modules` (it throws ERR_UNSUPPORTED_NODE_MODULES_
+// TYPE_STRIPPING), which is exactly where this package's `.ts` files live
+// once it's a dependency. A registered `load` hook is not bound by that
+// rule, so it restores `.ts` execution from inside `node_modules`.
+//
+// Registered as an entry point — `@preventive/triage/strip-types-loader` —
+// so consumers can run the server (or import `@preventive/triage/server`)
+// with the hook active:
+//   node --import @preventive/triage/strip-types-loader <entry>
+//
+// `registerHooks` (synchronous, in-thread) is used over the async,
+// worker-thread `module.register`: stripping is a pure synchronous string
+// transform, so there's no reason to round-trip every load through a
+// worker — and the read below is synchronous too.
+//
+// We must read + strip the source OURSELVES rather than delegate to
+// `nextLoad`: under `node_modules`, `nextLoad`'s default format detection
+// is what throws ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING, before our
+// hook ever sees the source. Reading the bytes and short-circuiting with
+// an explicit format sidesteps that gate.
+//
+// `mode: 'strip'` (types elided, no enum/namespace transform) suffices —
+// the repo is `erasableSyntaxOnly` (tsconfig.json). Strip mode replaces
+// each elided type with equal-width whitespace, so line AND column
+// positions survive 1:1 and stack traces stay exact without a source map.
+
+import { isUtf8 } from 'node:buffer'
+import { readFileSync } from 'node:fs'
+import { registerHooks, stripTypeScriptTypes } from 'node:module'
+import { fileURLToPath } from 'node:url'
+
+// `.ts` / `.mts` -> ESM, `.cts` -> CommonJS. The `kind` group is the
+// optional `m`/`c` infix; absent (plain `.ts`) defaults to ESM, which is
+// correct for this `"type": "module"` package.
+const TS_RE = /\.(?<kind>[cm])?ts$/u
+
+// Defence-in-depth: assert strip mode only ERASED — every output character
+// is either unchanged, replaced by whitespace, or replaced by a semicolon
+// (swc's ASI guard — swc-project/swc#9331). This enforces at runtime what
+// tsconfig's `erasableSyntaxOnly` asserts at type-check time: nothing but
+// type syntax was removed, so the bytes Node runs can't silently diverge
+// from the bytes we wrote.
+//
+// The comparison is per-CODE-POINT, not per-byte. swc preserves byte
+// offsets by swapping each elided multi-byte character for a *same-width*
+// Unicode whitespace char — e.g. an em-dash (U+2014) in a type-level
+// comment becomes U+2002 EN SPACE, not ASCII 0x20 — so a raw-byte check
+// would false-positive on the many such comments in this codebase. `\s`
+// matches those Unicode spaces, and strip preserves code-unit length too,
+// so string indices stay aligned.
+const WHITESPACE = /\s/u
+
+function assertOnlyErased(url, source, stripped) {
+  if (source.length !== stripped.length) {
+    throw new Error(`strip-types-loader: ${url} changed length ${source.length} -> ${stripped.length}; not a pure type erasure`)
+  }
+  for (let i = 0; i < stripped.length; i++) {
+    const ch = stripped[i]
+    if (ch === source[i] || ch === ';' || WHITESPACE.test(ch)) continue
+    throw new Error(`strip-types-loader: ${url} char ${i} changed ${JSON.stringify(source[i])} -> ${JSON.stringify(ch)}; not a pure type erasure`)
+  }
+}
+
+registerHooks({
+  load(url, context, nextLoad) {
+    const match = TS_RE.exec(new URL(url).pathname)
+    if (match) {
+      const bytes = readFileSync(fileURLToPath(url))
+      // Assert the source is valid UTF-8 before decoding: a mis-encoded
+      // file (latin-1, UTF-16, a stray binary) would otherwise decode with
+      // U+FFFD replacement chars and we'd strip / execute silent garbage.
+      if (!isUtf8(bytes)) {
+        throw new Error(`strip-types-loader: ${url} is not valid UTF-8`)
+      }
+      const raw = bytes.toString('utf8')
+      const stripped = stripTypeScriptTypes(raw, { mode: 'strip' })
+      assertOnlyErased(url, raw, stripped)
+      return {
+        format: match.groups.kind === 'c' ? 'commonjs' : 'module',
+        source: stripped,
+        shortCircuit: true,
+      }
+    }
+    return nextLoad(url, context)
+  },
+})

package/server/http.ts

@@ -1,142 +0,0 @@
-// HTTP plane: the REST byte-transfer routing (`/api/objstore/...`), the
-// static UI bundle, and the WebSocket upgrade gate. Built once at boot
-// with the WS server plus the lifecycle hooks it needs (`track` to
-// drain in-flight requests on shutdown, `isShuttingDown` to gate new
-// ones). The WS *connection* handler is wired on `wss` separately in
-// index.ts; this module only owns the upgrade handshake.
-
-import { type IncomingMessage as HttpRequest, type Server, type ServerResponse, createServer } from 'node:http'
-import { Buffer } from 'node:buffer'
-import { fileURLToPath } from 'node:url'
-import type { WebSocketServer } from 'ws'
-import { type ObjstoreRestDeps, handleRest, matchRoute } from './objstore/rest.ts'
-import { loadStatic } from './static.ts'
-import { errStack } from './util.ts'
-
-// `/api/*` is reserved for backend traffic so a fronting nginx (or
-// similar) can route `/api/*` → this process and `/*` → the static UI
-// bundle with a single location block.
-export const WS_UPGRADE_PATH = '/api/sync'
-function isUpgradePath(url: string | undefined): boolean {
-  if (typeof url !== 'string') return false
-  // Strip `?…` so clients can carry build / debug tags. Exact match
-  // otherwise — `/api/sync/` (trailing slash) doesn't pass.
-  return url.split('?', 1)[0] === WS_UPGRADE_PATH
-}
-
-const NOT_FOUND_BODY = JSON.stringify({ error: 'not-found' })
-
-type HasHeaders = { headers: HttpRequest['headers'] }
-
-export type HttpServerDeps = {
-  wss: WebSocketServer
-  restDeps: ObjstoreRestDeps
-  isOriginAllowed: (req: HasHeaders) => boolean
-  isShuttingDown: () => boolean
-  track: (promise: Promise<unknown>) => void
-  restPutIdleTimeoutMs: number
-  debug: boolean
-}
-
-export function createHttpServer(deps: HttpServerDeps): Server {
-  const { wss, restDeps, isOriginAllowed, isShuttingDown, track, restPutIdleTimeoutMs, debug } = deps
-  // Static-file plane (see ./static.ts). The directory is the
-  // `build.js build` output sibling to this file; the loader handles
-  // enumeration, pre-compression, and ETag derivation. Plugged in after
-  // the `/api/objstore/...` REST branch.
-  const handleStatic = loadStatic(fileURLToPath(new URL('../out', import.meta.url)))
-
-  const httpServer = createServer((req: HttpRequest, res: ServerResponse) => {
-    if (matchRoute(req.url) != null) {
-      // Shutdown gate. The WS plane gates new messages on `shuttingDown`;
-      // REST handlers go through a separate path and must mirror it.
-      // Without this, a REST PUT arriving on an existing keep-alive
-      // socket AFTER SIGTERM but BEFORE `httpServer.close()` finishes
-      // draining could land in `withCommitLock`, acquire a lease, and
-      // finish its `finally { release() }` AFTER the shutdown's
-      // `heldLeaseCount` snapshot — leaving an orphan lock row that pins
-      // the key until TTL expiry. The 503 + `shutting-down` reason tells
-      // the client to retry against a different replica. Transport
-      // audit + multi-replica shutdown ordering review.
-      if (isShuttingDown()) {
-        res.writeHead(503, { 'content-type': 'application/json', 'connection': 'close' })
-        res.end(JSON.stringify({ error: 'shutting-down' }))
-        return
-      }
-      // Same-origin gate. Token IS the auth on REST, but a hostile origin
-      // that holds a valid token (e.g. via XSS that read a freshly-minted
-      // one) would PUT with its own Origin header — caught here.
-      // Same-origin XHR/fetch may omit Origin; that path is allowed (see
-      // `isOriginAllowed`). Transport audit `server/objstore/rest.ts:103`.
-      if (!isOriginAllowed(req)) {
-        res.writeHead(403, { 'content-type': 'application/json' })
-        res.end(JSON.stringify({ error: 'origin-denied' }))
-        return
-      }
-      // PUT idle-body timeout — a slow-loris client trickling bytes
-      // within the declared Content-Length holds the staging fd + an
-      // inFlightSids slot indefinitely. `req.setTimeout` fires on
-      // inactivity; we destroy the request, aborting the body pipeline.
-      // Transport audit `server/objstore/rest.ts:218`.
-      if (req.method === 'PUT') {
-        req.setTimeout(restPutIdleTimeoutMs, () => {
-          if (debug) console.warn(`REST PUT idle ${restPutIdleTimeoutMs}ms → abort`)
-          try { req.destroy(new Error('idle-timeout')) } catch {}
-        })
-      }
-      // Track so SIGTERM mid-upload/download awaits handleRest before the
-      // DB close. The outer `.catch` is the unhandled-rejection guard for
-      // a stray throw OUTSIDE handleRest's internal try/catch blocks —
-      // Node 20+ defaults `--unhandled-rejections=throw`, which would
-      // crash the server. Logs and terminates the response so the TCP
-      // socket doesn't dangle.
-      const p = handleRest(restDeps, req, res).catch((err) => {
-        console.warn('REST handler error:', errStack(err))
-        if (res.headersSent) { try { res.destroy() } catch {} }
-        else { try { res.writeHead(500, { 'content-type': 'application/json' }); res.end(JSON.stringify({ error: 'internal' })) } catch {} }
-      })
-      track(p)
-      return
-    }
-    if (handleStatic(req, res)) return
-    // `Connection: close` so an HTTP/1.1 keep-alive client doesn't hold
-    // the socket open expecting more requests on a server that only
-    // serves a small REST surface.
-    res.writeHead(404, { 'content-type': 'application/json', 'connection': 'close' })
-    res.end(NOT_FOUND_BODY)
-  })
-
-  httpServer.on('upgrade', (req, socket, head) => {
-    // RFC 6455: the WS upgrade IS an HTTP request; reject with a normal
-    // HTTP response so a misconfigured client sees the JSON body instead
-    // of ECONNRESET. `socket.end(body)` flushes before sending FIN.
-    if (!isUpgradePath(req.url)) {
-      socket.end(
-        'HTTP/1.1 404 Not Found\r\n' +
-        'Content-Type: application/json\r\n' +
-        `Content-Length: ${Buffer.byteLength(NOT_FOUND_BODY)}\r\n` +
-        'Connection: close\r\n\r\n' +
-        NOT_FOUND_BODY,
-      )
-      return
-    }
-    // Same-origin gate. The WS upgrade IS a cross-origin-reachable
-    // surface in the browser; without this any tab can open a session to
-    // a 127.0.0.1 relay and probe handler shape / burn verify CPU.
-    // Browser WS handshakes always carry Origin (RFC 6455); non-browser
-    // clients omit it and are allowed (network is their trust boundary).
-    if (!isOriginAllowed(req)) {
-      socket.end(
-        'HTTP/1.1 403 Forbidden\r\n' +
-        'Content-Type: application/json\r\n' +
-        'Content-Length: 26\r\n' +
-        'Connection: close\r\n\r\n' +
-        '{"error":"origin-denied"}\n',
-      )
-      return
-    }
-    wss.handleUpgrade(req, socket, head, (ws) => { wss.emit('connection', ws, req) })
-  })
-
-  return httpServer
-}