tina4-nodejs 3.13.94 → 3.13.96

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

@@ -10,7 +10,7 @@
  *   TINA4_SESSION_MONGO_URI        (overrides host/port if set)
  *   TINA4_SESSION_MONGO_USERNAME   (optional)
  *   TINA4_SESSION_MONGO_PASSWORD   (optional)
- *   TINA4_SESSION_MONGO_DB         (default: "tina4_sessions")
+ *   TINA4_SESSION_MONGO_DB         (default: "tina4")
  *   TINA4_SESSION_MONGO_COLLECTION (default: "sessions")
  */
 import type { SessionHandler } from "../session.js";
@@ -57,8 +57,18 @@ export class MongoSessionHandler implements SessionHandler {
   private password: string;
   private database: string;
   private collection: string;
+  private hostExplicit: boolean;
+  private portExplicit: boolean;
+  private uriExplicit: boolean;
 
   constructor(config?: MongoSessionConfig) {
+    // WHICH VALUES THE CALLER GAVE US EXPLICITLY, recorded because a URI from the
+    // ENVIRONMENT must never override an argument the caller passed by hand. See
+    // target() for the precedence and the defect this fixes.
+    this.hostExplicit = config?.host !== undefined;
+    this.portExplicit = config?.port !== undefined;
+    this.uriExplicit = config?.uri !== undefined;
+
     this.host = config?.host
       ?? process.env.TINA4_SESSION_MONGO_HOST
       ?? "127.0.0.1";
@@ -77,23 +87,67 @@ export class MongoSessionHandler implements SessionHandler {
     this.password = config?.password
       ?? process.env.TINA4_SESSION_MONGO_PASSWORD
       ?? "";
+    // "tina4" is the default in tina4-python, tina4-php and tina4-ruby. Node was
+    // the outlier at "tina4_sessions", so the SAME .env put Node's sessions in a
+    // different database from the other three - identical configuration, different
+    // observable outcome (the ADR-0024 failure mode). Breaking on purpose: see the
+    // migration note in the commit. No fallback read is offered; a session store is
+    // ephemeral by definition, so the impact self-heals within one TTL.
     this.database = config?.database
       ?? process.env.TINA4_SESSION_MONGO_DB
-      ?? "tina4_sessions";
+      ?? "tina4";
     this.collection = config?.collection
       ?? process.env.TINA4_SESSION_MONGO_COLLECTION
       ?? "sessions";
   }
 
-  /** Resolve the effective host/port (honours a configured mongodb:// URI). */
+  /**
+   * Resolve the effective host/port (honours a configured mongodb:// URI).
+   *
+   * PRECEDENCE, and it runs the way every other resolver in Tina4 runs -
+   * EXPLICIT CONFIGURATION BEATS THE ENVIRONMENT:
+   *
+   *   1. an explicitly passed `uri`      - the caller named a complete address
+   *   2. an explicitly passed host/port  - per field, and an ENV uri may not touch them
+   *   3. TINA4_SESSION_MONGO_URI / _URL  - the ambient address
+   *   4. TINA4_SESSION_MONGO_HOST/_PORT  - ambient parts
+   *   5. 127.0.0.1:27017
+   *
+   * THE DEFECT THIS FIXES, measured 2026-08-05 on the lab host: the URI won
+   * UNCONDITIONALLY, including over an argument the caller had just passed by
+   * hand. With TINA4_SESSION_MONGO_URI=mongodb://127.0.0.1:27017/tina4_node
+   * exported - an entirely ordinary deployment setting -
+   *
+   *     new MongoSessionHandler({ host: "127.0.0.1", port: 59999 })
+   *
+   * resolved to 127.0.0.1:27017. The handler dialled a DIFFERENT SERVER from the
+   * one it was told to use, said nothing, and a read against it came back null:
+   * indistinguishable from a genuine miss. So an app that points a handler at one
+   * Mongo while the environment names another writes its sessions to the wrong
+   * server, and the backend-failure policy cannot fire because nothing failed.
+   *
+   * It also made two suites report a framework contract as broken - the
+   * unreachable-server-must-throw cases in sessionHandlers and
+   * sessionMongoRawProtocol never reached the dead port at all, so they measured
+   * a live server and got a miss. Those cases were RIGHT; this was the bug they
+   * were catching.
+   *
+   * Same class as the TINA4_QUEUE_URL precedence inversion fixed in PHP's
+   * Queue::resolveMongoConfig earlier the same day: environment quietly beating
+   * an explicit argument.
+   */
   private target(): MongoTarget {
     let host = this.host;
     let port = this.port;
-    if (this.uri) {
+    // An ENV-supplied uri may fill in only what the caller did NOT pin. An
+    // explicitly passed uri is the caller's own choice and still wins outright.
+    const uriMayOverrideHost = this.uriExplicit || !this.hostExplicit;
+    const uriMayOverridePort = this.uriExplicit || !this.portExplicit;
+    if (this.uri && (uriMayOverrideHost || uriMayOverridePort)) {
       const match = this.uri.match(/mongodb:\/\/(?:[^@/]+@)?([^/:]+):?(\d+)?/);
       if (match) {
-        host = match[1];
-        port = match[2] ? parseInt(match[2], 10) : 27017;
+        if (uriMayOverrideHost) host = match[1];
+        if (uriMayOverridePort) port = match[2] ? parseInt(match[2], 10) : 27017;
       }
     }
     return { host, port, database: this.database, collection: this.collection };
@@ -103,7 +157,21 @@ export class MongoSessionHandler implements SessionHandler {
     const result = mongoCommandSync(this.target(), "find", { filter: { _id: sessionId } });
     if (!result || result === "__EMPTY__") return null;   // genuine miss
     try {
-      const doc = JSON.parse(result) as { data?: unknown };
+      const doc = JSON.parse(result) as { data?: unknown; expires_at?: number };
+
+      // Expiry is an ABSOLUTE deadline stamped at write time, and an absent or
+      // zero stamp means "never expires" - so it is guarded OUT of the
+      // comparison, never fed INTO it. Before this, read() consulted NOTHING:
+      // no stamp was stored, no TTL index was created, and write() took the ttl
+      // as `_ttl` and discarded it, so a mongodb-backed session never expired at
+      // all. Measured: write with ttl=1, sleep 3s, read still returned the data
+      // while file/redis/valkey/memcached/database all returned null.
+      const expiresAt = Number(doc?.expires_at ?? 0);
+      if (expiresAt > 0 && Date.now() / 1000 > expiresAt) {
+        this.destroy(sessionId);
+        return null;
+      }
+
       const data = doc?.data;
       // Stored as a nested document (parity with the Python master); read returns it.
       return data && typeof data === "object" ? (data as SessionData) : null;
@@ -112,10 +180,22 @@ export class MongoSessionHandler implements SessionHandler {
     }
   }
 
-  write(sessionId: string, data: SessionData, _ttl: number): void {
+  /**
+   * Write session data.
+   *
+   * The ttl is consumed HERE, at write time, and baked into an absolute deadline,
+   * so nothing at read time needs to know what the ttl was. The parameter used to
+   * be named `_ttl` and thrown away.
+   *
+   * @param sessionId - the session id
+   * @param data - the payload to store
+   * @param ttl - lifetime in seconds; 0 or less means never expires
+   */
+  write(sessionId: string, data: SessionData, ttl: number = 0): void {
     mongoCommandSync(this.target(), "update", {
       filter: { _id: sessionId },
       data,
+      expires_at: ttl > 0 ? Math.floor(Date.now() / 1000) + ttl : 0,
       last_accessed: Date.now() / 1000,
     });
   }

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

@@ -1,22 +1,17 @@
 /**
  * Tina4 synchronous RESP transport — shared by every Redis/Valkey session handler.
  *
- * The session-handler interface is synchronous, but node:net is async-only, so a
- * command runs in a short-lived `node -e` child (execFileSync) that blocks the
- * caller until it exits. This module is the ONE correct implementation of that
- * child; the Redis/Valkey handlers delegate here instead of inlining their own.
+ * The session-handler interface is synchronous but node:net is async-only, so
+ * this delegates to syncSocket, which owns ONE persistent connection per target
+ * behind a worker thread. See that file for why: the previous implementation ran
+ * every command in a short-lived `node -e` child, paying a process spawn AND a
+ * fresh TCP connection per command (p50 41ms, p99 487ms), and its long tail
+ * tripped the child's own deadline — the cause of the sessionHandlers flake.
  *
- * The bug this replaces: the old child parsed the reply on the socket "end" event.
- * Redis/Valkey keep the connection OPEN after a reply (they never half-close for a
- * GET/SET/DEL), so "end" never fires — the child waited out its timeout, exited
- * non-zero, and execFileSync re-threw it as a "transport failure". EVERY command
- * failed against a reachable server. Here the child parses replies INCREMENTALLY on
- * the "data" event (the same proven RESP parser cache.ts's RespClient uses): it
- * reads exactly the replies it sent commands for (AUTH? + SELECT? + the command),
- * then returns the LAST (command) reply.
+ * This module stays as the RESP-shaped seam the Redis/Valkey handlers call, so
+ * neither has to know how the synchronous transport is implemented.
  */
-import { execFileSync } from "node:child_process";
-import { childFailureError } from "./childError.js";
+import { syncCommand } from "./syncSocket.js";
 
 export interface RespTarget {
   host: string;
@@ -37,139 +32,13 @@ export interface RespTarget {
  *   `<label> error: ...`. A rejected handshake is a transport failure, not a
  *   result, so it is surfaced ahead of the command reply.
  *
- * Session values are JSON strings (they start with `{`), so they never collide
- * with the `__NULL__` / `__ERR__` sentinels the child uses on stdout.
+ * 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.
  */
 export function respCommandSync(target: RespTarget, args: string[], label = "Redis"): string {
-  const host = target.host;
-  const port = target.port;
-  const password = target.password ?? "";
-  const db = target.db ?? 0;
-
-  const script = `
-    const net = require("node:net");
-    const host = ${JSON.stringify(host)};
-    const port = ${port};
-    const password = ${JSON.stringify(password)};
-    const db = ${db};
-    const args = ${JSON.stringify(args)};
-    // Replies to consume = AUTH? + SELECT? + the command. The LAST is our result.
-    const expected = (password ? 1 : 0) + (db !== 0 ? 1 : 0) + 1;
-
-    function encode(a) {
-      let c = "*" + a.length + "\\r\\n";
-      for (const s of a) c += "$" + Buffer.byteLength(s) + "\\r\\n" + s + "\\r\\n";
-      return c;
-    }
-
-    // Parse one RESP value at offset. Returns { value, next } or null if more bytes
-    // are needed (so a bulk string split across TCP chunks is handled correctly).
-    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 };             // '+' simple string
-      if (type === 0x3a) return { value: line, next: after };             // ':' integer
-      if (type === 0x2d) return { value: { __err: line }, next: after };  // '-' error
-      if (type === 0x24) {                                                // '$' bulk string
-        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) {                                                // '*' array
-        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 };
-    }
-
-    const sock = net.createConnection({ host, port });
-    sock.setNoDelay(true);
-    let buffer = Buffer.alloc(0);
-    const replies = [];
-    let done = false;
-    const timer = setTimeout(() => { if (!done) { done = true; try { sock.destroy(); } catch (e) {} process.stderr.write("timeout"); process.exitCode = 1; } }, 3000);
-
-    function emit(s) {
-      if (done) return;
-      done = true;
-      clearTimeout(timer);
-      // The write callback guarantees stdout is flushed before exit (a bare
-      // process.exit can truncate piped stdout).
-      process.stdout.write(s, () => { try { sock.destroy(); } catch (e) {} });
-    }
-    function fail(msg) {
-      if (done) return;
-      done = true;
-      clearTimeout(timer);
-      try { sock.destroy(); } catch (e) {}
-      process.stderr.write(msg || "");
-      process.exitCode = 1;
-    }
-
-    sock.on("connect", () => {
-      let cmds = "";
-      if (password) cmds += encode(["AUTH", password]);
-      if (db !== 0) cmds += encode(["SELECT", String(db)]);
-      cmds += encode(args);
-      sock.write(cmds);
-    });
-    sock.on("data", (chunk) => {
-      buffer = buffer.length ? Buffer.concat([buffer, chunk]) : chunk;
-      while (true) {
-        const p = parse(buffer, 0);
-        if (!p) break;
-        buffer = buffer.subarray(p.next);
-        replies.push(p.value);
-        if (replies.length < expected) continue;
-        // A rejected AUTH/SELECT is a transport failure — surface it first.
-        for (let i = 0; i < expected - 1; i++) {
-          const r = replies[i];
-          if (r && typeof r === "object" && r.__err !== undefined) { emit("__ERR__" + r.__err); return; }
-        }
-        const result = replies[expected - 1];
-        if (result && typeof result === "object" && result.__err !== undefined) emit("__ERR__" + result.__err);
-        else if (result === null || result === undefined) emit("__NULL__");
-        else emit(String(result));
-        return;
-      }
-    });
-    sock.on("error", (err) => fail(err.message));
-    sock.on("close", () => { if (!done) fail("connection closed before reply"); });
-  `;
-
-  let result: string;
-  try {
-    result = execFileSync(process.execPath, ["-e", script], {
-      encoding: "utf-8",
-      timeout: 5000,
-      stdio: ["pipe", "pipe", "pipe"],
-    });
-  } catch (err) {
-    // Non-zero exit = socket error / timeout / closed connection: a transport
-    // FAILURE, not a key miss. Surface it so the Session boundary logs + degrades
-    // (or re-throws under strict mode).
-    //
-    // Report the CHILD's stderr, not execFileSync's message -- that message
-    // embeds the whole generated script and buries the actual reason.
-    throw childFailureError(label, err);
-  }
-  if (result === "__NULL__") return "";       // genuine key miss
-  if (result.startsWith("__ERR__")) {
-    throw new Error(`${label} error: ${result.slice("__ERR__".length)}`);
-  }
-  return result;
+  return syncCommand(
+    { host: target.host, port: target.port, password: target.password, db: target.db },
+    args,
+    label,
+  );
 }

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

@@ -0,0 +1,290 @@
+/**
+ * Tina4 synchronous SQL transport for the database session backend.
+ *
+ * WHY IT EXISTS. The SessionHandler interface is SYNCHRONOUS and every SQL
+ * driver Node offers for a networked engine (pg, mysql2, tedious,
+ * node-firebird) is async-only. That mismatch was previously "resolved" by
+ * refusing every engine except SQLite: resolveDbPath() THREW on any non-sqlite
+ * TINA4_DATABASE_URL. So an app developed on SQLite and deployed on PostgreSQL
+ * did not start, in the one subsystem that decides whether anybody is logged in.
+ *
+ * The mismatch is not a reason to refuse an engine, because the fix already
+ * existed: syncBridge.ts. A Worker thread keeps its own event loop, so it can
+ * hold a long-lived driver connection and do ordinary async I/O, while the
+ * caller blocks in Atomics.wait until the worker writes its reply into a
+ * SharedArrayBuffer. RESP (Redis/Valkey), memcached and MongoDB have all ridden
+ * that bridge for months. This is a fifth consumer of a proven mechanism, not a
+ * new mechanism.
+ *
+ * SQLITE DOES NOT COME THROUGH HERE. `node:sqlite` is already synchronous, so
+ * routing it through a worker would add a thread hop and a JSON round-trip to
+ * the one engine that needs neither. DatabaseSessionHandler drives it directly.
+ *
+ * WHY THE DRIVERS ARE REQUIRED INSIDE THE WORKER rather than reaching for the
+ * ORM adapters: exactly the reason mongoClient.ts requires "mongodb" itself.
+ * The worker body is an eval'd CJS string, so a bare `require` is the one module
+ * resolution that works identically under tsx, under plain node, from source and
+ * from a built dist. @tina4/orm already declares pg / mysql2 / tedious as
+ * optional dependencies, so nothing new is installed for this - core stays
+ * zero-dependency.
+ *
+ * The SQL itself is NOT built here. The handler builds engine-neutral SQL with
+ * `?` placeholders - the same statement text as the Python master - and this
+ * transport rewrites the placeholders into the dialect the driver wants. Only
+ * the placeholder style and the CREATE TABLE types differ per engine.
+ */
+import { createRequire } from "node:module";
+import { getBridge, STATUS_OK, STATUS_TRANSPORT } from "./syncBridge.js";
+
+/**
+ * The SQL engines the database session backend speaks.
+ *
+ * This IS the invariant: it is the engine set of the ORM Database layer minus
+ * the two non-SQL entries (mongodb has its own session backend, odbc has no
+ * session story in any of the four frameworks). Naming it once means the
+ * refusal message and the dispatch can never disagree about what is supported.
+ */
+export const SQL_SESSION_ENGINES = ["sqlite", "postgres", "mysql", "mssql", "firebird"] as const;
+
+export type SqlSessionEngine = (typeof SQL_SESSION_ENGINES)[number];
+
+/** The engines that need the bridge - everything except already-sync SQLite. */
+export type BridgedEngine = Exclude<SqlSessionEngine, "sqlite">;
+
+/**
+ * A connection target for the worker.
+ *
+ * A PLAIN object, deliberately - never a `DatabaseUrl`. That class carries a
+ * cleartext password and its own docblock forbids persisting it across a
+ * structured-clone boundary (test/databaseUrlRedaction.test.ts enforces it).
+ * The worker genuinely needs credentials to authenticate, so it gets the fields
+ * it needs and nothing that renders itself.
+ */
+export interface SqlTarget {
+  engine: BridgedEngine;
+  host: string;
+  port: number;
+  database: string;
+  username: string | null;
+  password: string | null;
+}
+
+/**
+ * Connect budget, kept BELOW the bridge's 5s reply timeout on purpose. An
+ * unreachable server then surfaces as a real driver message ("ECONNREFUSED
+ * 127.0.0.1:5432") instead of the caller's generic "timed out after 5000ms",
+ * which says nothing about what is actually wrong. Same reasoning, same number
+ * as mongoClient's SERVER_SELECTION_MS.
+ */
+const CONNECT_TIMEOUT_MS = 3000;
+
+/** The driver each engine needs. All are already optional deps of @tina4/orm. */
+const DRIVER_PACKAGE: Record<BridgedEngine, string> = {
+  postgres: "pg",
+  mysql: "mysql2",
+  mssql: "tedious",
+  firebird: "node-firebird",
+};
+
+const requireFromHere = createRequire(import.meta.url);
+
+/**
+ * Resolve the driver to an ABSOLUTE path, on the main thread, before the worker
+ * starts.
+ *
+ * A bare `require("pg")` inside the worker would resolve from the process
+ * WORKING DIRECTORY (an eval'd worker has no real filename to resolve from), so
+ * a server started from anywhere other than the project root would fail to find
+ * a driver that is installed. Resolving from THIS module instead walks up from
+ * the framework's own location, which is correct in the monorepo and in an
+ * installed app alike.
+ *
+ * @throws Error naming the missing package and how to install it.
+ */
+function driverPath(engine: BridgedEngine): string {
+  const packageName = DRIVER_PACKAGE[engine];
+  try {
+    return requireFromHere.resolve(packageName);
+  } catch {
+    throw new Error(
+      `The "database" session backend on ${engine} requires the "${packageName}" package. `
+      + `Install it with: npm install ${packageName}`,
+    );
+  }
+}
+
+const SQL_WORKER = `
+const target = workerData.target;
+const engine = target.engine;
+const driver = require(workerData.driverPath);
+
+let client = null;
+
+/**
+ * Rewrite the handler's neutral \`?\` placeholders into the driver's dialect.
+ * mysql2 and node-firebird already take \`?\`, so they are left alone.
+ */
+function convert(sql) {
+  if (engine === "postgres") { let n = 0; return sql.replace(/\\?/g, () => "$" + (++n)); }
+  if (engine === "mssql") { let n = 0; return sql.replace(/\\?/g, () => "@p" + (n++)); }
+  return sql;
+}
+
+async function connect() {
+  if (engine === "postgres") {
+    const Client = driver.Client || (driver.default && driver.default.Client);
+    const c = new Client({
+      host: target.host,
+      port: target.port,
+      user: target.username === null ? undefined : target.username,
+      password: target.password === null ? undefined : target.password,
+      database: target.database,
+      connectionTimeoutMillis: ${CONNECT_TIMEOUT_MS},
+    });
+    await c.connect();
+    return c;
+  }
+  if (engine === "mysql") {
+    const c = driver.createConnection({
+      host: target.host,
+      port: target.port,
+      user: target.username === null ? undefined : target.username,
+      password: target.password === null ? undefined : target.password,
+      database: target.database,
+      connectTimeout: ${CONNECT_TIMEOUT_MS},
+    });
+    await new Promise((resolve, reject) => c.connect((err) => (err ? reject(err) : resolve())));
+    return c;
+  }
+  if (engine === "mssql") {
+    const c = new driver.Connection({
+      server: target.host,
+      authentication: {
+        type: "default",
+        options: { userName: target.username, password: target.password },
+      },
+      options: {
+        database: target.database,
+        port: target.port,
+        trustServerCertificate: true,
+        encrypt: false,
+        connectTimeout: ${CONNECT_TIMEOUT_MS},
+      },
+    });
+    await new Promise((resolve, reject) => {
+      c.on("connect", (err) => (err ? reject(err) : resolve()));
+      c.connect();
+    });
+    return c;
+  }
+  if (engine === "firebird") {
+    return await new Promise((resolve, reject) => {
+      driver.attach(
+        {
+          host: target.host,
+          port: target.port,
+          database: target.database,
+          user: target.username,
+          password: target.password,
+        },
+        (err, db) => (err ? reject(err) : resolve(db)),
+      );
+    });
+  }
+  throw new Error("unsupported session SQL engine: " + engine);
+}
+
+function runMssql(sql, params) {
+  return new Promise((resolve, reject) => {
+    const rows = [];
+    const request = new driver.Request(convert(sql), (err) => (err ? reject(err) : resolve(rows)));
+    params.forEach((value, i) => {
+      // EVERY number binds as Float, never Int. tedious' Int is 32-bit and an
+      // expiry stamp is epoch SECONDS - an integral value above 2147483647
+      // (2038-01-19) would overflow and be stored as garbage, silently.
+      if (typeof value === "number") request.addParameter("p" + i, driver.TYPES.Float, value);
+      else if (value === null || value === undefined) request.addParameter("p" + i, driver.TYPES.NVarChar, null);
+      // length: Infinity means NVARCHAR(MAX). Without it tedious caps the
+      // parameter at 4000 characters and a large session TRUNCATES on write.
+      else request.addParameter("p" + i, driver.TYPES.NVarChar, String(value), { length: Infinity });
+    });
+    request.on("row", (columns) => {
+      const row = {};
+      columns.forEach((column) => { row[column.metadata.colName] = column.value; });
+      rows.push(row);
+    });
+    client.execSql(request);
+  });
+}
+
+async function run(sql, params) {
+  if (!client) client = await connect();
+  if (engine === "postgres") {
+    const result = await client.query(convert(sql), params);
+    return result.rows || [];
+  }
+  if (engine === "mysql") {
+    const results = await new Promise((resolve, reject) => {
+      client.query(sql, params, (err, rows) => (err ? reject(err) : resolve(rows)));
+    });
+    return Array.isArray(results) ? results : [];
+  }
+  if (engine === "mssql") return await runMssql(sql, params);
+  const rows = await new Promise((resolve, reject) => {
+    client.query(sql, params, (err, result) => (err ? reject(err) : resolve(result)));
+  });
+  return Array.isArray(rows) ? rows : [];
+}
+
+parentPort.on("message", (message) => {
+  void (async () => {
+    try {
+      const rows = await run(message.sql, message.params || []);
+      __reply(${STATUS_OK}, JSON.stringify(rows));
+    } catch (err) {
+      // Drop the connection so the NEXT command reconnects. A transient blip
+      // must not poison the channel for the life of the process.
+      try {
+        if (client) {
+          if (typeof client.end === "function") client.end();
+          else if (typeof client.close === "function") client.close();
+          else if (typeof client.detach === "function") client.detach();
+        }
+      } catch (ignored) {}
+      client = null;
+      __reply(${STATUS_TRANSPORT}, String((err && err.message) || err));
+    }
+  })();
+});
+`;
+
+/**
+ * Run one SQL statement synchronously against a networked engine.
+ *
+ * @returns the result rows - always an array, empty for a write or DDL.
+ * @throws Error on ANY driver failure (server unreachable, bad credentials,
+ *         SQL error). It is never swallowed into an empty result: for a session
+ *         store, "the database is down" and "no session yet" must stay
+ *         distinguishable, or a dead backend silently logs every user out.
+ */
+export function sqlCommandSync(
+  target: SqlTarget,
+  sql: string,
+  params: unknown[] = [],
+  label = "Database session",
+): Record<string, unknown>[] {
+  const key = `sql:${target.engine}:${target.host}:${target.port}:${target.database}:${target.username ?? ""}`;
+  const { status, payload } = getBridge(key, SQL_WORKER, {
+    target,
+    driverPath: driverPath(target.engine),
+  }).call({ sql, params }, label);
+
+  if (status !== STATUS_OK) {
+    throw new Error(`${label} command failed: ${payload}`);
+  }
+  try {
+    return JSON.parse(payload) as Record<string, unknown>[];
+  } catch {
+    return [];
+  }
+}