@openparachute/hub 0.7.0 → 0.7.1

package/src/ws-bridge.ts

@@ -0,0 +1,256 @@
+/**
+ * Bun-native WebSocket upgrade bridge (H1, surface-runtime design §"Hub work
+ * items").
+ *
+ * The hub's HTTP proxy is fetch-based, and WebSocket upgrades don't traverse
+ * fetch — so until now the route table simply couldn't forward them (the
+ * hub-server docstring acknowledged it). This module is the transport half of
+ * the fix: when `hub-server.ts` accepts an upgrade for a service mount whose
+ * module DECLARES the capability (`websocket: true` on its services.json row
+ * or module.json — deny-by-default), it calls `server.upgrade(req, { data })`
+ * with a {@link WsBridgeData} payload, and these handlers pipe frames
+ * bidirectionally between the client socket and a Bun WebSocket client
+ * connected to the upstream daemon (same path, loopback).
+ *
+ * Scope discipline: this is TRANSPORT, not features —
+ *
+ *   - The upstream connect carries the substrate trust headers (H2:
+ *     X-Parachute-Layer / X-Parachute-Client-IP) plus the client's own
+ *     headers (cookie, authorization) so the module authenticates the
+ *     connection itself; the hub adds no WS-level auth of its own beyond the
+ *     route gates that ran BEFORE the upgrade (publicExposure cloak,
+ *     audience gate).
+ *   - Subprotocol negotiation (`Sec-WebSocket-Protocol`) is NOT forwarded in
+ *     v1 — none of the in-design consumers (y-websocket / Hocuspocus manual
+ *     pumping) require it; forwarding it correctly needs a negotiation
+ *     round-trip the first real consumer can motivate.
+ *   - Backpressure is a blunt cap, not flow control: when either side's
+ *     buffered amount exceeds {@link DEFAULT_MAX_BUFFERED_BYTES}, the bridge
+ *     closes BOTH sides (1011). A slow consumer should reconnect rather than
+ *     let the hub buffer unboundedly.
+ *   - Admission control is upstream of this module (hub#649): the gate in
+ *     `maybeUpgradeWebSocket` enforces per-client-IP + total connection caps
+ *     (defaults 32 / 512, env-overridable via PARACHUTE_WS_MAX_PER_IP /
+ *     PARACHUTE_WS_MAX_TOTAL — see `ws-connection-caps.ts`) BEFORE
+ *     `server.upgrade()`. The bridge's part of the contract is release: the
+ *     `close` handler below is the single funnel every accepted socket
+ *     passes through, so it invokes {@link WsBridgeData.releaseCap} first
+ *     thing — whatever the teardown reason — and the counters churn back to
+ *     zero with the sockets.
+ *
+ * Lifecycle: either side closing tears down the other (close code + reason
+ * propagated where the RFC 6455 rules allow), and an upstream connect failure
+ * closes the client with 1011. The bridge holds no per-connection state
+ * outside `ws.data`, so a dropped socket leaks nothing.
+ */
+
+import type { ServerWebSocket, WebSocketHandler } from "bun";
+
+/**
+ * Default cap on either side's buffered (un-flushed) bytes before the bridge
+ * gives up and closes both sockets. 8 MiB comfortably covers CRDT sync bursts
+ * (a full Yjs document state vector is typically KBs) while bounding what a
+ * slow or stalled consumer can pin in hub memory per connection.
+ */
+export const DEFAULT_MAX_BUFFERED_BYTES = 8 * 1024 * 1024;
+
+/**
+ * Per-connection payload attached at `server.upgrade(req, { data })` time by
+ * the hub's dispatch (which already ran the route gates). Everything the
+ * bridge needs to dial the upstream — it never re-derives routing or trust.
+ */
+export interface WsBridgeData {
+  /** Absolute ws:// URL of the upstream daemon (same path + query, loopback). */
+  upstreamUrl: string;
+  /**
+   * Headers presented on the upstream connect: the client's own headers
+   * (minus hop-by-hop + WS handshake headers, which the Bun client re-mints)
+   * plus the H2 substrate trust stamps.
+   */
+  upstreamHeaders: Record<string, string>;
+  /**
+   * Releases this connection's slot in the connection-cap accounting
+   * (hub#649) — attached by the acquire site in `maybeUpgradeWebSocket`,
+   * invoked by the `close` handler. Self-disarming (safe to call more than
+   * once). Optional so handler-level unit tests that fake `ws.data` don't
+   * have to care about caps.
+   */
+  releaseCap?: () => void;
+  /** Internal bridge state — attached by `open()`, owned by this module. */
+  _bridge?: BridgeState;
+}
+
+interface BridgeState {
+  upstream: WebSocket;
+  /** Client frames received while the upstream is still CONNECTING. */
+  pending: (string | Uint8Array)[];
+  pendingBytes: number;
+  /** Set once either side initiated teardown — makes close idempotent. */
+  closed: boolean;
+}
+
+export interface WsBridgeOptions {
+  /** Override the buffered-bytes cap (tests use a tiny value). */
+  maxBufferedBytes?: number;
+  /** Test seam for the upstream WebSocket constructor. */
+  connectUpstream?: (url: string, headers: Record<string, string>) => WebSocket;
+  logger?: Pick<Console, "warn">;
+}
+
+/**
+ * RFC 6455: only codes 1000–4999 may be sent on the wire, and 1004/1005/1006/
+ * 1015 are reserved (never sent). A close event surfacing one of those (e.g.
+ * 1006 abnormal closure) is re-mapped to a no-code close, which the peer
+ * observes as 1005.
+ */
+function sendableCloseCode(code: number | undefined): number | undefined {
+  if (code === undefined) return undefined;
+  if (code < 1000 || code > 4999) return undefined;
+  if (code === 1004 || code === 1005 || code === 1006 || code === 1015) return undefined;
+  return code;
+}
+
+/** Close reasons are capped at 123 bytes on the wire (RFC 6455 §5.5.1). */
+function trimReason(reason: string | undefined): string {
+  if (!reason) return "";
+  // Trim by UTF-8 byte length, not string length.
+  let out = reason;
+  while (Buffer.byteLength(out, "utf8") > 123) out = out.slice(0, -1);
+  return out;
+}
+
+function closeQuietly(close: () => void): void {
+  try {
+    close();
+  } catch {
+    // Already closed / closing — teardown is best-effort by design.
+  }
+}
+
+/** Tear down both sides exactly once. */
+function closeBoth(
+  ws: ServerWebSocket<WsBridgeData>,
+  state: BridgeState,
+  code: number,
+  reason: string,
+): void {
+  if (state.closed) return;
+  state.closed = true;
+  closeQuietly(() => state.upstream.close(sendableCloseCode(code), trimReason(reason)));
+  closeQuietly(() => ws.close(sendableCloseCode(code), trimReason(reason)));
+}
+
+function frameBytes(frame: string | Uint8Array | ArrayBuffer): number {
+  if (typeof frame === "string") return Buffer.byteLength(frame, "utf8");
+  return frame instanceof ArrayBuffer ? frame.byteLength : frame.byteLength;
+}
+
+/**
+ * Build the Bun.serve `websocket` handler set implementing the bridge. One
+ * handler object serves every bridged connection; per-connection state lives
+ * on `ws.data`.
+ */
+export function createWsBridgeHandlers(opts: WsBridgeOptions = {}): WebSocketHandler<WsBridgeData> {
+  const cap = opts.maxBufferedBytes ?? DEFAULT_MAX_BUFFERED_BYTES;
+  const logger = opts.logger ?? console;
+  const connect =
+    opts.connectUpstream ??
+    ((url: string, headers: Record<string, string>) =>
+      // Bun's WebSocket client accepts custom headers (a Bun extension over
+      // the WHATWG constructor) — this is what carries the H2 trust stamps +
+      // the client's cookies/authorization to the upstream daemon.
+      new WebSocket(url, { headers } as unknown as string[]));
+
+  return {
+    open(ws) {
+      let upstream: WebSocket;
+      try {
+        upstream = connect(ws.data.upstreamUrl, ws.data.upstreamHeaders);
+      } catch (err) {
+        logger.warn(
+          `[ws-bridge] upstream connect threw for ${ws.data.upstreamUrl}: ${
+            err instanceof Error ? err.message : String(err)
+          }`,
+        );
+        closeQuietly(() => ws.close(1011, "upstream connect failed"));
+        return;
+      }
+      upstream.binaryType = "arraybuffer";
+      const state: BridgeState = { upstream, pending: [], pendingBytes: 0, closed: false };
+      ws.data._bridge = state;
+
+      upstream.addEventListener("open", () => {
+        if (state.closed) {
+          closeQuietly(() => upstream.close(1000, ""));
+          return;
+        }
+        for (const frame of state.pending) upstream.send(frame);
+        state.pending = [];
+        state.pendingBytes = 0;
+      });
+
+      upstream.addEventListener("message", (ev: MessageEvent) => {
+        if (state.closed) return;
+        const data = ev.data as string | ArrayBuffer;
+        ws.send(typeof data === "string" ? data : new Uint8Array(data));
+        // Backpressure: the client isn't draining what the upstream sends.
+        if (ws.getBufferedAmount() > cap) {
+          closeBoth(ws, state, 1011, "bridge backpressure cap exceeded");
+        }
+      });
+
+      upstream.addEventListener("close", (ev: CloseEvent) => {
+        if (state.closed) return;
+        state.closed = true;
+        closeQuietly(() => ws.close(sendableCloseCode(ev.code), trimReason(ev.reason)));
+      });
+
+      upstream.addEventListener("error", () => {
+        // A connect refusal (upstream not listening) surfaces here before
+        // any close event. Tear down the client; the close listener above is
+        // a no-op afterwards thanks to the `closed` latch.
+        closeBoth(ws, state, 1011, "upstream error");
+      });
+    },
+
+    message(ws, message) {
+      const state = ws.data._bridge;
+      if (!state || state.closed) return;
+      const frame: string | Uint8Array =
+        typeof message === "string" ? message : new Uint8Array(message);
+      const { upstream } = state;
+      if (upstream.readyState === WebSocket.OPEN) {
+        upstream.send(frame);
+        // Backpressure: the upstream isn't draining what the client sends.
+        if (upstream.bufferedAmount > cap) {
+          closeBoth(ws, state, 1011, "bridge backpressure cap exceeded");
+        }
+      } else if (upstream.readyState === WebSocket.CONNECTING) {
+        state.pending.push(frame);
+        state.pendingBytes += frameBytes(frame);
+        if (state.pendingBytes > cap) {
+          closeBoth(ws, state, 1011, "bridge backpressure cap exceeded");
+        }
+      }
+      // CLOSING / CLOSED: drop the frame — teardown is already in flight.
+    },
+
+    close(ws, code, reason) {
+      // Connection-cap release FIRST (hub#649) — before the bridge-state
+      // early-returns, because this callback fires even for sockets whose
+      // upstream connect threw in open() (no `_bridge` attached) and is the
+      // one teardown funnel every accepted socket passes through. The
+      // closure latches, so re-entry is harmless.
+      ws.data.releaseCap?.();
+      // Client → upstream close propagation. Note: Bun's server-side close
+      // callback delivers the client's close CODE but an empty `reason`
+      // (verified on Bun 1.3.13), so only the code propagates upstream in
+      // this direction. Upstream → client propagation (the close listener in
+      // open()) carries both.
+      const state = ws.data._bridge;
+      if (!state || state.closed) return;
+      state.closed = true;
+      closeQuietly(() => state.upstream.close(sendableCloseCode(code), trimReason(reason)));
+    },
+  };
+}

package/src/ws-connection-caps.ts

@@ -0,0 +1,170 @@
+/**
+ * WebSocket connection caps for the upgrade bridge (hub#649) — the gate
+ * before any backed surface goes public-facing.
+ *
+ * The H1 bridge (`ws-bridge.ts`) holds one client socket + one upstream
+ * socket per connection, and the only per-connection bound before this
+ * module was the 8 MiB buffered-byte backpressure cap — a public client
+ * could hold upgrade slots open indefinitely at near-zero send rate and
+ * exhaust daemon memory at ~KB/connection. With the `surface` audience tier
+ * (H3, hub#651) anonymous WS is REACHABLE BY DESIGN on surface-audience
+ * mounts, so admission control can't lean on auth: the hub needs a blunt
+ * concurrent-connection bound of its own.
+ *
+ * Enforcement lives in `maybeUpgradeWebSocket` (hub-server.ts), which calls
+ * {@link WsConnectionTracker.tryAcquire} synchronously right before
+ * `server.upgrade()` — over-cap upgrades are refused with a clean HTTP 429
+ * (the upgrade never happens, so a normal Response is the correct refusal
+ * shape in Bun) BEFORE the proxy commits any socket or upstream-dial
+ * resources. The refusal body is generic: it never reveals counts, caps, or
+ * which cap tripped (the hub log carries the specifics for the operator).
+ *
+ * Release rides the bridge's socket lifecycle: the acquire site threads a
+ * self-disarming release closure into `ws.data` ({@link
+ * WsBridgeData.releaseCap}), and the bridge's Bun-level `close` handler —
+ * the single funnel every accepted socket passes through, whatever the
+ * teardown reason (client close, upstream close, backpressure, connect
+ * failure) — invokes it first thing. A failed `server.upgrade()` releases
+ * inline (no socket ⇒ no close callback). The closure latches, so a stray
+ * double-close can't corrupt the counters.
+ *
+ * Defaults (overridable via env, the hub's config precedent —
+ * `PARACHUTE_HUB_ORIGIN` et al.):
+ *
+ *   - {@link DEFAULT_WS_MAX_PER_IP} = 32 per client IP
+ *     (`PARACHUTE_WS_MAX_PER_IP`). An owner-operated box realistically
+ *     serves a handful of humans; a collab surface opens a socket or two
+ *     per tab, so 32 covers a small team behind one NAT egress IP with
+ *     headroom, while turning a single-source flood into a rotate-IPs
+ *     problem.
+ *   - {@link DEFAULT_WS_MAX_TOTAL} = 512 total (`PARACHUTE_WS_MAX_TOTAL`).
+ *     Bounds worst-case hub memory under a distributed flood (512 bridged
+ *     pairs ≈ low MBs idle) at a ceiling far above any realistic legitimate
+ *     concurrent load for a single-operator hub.
+ *
+ * Keying: callers derive the bucket key with `wsCapBucketKey`
+ * (hub-server.ts), which follows the hub's substrate trust model — forwarded
+ * IP headers are only believed when the peer is an on-box (loopback)
+ * forwarder; direct network peers key by their socket address no matter
+ * what headers they inject; an underivable IP lands in one shared bucket
+ * (fail closed, same posture as rate-limit.ts's UNKNOWN_IP_SENTINEL).
+ */
+
+/** Default cap on concurrent bridged WS connections per client-IP bucket. */
+export const DEFAULT_WS_MAX_PER_IP = 32;
+/** Default cap on concurrent bridged WS connections across all clients. */
+export const DEFAULT_WS_MAX_TOTAL = 512;
+
+/** Env var overriding {@link DEFAULT_WS_MAX_PER_IP}. */
+export const WS_MAX_PER_IP_ENV = "PARACHUTE_WS_MAX_PER_IP";
+/** Env var overriding {@link DEFAULT_WS_MAX_TOTAL}. */
+export const WS_MAX_TOTAL_ENV = "PARACHUTE_WS_MAX_TOTAL";
+
+export interface WsCaps {
+  maxPerIp: number;
+  maxTotal: number;
+}
+
+/**
+ * Parse the cap overrides from an env bag. Only positive integers are
+ * honored; absent / malformed / non-positive values fall back to the
+ * defaults (an operator typo must not silently disable the gate — fail to
+ * the safe defaults, never to "unlimited").
+ */
+export function wsCapsFromEnv(env: NodeJS.ProcessEnv = process.env): WsCaps {
+  return {
+    maxPerIp: parseCap(env[WS_MAX_PER_IP_ENV], DEFAULT_WS_MAX_PER_IP),
+    maxTotal: parseCap(env[WS_MAX_TOTAL_ENV], DEFAULT_WS_MAX_TOTAL),
+  };
+}
+
+function parseCap(raw: string | undefined, fallback: number): number {
+  if (raw === undefined) return fallback;
+  const n = Number.parseInt(raw.trim(), 10);
+  if (!Number.isSafeInteger(n) || n <= 0 || String(n) !== raw.trim()) return fallback;
+  return n;
+}
+
+/** The verdict of {@link WsConnectionTracker.tryAcquire}. */
+export type WsAcquireResult =
+  | { ok: true; release: () => void }
+  | { ok: false; reason: "per_ip_cap" | "total_cap" };
+
+/**
+ * Concurrent-connection accounting: a per-key map + a global counter.
+ *
+ * Acquire and release are synchronous and O(1); `tryAcquire` is called in
+ * the same synchronous block as `server.upgrade()` (no await between check
+ * and commit), so the counters can't race the admission decision.
+ *
+ * The returned `release` closure is latched — calling it twice decrements
+ * once. That makes leaks structurally hard: the caller doesn't need to know
+ * which teardown paths can double-fire; any number of invocations after the
+ * first are no-ops, and a key's bucket entry is deleted at zero so an
+ * attacker cycling keys can't grow the map without also holding sockets.
+ */
+export class WsConnectionTracker {
+  private readonly perKey = new Map<string, number>();
+  private total = 0;
+
+  constructor(
+    private readonly maxPerKey: number = DEFAULT_WS_MAX_PER_IP,
+    private readonly maxTotal: number = DEFAULT_WS_MAX_TOTAL,
+  ) {}
+
+  /**
+   * Admit-or-refuse a would-be connection for `key`. On admission the slot
+   * is counted immediately and the caller MUST either hand the returned
+   * `release` to the socket's close path or invoke it inline when the
+   * upgrade fails to complete.
+   */
+  tryAcquire(key: string): WsAcquireResult {
+    if (this.total >= this.maxTotal) return { ok: false, reason: "total_cap" };
+    const current = this.perKey.get(key) ?? 0;
+    if (current >= this.maxPerKey) return { ok: false, reason: "per_ip_cap" };
+    this.perKey.set(key, current + 1);
+    this.total += 1;
+
+    let released = false;
+    return {
+      ok: true,
+      release: () => {
+        if (released) return;
+        released = true;
+        const n = this.perKey.get(key) ?? 0;
+        if (n <= 1) this.perKey.delete(key);
+        else this.perKey.set(key, n - 1);
+        if (this.total > 0) this.total -= 1;
+      },
+    };
+  }
+
+  /** Current global connection count (observability + tests). */
+  get totalCount(): number {
+    return this.total;
+  }
+
+  /** Current count for one key (observability + tests). 0 when absent. */
+  countFor(key: string): number {
+    return this.perKey.get(key) ?? 0;
+  }
+
+  /** Number of distinct keys currently holding connections (leak probe). */
+  get keyCount(): number {
+    return this.perKey.size;
+  }
+}
+
+/**
+ * The production tracker — one per hub process, shared by every upgrade.
+ * Caps come from the env at module load (the hub reads its config once at
+ * boot; changing the env requires a restart, same as every other
+ * `PARACHUTE_*` knob). Tests construct their own trackers and inject them
+ * via `HubFetchDeps.wsConnectionTracker` so they never consume (or depend
+ * on) the shared process-level counters.
+ */
+const bootCaps = wsCapsFromEnv();
+export const defaultWsConnectionTracker = new WsConnectionTracker(
+  bootCaps.maxPerIp,
+  bootCaps.maxTotal,
+);