tina4-nodejs 3.13.94 → 3.13.95

package/packages/orm/src/cachedDatabase.ts

@@ -94,8 +94,23 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
   private backendPromise: Promise<CacheBackend | null> | null = null;
   private backendName: string;
 
+  /**
+   * WHICH DATABASE this wrapper caches for, folded into every cache key.
+   * Empty only for an adapter built outside the URL/config funnels, which then
+   * behaves exactly as before rather than colliding with a tagged one.
+   *
+   * Optional-chained on the ADAPTER, not just the property. `setAdapter(null)`
+   * is the documented reset idiom (migrateCli.test.ts uses it to clear ORM
+   * state between cases) and it reaches here through wrapWithCache. Before the
+   * identity field existed the constructor only STORED the adapter, so a null
+   * passed through harmlessly; reading `adapter.cacheIdentity` turned that
+   * reset into "Cannot read properties of null".
+   */
+  private readonly identity: string;
+
   constructor(adapter: DatabaseAdapter, options: CachedAdapterOptions = {}) {
     this.adapter = adapter;
+    this.identity = adapter?.cacheIdentity ?? "";
     this.cachePersistent = options.persistent ?? isTruthy(process.env.TINA4_DB_CACHE);
     // Request-scoped cache defaults to OFF (opt-in). A request-scoped cache
     // defaulting ON is a footgun: a `SELECT MAX(id)` (or generator read) right
@@ -312,7 +327,7 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
     // where every ORM read flows through the cached db.fetch(). Same store, same
     // counters, flushed on writes.
     if (this.enabled) {
-      const key = QueryCache.queryKey(sql + ":Q", params as unknown[] | undefined);
+      const key = QueryCache.queryKey(sql + ":Q", params as unknown[] | undefined, this.identity);
       const cached = this.cache.get<T[]>(key);
       if (cached !== undefined) {
         this.hits++;
@@ -332,7 +347,7 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
     // master's `no_cache`). Counters are left untouched so a bypass read isn't
     // misreported as a hit or a miss.
     if (this.enabled && !noCache) {
-      const key = QueryCache.queryKey(sql + `:L${limit}:S${skip}`, params as unknown[] | undefined);
+      const key = QueryCache.queryKey(sql + `:L${limit}:S${skip}`, params as unknown[] | undefined, this.identity);
       const cached = this.cache.get<T[]>(key);
       if (cached !== undefined) {
         this.hits++;
@@ -348,7 +363,7 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
 
   fetchOne<T = Record<string, unknown>>(sql: string, params?: unknown[], noCache?: boolean): T | null {
     if (this.enabled && !noCache) {
-      const key = QueryCache.queryKey(sql + ":ONE", params as unknown[] | undefined);
+      const key = QueryCache.queryKey(sql + ":ONE", params as unknown[] | undefined, this.identity);
       const cached = this.cache.get<T | null>(key);
       if (cached !== undefined) {
         this.hits++;
@@ -367,14 +382,20 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
     return this.adapter.insert(table, data);
   }
 
-  update(table: string, data: Record<string, unknown>, filter: Record<string, unknown>): DatabaseResult {
+  // `params` MUST be forwarded. This wrapper sits in front of EVERY adapter, so
+  // dropping it silently unbinds a string filter: `delete(t, "id = ?", [2])`
+  // reached the adapter as `delete(t, "id = ?")`, ran `DELETE ... WHERE id = ?`
+  // with nothing bound, matched no row, and returned
+  // { success: true, affectedRows: 0 } — a silent no-op on a documented calling
+  // form, caught by the shared write-path contract.
+  update(table: string, data: Record<string, unknown>, filter: Record<string, unknown> | string, params?: unknown[]): DatabaseResult {
     if (this.enabled) this.invalidate();
-    return this.adapter.update(table, data, filter);
+    return this.adapter.update(table, data, filter, params);
   }
 
-  delete(table: string, filter: Record<string, unknown> | string | Record<string, unknown>[]): DatabaseResult {
+  delete(table: string, filter: Record<string, unknown> | string | Record<string, unknown>[], params?: unknown[]): DatabaseResult {
     if (this.enabled) this.invalidate();
-    return this.adapter.delete(table, filter);
+    return this.adapter.delete(table, filter, params);
   }
 
   startTransaction(): void {
@@ -389,12 +410,12 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
     this.adapter.rollback();
   }
 
-  tables(): string[] {
-    return this.adapter.tables();
+  getTables(): string[] {
+    return this.adapter.getTables();
   }
 
-  columns(table: string): ColumnInfo[] {
-    return this.adapter.columns(table);
+  getColumns(table: string): ColumnInfo[] {
+    return this.adapter.getColumns(table);
   }
 
   lastInsertId(): number | bigint | string | null {
@@ -437,7 +458,7 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
     // `noCache` bypasses both cache layers for this one call — no lookup, no
     // store, run directly (mirrors the Python master's `no_cache`).
     if (this.enabled && !noCache) {
-      const key = QueryCache.queryKey(sql + `:L${limit}:S${skip}`, params as unknown[] | undefined);
+      const key = QueryCache.queryKey(sql + `:L${limit}:S${skip}`, params as unknown[] | undefined, this.identity);
       // Persistent distributed backend is AUTHORITATIVE (mirrors Python, where a
       // configured _cache_backend bypasses the in-process dict). This keeps
       // cross-instance write-invalidation deterministic: a write clears the
@@ -469,7 +490,7 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
       : this.adapter.fetchOne<T>(sql, params);
     // `noCache` bypasses both cache layers for this one call (see fetchAsync).
     if (this.enabled && !noCache) {
-      const key = QueryCache.queryKey(sql + ":ONE", params as unknown[] | undefined);
+      const key = QueryCache.queryKey(sql + ":ONE", params as unknown[] | undefined, this.identity);
       if (this.usesPersistentBackend()) {
         const shared = await this.backendGetOne<T>(key);
         if (shared !== undefined) { this.hits++; return shared.row; }
@@ -496,7 +517,7 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
       ? await (this.adapter as any).queryAsync(sql, params)
       : this.adapter.query<T>(sql, params);
     if (this.enabled) {
-      const key = QueryCache.queryKey(sql + ":Q", params as unknown[] | undefined);
+      const key = QueryCache.queryKey(sql + ":Q", params as unknown[] | undefined, this.identity);
       if (this.usesPersistentBackend()) {
         const shared = await this.backendGetRows<T>(key);
         if (shared !== undefined) { this.hits++; return shared; }
@@ -532,18 +553,21 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
       : this.adapter.insert(table, data);
   }
 
-  async updateAsync(table: string, data: Record<string, unknown>, filter: Record<string, unknown>, params?: unknown[]): Promise<DatabaseResult> {
+  // The SYNC fallback must forward `params` too. An adapter without an async
+  // variant (sqlite) took this branch, so a string filter arrived unbound — the
+  // same silent no-op as above, on the default engine.
+  async updateAsync(table: string, data: Record<string, unknown>, filter: Record<string, unknown> | string, params?: unknown[]): Promise<DatabaseResult> {
     if (this.enabled) await this.invalidateAsync();
     return (this.adapter as any).updateAsync
       ? await (this.adapter as any).updateAsync(table, data, filter, params)
-      : this.adapter.update(table, data, filter);
+      : this.adapter.update(table, data, filter, params);
   }
 
   async deleteAsync(table: string, filter: Record<string, unknown> | string | Record<string, unknown>[], params?: unknown[]): Promise<DatabaseResult> {
     if (this.enabled) await this.invalidateAsync();
     return (this.adapter as any).deleteAsync
       ? await (this.adapter as any).deleteAsync(table, filter, params)
-      : this.adapter.delete(table, filter as Record<string, unknown>);
+      : this.adapter.delete(table, filter, params);
   }
 
   async startTransactionAsync(): Promise<void> {
@@ -570,13 +594,13 @@ export class CachedDatabaseAdapter implements DatabaseAdapter {
   async tablesAsync(): Promise<string[]> {
     return (this.adapter as any).tablesAsync
       ? await (this.adapter as any).tablesAsync()
-      : this.adapter.tables();
+      : this.adapter.getTables();
   }
 
   async columnsAsync(table: string): Promise<ColumnInfo[]> {
     return (this.adapter as any).columnsAsync
       ? await (this.adapter as any).columnsAsync(table)
-      : this.adapter.columns(table);
+      : this.adapter.getColumns(table);
   }
 
   async createTableAsync(name: string, columns: Record<string, FieldDefinition>): Promise<void> {

package/packages/orm/src/connectTimeout.ts

@@ -0,0 +1,265 @@
+/**
+ * TINA4_DATABASE_CONNECT_TIMEOUT - bound a database connect attempt.
+ *
+ * THE DEFECT, measured 2026-08-06. The Firebird adapter awaited `fb.attach()` in
+ * a bare promise with no timeout, so a driver that never calls back hung the app
+ * on connect with no log, no error and no signal. A probe reproduced exactly
+ * that against a socket that accepts and never replies: 16 minutes at 0.0% CPU,
+ * a process that looked alive to every health check and served nothing.
+ *
+ * THE SHARED CONTRACT, identical in all four frameworks:
+ *
+ *     name:      TINA4_DATABASE_CONNECT_TIMEOUT
+ *     unit:      SECONDS
+ *     default:   10
+ *     <= 0:      disables the bound (unbounded, the old behaviour)
+ *     garbage:   warn and use 10
+ *     on expiry: throw an error naming the host, the port, the elapsed seconds,
+ *                and the variable that tunes it
+ *
+ * TWO LAYERS, because one is not enough:
+ *
+ *   1. The driver's own knob where it has one (`connectionTimeoutMillis` on pg,
+ *      `connectTimeout` on mysql2 and tedious, `serverSelectionTimeoutMS` on the
+ *      Mongo driver). Without this the variable would be a lie on those
+ *      adapters: tedious defaults to 15s and Mongo to 30s, so a configured 60s
+ *      would still fail early with the driver's message rather than ours.
+ *   2. `withConnectTimeout()` around the whole attempt. Without this the bound
+ *      would not exist at all where the driver has no knob - node-firebird, the
+ *      measured case - and a driver knob covers only the phase the driver
+ *      thinks it covers, never the whole handshake.
+ *
+ * THE DRIVER'S TIMER IS MEANT TO WIN, and `withConnectTimeout` TRANSLATES what
+ * it raises rather than racing it. Node shipped the other shape first: the knob
+ * was set to the bound PLUS a 1000ms grace so an outer timer expired first and
+ * Node's own message surfaced. Python, PHP and Ruby all landed on the translator
+ * instead, leaving Node the lone outlier of four, for three reasons this file
+ * now accepts:
+ *
+ *   - it inflates the operator's configured N into N + grace, so
+ *     TINA4_DATABASE_CONNECT_TIMEOUT=10 silently means 11 to the driver;
+ *   - it throws away the driver's own diagnosis, which is frequently the more
+ *     specific one ("connection to server at 127.0.0.1, port 5432 failed:
+ *     timeout expired" says more than a bare bound expiring);
+ *   - where a watchdog is involved it abandons work the driver could have
+ *     unwound itself.
+ *
+ * So the knob is set to the bound EXACTLY (rounded up, never to 0), our clock
+ * starts BEFORE the driver arms its own, and a driver failure that took at least
+ * that long is re-thrown in the framework's words with the driver's error kept
+ * as `cause`. N means N. The outer timer stays as the BACKSTOP for the phases a
+ * knob does not cover and the adapters that have no knob at all; because it is
+ * armed after the driver's, it only ever fires when the driver's did not.
+ *
+ * DISABLED (<= 0) MEANS THE OLD BEHAVIOUR, exactly. Neither layer is applied,
+ * so each driver keeps whatever it did before this existed.
+ */
+import { Log } from "../../core/src/index.js";
+
+/** Seconds. Long enough for a cold cross-region connect, short enough to page. */
+export const DEFAULT_DATABASE_CONNECT_TIMEOUT_SECONDS = 10;
+
+/**
+ * Resolve the connect budget in MILLISECONDS, or `null` when the bound is
+ * disabled.
+ *
+ * Milliseconds because every consumer needs them: `setTimeout` and all four
+ * driver knobs are in ms. Seconds are the operator-facing unit, so the variable
+ * is read as seconds and converted once, here.
+ *
+ * Call this ONCE per connect and pass the result down - it is the only resolver,
+ * so calling it twice would warn twice about one typo.
+ */
+export function connectTimeoutMillis(): number | null {
+  const raw = process.env.TINA4_DATABASE_CONNECT_TIMEOUT;
+  if (raw === undefined || raw.trim() === "") {
+    return DEFAULT_DATABASE_CONNECT_TIMEOUT_SECONDS * 1000;
+  }
+  const seconds = Number(raw);
+  if (!Number.isFinite(seconds)) {
+    Log.warning(
+      `TINA4_DATABASE_CONNECT_TIMEOUT="${raw}" is not a valid number of seconds - `
+      + `using ${DEFAULT_DATABASE_CONNECT_TIMEOUT_SECONDS}`,
+    );
+    return DEFAULT_DATABASE_CONNECT_TIMEOUT_SECONDS * 1000;
+  }
+  // <= 0 is a deliberate opt-out, not a typo: unbounded, the old behaviour.
+  return seconds <= 0 ? null : seconds * 1000;
+}
+
+/**
+ * Clock slack when deciding whether a failed connect was OUR bound expiring.
+ *
+ * THE DECISION IS MADE BY ELAPSED TIME, NEVER BY MATCHING THE DRIVER'S TEXT.
+ * The four clients word an expiry four different ways - pg `timeout expired`,
+ * mysql2 `connect ETIMEDOUT`, tedious `Failed to connect to ... in 2000ms`,
+ * Mongo `Server selection timed out after 2000 ms` - and a marker table would
+ * drift the moment any of them reworded, then MISS. A missed timeout is the
+ * whole defect this file exists to prevent, so nothing here reads the message.
+ *
+ * WHY 50ms, AND WHY NOT ZERO. Python and PHP use no tolerance at all, PHP having
+ * measured its four C clients OVERSHOOTING their deadline by ~3ms at a 3s bound -
+ * a client that measures its own elapsed time can never report early. Node's
+ * knobs are not those: all four are plain JS `setTimeout` calls (pg `client.js`,
+ * mysql2 `base/connection.js`, tedious `connection.js`, and the Mongo driver's
+ * selection loop), and libuv's loop time is coarse, so a Node timer CAN fire
+ * before `performance.now()` agrees the budget has passed. MEASURED, 60 rounds
+ * at a 200ms budget:
+ *
+ *     Linux  x64,   Node v24.18.0   earliest -0.7125ms   (fires EARLY)
+ *     darwin arm64, Node v24.9.0    earliest +0.0872ms   (never early)
+ *
+ * Zero would therefore be a real miss on Linux. 50ms is a ~70x margin on the
+ * measured worst case, and still 0.5% of the 10s default. Ruby's 250ms is for a
+ * different problem - libpq's `connect_timeout` is INTEGER SECONDS and reads a
+ * 10s bound back as 9.998s - which no Node client has.
+ *
+ * It does NOT inflate the operator's N: it only widens what COUNTS as the bound
+ * expiring, never how long anything waits. It errs deliberately: over-translating
+ * a genuine fast failure that lands within 50ms of the bound still shows the
+ * operator the driver's real error (`Driver reported:`, plus `cause`), whereas
+ * under-translating hands them a bare driver message naming no variable.
+ */
+export const CONNECT_TIMEOUT_TOLERANCE_MS = 50;
+
+/**
+ * The value for a driver's own connect-timeout option, from the Tina4 budget.
+ * `null` in, `null` out - a disabled bound sets no driver option at all.
+ *
+ * ROUNDED UP, AND NEVER TO 0. Up, so the driver's timer can never expire before
+ * our clock has reached the bound - that ordering is the whole basis for the
+ * elapsed-time test in `withConnectTimeout`, and rounding down would break it.
+ * Never 0, because three of the four knobs read 0 as WAIT FOREVER: pg does
+ * `connectionTimeoutMillis || 0` then `if (> 0)`, mysql2 does
+ * `if (this.config.connectTimeout)`, and libpq (the same trap Python and Ruby
+ * name) treats `connect_timeout=0` as no limit. A sub-millisecond bound must
+ * therefore floor at 1ms rather than silently disabling the bound being set.
+ */
+export function driverConnectTimeoutMillis(budgetMs: number | null): number | null {
+  return budgetMs === null ? null : Math.max(1, Math.ceil(budgetMs));
+}
+
+/**
+ * Best-effort host/port for the DIAGNOSTIC, from either a config object or a
+ * connection URL. Never used to connect - the adapter has already done that with
+ * its own parsing, and this must not become a second, divergent parser that
+ * decides where anything dials.
+ */
+export function connectTarget(
+  config: { host?: string; port?: number } | string,
+  defaultPort: number,
+): { host: string; port: number | string } {
+  if (typeof config === "string") {
+    try {
+      const url = new URL(config);
+      return { host: url.hostname || "localhost", port: url.port ? Number(url.port) : defaultPort };
+    } catch {
+      return { host: "localhost", port: defaultPort };
+    }
+  }
+  return { host: config.host ?? "localhost", port: config.port ?? defaultPort };
+}
+
+/**
+ * The ONE error a timed-out connect carries: it names the host, the port, the
+ * seconds actually spent, and the variable that tunes it - the four things an
+ * operator needs to tell "my bound fired" apart from "the database rejected me",
+ * which no driver's own timeout message provides.
+ *
+ * The driver's diagnosis is kept BOTH ways: appended to the text, because that
+ * is the line that reaches a log, and as `cause`, matching Python's `__cause__`
+ * and Ruby's cause chain. Its whitespace is flattened first - pg's is
+ * multi-line, and a log line that wraps is a log line that gets grepped wrong.
+ */
+function connectTimedOutError(
+  host: string,
+  port: number | string,
+  elapsedMs: number,
+  budgetMs: number,
+  cause?: unknown,
+): Error {
+  const reported = cause instanceof Error ? cause.message : cause === undefined ? "" : String(cause);
+  const detail = reported ? ` Driver reported: ${reported.replace(/\s+/g, " ").trim()}` : "";
+  return new Error(
+    `Database connect to ${host}:${port} timed out after ${(elapsedMs / 1000).toFixed(1)}s `
+    + `(TINA4_DATABASE_CONNECT_TIMEOUT=${budgetMs / 1000} seconds; set it to 0 to wait `
+    + `indefinitely).${detail}`,
+    cause === undefined ? undefined : { cause },
+  );
+}
+
+/**
+ * Bound a driver connect, and name the bound when it expires.
+ *
+ * @param attempt   a THUNK that starts the driver's connect. It is a thunk, not a
+ *                  promise, so OUR CLOCK STARTS FIRST - everything that touches
+ *                  the driver must run inside it. That ordering is load-bearing:
+ *                  the driver arms its own timer somewhere in here (mysql2 arms
+ *                  its at the END OF ITS CONSTRUCTOR, not in `connect()`), and
+ *                  only by starting first can we know that the driver's timer
+ *                  cannot expire before `elapsed` has reached the bound.
+ * @param budgetMs  from `connectTimeoutMillis()`; `null` runs `attempt` untouched
+ * @param host      named in the error - an operator needs to know WHICH server hung
+ * @param port      named in the error alongside the host
+ * @param abandon   called if the driver answers AFTER we gave up, with whatever it
+ *                  produced. Nobody will ever use that connection, so the adapter
+ *                  closes it here rather than leaking a socket for the life of the
+ *                  process - a connect that is retried every 10s would otherwise
+ *                  accumulate one abandoned connection per attempt, forever.
+ *
+ * TWO WAYS OUT, both wearing the same message. Normally the DRIVER's timer fires
+ * first (it was armed first) and we TRANSLATE its failure; where the driver has
+ * no knob, or its knob did not cover the phase that hung, our own timer fires as
+ * the backstop and there is no driver diagnosis to report.
+ */
+export function withConnectTimeout<T>(
+  attempt: () => Promise<T>,
+  budgetMs: number | null,
+  host: string,
+  port: number | string,
+  abandon?: (arrived: T) => void,
+): Promise<T> {
+  // performance.now() is MONOTONIC. Date.now() is not: an NTP step backwards
+  // mid-connect would shrink `elapsed`, the test below would read a real timeout
+  // as an ordinary failure, and the bare driver message would surface - the exact
+  // defect. Python uses time.monotonic() and Ruby CLOCK_MONOTONIC for this.
+  const startedAt = performance.now();
+  const elapsedMs = (): number => performance.now() - startedAt;
+
+  // Unbounded: no clock, no knob, no wrapper - exactly the old behaviour.
+  if (budgetMs === null) return attempt();
+
+  const started = attempt();
+
+  return new Promise<T>((resolve, reject) => {
+    let expired = false;
+
+    const timer = setTimeout(() => {
+      expired = true;
+      reject(connectTimedOutError(host, port, elapsedMs(), budgetMs));
+    }, budgetMs);
+
+    started.then(
+      (arrived) => {
+        clearTimeout(timer);
+        if (expired) abandon?.(arrived);
+        else resolve(arrived);
+      },
+      (failure: unknown) => {
+        clearTimeout(timer);
+        // Already rejected with the timeout; the driver's late error has no
+        // caller left to reach. Attaching this handler is what keeps it from
+        // surfacing as an unhandled rejection.
+        if (expired) return;
+        const elapsed = elapsedMs();
+        // Faster than the bound is a REAL error - a refused connection, bad
+        // credentials, an unknown database - and is re-thrown untouched.
+        reject(
+          elapsed < budgetMs - CONNECT_TIMEOUT_TOLERANCE_MS
+            ? failure
+            : connectTimedOutError(host, port, elapsed, budgetMs, failure),
+        );
+      },
+    );
+  });
+}