tina4-nodejs 3.13.92 → 3.13.95

package/packages/core/src/sessionHandlers/syncSocket.ts

@@ -0,0 +1,236 @@
+/**
+ * Tina4 synchronous socket transport — ONE persistent connection per target.
+ *
+ * Serves the RESP backends (Redis, Valkey) and memcached's text protocol. The
+ * sync-over-async plumbing lives in syncBridge; this file is only the socket
+ * worker and the two protocol entry points.
+ *
+ * See syncBridge for WHY: each command used to run in a short-lived `node -e`
+ * child, paying a process spawn AND a fresh TCP connection every time (spawn p50
+ * 41ms / p99 487ms, connect tail 0.5-0.9s), and that tail tripped the child's
+ * deadline under load — the cause of the Valkey session flake.
+ *
+ * Reconnection is the worker's business: a dropped socket is re-established on
+ * the next command rather than surfacing as a caller error.
+ */
+import {
+  getBridge,
+  closeBridges,
+  DATA_BYTES,
+  STATUS_ERROR,
+  STATUS_NIL,
+  STATUS_OK,
+  STATUS_TRANSPORT,
+} from "./syncBridge.js";
+
+export interface SyncSocketTarget {
+  host: string;
+  port: number;
+  /** AUTH password (empty/undefined = no AUTH sent). */
+  password?: string;
+  /** SELECT db index (0/undefined = no SELECT sent). */
+  db?: number;
+}
+
+/**
+ * How long the worker waits for a TCP connection. Deliberately shorter than the
+ * bridge's reply timeout so an unreachable host is reported as a connect failure
+ * with a useful message, rather than as a generic reply timeout — before this
+ * existed, learning a server was down took the full 5s deadline.
+ */
+const CONNECT_TIMEOUT_MS = 2000;
+
+const SOCKET_WORKER = `
+const net = require("node:net");
+const target = workerData.target;
+
+let sock = null;
+let buffer = Buffer.alloc(0);
+let pending = null;
+
+function encodeCommand(args) {
+  let out = "*" + args.length + "\\r\\n";
+  for (const s of args) out += "$" + Buffer.byteLength(s) + "\\r\\n" + s + "\\r\\n";
+  return out;
+}
+
+// Parse one RESP value at offset. Returns { value, next } or null when more
+// bytes are needed, so a bulk string split across TCP chunks is reassembled
+// rather than truncated.
+function parse(buf, off) {
+  if (off >= buf.length) return null;
+  const type = buf[off];
+  const crlf = buf.indexOf("\\r\\n", off + 1, "utf-8");
+  if (crlf === -1) return null;
+  const line = buf.toString("utf-8", off + 1, crlf);
+  const after = crlf + 2;
+  if (type === 0x2b) return { value: line, next: after };              // '+'
+  if (type === 0x3a) return { value: line, next: after };              // ':'
+  if (type === 0x2d) return { value: { __err: line }, next: after };   // '-'
+  if (type === 0x24) {                                                 // '$'
+    const len = parseInt(line, 10);
+    if (len === -1) return { value: null, next: after };
+    if (after + len + 2 > buf.length) return null;
+    return { value: buf.toString("utf-8", after, after + len), next: after + len + 2 };
+  }
+  if (type === 0x2a) {                                                 // '*'
+    const count = parseInt(line, 10);
+    if (count === -1) return { value: null, next: after };
+    const arr = [];
+    let pos = after;
+    for (let i = 0; i < count; i++) {
+      const el = parse(buf, pos);
+      if (!el) return null;
+      arr.push(el.value);
+      pos = el.next;
+    }
+    return { value: arr, next: pos };
+  }
+  return { value: line, next: after };
+}
+
+function settle(status, payload) {
+  if (!pending) return;
+  pending = null;
+  __reply(status, payload);
+}
+
+function drop(err) {
+  // The socket is gone. Fail the in-flight command, then let the NEXT command
+  // reconnect - a transient blip must not poison the channel forever.
+  try { if (sock) sock.destroy(); } catch (e) {}
+  sock = null;
+  buffer = Buffer.alloc(0);
+  settle(${STATUS_TRANSPORT}, err || "connection lost");
+}
+
+function onRespData(chunk) {
+  buffer = buffer.length ? Buffer.concat([buffer, chunk]) : chunk;
+  while (pending) {
+    const p = parse(buffer, 0);
+    if (!p) break;
+    buffer = buffer.subarray(p.next);
+    pending.replies.push(p.value);
+    if (pending.replies.length < pending.expected) continue;
+
+    // A rejected AUTH/SELECT is surfaced ahead of the command's own reply.
+    for (let i = 0; i < pending.expected - 1; i++) {
+      const r = pending.replies[i];
+      if (r && typeof r === "object" && r.__err !== undefined) { settle(${STATUS_ERROR}, r.__err); return; }
+    }
+    const result = pending.replies[pending.expected - 1];
+    if (result && typeof result === "object" && result.__err !== undefined) settle(${STATUS_ERROR}, result.__err);
+    else if (result === null || result === undefined) settle(${STATUS_NIL}, null);
+    else settle(${STATUS_OK}, result);
+    return;
+  }
+}
+
+function onTextData(chunk) {
+  // Text protocols (memcached) carry no length prefix: the reply is complete
+  // when one of the caller's terminators appears.
+  buffer = buffer.length ? Buffer.concat([buffer, chunk]) : chunk;
+  if (!pending) return;
+  const text = buffer.toString("utf-8");
+  for (const t of pending.terminators) {
+    if (text.includes(t)) { buffer = Buffer.alloc(0); settle(${STATUS_OK}, text); return; }
+  }
+}
+
+function connect(then) {
+  const s = net.createConnection({ host: target.host, port: target.port });
+  s.setNoDelay(true);
+  // An unroutable host neither connects nor errors promptly, so bound it here:
+  // otherwise the caller sits out its whole reply deadline for a host that was
+  // never going to answer.
+  const connectTimer = setTimeout(() => {
+    if (sock !== s) { try { s.destroy(); } catch (e) {} drop("connect timed out"); }
+  }, ${CONNECT_TIMEOUT_MS});
+  s.on("data", (c) => (pending && pending.text ? onTextData(c) : onRespData(c)));
+  s.on("error", (e) => { clearTimeout(connectTimer); drop(e.message); });
+  s.on("close", () => { clearTimeout(connectTimer); if (sock === s) drop("connection closed"); });
+  s.on("connect", () => { clearTimeout(connectTimer); sock = s; then(); });
+}
+
+parentPort.on("message", (msg) => {
+  // Set pending BEFORE connecting. A connect error (ECONNREFUSED) otherwise
+  // arrives with nothing in flight, and the caller blocks for its full reply
+  // timeout just to learn the server is down.
+  const fresh = !sock;
+
+  if (msg.mode === "text") {
+    pending = { text: true, terminators: msg.terminators };
+    const writeText = () => {
+      try { sock.write(msg.payload, "utf-8"); } catch (e) { drop(e.message); }
+    };
+    if (sock) writeText(); else { try { connect(writeText); } catch (e) { drop(e.message); } }
+    return;
+  }
+
+  // The handshake rides with the FIRST command on a fresh connection only;
+  // afterwards the connection is already authenticated and selected.
+  const handshake = fresh ? ((target.password ? 1 : 0) + (target.db ? 1 : 0)) : 0;
+  pending = { expected: 1 + handshake, replies: [] };
+
+  const write = () => {
+    let payload = "";
+    if (fresh) {
+      if (target.password) payload += encodeCommand(["AUTH", target.password]);
+      if (target.db) payload += encodeCommand(["SELECT", String(target.db)]);
+    }
+    payload += encodeCommand(msg.args);
+    try { sock.write(payload); } catch (e) { drop(e.message); }
+  };
+
+  if (sock) write(); else { try { connect(write); } catch (e) { drop(e.message); } }
+});
+`;
+
+function socketBridge(target: SyncSocketTarget) {
+  const key = `sock:${target.host}:${target.port}:${target.db ?? 0}:${target.password ? "auth" : ""}`;
+  return getBridge(key, SOCKET_WORKER, { target });
+}
+
+/**
+ * Run a single RESP command synchronously and return the reply.
+ *
+ * - A genuine nil / key-miss returns `""` (callers treat "" as "no session yet").
+ * - A transport FAILURE (unreachable, timeout, connection closed) THROWS
+ *   `<label> command failed: ...`.
+ * - A RESP error reply — including a rejected AUTH/SELECT — THROWS
+ *   `<label> error: ...`.
+ *
+ * The miss/failure split is the whole contract: collapsing them is how a dead
+ * backend silently logs every user out instead of surfacing an outage. A dead
+ * socket and a healthy server saying "-ERR" are different failures and read
+ * differently in a log, so they keep different wording.
+ */
+export function syncCommand(target: SyncSocketTarget, args: string[], label = "Redis"): string {
+  const { status, payload } = socketBridge(target).call({ args }, label);
+
+  if (status === STATUS_NIL) return "";               // genuine key miss
+  if (status === STATUS_TRANSPORT) throw new Error(`${label} command failed: ${payload}`);
+  if (status === STATUS_ERROR) throw new Error(`${label} error: ${payload}`);
+  return payload;
+}
+
+/**
+ * Run a raw text-protocol command (memcached) over the same persistent channel.
+ *
+ * The reply is whatever arrived once one of `terminators` appears — a text
+ * protocol carries no length prefix, so the caller names its own end markers.
+ * Failure semantics match {@link syncCommand}.
+ */
+export function syncTextCommand(
+  target: SyncSocketTarget,
+  payload: string,
+  terminators: string[],
+  label = "Memcached",
+): string {
+  const reply = socketBridge(target).call({ mode: "text", payload, terminators }, label);
+  if (reply.status === STATUS_TRANSPORT) throw new Error(`${label} command failed: ${reply.payload}`);
+  return reply.payload;
+}
+
+/** Re-exported so callers do not need to know the bridge exists. */
+export { closeBridges as closeSyncSockets, DATA_BYTES };

package/packages/core/src/testClient.ts

@@ -19,7 +19,7 @@ import { Socket } from "node:net";
 import { createRequest } from "./request.js";
 import { createResponse } from "./response.js";
 import { defaultRouter, Router, runRouteMiddlewares } from "./router.js";
-import { MiddlewareRunner } from "./middleware.js";
+import { MiddlewareRunner, isMiddlewareClass } from "./middleware.js";
 import { enforceRouteAuth } from "./authGate.js";
 
 export class TestResponse {
@@ -220,10 +220,21 @@ export class TestClient {
       }
     }
 
-    // Per-route middleware, same as the live dispatcher.
+    // Per-route middleware: functions, string specs, and CLASSES, through the
+    // same runner the live dispatcher uses. A route class's afterX hooks join
+    // the after pass below, exactly as in server.ts.
+    //
+    // ORDER DRIFT, stated rather than hidden: the live dispatcher runs the auth
+    // gate BEFORE the route's own middleware (ADR-0012 — middleware on a
+    // secured route must never process a request that is about to be rejected);
+    // here it still runs before the gate. Aligning the two is a behaviour
+    // change to the test surface and belongs in its own change.
+    const routeMiddlewareClasses = (match.middlewares ?? []).filter(isMiddlewareClass);
     if (match.middlewares && match.middlewares.length > 0) {
       const proceed = await runRouteMiddlewares(match.middlewares, req, res);
       if (!proceed || res.raw.writableEnded) {
+        await MiddlewareRunner.runAfter([...globalMiddleware, ...routeMiddlewareClasses], req, res);
+        if (!res.raw.writableEnded) res.raw.end();
         return this._collect(rawRes, chunks, socket);
       }
     }
@@ -243,9 +254,11 @@ export class TestClient {
     // Execute handler (only if auth passed)
     if (!rejected) {
       await match.handler(req, res);
-      // Global afterX hooks (logging / post-processing), mirroring the live tail.
-      if (globalMiddleware.length > 0) {
-        await MiddlewareRunner.runAfter(globalMiddleware, req, res);
+      // Global + route-class afterX hooks (logging / post-processing),
+      // mirroring the live tail.
+      const afterMiddleware = [...globalMiddleware, ...routeMiddlewareClasses];
+      if (afterMiddleware.length > 0) {
+        await MiddlewareRunner.runAfter(afterMiddleware, req, res);
       }
     }
 

package/packages/core/src/trustedProxy.ts

@@ -0,0 +1,249 @@
+/**
+ * Which upstream hops are allowed to speak for a client (ADR-0019).
+ *
+ * X-Forwarded-For is written by whoever sends it. Reading it unconditionally
+ * lets any client choose its own rate-limit bucket, and - worse - choose
+ * SOMEONE ELSE'S, which is a starvation primitive against a third party. So
+ * the forwarding headers are believed only when the raw socket peer is a proxy
+ * the operator has explicitly declared.
+ *
+ * Configured by TINA4_TRUSTED_PROXIES: comma-separated exact addresses and/or
+ * CIDR ranges, IPv4 and IPv6, e.g. "10.0.0.0/8, 192.168.1.5, ::1, fd00::/8".
+ * Empty or unset means trust NOTHING, which is the secure default.
+ *
+ * Zero-dependency: node: has no CIDR matcher, so the packing and prefix
+ * comparison are done here over plain byte arrays.
+ */
+
+import { Log } from "./logger.js";
+
+/** [packed network address, prefix bits] */
+type Network = [Uint8Array, number];
+
+// Parsed TINA4_TRUSTED_PROXIES, cached on the raw env string so a change is
+// picked up but the parse does not run per request.
+let cachedRaw: string | null = null;
+let cachedNetworks: Network[] = [];
+
+/**
+ * Strip the decorations a peer address can arrive with: the "[::1]" bracket
+ * form and an IPv6 zone id ("fe80::1%eth0").
+ */
+function normalise(value: string): string {
+  let out = value.trim();
+  if (out.startsWith("[")) {
+    const close = out.indexOf("]");
+    if (close !== -1) out = out.slice(1, close);
+  }
+  const pct = out.indexOf("%");
+  if (pct !== -1) out = out.slice(0, pct);
+  return out;
+}
+
+function parseIpv4(value: string): Uint8Array | null {
+  const parts = value.split(".");
+  if (parts.length !== 4) return null;
+  const bytes = new Uint8Array(4);
+  for (let i = 0; i < 4; i++) {
+    const part = parts[i];
+    // Reject "", "01", "1e2", "+1" and anything out of range. A permissive
+    // parse here would let "10.0.0.01" or "10.0.0.1x" through as a match.
+    if (!/^\d{1,3}$/.test(part)) return null;
+    const n = Number(part);
+    if (n > 255) return null;
+    bytes[i] = n;
+  }
+  return bytes;
+}
+
+function parseIpv6(value: string): Uint8Array | null {
+  const halves = value.split("::");
+  if (halves.length > 2) return null;
+
+  const expand = (chunk: string): string[] => (chunk === "" ? [] : chunk.split(":"));
+  const head = expand(halves[0]);
+  const tail = halves.length === 2 ? expand(halves[1]) : [];
+
+  // A trailing IPv4 literal (::ffff:10.0.0.1) occupies the last two groups.
+  const groups: string[] = [];
+  const consume = (source: string[], into: string[]): boolean => {
+    for (let i = 0; i < source.length; i++) {
+      const part = source[i];
+      if (part.includes(".")) {
+        if (i !== source.length - 1) return false;
+        const v4 = parseIpv4(part);
+        if (!v4) return false;
+        into.push(((v4[0] << 8) | v4[1]).toString(16), ((v4[2] << 8) | v4[3]).toString(16));
+        continue;
+      }
+      if (!/^[0-9a-fA-F]{1,4}$/.test(part)) return false;
+      into.push(part);
+    }
+    return true;
+  };
+
+  const headGroups: string[] = [];
+  const tailGroups: string[] = [];
+  if (!consume(head, headGroups) || !consume(tail, tailGroups)) return null;
+
+  const missing = 8 - headGroups.length - tailGroups.length;
+  if (halves.length === 2) {
+    if (missing < 0) return null;
+    groups.push(...headGroups, ...Array(missing).fill("0"), ...tailGroups);
+  } else {
+    if (headGroups.length !== 8) return null;
+    groups.push(...headGroups);
+  }
+
+  const bytes = new Uint8Array(16);
+  for (let i = 0; i < 8; i++) {
+    const n = parseInt(groups[i], 16);
+    if (Number.isNaN(n)) return null;
+    bytes[i * 2] = (n >> 8) & 0xff;
+    bytes[i * 2 + 1] = n & 0xff;
+  }
+  return bytes;
+}
+
+/**
+ * Pack an address to its bytes, unmapping IPv4-in-IPv6.
+ *
+ * A peer arriving as ::ffff:10.0.0.1 must match an allow-list entry of
+ * 10.0.0.0/8 - dual-stack listeners hand out the mapped form routinely, and
+ * Node's socket.remoteAddress is a common source of it.
+ */
+export function packAddress(value: string): Uint8Array | null {
+  const address = normalise(value);
+  if (address === "") return null;
+  const packed = address.includes(":") ? parseIpv6(address) : parseIpv4(address);
+  if (!packed) return null;
+  if (packed.length === 16) {
+    let mapped = true;
+    for (let i = 0; i < 10; i++) {
+      if (packed[i] !== 0) { mapped = false; break; }
+    }
+    if (mapped && packed[10] === 0xff && packed[11] === 0xff) {
+      return packed.slice(12);
+    }
+  }
+  return packed;
+}
+
+function parseNetwork(entry: string): Network | null {
+  let address = entry;
+  let bits: number | null = null;
+
+  const slash = entry.lastIndexOf("/");
+  if (slash !== -1) {
+    address = entry.slice(0, slash).trim();
+    const suffix = entry.slice(slash + 1).trim();
+    if (!/^\d{1,3}$/.test(suffix)) return null;
+    bits = Number(suffix);
+  }
+
+  const packed = packAddress(address);
+  if (!packed) return null;
+
+  const maxBits = packed.length * 8;
+  if (bits === null) bits = maxBits;
+  if (bits < 0 || bits > maxBits) return null;
+  return [packed, bits];
+}
+
+/** Do the first `bits` bits of two packed addresses agree? */
+function prefixMatches(candidate: Uint8Array, network: Uint8Array, bits: number): boolean {
+  const wholeBytes = Math.floor(bits / 8);
+  for (let i = 0; i < wholeBytes; i++) {
+    if (candidate[i] !== network[i]) return false;
+  }
+  const remainder = bits % 8;
+  if (remainder === 0) return true;
+  const mask = (0xff << (8 - remainder)) & 0xff;
+  return (candidate[wholeBytes] & mask) === (network[wholeBytes] & mask);
+}
+
+/**
+ * The configured trusted-proxy networks, parsed once per distinct config value.
+ */
+export function trustedProxyNetworks(): Network[] {
+  const raw = process.env.TINA4_TRUSTED_PROXIES ?? "";
+  if (raw === cachedRaw) return cachedNetworks;
+
+  const networks: Network[] = [];
+  for (const rawEntry of raw.split(",")) {
+    const entry = normalise(rawEntry);
+    if (entry === "") continue;
+
+    const parsed = parseNetwork(entry);
+    if (!parsed) {
+      // Loud, and exactly once per distinct config value (the cache below
+      // means this parse runs once). A silently-skipped entry would leave a
+      // real proxy untrusted, which looks like the app over-limiting every
+      // client - a very expensive typo to debug.
+      Log.error(
+        `TINA4_TRUSTED_PROXIES: ignoring invalid entry '${entry}' - ` +
+        "expected an IP address or CIDR range, e.g. 10.0.0.0/8 or 192.168.1.5",
+      );
+      continue;
+    }
+    networks.push(parsed);
+  }
+
+  cachedRaw = raw;
+  cachedNetworks = networks;
+  return networks;
+}
+
+/** Is this address a configured trusted proxy? */
+export function isTrustedProxy(address: string): boolean {
+  const networks = trustedProxyNetworks();
+  if (networks.length === 0 || !address) return false;
+
+  const packed = packAddress(address);
+  if (!packed) return false;
+
+  for (const [network, bits] of networks) {
+    if (network.length === packed.length && prefixMatches(packed, network, bits)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/** Reset the parsed cache. Test hook - config normally changes only at boot. */
+export function resetTrustedProxyCache(): void {
+  cachedRaw = null;
+  cachedNetworks = [];
+}
+
+/**
+ * Resolve the client IP, honouring forwarding headers ONLY behind a trusted proxy.
+ *
+ * Within the chain the RIGHTMOST entry that is not itself a trusted proxy wins.
+ * Taking the leftmost would be no safer than trusting the header outright: a
+ * client can prepend its own hop, and the proxy appends rather than replaces.
+ * This is the algorithm Rack uses (Rack::Request#ip).
+ */
+export function resolveClientIp(
+  headers: Record<string, string | string[] | undefined>,
+  peer: string,
+): string {
+  if (!peer || !isTrustedProxy(peer)) return peer;
+
+  const rawForwarded = headers["x-forwarded-for"];
+  // A repeated header arrives as an array. Joining keeps every hop in order;
+  // reading only element 0 would silently drop the rest of the chain.
+  const forwarded = Array.isArray(rawForwarded) ? rawForwarded.join(",") : rawForwarded;
+  if (forwarded && forwarded.trim() !== "") {
+    const hops = forwarded.split(",").map((hop) => hop.trim()).filter(Boolean);
+    for (let i = hops.length - 1; i >= 0; i--) {
+      if (!isTrustedProxy(hops[i])) return hops[i];
+    }
+    // Every hop is itself a trusted proxy - the peer is the best we have.
+    return peer;
+  }
+
+  const rawRealIp = headers["x-real-ip"];
+  const realIp = (Array.isArray(rawRealIp) ? rawRealIp[0] : rawRealIp)?.trim();
+  return realIp || peer;
+}

package/packages/core/src/types.ts

@@ -45,10 +45,24 @@ export interface Tina4Request extends IncomingMessage {
   url: string;
   body: unknown;
   ip: string;
+  /**
+   * Raw socket peer address - NEVER honours X-Forwarded-For (which any
+   * caller can spoof), so it can be trusted for security decisions.
+   * Empty for in-process / synthetic requests. Parity with Python's
+   * request.remote_ip and PHP's Request::$remoteIp.
+   */
+  remoteIp: string;
   files: Record<string, UploadedFile | UploadedFile[]>;
   cookies: Record<string, string>;
   contentType: string;
-  session: Tina4Session;
+  /**
+   * NULL when the session backend was unusable for this request (ADR-0021).
+   * The request path logs the failure and degrades rather than 500-ing, so a
+   * request really can arrive without a session and the type has to say so -
+   * `req.session?.get(...)`. Parity with Python, where `request.session` is
+   * `None` on the same path.
+   */
+  session: Tina4Session | null;
   user?: Record<string, unknown>;
   /** Get a specific header value by name (case-insensitive). */
   header(name: string): string | undefined;
@@ -194,8 +208,15 @@ export type Middleware = (
 ) => void | Promise<void>;
 
 /**
- * A route middleware entry: either a middleware function, or a string spec
- * resolved by the router to a built-in middleware.
+ * A class-based middleware: static `beforeX` / `afterX` hooks discovered by
+ * `MiddlewareRunner`. The hooks are a NAMING CONVENTION, not an interface —
+ * exactly as in Python/PHP/Ruby — so this is deliberately just "a class".
+ */
+export type MiddlewareClass = abstract new (...args: never[]) => unknown;
+
+/**
+ * A route middleware entry: a middleware function, a middleware CLASS, or a
+ * string spec resolved by the router to a built-in middleware.
  *
  * String forms (parity with Python/PHP/Ruby):
  *   "ResponseCache"      → responseCache() with the default/env TTL
@@ -203,9 +224,12 @@ export type Middleware = (
  *
  * The router resolves string specs to middleware functions when the route
  * runs, so callers can register a response-cache middleware without importing
- * `responseCache`.
+ * `responseCache`. A CLASS runs its beforeX/afterX hooks through the same
+ * `MiddlewareRunner` as global middleware — Python and PHP already ran
+ * per-route class hooks; Node used to invoke every spec as `mw(req, res, next)`
+ * and a class was therefore inert.
  */
-export type MiddlewareSpec = Middleware | string;
+export type MiddlewareSpec = Middleware | MiddlewareClass | string;
 
 /**
  * Handler for WebSocket routes.

package/packages/core/src/websocket.ts

@@ -82,6 +82,20 @@ type EventHandler = (...args: unknown[]) => void;
 /**
  * Compute Sec-WebSocket-Accept from Sec-WebSocket-Key per RFC 6455.
  */
+/**
+ * Build an RFC 6455 close frame carrying a status code and optional reason.
+ *
+ * The code is a big-endian uint16 in the first two payload bytes (s5.5.1), so
+ * a peer that only reads the code still gets a valid one.
+ */
+export function buildCloseFrame(code: number, reason: string = ""): Buffer {
+  const reasonBytes = Buffer.from(reason, "utf-8");
+  const payload = Buffer.alloc(2 + reasonBytes.length);
+  payload.writeUInt16BE(code, 0);
+  reasonBytes.copy(payload, 2);
+  return buildFrame(OP_CLOSE, payload);
+}
+
 export function computeAcceptKey(key: string): string {
   return createHash("sha1")
     .update(key + MAGIC_STRING)
@@ -957,6 +971,35 @@ class WsRouteManager {
     if (state.trackerId && this.onRemove) this.onRemove(state.trackerId);
   }
 
+  /**
+   * Close every open route connection with an RFC 6455 status code.
+   *
+   * Used by graceful shutdown with 1001 "going away", which is the code RFC
+   * 6455 s7.4.1 defines for exactly this case ("a server going down"). A
+   * client that is told 1001 can reconnect on a schedule; a socket that just
+   * vanishes looks like a network fault and produces an error instead.
+   *
+   * Best-effort per connection: a dead socket is skipped, never aborting the
+   * rest. Returns how many were signalled.
+   */
+  closeAll(code: number = CLOSE_GOING_AWAY, reason: string = "server shutting down"): number {
+    const frame = buildCloseFrame(code, reason);
+    let closed = 0;
+    for (const state of [...this.connections.values()]) {
+      if (state.closed) continue;
+      state.closed = true;
+      try {
+        state.socket.write(frame);
+        state.socket.end();
+        closed++;
+      } catch {
+        /* already gone */
+      }
+      this.remove(state.conn.id);
+    }
+    return closed;
+  }
+
   /** Send a text frame to one connection (best-effort). */
   sendTo(id: string, message: string): void {
     const state = this.connections.get(id);
@@ -1266,6 +1309,29 @@ class DevReloadWsManager {
     return this.clients.size;
   }
 
+  /**
+   * Close every open dev-reload socket with an RFC 6455 status code (1001
+   * "going away" on shutdown). The browser client reconnects on a schedule
+   * when it is told the server went away, rather than reporting an error.
+   * Best-effort per socket. Returns how many were signalled.
+   */
+  closeAll(code: number = CLOSE_GOING_AWAY, reason: string = "server shutting down"): number {
+    const frame = buildCloseFrame(code, reason);
+    let closed = 0;
+    for (const client of [...this.clients]) {
+      try {
+        client.socket.write(frame);
+        client.socket.end();
+        closed++;
+      } catch {
+        /* already gone */
+      }
+      this.clients.delete(client);
+      if (client.trackerId && this.onRemove) this.onRemove(client.trackerId);
+    }
+    return closed;
+  }
+
   /**
    * Accept a WebSocket upgrade on `/__dev_reload` and hold the socket open.
    *