turbine-orm 0.60.1 → 0.62.0

package/dist/client.js

@@ -23,11 +23,11 @@
  */
 import pg from 'pg';
 import { postgresDialect } from './dialect.js';
-import { setErrorMessageMode, TimeoutError, UnsupportedFeatureError, ValidationError, wrapPgError, } from './errors.js';
+import { ConnectionError, setErrorMessageMode, TimeoutError, UnsupportedFeatureError, ValidationError, wrapPgError, } from './errors.js';
 import { ObserveEngine } from './observe.js';
 import { executePipeline, pipelineSupported } from './pipeline.js';
 import { QueryInterface, } from './query/index.js';
-import { markTurbineParser, quoteIdent, registerUtcTemporalParsers, suggestKey, warnParserOverwrite, } from './query/utils.js';
+import { markTurbineParser, ownLookup, quoteIdent, registerUtcTemporalParsers, suggestKey, warnParserOverwrite, } from './query/utils.js';
 import { shouldWarnOnce, WARN_NS } from './query/warn-registry.js';
 import { createSubscription, validateChannel, } from './realtime.js';
 import { buildTypedSql, TypedSqlQuery } from './typed-sql.js';
@@ -186,13 +186,215 @@ function warnUnknownConfigKeys(config) {
         // must never be the reason a client fails to construct.
     }
 }
-/** Maps isolation level names to SQL */
-const ISOLATION_LEVELS = {
+/**
+ * Two bases that differ ONLY in host, used to detect whether the host pg ends
+ * up with came from the connection string or from pg's own placeholder base.
+ *
+ * pg-connection-string resolves a connection string as `new URL(str,
+ * 'postgres://base')`. A string with no scheme is therefore a RELATIVE url, and
+ * silently inherits the literal host `base`, which is where
+ * `getaddrinfo ENOTFOUND base` comes from. Parsing against two different bases
+ * and comparing the resulting hostnames identifies that case exactly, and
+ * cannot be fooled by a string that genuinely names a host called `base`.
+ */
+const CONNECTION_STRING_PROBE_BASES = ['postgres://turbine-probe-a', 'postgres://turbine-probe-b'];
+/**
+ * Classify a connection string by replaying the parse pg itself performs.
+ *
+ * This is a deliberate mirror of `pg-connection-string`'s `parse()`, in the
+ * same order, because that function IS the oracle: anything it resolves to a
+ * real host/socket is a string pg will connect with, and a validator that
+ * refuses one of those breaks a working deployment. In particular all of these
+ * are usable and must pass:
+ *   - `/var/run/postgresql app` and `/cloudsql/proj:region:instance`, the
+ *     leading-slash unix-socket form (peer auth, Cloud SQL),
+ *   - `socket:/var/run/postgresql?db=app`, the explicit socket scheme,
+ *   - `postgresql:///db`, `postgres:/db`, `postgres://`, all empty-host forms
+ *     that fall back to pg's localhost default,
+ *   - `postgres://user:pw@/db` (the `@/` dummy-host retry) and
+ *     `?host=/var/run/postgresql` (host as a query parameter),
+ *   - anything else that parses as an absolute URL, `localhost:5432` included.
+ *
+ * Only two shapes are not usable: a string with no scheme (pg substitutes its
+ * placeholder host) and a string neither parse attempt can turn into a URL (pg
+ * throws `Invalid URL` from its own constructor).
+ */
+function classifyConnectionString(value) {
+    // Leading slash: pg short-circuits to `{ host: <path>, database: <word 2> }`
+    // before any URL parsing. Unix-domain socket directory or Cloud SQL path.
+    if (value.charAt(0) === '/')
+        return { kind: 'usable' };
+    // pg percent-encodes before parsing, so a string with spaces (or a stray
+    // half-written escape) reaches the URL constructor already encoded.
+    const encoded = / |%[^a-f0-9]|%[a-f0-9][^a-f0-9]/i.test(value)
+        ? encodeURI(value).replace(/%25(\d\d)/g, '%$1')
+        : value;
+    const parseAgainst = (base) => {
+        try {
+            return { url: new URL(encoded, base), dummyHost: false };
+        }
+        catch {
+            // pg's own second attempt: `postgres://user:pw@/db` is not a valid URL,
+            // so it retries with a placeholder authority and treats the host as empty.
+            try {
+                return { url: new URL(encoded.replace('@/', '@___DUMMY___/'), base), dummyHost: true };
+            }
+            catch {
+                return null;
+            }
+        }
+    };
+    const a = parseAgainst(CONNECTION_STRING_PROBE_BASES[0]);
+    const b = parseAgainst(CONNECTION_STRING_PROBE_BASES[1]);
+    if (!a || !b)
+        return { kind: 'unparseable' };
+    // `socket:` is handled by its own branch in pg's parse: the pathname is the
+    // socket directory and the base never contributes.
+    if (a.url.protocol === 'socket:')
+        return { kind: 'usable' };
+    // The dummy-host retry only happens for an absolute URL, so the host is
+    // empty by construction and pg falls back to its localhost default.
+    if (a.dummyHost)
+        return { kind: 'usable' };
+    // A `host=` query parameter wins over the URL authority in pg's parse.
+    if (a.url.searchParams.get('host'))
+        return { kind: 'usable' };
+    return a.url.hostname === b.url.hostname ? { kind: 'usable' } : { kind: 'phantom-host' };
+}
+/**
+ * Reject a connection string pg cannot connect with, at construction, naming
+ * the string as the problem.
+ *
+ * Without this, a typo'd or truncated string is handed to pg, which resolves it
+ * as a URL relative to its own `postgres://base`, so the string silently
+ * becomes a request for a host named `base`. The failure surfaces one query
+ * later as `[TURBINE_E004] Database connection error: getaddrinfo ENOTFOUND
+ * base`, and sends the reader looking for a DNS problem with a host they never
+ * configured.
+ *
+ * The oracle is pg itself (see {@link classifyConnectionString}), not a scheme
+ * pattern. An earlier scheme-matching version of this check refused
+ * `/var/run/postgresql app` and `/cloudsql/project:region:instance`, which are
+ * documented, working unix-socket connection strings, i.e. it broke peer-auth
+ * and Cloud SQL deployments at `new TurbineClient(...)`.
+ *
+ * The empty string never reaches here: the call sites skip a falsy value, which
+ * is exactly what the pool-building branch does with it, so
+ * `connectionString: process.env.DATABASE_URL ?? ''` keeps constructing.
+ */
+function assertUsableConnectionString(value, source) {
+    // Whitespace-only is not empty: it is truthy, so pg WOULD take it, encode it
+    // to `%20%20%20`, and resolve it against its placeholder host. Naming it as
+    // empty is more useful than reporting the phantom host.
+    if (value.trim().length === 0) {
+        throw new ConnectionError(`[turbine] The ${source} is empty. Expected a Postgres connection string such as ` +
+            '"postgresql://user:password@host:5432/database".');
+    }
+    const verdict = classifyConnectionString(value);
+    if (verdict.kind === 'usable')
+        return;
+    // Never echo the value: it may carry a password, and it is malformed, so no
+    // redaction written against the URL grammar can be trusted on it.
+    const tail = '(Check for a missing "//", a stray quote copied out of a .env file, or a shell-truncated value.) ' +
+        'The value is not included here because it may contain a password.';
+    if (verdict.kind === 'unparseable') {
+        throw new ConnectionError(`[turbine] The ${source} cannot be parsed as a connection string, pg rejects it with "Invalid URL" ` +
+            '(most often a non-numeric port). Expected something like ' +
+            `"postgresql://user:password@host:5432/database". ${tail}`);
+    }
+    // libpq keyword/value strings land here, and deserve their own sentence:
+    // node-postgres does NOT implement that form, it feeds the whole string to
+    // the URL parser, so `host=localhost dbname=app` becomes a request for the
+    // host `base` with the database `host=localhost dbname=app`.
+    const keywordForm = /^[A-Za-z_][A-Za-z0-9_]*\s*=/.test(value.trimStart())
+        ? 'It looks like a libpq "host=… dbname=…" keyword/value string, which node-postgres does not support. '
+        : '';
+    throw new ConnectionError(`[turbine] The ${source} names no host: it has no "postgres://" or "postgresql://" scheme, so pg would ` +
+        `resolve it as a relative URL and try to connect to its internal placeholder host. ${keywordForm}` +
+        `Expected something like "postgresql://user:password@host:5432/database". ${tail}`);
+}
+/**
+ * Maps isolation level names to SQL. Null-prototype and read through
+ * {@link resolveIsolationLevel}, never indexed directly: an inherited key
+ * (`constructor`, `toString`) would otherwise resolve to a function and be
+ * interpolated verbatim into `BEGIN ISOLATION LEVEL …`.
+ */
+const ISOLATION_LEVELS = Object.assign(Object.create(null), {
     ReadUncommitted: 'READ UNCOMMITTED',
     ReadCommitted: 'READ COMMITTED',
     RepeatableRead: 'REPEATABLE READ',
     Serializable: 'SERIALIZABLE',
-};
+});
+/**
+ * Resolve a requested isolation level, REFUSING anything not in the map.
+ *
+ * A miss used to yield `undefined`, which `beginStatement` renders as a plain
+ * `BEGIN`. So `isolationLevel: 'serializable'` (wrong case) asked for
+ * SERIALIZABLE and silently got READ COMMITTED, which is the worst available
+ * outcome for this option: the caller believes it has a guarantee it does not
+ * have, and the workload that depended on it produces wrong data with no error.
+ *
+ * The TypeScript union on `TransactionOptions.isolationLevel` does not prevent
+ * this. It is not enforced for a JavaScript consumer of a published package, for
+ * a value read from config or an environment variable, or across any `as`.
+ * Throwing costs a caller who was already broken one clear error.
+ */
+/**
+ * Run a transaction-control statement (BEGIN / COMMIT / ROLLBACK) with the same
+ * error translation every other query boundary gets.
+ *
+ * These four statements were the only ones issued raw, and COMMIT is the one
+ * that matters: Postgres reports DEFERRABLE constraint violations and a good
+ * share of SERIALIZABLE conflicts at COMMIT rather than at the statement that
+ * caused them. Unwrapped, those surfaced as a raw `DatabaseError` carrying a
+ * SQLSTATE in `.code`, which is the SAME property Turbine puts `TURBINE_E0NN`
+ * in, so `err.code === 'TURBINE_E008'` silently missed them and a `switch` on
+ * `.code` received a value from a foreign namespace. Worse for the retry case:
+ * `SerializationFailureError.isRetryable` exists so callers can build retry
+ * loops, and a loop keyed on it would never fire for the commit-time conflicts
+ * that are the main reason to run SERIALIZABLE at all.
+ */
+/**
+ * Check out a pooled connection, translating a driver failure into a typed
+ * Turbine error.
+ *
+ * `pool.connect()` is where the first-run failures actually land: wrong
+ * password (SQLSTATE 28P01), no such database (3D000), nothing listening
+ * (ECONNREFUSED), an unverifiable TLS certificate. Unwrapped, every one of
+ * those left `$transaction`, `transaction()` and `connect()` as a raw pg
+ * `DatabaseError` carrying a SQLSTATE in `.code`, the same property Turbine
+ * puts `TURBINE_E0NN` in, so the single error a new user is most likely to see
+ * was the one error the typed-error contract did not cover.
+ *
+ * Query paths need no equivalent: `pool.query()` opens the connection itself
+ * and rejects with the connect error, which the query boundary already wraps.
+ */
+async function acquireConnection(pool) {
+    try {
+        return await pool.connect();
+    }
+    catch (err) {
+        throw wrapPgError(err);
+    }
+}
+async function runTxControl(client, sql) {
+    try {
+        await client.query(sql);
+    }
+    catch (err) {
+        throw wrapPgError(err);
+    }
+}
+function resolveIsolationLevel(level) {
+    if (level === undefined)
+        return undefined;
+    const sql = ownLookup(ISOLATION_LEVELS, level);
+    if (sql === undefined) {
+        throw new ValidationError(`[turbine] $transaction: unknown isolationLevel ${JSON.stringify(level)}. ` +
+            `Expected one of: ${Object.keys(ISOLATION_LEVELS).join(', ')} (case-sensitive).`);
+    }
+    return sql;
+}
 /**
  * Strict GUC (session variable) name: an optionally namespaced identifier such
  * as `app.current_tenant` or `search_path`. Even though the name is passed as a
@@ -531,6 +733,39 @@ export class TurbineClient {
         // would poison the next, valid, TurbineClient with a phantom conflict.
         const dialect = config.dialect ?? postgresDialect;
         const planCacheMode = TurbineClient.resolvePlanCacheMode(config.planCacheMode, dialect);
+        // Refuse a connection string that cannot address a database, before it
+        // reaches pg's permissive parser and comes back one query later as a DNS
+        // error about a fragment of itself. Only the strings this client will
+        // actually USE are checked: with an external pool the connection target is
+        // the caller's, and an explicit host/port/user config makes DATABASE_URL
+        // irrelevant (the same precedence the pool-building branch below applies).
+        // The truthiness checks here mirror the pool-building branch below EXACTLY.
+        // An empty `connectionString` is ignored there (pg ignores it too), so
+        // `connectionString: process.env.DATABASE_URL ?? ''` must keep constructing,
+        // and it still suppresses the DATABASE_URL fallback because
+        // `hasExplicitConnection` tests `!= null`, not truthiness.
+        if (!config.pool) {
+            if (config.connectionString) {
+                assertUsableConnectionString(config.connectionString, 'connectionString');
+            }
+            else if (config.connectionString == null &&
+                config.host == null &&
+                config.port == null &&
+                config.database == null &&
+                config.user == null &&
+                config.password == null &&
+                process.env.DATABASE_URL) {
+                assertUsableConnectionString(process.env.DATABASE_URL, 'DATABASE_URL environment variable');
+            }
+        }
+        for (const [i, replica] of (config.replicas ?? []).entries()) {
+            // Only string replicas are ours to open; a PgCompatPool entry is already
+            // connected by its owner. An empty string is skipped for the same reason
+            // as above: pg ignores a falsy connectionString and uses its defaults.
+            if (typeof replica === 'string' && replica) {
+                assertUsableConnectionString(replica, `replicas[${i}] connection string`);
+            }
+        }
         /**
          * Parse int8 (bigint, OID 20) as JavaScript number instead of string.
          * Safe for values up to Number.MAX_SAFE_INTEGER (9,007,199,254,740,991).
@@ -1251,7 +1486,7 @@ export class TurbineClient {
      * ```
      */
     async transaction(fn) {
-        const client = await this.pool.connect();
+        const client = await acquireConnection(this.pool);
         /**
          * Only true once BEGIN has actually succeeded. If BEGIN itself throws
          * (e.g. a single-writer engine's transaction gate times out or rejects a
@@ -1262,7 +1497,7 @@ export class TurbineClient {
          */
         let began = false;
         try {
-            await client.query(this.dialect.beginStatement());
+            await runTxControl(client, this.dialect.beginStatement());
             began = true;
             // Engine seam: single-writer engines scope their transaction re-entrancy
             // marker to the callback's async subtree (see
@@ -1270,7 +1505,7 @@ export class TurbineClient {
             const wrap = client.wrapTransactionCallback;
             // `.call` erases the generic, so the callback's Promise<T> is re-asserted.
             const result = wrap ? (await wrap.call(client, () => fn(client))) : await fn(client);
-            await client.query(this.dialect.commitStatement());
+            await runTxControl(client, this.dialect.commitStatement());
             return result;
         }
         catch (err) {
@@ -1295,7 +1530,10 @@ export class TurbineClient {
             return this.transactionBatch(fnOrQueries);
         }
         const fn = fnOrQueries;
-        const client = await this.pool.connect();
+        // Resolve the isolation level BEFORE taking a pool slot: a bad argument is
+        // the caller's bug and should not cost a connection to discover.
+        const isolationSql = resolveIsolationLevel(options?.isolationLevel);
+        const client = await acquireConnection(this.pool);
         const timeout = options?.timeout;
         /**
          * Track whether the connection has already been released so the finally
@@ -1327,8 +1565,7 @@ export class TurbineClient {
         try {
             // BEGIN with optional isolation level, the dialect owns the keyword and
             // BEGIN+isolation composition (Postgres appends ` ISOLATION LEVEL …`).
-            const isolationSql = options?.isolationLevel ? ISOLATION_LEVELS[options.isolationLevel] : undefined;
-            await client.query(this.dialect.beginStatement(isolationSql));
+            await runTxControl(client, this.dialect.beginStatement(isolationSql));
             began = true;
             // Apply transaction-local session context (RLS / multi-tenant GUCs).
             // Order matters: BEGIN -> isolation level (above) -> set_config loop ->
@@ -1400,7 +1637,7 @@ export class TurbineClient {
             else {
                 result = await runCallback();
             }
-            await client.query(this.dialect.commitStatement());
+            await runTxControl(client, this.dialect.commitStatement());
             if (this.logging) {
                 console.log('[turbine] Transaction committed');
             }
@@ -1620,7 +1857,7 @@ export class TurbineClient {
      * Throws if the connection fails.
      */
     async connect() {
-        const client = await this.pool.connect();
+        const client = await acquireConnection(this.pool);
         try {
             await client.query('SELECT 1');
             if (this.logging) {

package/dist/errors.d.ts

@@ -53,10 +53,29 @@ export type ErrorMessageMode = 'safe' | 'verbose';
  *     clause (e.g. `where: { id, email }`). Values are redacted.
  *   - `'verbose'`: the message includes the full JSON-serialized where
  *     clause (e.g. `where: {"id":1,"email":"alice@x.com"}`).
+ *
+ * SCOPE, stated precisely because the useful version of this contract is the
+ * one that is true. 'safe' mode redacts row values from the surfaces Turbine
+ * OWNS: its own error messages, and the `detail` field of a driver error it
+ * wraps and attaches as `.cause` (see redactCauseForMode).
+ *
+ * It is NOT a blanket guarantee that no row value can be reached from a thrown
+ * error. A driver error whose SQLSTATE {@link wrapPgError} does not classify is
+ * returned UNCHANGED, and some of those carry a value in the `message` field
+ * itself, where nothing can be removed without destroying the diagnosis:
+ * `22P02 invalid input syntax for type integer: "alice@example.com"` is the
+ * common one. Treat 'safe' mode as removing Turbine's own contribution to the
+ * leak, not as a log-scrubbing boundary.
  */
 export declare function setErrorMessageMode(mode: ErrorMessageMode): void;
 /** Returns the current NotFoundError message mode. Exported for tests. */
 export declare function getErrorMessageMode(): ErrorMessageMode;
+/**
+ * The marker left where a driver `detail` string was removed in 'safe' mode.
+ * Re-exported from the package root so tests and callers writing log
+ * assertions can match on it without hardcoding the wording.
+ */
+export declare const REDACTED_DETAIL = "[redacted by turbine errorMessages:\"safe\"]";
 /**
  * Render a user-supplied `where` / `connect` target for a "no row found" error
  * message, honoring the global {@link ErrorMessageMode}. In 'safe' mode (the
@@ -122,13 +141,29 @@ export declare class ValidationError extends TurbineError {
 }
 /** Thrown when a database connection fails */
 export declare class ConnectionError extends TurbineError {
+    /**
+     * The driver code that produced this error: a Postgres SQLSTATE (`28P01`
+     * wrong password, `3D000` no such database, `08006` connection failure, ...)
+     * or a Node socket/TLS code (`ECONNREFUSED`, `CERT_HAS_EXPIRED`, ...).
+     *
+     * Exposed because E004 covers causes with very different remedies, and the
+     * alternative for a caller who needs to tell "wrong password" from "server
+     * down" is matching on `.message` text or reaching into `.cause`, both of
+     * which are exactly the untyped handling this error class exists to remove.
+     * Undefined when Turbine raised the error itself rather than wrapping a
+     * driver error (a malformed connection string, a subscription on an HTTP
+     * pool).
+     */
+    readonly sqlstate?: string;
     /**
      * @param message human-readable connection failure description.
      * @param options optional pg/driver `cause` to preserve, used when wrapping a
-     *   connection-class driver error via `wrapPgError`.
+     *   connection-class driver error via `wrapPgError`, plus the driver `code`
+     *   that classified it.
      */
     constructor(message: string, options?: {
         cause?: unknown;
+        sqlstate?: string;
     });
 }
 /** Thrown when a relation reference is invalid */
@@ -363,6 +398,8 @@ export declare class ReadOnlyError extends TurbineError {
  *   40P01 (deadlock_detected)     -> DeadlockError       (retryable)
  *   40001 (serialization_failure) -> SerializationFailureError (retryable)
  *   57014 (query_canceled)        -> TimeoutError (server-side statement_timeout)
+ *   28P01 / 28000 (auth refused)  -> ConnectionError, with a remediation hint
+ *   3D000 (no such database)      -> ConnectionError, with a remediation hint
  *   connection-class codes        -> ConnectionError (see CONNECTION_ERROR_CODES)
  *
  * The original pg error is preserved as `.cause` on the wrapped error.