tina4-nodejs 3.13.92 → 3.13.95

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

@@ -1,16 +1,50 @@
 /**
- * Tina4 Database Session Handler — SQLite via Node's built-in node:sqlite,
- * zero extra dependencies.
+ * Tina4 Database Session Handler — sessions in a `tina4_session` table on ANY
+ * engine the ORM Database layer supports: sqlite, postgres, mysql, mssql,
+ * firebird.
  *
- * Uses the same `node:sqlite` (DatabaseSync) the ORM's SQLite adapter uses —
- * no third-party driver, nothing to install.
- * Stores sessions in a `tina4_session` table with JSON data and expiry.
+ * WHAT THIS USED TO BE, and why it changed. This handler was SQLite-only by
+ * construction: resolveDbPath() THREW on any non-sqlite TINA4_DATABASE_URL. So
+ * an app developed on SQLite and deployed on PostgreSQL did not start at all -
+ * the founding scenario of ADR-0024, landing in the one subsystem that decides
+ * whether anybody is logged in. A backend that advertises support for an engine
+ * has to work on that engine.
+ *
+ * The refusal was defended on the grounds that the session API is SYNCHRONOUS
+ * and a PostgreSQL driver is async, so multi-engine "would need a synchronous
+ * Postgres bridge". That premise was wrong: the bridge already existed
+ * (syncBridge.ts) with four consumers - RESP for Redis/Valkey, memcached and
+ * MongoDB. sqlClient.ts makes this the fifth.
+ *
+ * SQLITE STAYS ON `node:sqlite`, DIRECTLY. It is already synchronous, so
+ * putting it on the bridge would add a thread hop and a JSON round-trip to the
+ * one engine that needs neither.
+ *
+ * WHAT DID NOT CHANGE: an unsupported engine still REFUSES, loudly, by name. It
+ * must never fall back to a local SQLite file - that hands every horizontally
+ * scaled instance its own private session store, so a user is logged out on
+ * every request that lands elsewhere. An outage that looks exactly like success
+ * is worse than a refusal, which is why the refusal is kept even though the
+ * supported set is now five engines instead of one.
  *
  * Configure via environment variables:
- *   TINA4_DATABASE_URL  (default: "sqlite:///data/tina4_sessions.db")
+ *   TINA4_DATABASE_URL       (default: a local SQLite file, "data/tina4_sessions.db")
+ *   TINA4_DATABASE_USERNAME  (used when the URL carries no credentials)
+ *   TINA4_DATABASE_PASSWORD  (same)
  */
 import { DatabaseSync } from "node:sqlite";
 import type { SessionHandler } from "../session.js";
+// The ORM's connection-string parser, NOT a second copy of it. The invariant is
+// "the session backend works on every engine the Database layer supports", so
+// it has to agree with that layer about what a connection string MEANS -
+// aliases (postgresql/pgsql/sqlserver), default ports, credential fallbacks and
+// the explicitly-blank-password rule included. A private parser here would be
+// free to drift from the corpus fixture that keeps all four frameworks honest.
+// databaseUrl.ts imports nothing but node:util, so this adds one pure module to
+// the graph and no package cycle.
+import { DatabaseUrl } from "../../../orm/src/databaseUrl.js";
+import { SQL_SESSION_ENGINES, sqlCommandSync } from "./sqlClient.js";
+import type { BridgedEngine, SqlTarget } from "./sqlClient.js";
 
 interface SessionData {
   _created: number;
@@ -19,7 +53,7 @@ interface SessionData {
 }
 
 export interface DatabaseSessionConfig {
-  /** SQLite database file path (default: extracted from TINA4_DATABASE_URL or "data/tina4_sessions.db") */
+  /** SQLite database file path. Explicit config wins over TINA4_DATABASE_URL. */
   dbPath?: string;
   // Unified SessionConfig fields are tolerated (and ignored) so the central
   // Session can forward its config object without a structural mismatch.
@@ -34,32 +68,267 @@ export interface DatabaseSessionConfig {
 }
 
 /**
- * Database session handler using node:sqlite (synchronous SQLite).
+ * CREATE TABLE per engine. The only genuinely per-engine SQL in this file -
+ * every other statement is written once with `?` placeholders and rewritten for
+ * the driver by sqlClient.
+ *
+ * The COLUMNS are identical everywhere (session_id, data, expires_at) because
+ * the table is a cross-framework contract: a tina4_session table written by
+ * tina4-python must be readable by tina4-nodejs. Only the type spellings and
+ * the "create it only if absent" idiom differ.
+ */
+const CREATE_TABLE: Record<string, string> = {
+  // Unchanged from the SQLite-only original, deliberately: an existing
+  // deployment's table must keep working untouched.
+  sqlite: `
+      CREATE TABLE IF NOT EXISTS tina4_session (
+          session_id TEXT PRIMARY KEY,
+          data TEXT NOT NULL,
+          expires_at REAL NOT NULL
+      )
+    `,
+  postgres: `
+      CREATE TABLE IF NOT EXISTS tina4_session (
+          session_id VARCHAR(255) PRIMARY KEY,
+          data TEXT NOT NULL,
+          expires_at DOUBLE PRECISION NOT NULL
+      )
+    `,
+  mysql: `
+      CREATE TABLE IF NOT EXISTS tina4_session (
+          session_id VARCHAR(255) PRIMARY KEY,
+          data TEXT NOT NULL,
+          expires_at DOUBLE NOT NULL
+      )
+    `,
+  // T-SQL has no CREATE TABLE IF NOT EXISTS; the catalog check is the idiom.
+  mssql: `
+      IF OBJECT_ID(N'tina4_session', N'U') IS NULL
+      CREATE TABLE tina4_session (
+          session_id NVARCHAR(255) NOT NULL PRIMARY KEY,
+          data NVARCHAR(MAX) NOT NULL,
+          expires_at FLOAT NOT NULL
+      )
+    `,
+  // Firebird has neither IF NOT EXISTS nor a TEXT type, so the catalog check
+  // goes in an EXECUTE BLOCK and the payload is a VARCHAR.
+  //
+  // VERIFIED 2026-08-04 against a live Firebird 5.0.4 (the lab's
+  // tina4-lab-firebird container). This comment previously said UNVERIFIED and
+  // claimed there was no server on the lab; there is, and this SQL was run on
+  // it. What was measured, at the isql prompt:
+  //
+  //   CREATE TABLE IF NOT EXISTS ...  -> SQLSTATE 42000, -104,
+  //                                      "Token unknown - line 1, column 17 -NOT"
+  //   a column typed TEXT             -> -607, "Specified domain or source
+  //                                      column TEXT does not exist"
+  //   DOUBLE PRECISION                -> accepted
+  //   this EXECUTE BLOCK              -> created the table; confirmed out of band
+  //                                      in RDB$RELATIONS
+  //   this EXECUTE BLOCK, run AGAIN
+  //   with the table present          -> clean, no error: it is IDEMPOTENT
+  //
+  // So both halves of the first line above are now measurement rather than
+  // inference: Firebird really has neither IF NOT EXISTS nor a TEXT type.
+  //
+  // The idempotence is NOT a race guard. It is check-then-act inside one block,
+  // so two connections can still both find the table absent and both create it -
+  // measured directly: a bare CREATE TABLE with the table present gives
+  // SQLSTATE 42S01 "Table TINA4_SESSION already exists". The caller's
+  // create-then-recheck rescue is what closes that window, on every engine.
+  //
+  // A VARCHAR rather than BLOB SUB_TYPE TEXT on purpose: node-firebird hands a
+  // blob back as a reader function rather than a string, which the read path
+  // here would not understand. The cost is a session payload ceiling of 8191
+  // characters on this engine alone. Still unverified: the node-firebird DRIVER
+  // path end to end - this measurement was taken at the SQL level via isql.
+  firebird: `
+      EXECUTE BLOCK AS BEGIN
+        IF (NOT EXISTS(SELECT 1 FROM RDB$RELATIONS WHERE RDB$RELATION_NAME = 'TINA4_SESSION')) THEN
+          EXECUTE STATEMENT 'CREATE TABLE TINA4_SESSION (SESSION_ID VARCHAR(255) NOT NULL PRIMARY KEY, DATA VARCHAR(8191) NOT NULL, EXPIRES_AT DOUBLE PRECISION NOT NULL)';
+      END
+    `,
+};
+
+/**
+ * Read a column out of a result row, case-insensitively.
+ *
+ * PostgreSQL folds unquoted identifiers to lower case and Firebird folds them
+ * to UPPER, so the same SELECT legitimately comes back as `expires_at` on four
+ * engines and `EXPIRES_AT` on one. Three lines here beats quoting every
+ * identifier in every statement.
+ */
+function column(row: Record<string, unknown>, name: string): unknown {
+  if (name in row) return row[name];
+  return row[name.toUpperCase()];
+}
+
+/**
+ * Database session handler.
  *
  * Stores session data as JSON in a `tina4_session` table.
  * Expiry is checked on read; expired rows are cleaned up lazily.
  */
 export class DatabaseSessionHandler implements SessionHandler {
-  private db: any;
+  private sqliteHandle: any = null;
+  /** Set for SQLite. Null when this handler talks to a networked engine. */
+  private dbPath: string | null = null;
+  /** Set for a networked engine. Null for SQLite. */
+  private target: SqlTarget | null = null;
   private initialized = false;
 
+  /**
+   * NO I/O IN A CONSTRUCTOR (ADR-0021).
+   *
+   * This used to run `new DatabaseSync(dbPath)` and a `PRAGMA journal_mode =
+   * WAL` right here. Both are real work against real storage: opening the
+   * database CREATES the file, and switching to WAL creates its `-wal` and
+   * `-shm` siblings. Measured from a clean temp cwd, merely constructing this
+   * handler left three files on disk before a single session was ever read or
+   * written.
+   *
+   * A constructor sits OUTSIDE the log-loud-and-degrade policy, so nothing it
+   * does can be logged, degraded, or re-raised by TINA4_SESSION_STRICT - the one
+   * place the policy cannot protect is the first thing that runs.
+   *
+   * Everything below is pure string work. Resolving the target parses a URL;
+   * refusing an unsupported engine is a CONFIGURATION error that must still be
+   * loud at construction. The database - file or socket - is opened on first
+   * use. Going multi-engine is the change most likely to reintroduce
+   * constructor-time I/O, which is why test/sessionHandlerConstruction.test.ts
+   * measures a real filesystem and a real listening socket rather than trusting
+   * this comment.
+   */
   constructor(config?: DatabaseSessionConfig) {
-    const dbPath = config?.dbPath ?? this.resolveDbPath();
+    if (config?.dbPath) {
+      // An explicit path is an explicit choice of SQLite, and it wins over the
+      // environment exactly as it always has.
+      this.dbPath = config.dbPath;
+      return;
+    }
+    this.resolveTarget();
+  }
+
+  /** Open the SQLite database on FIRST USE, not at construction. */
+  private get sqlite(): any {
+    if (this.sqliteHandle === null) {
+      this.sqliteHandle = new DatabaseSync(this.dbPath as string);
+      this.sqliteHandle.exec("PRAGMA journal_mode = WAL");
+    }
+    return this.sqliteHandle;
+  }
 
-    this.db = new DatabaseSync(dbPath);
-    this.db.exec("PRAGMA journal_mode = WAL");
+  private get engine(): string {
+    return this.target === null ? "sqlite" : this.target.engine;
   }
 
   /**
-   * Resolve the database file path from TINA4_DATABASE_URL or use the default.
+   * Decide, from TINA4_DATABASE_URL, which engine this handler talks to.
+   *
+   * A NON-SQLITE URL NOW WORKS. It used to throw, because the handler drove
+   * `node:sqlite` directly and had no way to reach anything else; the async
+   * drivers now ride the sync bridge, so the reason for the refusal is gone.
+   *
+   * AN UNSUPPORTED ENGINE STILL REFUSES, and that half is not negotiable. The
+   * original defect was worse than a refusal: an unrecognised URL fell through
+   * to the literal default `"data/tina4_sessions.db"`, so
+   * `TINA4_DATABASE_URL=postgres://...` with `TINA4_SESSION_BACKEND=database`
+   * round-tripped happily while writing SQLite files into the process working
+   * directory. Measured from a clean temp cwd: round-trip true, and `data/`
+   * contained `tina4_sessions.db`, `-shm` and `-wal`. Every horizontally-scaled
+   * instance therefore had its own private session store and a user was logged
+   * out on every request that landed elsewhere.
+   *
+   * This is the same rule `resolveBackend()` applies one layer up, where an
+   * unknown backend name raises rather than falling through to disk.
+   *
+   * @throws Error naming the offending scheme and the engines this backend
+   *         speaks. The URL itself is NEVER in the message - it may carry a
+   *         password.
    */
-  private resolveDbPath(): string {
+  private resolveTarget(): void {
     const url = process.env.TINA4_DATABASE_URL;
-    if (url && url.startsWith("sqlite://")) {
+    if (!url) {
+      this.dbPath = "data/tina4_sessions.db";
+      return;
+    }
+
+    if (url.startsWith("sqlite:")) {
       // sqlite:///path/to/db  or  sqlite://./relative/path
-      return url.replace(/^sqlite:\/\//, "");
+      //
+      // KNOWN DIVERGENCE, deliberately left alone. DatabaseUrl reads the
+      // three-slash form as RELATIVE (`sqlite:///data/app.db` -> `data/app.db`)
+      // per the documented cross-framework contract, while this strips the
+      // prefix and yields `/data/app.db` - an absolute path at the filesystem
+      // root. They disagree, and the ORM's reading is the correct one. Changing
+      // it here would silently relocate the session store of every deployment
+      // using that form, which is precisely the class of failure this invariant
+      // is about, so it is reported rather than smuggled into a multi-engine
+      // change.
+      this.dbPath = url.replace(/^sqlite:(\/\/)?/, "");
+      return;
+    }
+
+    let parsed: DatabaseUrl;
+    try {
+      parsed = new DatabaseUrl(
+        url,
+        process.env.TINA4_DATABASE_USERNAME,
+        process.env.TINA4_DATABASE_PASSWORD,
+      );
+    } catch {
+      // DatabaseUrl refuses a scheme it does not know at all. Its own message
+      // lists engines this backend cannot use (mongodb, odbc), so the refusal
+      // is restated in terms of what the SESSION backend actually speaks.
+      throw this.unsupportedEngine(schemeOf(url));
+    }
+
+    if (!(SQL_SESSION_ENGINES as readonly string[]).includes(parsed.engine)) {
+      // A real engine the Database layer supports, but not a SQL one - mongodb
+      // and odbc land here.
+      throw this.unsupportedEngine(parsed.engine);
+    }
+
+    this.target = {
+      engine: parsed.engine as BridgedEngine,
+      host: parsed.host ?? "127.0.0.1",
+      port: parsed.port ?? 0,
+      database: parsed.database,
+      username: parsed.username,
+      password: parsed.password,
+    };
+  }
+
+  private unsupportedEngine(scheme: string): Error {
+    return new Error(
+      `The "database" session backend cannot use a "${scheme}" URL. It speaks the SQL `
+      + `engines the Database layer supports: ${SQL_SESSION_ENGINES.join(", ")}. Point `
+      + `TINA4_DATABASE_URL at one of those, or pass an explicit dbPath in the session `
+      + `config, or choose a session backend that speaks ${scheme} (redis, valkey, `
+      + `mongodb, memcached). It will NOT fall back to a local SQLite file: that gives `
+      + `every instance its own private session store and logs users out at random.`,
+    );
+  }
+
+  // ── one statement, five engines ───────────────────────────────────
+  // The SQL is written ONCE with `?` placeholders - the same statement text as
+  // the Python master - and sqlClient rewrites the placeholders per driver.
+
+  /** Run a statement that returns rows. */
+  private query(sql: string, params: unknown[]): Record<string, unknown>[] {
+    if (this.target === null) {
+      return this.sqlite.prepare(sql).all(...params) as Record<string, unknown>[];
+    }
+    return sqlCommandSync(this.target, sql, params);
+  }
+
+  /** Run a statement that returns nothing. */
+  private exec(sql: string, params: unknown[]): void {
+    if (this.target === null) {
+      this.sqlite.prepare(sql).run(...params);
+      return;
     }
-    return "data/tina4_sessions.db";
+    sqlCommandSync(this.target, sql, params);
   }
 
   /**
@@ -67,35 +336,40 @@ export class DatabaseSessionHandler implements SessionHandler {
    */
   private ensureTable(): void {
     if (this.initialized) return;
-    this.db.exec(`
-      CREATE TABLE IF NOT EXISTS tina4_session (
-          session_id TEXT PRIMARY KEY,
-          data TEXT NOT NULL,
-          expires_at REAL NOT NULL
-      )
-    `);
+    const ddl = CREATE_TABLE[this.engine];
+    if (this.target === null) this.sqlite.exec(ddl);
+    else sqlCommandSync(this.target, ddl, []);
     this.initialized = true;
   }
 
   read(sessionId: string): SessionData | null {
     this.ensureTable();
 
-    const row = this.db
-      .prepare("SELECT data, expires_at FROM tina4_session WHERE session_id = ?")
-      .get(sessionId) as { data: string; expires_at: number } | undefined;
-
+    const rows = this.query(
+      "SELECT data, expires_at FROM tina4_session WHERE session_id = ?",
+      [sessionId],
+    );
+    const row = rows[0];
     if (!row) return null;
 
-    // Check expiry
+    // Check expiry.
+    //
+    // An ABSENT or ZERO deadline means "never expires" and is guarded OUT of the
+    // comparison. Without the `> 0` test, a row carrying no expiry (0) satisfies
+    // `0 < now` against every clock and is DESTROYED on read — the same shape
+    // that made tina4-php's file backend delete records. gc() below has always
+    // had this guard (`WHERE expires_at > 0 AND expires_at < ?`); this read path
+    // did not, so the two disagreed about what a zero meant.
     const now = Date.now() / 1000;
-    if (row.expires_at < now) {
+    const expiresAt = Number(column(row, "expires_at") ?? 0);
+    if (expiresAt > 0 && expiresAt < now) {
       // Expired — clean up and return null
       this.destroy(sessionId);
       return null;
     }
 
     try {
-      return JSON.parse(row.data) as SessionData;
+      return JSON.parse(String(column(row, "data"))) as SessionData;
     } catch {
       return null;
     }
@@ -105,35 +379,51 @@ export class DatabaseSessionHandler implements SessionHandler {
     this.ensureTable();
 
     const json = JSON.stringify(data);
-    const expiresAt = (Date.now() / 1000) + (ttl > 0 ? ttl : 3600);
+    // A ttl of 0 (or less) means NEVER EXPIRES and is stored as the 0 that read()
+    // and gc() both guard out. It used to silently substitute 3600, so asking for
+    // a non-expiring session quietly got a one-hour one.
+    const expiresAt = ttl > 0 ? (Date.now() / 1000) + ttl : 0;
 
-    const existing = this.db
-      .prepare("SELECT 1 FROM tina4_session WHERE session_id = ?")
-      .get(sessionId);
+    // SELECT-then-UPDATE-or-INSERT, matching the Python master. Deliberately NOT
+    // an upsert: ON CONFLICT / ON DUPLICATE KEY / MERGE are spelled differently
+    // on all five engines, and this shape needs no dialect at all.
+    const existing = this.query(
+      "SELECT session_id FROM tina4_session WHERE session_id = ?",
+      [sessionId],
+    );
 
-    if (existing) {
-      this.db
-        .prepare("UPDATE tina4_session SET data = ?, expires_at = ? WHERE session_id = ?")
-        .run(json, expiresAt, sessionId);
+    if (existing.length > 0) {
+      this.exec(
+        "UPDATE tina4_session SET data = ?, expires_at = ? WHERE session_id = ?",
+        [json, expiresAt, sessionId],
+      );
     } else {
-      this.db
-        .prepare("INSERT INTO tina4_session (session_id, data, expires_at) VALUES (?, ?, ?)")
-        .run(sessionId, json, expiresAt);
+      this.exec(
+        "INSERT INTO tina4_session (session_id, data, expires_at) VALUES (?, ?, ?)",
+        [sessionId, json, expiresAt],
+      );
     }
   }
 
   destroy(sessionId: string): void {
     this.ensureTable();
-    this.db
-      .prepare("DELETE FROM tina4_session WHERE session_id = ?")
-      .run(sessionId);
+    this.exec("DELETE FROM tina4_session WHERE session_id = ?", [sessionId]);
   }
 
   gc(_maxLifetime: number): void {
     this.ensureTable();
     const now = Date.now() / 1000;
-    this.db
-      .prepare("DELETE FROM tina4_session WHERE expires_at > 0 AND expires_at < ?")
-      .run(now);
+    this.exec("DELETE FROM tina4_session WHERE expires_at > 0 AND expires_at < ?", [now]);
   }
 }
+
+/**
+ * The scheme of a connection URL, for an error message.
+ *
+ * Only the scheme, never the URL: a connection string may carry a password, and
+ * an exception message ends up in the boot log, the crash report and CI output.
+ */
+function schemeOf(url: string): string {
+  const match = url.match(/^([a-zA-Z][a-zA-Z0-9+.-]*):/);
+  return match ? match[1].toLowerCase() : "unknown";
+}

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

@@ -0,0 +1,181 @@
+/**
+ * Tina4 Memcached Session Handler — zero-dependency text protocol over TCP.
+ *
+ * Memcached was already one of the seven CACHE backends in all four frameworks
+ * but was NOT a session backend in any of them, even though it is the classic
+ * PHP session store. This closes that gap.
+ *
+ * The SessionHandler interface is synchronous and node:net is async-only, so
+ * commands go through the shared persistent-connection transport (syncSocket) —
+ * one long-lived socket behind a worker thread, the same transport the
+ * Redis/Valkey handlers use. Memcached keeps the connection open after a reply
+ * and its text protocol carries no length prefix, so the reply is complete when
+ * one of the caller's terminators appears.
+ *
+ * BACKEND-FAILURE POLICY. A genuine key miss returns `null` silently (no session
+ * yet is normal). A TRANSPORT failure — server unreachable, connection dropped
+ * mid-reply, a protocol error — THROWS, so the Session layer can log-loud and
+ * degrade. Collapsing the two is how a dead cache silently logs every user out.
+ *
+ * Memcached has no persistence and no replication: a restart drops every
+ * session. That is a deliberate trade (it is a cache), and it is why
+ * file/database remain the defaults.
+ *
+ * Configure via environment variables:
+ *   TINA4_SESSION_MEMCACHED_HOST   (default: "127.0.0.1")
+ *   TINA4_SESSION_MEMCACHED_PORT   (default: 11211)
+ *   TINA4_SESSION_MEMCACHED_PREFIX (default: "tina4:session:")
+ *   TINA4_SESSION_TTL              (default: 3600)
+ */
+import { createHash } from "node:crypto";
+import type { SessionHandler } from "../session.js";
+import { syncTextCommand } from "./syncSocket.js";
+
+interface SessionData {
+  _created: number;
+  _accessed: number;
+  [key: string]: unknown;
+}
+
+export interface MemcachedSessionConfig {
+  host?: string;
+  port?: number;
+  prefix?: string;
+  ttl?: number;
+  // Unified SessionConfig fields are tolerated (and ignored) so the central
+  // Session can forward its config object without a structural mismatch.
+  backend?: string;
+  path?: string;
+}
+
+/**
+ * Memcached rejects a key over 250 bytes or containing a space/control
+ * character. A key that could break either rule is HASHED rather than
+ * truncated — truncating would let two different sessions collide on one key,
+ * handing one user another user's session.
+ */
+const MAX_KEY_BYTES = 250;
+
+/**
+ * memcached's exptime field changes meaning at 30 days: at or below this it is
+ * RELATIVE seconds, above it the server reads an ABSOLUTE UNIX TIMESTAMP.
+ * See MemcachedSessionHandler.expTime for why we convert instead of clamping.
+ */
+const MAX_RELATIVE_EXPTIME = 2592000;
+
+export class MemcachedSessionHandler implements SessionHandler {
+  private host: string;
+  private port: number;
+  private prefix: string;
+  private ttl: number;
+
+  constructor(config?: MemcachedSessionConfig) {
+    this.host = config?.host ?? process.env.TINA4_SESSION_MEMCACHED_HOST ?? "127.0.0.1";
+    this.port =
+      config?.port ??
+      (process.env.TINA4_SESSION_MEMCACHED_PORT
+        ? parseInt(process.env.TINA4_SESSION_MEMCACHED_PORT, 10)
+        : 11211);
+    this.prefix = config?.prefix ?? process.env.TINA4_SESSION_MEMCACHED_PREFIX ?? "tina4:session:";
+    this.ttl =
+      config?.ttl ??
+      (process.env.TINA4_SESSION_TTL ? parseInt(process.env.TINA4_SESSION_TTL, 10) : 3600);
+  }
+
+  private key(sessionId: string): string {
+    const candidate = `${this.prefix}${sessionId}`;
+    if (Buffer.byteLength(candidate) > MAX_KEY_BYTES || /[\x00-\x20\x7f]/.test(candidate)) {
+      return `${this.prefix}${createHash("sha256").update(sessionId).digest("hex")}`;
+    }
+    return candidate;
+  }
+
+  /**
+   * Run one memcached command synchronously and return the raw reply.
+   *
+   * Delegates to the shared persistent-connection transport (syncSocket) rather
+   * than spawning a child per command: that cost a process spawn plus a fresh
+   * TCP connection every time (p50 41ms, p99 487ms) and its tail tripped the
+   * deadline under load — the same defect that made the Valkey session tests
+   * flaky, which this handler inherited on the day it was written.
+   *
+   * @throws Error on any transport failure — never swallowed to an empty
+   *         result, because for a session an outage must be distinguishable
+   *         from "no session yet".
+   */
+  private command(payload: string, terminators: string[]): string {
+    return syncTextCommand(
+      { host: this.host, port: this.port },
+      payload,
+      terminators,
+      "Memcached",
+    );
+  }
+
+  read(sessionId: string): SessionData | null {
+    const resp = this.command(`get ${this.key(sessionId)}\r\n`, ["END\r\n"]);
+    if (!resp.startsWith("VALUE")) return null;   // genuine miss — NOT an error
+
+    const split = resp.indexOf("\r\n");
+    if (split === -1) return null;
+    const header = resp.slice(0, split).split(" ");
+    const bytes = parseInt(header[3] ?? "0", 10);
+    const body = Buffer.from(resp.slice(split + 2), "utf-8").subarray(0, bytes).toString("utf-8");
+    try {
+      return JSON.parse(body) as SessionData;
+    } catch {
+      // A corrupt value is treated as no session rather than crashing the
+      // request; the next write replaces it.
+      return null;
+    }
+  }
+
+  /**
+   * Convert a ttl in SECONDS to memcached's dual-meaning exptime field.
+   *
+   * memcached documents exptime as RELATIVE seconds up to 2592000 (30 days),
+   * and as an ABSOLUTE UNIX TIMESTAMP for anything larger. Sending a raw ttl of
+   * 2592001 therefore does not mean "30 days and one second" - it means
+   * 1970-01-31, which is already past, so the item expires the instant it is
+   * stored. memcached still replies STORED, so the write looks successful and
+   * the very next read is a miss: a silent logout on every request.
+   *
+   * Measured against real memcached 1.6.45: ttl=2592000 survives, ttl=2592001
+   * vanishes instantly.
+   *
+   * We CONVERT rather than CLAMP. Clamping a 60-day session down to 30 days
+   * would silently shorten a lifetime the operator explicitly asked to be
+   * longer, which is the same class of lie in the other direction.
+   */
+  private expTime(ttl: number): number {
+    return ttl > MAX_RELATIVE_EXPTIME ? Math.floor(Date.now() / 1000) + ttl : ttl;
+  }
+
+  write(sessionId: string, data: SessionData, ttl: number): void {
+    const effectiveTtl = this.expTime(ttl > 0 ? ttl : this.ttl);
+    const json = JSON.stringify(data);
+    const bytes = Buffer.byteLength(json);
+    const cmd = `set ${this.key(sessionId)} 0 ${effectiveTtl} ${bytes}\r\n`;
+    const resp = this.command(`${cmd}${json}\r\n`, [
+      "STORED\r\n",
+      "ERROR\r\n",
+      "SERVER_ERROR",
+      "CLIENT_ERROR",
+    ]);
+    if (!resp.startsWith("STORED")) {
+      throw new Error(`Memcached did not store the session: ${resp.slice(0, 80)}`);
+    }
+  }
+
+  destroy(sessionId: string): void {
+    // A session that was already gone is not an error.
+    this.command(`delete ${this.key(sessionId)}\r\n`, [
+      "DELETED\r\n",
+      "NOT_FOUND\r\n",
+      "ERROR\r\n",
+    ]);
+  }
+
+  /** No-op — memcached expires its own keys via the TTL set on write. */
+  gc(_maxLifetime: number): void {}
+}