tina4-nodejs 3.13.94 → 3.13.95

package/types/core/src/sessionHandlers/databaseHandler.d.ts

@@ -5,7 +5,7 @@ interface SessionData {
     [key: string]: unknown;
 }
 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;
     backend?: string;
     path?: string;
@@ -17,19 +17,74 @@ export interface DatabaseSessionConfig {
     redisDb?: number;
 }
 /**
- * Database session handler using node:sqlite (synchronous SQLite).
+ * 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 declare class DatabaseSessionHandler implements SessionHandler {
-    private db;
+    private sqliteHandle;
+    /** Set for SQLite. Null when this handler talks to a networked engine. */
+    private dbPath;
+    /** Set for a networked engine. Null for SQLite. */
+    private target;
     private initialized;
+    /**
+     * 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);
+    /** Open the SQLite database on FIRST USE, not at construction. */
+    private get sqlite();
+    private get 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;
+    private resolveTarget;
+    private unsupportedEngine;
+    /** Run a statement that returns rows. */
+    private query;
+    /** Run a statement that returns nothing. */
+    private exec;
     /**
      * Ensure the session table exists (called once on first use).
      */

package/types/core/src/sessionHandlers/memcachedHandler.d.ts

@@ -0,0 +1,60 @@
+import type { SessionHandler } from "../session.js";
+interface SessionData {
+    _created: number;
+    _accessed: number;
+    [key: string]: unknown;
+}
+export interface MemcachedSessionConfig {
+    host?: string;
+    port?: number;
+    prefix?: string;
+    ttl?: number;
+    backend?: string;
+    path?: string;
+}
+export declare class MemcachedSessionHandler implements SessionHandler {
+    private host;
+    private port;
+    private prefix;
+    private ttl;
+    constructor(config?: MemcachedSessionConfig);
+    private key;
+    /**
+     * 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;
+    read(sessionId: string): SessionData | 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;
+    write(sessionId: string, data: SessionData, ttl: number): void;
+    destroy(sessionId: string): void;
+    /** No-op — memcached expires its own keys via the TTL set on write. */
+    gc(_maxLifetime: number): void;
+}
+export {};

package/types/core/src/sessionHandlers/mongoClient.d.ts

@@ -4,21 +4,32 @@ export interface MongoTarget {
     database: string;
     collection: string;
 }
-/** Command args: `filter` (always), plus `data`/`last_accessed` for an update. */
+/**
+ * Command args: `filter` (always), plus `data`/`expires_at`/`last_accessed` for
+ * an update.
+ *
+ * `expires_at` is an ABSOLUTE epoch-seconds deadline computed at write time. It
+ * is what makes the session actually expire: this handler previously stored no
+ * expiry at all, created no TTL index, and never consulted anything on read, so
+ * MongoDB sessions lived forever.
+ */
 export interface MongoCommandArgs {
     filter: Record<string, unknown>;
     data?: unknown;
+    expires_at?: number;
     last_accessed?: number;
 }
 /**
- * Run a session Mongo command synchronously and return the raw child stdout.
+ * Run a session Mongo command synchronously.
  *
  * - command "find"   -> the matched document as a JSON string, or "__EMPTY__".
  * - command "update" -> "__OK__" (upsert of `{_id, data, last_accessed}`).
  * - command "delete" -> "__OK__".
  *
- * THROWS `<label> command failed: ...` on a transport failure (server unreachable,
- * timeout) OR a Mongo command error (`ok != 1`), so the Session boundary can
- * log-loud + degrade (or re-throw under strict mode).
+ * THROWS `<label> command failed: ...` on a transport failure (server
+ * unreachable, timeout) OR a Mongo command error (`ok != 1`), so the Session
+ * boundary can log-loud + degrade (or re-throw under strict mode). A genuine
+ * miss is NOT a failure and comes back as "__EMPTY__" — collapsing the two is
+ * how a dead backend silently logs every user out.
  */
 export declare function mongoCommandSync(target: MongoTarget, command: "find" | "update" | "delete", args: MongoCommandArgs, label?: string): string;

package/types/core/src/sessionHandlers/mongoHandler.d.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";
@@ -51,11 +51,59 @@ export declare class MongoSessionHandler implements SessionHandler {
     private password;
     private database;
     private collection;
+    private hostExplicit;
+    private portExplicit;
+    private uriExplicit;
     constructor(config?: MongoSessionConfig);
-    /** 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;
     read(sessionId: string): SessionData | null;
-    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): void;
     destroy(sessionId: string): void;
 }
 export {};

package/types/core/src/sessionHandlers/respClient.d.ts

@@ -16,7 +16,7 @@ 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 declare function respCommandSync(target: RespTarget, args: string[], label?: string): string;

package/types/core/src/sessionHandlers/sqlClient.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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 declare const SQL_SESSION_ENGINES: readonly ["sqlite", "postgres", "mysql", "mssql", "firebird"];
+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;
+}
+/**
+ * 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 declare function sqlCommandSync(target: SqlTarget, sql: string, params?: unknown[], label?: string): Record<string, unknown>[];

package/types/core/src/sessionHandlers/syncBridge.d.ts

@@ -0,0 +1,91 @@
+/**
+ * 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 declare const STATUS_OK = 0;
+/** A healthy server answered with an error (RESP `-ERR`, a Mongo command error). */
+export declare const STATUS_ERROR = 1;
+/** A genuine miss — no such key/document. NOT a failure. */
+export declare const STATUS_NIL = 2;
+/** The reply did not fit the shared buffer. */
+export declare const STATUS_TOO_LARGE = 3;
+/** Connection/socket/driver failure, as opposed to an answer from a healthy server. */
+export declare const STATUS_TRANSPORT = 4;
+export declare const IDX_SEQ = 0;
+export declare const IDX_LENGTH = 1;
+export declare const IDX_STATUS = 2;
+export declare const IDX_READY = 3;
+/**
+ * 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 declare const DATA_BYTES: number;
+/** How long a caller blocks before giving up on a reply. */
+export declare 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 declare 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 declare const WORKER_REPLY_HELPER = "\nconst __control = new Int32Array(workerData.controlBuffer);\nconst __data = new Uint8Array(workerData.dataBuffer);\nconst __encoder = new TextEncoder();\n\n// Announce readiness the moment this thread is executing. The parent blocks on\n// this before its first command, so a slow boot can never be mistaken for a\n// slow command. This is signalled by the worker's OWN bootstrap and needs no\n// message from the parent, so it is safe even while the parent is blocked.\nAtomics.store(__control, 3, 1);\nAtomics.notify(__control, 3);\n\nfunction __reply(status, payload) {\n  let length = 0;\n  if (payload !== undefined && payload !== null && status !== 2) {\n    const bytes = __encoder.encode(String(payload));\n    if (bytes.length > __data.length) {\n      Atomics.store(__control, 2, 3);\n      Atomics.store(__control, 1, 0);\n      Atomics.add(__control, 0, 1);\n      Atomics.notify(__control, 0);\n      return;\n    }\n    __data.set(bytes, 0);\n    length = bytes.length;\n  }\n  Atomics.store(__control, 2, status);\n  Atomics.store(__control, 1, length);\n  Atomics.add(__control, 0, 1);\n  Atomics.notify(__control, 0);\n}\n";
+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;
+}
+/**
+ * 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 declare function getBridge(key: string, workerSource: string, workerData: Record<string, unknown>): 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 declare function closeBridges(): void;

package/types/core/src/sessionHandlers/syncSocket.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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 { closeBridges, DATA_BYTES } 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;
+}
+/**
+ * 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 declare function syncCommand(target: SyncSocketTarget, args: string[], label?: string): string;
+/**
+ * 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 declare function syncTextCommand(target: SyncSocketTarget, payload: string, terminators: string[], label?: string): string;
+/** Re-exported so callers do not need to know the bridge exists. */
+export { closeBridges as closeSyncSockets, DATA_BYTES };

package/types/core/src/trustedProxy.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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.
+ */
+/** [packed network address, prefix bits] */
+type Network = [Uint8Array, number];
+/**
+ * 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 declare function packAddress(value: string): Uint8Array | null;
+/**
+ * The configured trusted-proxy networks, parsed once per distinct config value.
+ */
+export declare function trustedProxyNetworks(): Network[];
+/** Is this address a configured trusted proxy? */
+export declare function isTrustedProxy(address: string): boolean;
+/** Reset the parsed cache. Test hook - config normally changes only at boot. */
+export declare function resetTrustedProxyCache(): void;
+/**
+ * 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 declare function resolveClientIp(headers: Record<string, string | string[] | undefined>, peer: string): string;
+export {};

package/types/core/src/types.d.ts

@@ -42,10 +42,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;
@@ -179,8 +193,14 @@ export interface Tina4Config {
 }
 export type Middleware = (req: Tina4Request, res: Tina4Response, next: () => void) => 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
@@ -188,9 +208,12 @@ export type Middleware = (req: Tina4Request, res: Tina4Response, next: () => voi
  *
  * 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.
  * connection — object with send/broadcast/close methods and route params.

package/types/core/src/websocket.d.ts

@@ -58,6 +58,13 @@ export interface WebSocketClient {
 /**
  * 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 declare function buildCloseFrame(code: number, reason?: string): Buffer;
 export declare function computeAcceptKey(key: string): string;
 /**
  * Return true if the upgrade request's `Origin` is permitted.
@@ -293,6 +300,18 @@ declare class WsRouteManager {
     get size(): number;
     add(state: RouteConnState): void;
     remove(id: string): void;
+    /**
+     * 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, reason?: string): number;
     /** Send a text frame to one connection (best-effort). */
     sendTo(id: string, message: string): void;
     /** Broadcast a text frame to every connection on the same path. */
@@ -355,6 +374,13 @@ declare class DevReloadWsManager {
     setTracker(onAdd: (remoteAddress: string, path: string) => string, onRemove: (id: string) => void): void;
     /** Number of currently-open dev-reload sockets (test/diagnostic helper). */
     get size(): number;
+    /**
+     * 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, reason?: string): number;
     /**
      * Accept a WebSocket upgrade on `/__dev_reload` and hold the socket open.
      *