tina4-nodejs 3.13.94 → 3.13.96

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

@@ -0,0 +1,190 @@
+/**
+ * Tina4 sync-over-async bridge — call an ASYNC worker from SYNCHRONOUS code.
+ *
+ * The SessionHandler interface is synchronous; every backend client Node offers
+ * (node:net, the mongodb driver) is async-only. The old resolution was to run
+ * each command in a short-lived `node -e` child and block on execFileSync. That
+ * works but pays a process spawn — and a fresh connection, and for Mongo a fresh
+ * driver load — PER COMMAND. Measured on this machine: spawn min 38ms / p50 41ms
+ * / p99 487ms, with a bare TCP connect adding a ~0.5-0.9s tail of its own. That
+ * tail tripped the child's deadline under load, which is what made the Valkey
+ * session tests flaky with the signature "a value that was just written reads
+ * back null" — the write timed out for the caller while still landing on the
+ * server.
+ *
+ * This is the ONE piece of plumbing that replaces it. A Worker thread keeps its
+ * own event loop, so it can do ordinary async I/O and hold a long-lived
+ * connection. The caller hands it a message with postMessage (delivered on the
+ * WORKER's loop, so a blocked main thread cannot deadlock it), then blocks in
+ * Atomics.wait until the worker writes a reply into a SharedArrayBuffer and
+ * Atomics.notify wakes it.
+ *
+ * Every session backend that needs sync-over-async uses this — RESP
+ * (Redis/Valkey), memcached's text protocol, and MongoDB — so the blocking
+ * handshake exists once rather than once per backend.
+ */
+import { Worker } from "node:worker_threads";
+
+/** Reply status, written by the worker into control[IDX_STATUS]. */
+export const STATUS_OK = 0;
+/** A healthy server answered with an error (RESP `-ERR`, a Mongo command error). */
+export const STATUS_ERROR = 1;
+/** A genuine miss — no such key/document. NOT a failure. */
+export const STATUS_NIL = 2;
+/** The reply did not fit the shared buffer. */
+export const STATUS_TOO_LARGE = 3;
+/** Connection/socket/driver failure, as opposed to an answer from a healthy server. */
+export const STATUS_TRANSPORT = 4;
+
+export const IDX_SEQ = 0;      // bumped by the worker on every reply; what Atomics.wait watches
+export const IDX_LENGTH = 1;   // reply byte length
+export const IDX_STATUS = 2;   // one of STATUS_*
+export const IDX_READY = 3;    // set to 1 by the worker as soon as its loop is running
+
+/**
+ * Reply payload ceiling. A session document beyond this is pathological, and a
+ * fixed buffer keeps the fast path allocation-free. A worker reports
+ * STATUS_TOO_LARGE rather than truncating — a silently truncated session would
+ * deserialise into garbage.
+ */
+export const DATA_BYTES = 8 * 1024 * 1024;
+
+/** How long a caller blocks before giving up on a reply. */
+export const REPLY_TIMEOUT_MS = 5000;
+
+/**
+ * How long the FIRST caller waits for a brand-new worker to come up.
+ *
+ * Boot and the command round-trip must not share one budget. Cold start is
+ * normally ~27ms, but on a loaded machine (the session suite spawns a batch of
+ * blocking Mongo children immediately beforehand) it can stretch — and when it
+ * ate into the 5s command budget the very first Valkey write failed with
+ * "timed out after 5000ms", which read exactly like the flake this transport
+ * was built to remove. Boot gets its own generous budget so the per-command
+ * timeout can stay tight and mean what it says.
+ */
+export const BOOT_TIMEOUT_MS = 15000;
+
+/**
+ * The worker-side helper, injected into every worker body. Kept here so the
+ * reply protocol is written once: a worker only has to call
+ * `__reply(status, payload)` and never touches Atomics itself.
+ */
+export const WORKER_REPLY_HELPER = `
+const __control = new Int32Array(workerData.controlBuffer);
+const __data = new Uint8Array(workerData.dataBuffer);
+const __encoder = new TextEncoder();
+
+// Announce readiness the moment this thread is executing. The parent blocks on
+// this before its first command, so a slow boot can never be mistaken for a
+// slow command. This is signalled by the worker's OWN bootstrap and needs no
+// message from the parent, so it is safe even while the parent is blocked.
+Atomics.store(__control, ${IDX_READY}, 1);
+Atomics.notify(__control, ${IDX_READY});
+
+function __reply(status, payload) {
+  let length = 0;
+  if (payload !== undefined && payload !== null && status !== ${STATUS_NIL}) {
+    const bytes = __encoder.encode(String(payload));
+    if (bytes.length > __data.length) {
+      Atomics.store(__control, ${IDX_STATUS}, ${STATUS_TOO_LARGE});
+      Atomics.store(__control, ${IDX_LENGTH}, 0);
+      Atomics.add(__control, ${IDX_SEQ}, 1);
+      Atomics.notify(__control, ${IDX_SEQ});
+      return;
+    }
+    __data.set(bytes, 0);
+    length = bytes.length;
+  }
+  Atomics.store(__control, ${IDX_STATUS}, status);
+  Atomics.store(__control, ${IDX_LENGTH}, length);
+  Atomics.add(__control, ${IDX_SEQ}, 1);
+  Atomics.notify(__control, ${IDX_SEQ});
+}
+`;
+
+export interface BridgeReply {
+  status: number;
+  payload: string;
+}
+
+export interface Bridge {
+  /** Send a message to the worker and BLOCK until it replies. */
+  call(message: unknown, label: string): BridgeReply;
+  worker: Worker;
+}
+
+const bridges = new Map<string, Bridge>();
+
+/**
+ * Get (or create) the bridge for a key. One worker per key, created once and
+ * unref'd so it can never hold the process open.
+ *
+ * @param key Identity of the connection target — same key, same worker
+ * @param workerSource The worker body; WORKER_REPLY_HELPER is prepended for it
+ * @param workerData Passed to the worker verbatim (plus the shared buffers)
+ */
+export function getBridge(key: string, workerSource: string, workerData: Record<string, unknown>): Bridge {
+  const existing = bridges.get(key);
+  if (existing) return existing;
+
+  const controlBuffer = new SharedArrayBuffer(4 * Int32Array.BYTES_PER_ELEMENT);
+  const dataBuffer = new SharedArrayBuffer(DATA_BYTES);
+  const control = new Int32Array(controlBuffer);
+  const data = new Uint8Array(dataBuffer);
+
+  const worker = new Worker(
+    `const { parentPort, workerData } = require("node:worker_threads");\n${WORKER_REPLY_HELPER}\n${workerSource}`,
+    { eval: true, workerData: { ...workerData, controlBuffer, dataBuffer } },
+  );
+  // A session channel must never keep a process alive.
+  worker.unref();
+
+  // Block until the worker is up. A cold channel pays this once.
+  if (Atomics.load(control, IDX_READY) === 0) {
+    if (Atomics.wait(control, IDX_READY, 0, BOOT_TIMEOUT_MS) === "timed-out") {
+      void worker.terminate();
+      bridges.delete(key);
+      throw new Error(`session worker failed to start within ${BOOT_TIMEOUT_MS}ms`);
+    }
+  }
+
+  const decoder = new TextDecoder();
+  const bridge: Bridge = {
+    worker,
+    call(message: unknown, label: string): BridgeReply {
+      // Watch a monotonic counter rather than a flag: a counter cannot race with
+      // a reset, so a late reply from a previous (timed-out) call can never be
+      // mistaken for this one's.
+      const before = Atomics.load(control, IDX_SEQ);
+      worker.postMessage(message);
+
+      if (Atomics.wait(control, IDX_SEQ, before, REPLY_TIMEOUT_MS) === "timed-out") {
+        throw new Error(`${label} command failed: timed out after ${REPLY_TIMEOUT_MS}ms`);
+      }
+
+      const status = Atomics.load(control, IDX_STATUS);
+      const length = Atomics.load(control, IDX_LENGTH);
+
+      if (status === STATUS_TOO_LARGE) {
+        throw new Error(`${label} command failed: reply exceeds the ${DATA_BYTES} byte buffer`);
+      }
+      return { status, payload: decoder.decode(data.subarray(0, length)) };
+    },
+  };
+
+  bridges.set(key, bridge);
+  return bridge;
+}
+
+/**
+ * Terminate every worker. Tests and short-lived scripts call this so a spawned
+ * worker never outlives the work that created it — "reap what you spawn". Normal
+ * apps do not need it: the workers are unref'd.
+ */
+export function closeBridges(): void {
+  for (const { worker } of bridges.values()) {
+    void worker.terminate();
+  }
+  bridges.clear();
+}

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);
       }
     }