@rebasepro/server-postgres 0.23.0 → 0.24.0

package/dist/services/BranchService.d.ts

@@ -23,10 +23,31 @@ export declare class BranchingUnsupportedError extends Error {
     readonly code = "BRANCHING_UNSUPPORTED";
     constructor(message: string);
 }
+/**
+ * Where a server's branches are kept: the main database — what a branch is
+ * copied from unless told otherwise, and what may never be dropped — and the
+ * connection whose `rebase.branches` records them.
+ */
+export interface BranchHome {
+    /** The main database's name. */
+    database(): Promise<string>;
+    /**
+     * A connection on the database the registry is in. Asked for at each use:
+     * a pool to the main database is closed before it is copied.
+     */
+    registry(): Promise<DrizzleClient>;
+}
 export declare class BranchService {
     private db;
     private poolManager;
-    constructor(db: DrizzleClient, poolManager: DatabasePoolManager);
+    private readonly home;
+    /**
+     * @param db    A connection on the server the branches are made on. Branch
+     *              DDL runs here.
+     * @param home  Where branches are kept. Without one, the database the
+     *              pool manager's connection string names, and `db`'s registry.
+     */
+    constructor(db: DrizzleClient, poolManager: DatabasePoolManager, home?: BranchHome);
     /**
      * Refuse a branch mutation the connected server cannot honour.
      *

package/dist/services/FetchService.d.ts

@@ -313,9 +313,10 @@ export declare class FetchService {
      * Extract cursor pagination conditions from startAfter options.
      *
      * "Every row that sorts after this one", written out as a comparison over
-     * the same keys the `ORDER BY` uses and ending on the same `id DESC`. With
-     * one key that is the familiar `k > v OR (k = v AND id < cursorId)`; with
-     * several it nests, each key's tie handing the decision to the next.
+     * the same keys the `ORDER BY` uses and ending on the same primary key,
+     * descending. With one sort key that is the familiar
+     * `k > v OR (k = v AND id < cursorId)`; with several it nests, each key's
+     * tie handing the decision to the next.
      */
     private buildCursorConditions;
     /** The table's primary key columns, in key order. */
@@ -359,7 +360,7 @@ export declare class FetchService {
      */
     private preciseCursorValue;
     /**
-     * "Sorts strictly after the cursor row", over `keys` and then the id.
+     * "Sorts strictly after the cursor row", over `keys` and then the primary key.
      *
      * Built by recursion rather than as a row-value comparison — `(a, b) > (x, y)`
      * would be shorter, but it is only correct when every key runs the same

package/dist/services/RelationService.d.ts

@@ -16,6 +16,24 @@ import { type ReadCallContextProvider } from "./read-scope.js";
  * the same claim about the same drizzle behaviour in a second spelling.
  */
 export declare function applyDynamicJoin<T>(query: T, joinTable: PgTable, condition: SQL): T;
+/**
+ * The ON condition of one `joinPath` step: every `from` column equal to its
+ * `to` column, or `undefined` naming the first column either table lacks.
+ *
+ * `on.from`/`on.to` are a column or a tuple, and a tuple is how a step joins on
+ * a composite key. Comparing the first pair alone joined each row to every row
+ * sharing that column — every locale of a translation, not the one addressed.
+ */
+export declare function joinStepCondition(currentTable: PgTable, joinTable: PgTable, step: {
+    on: {
+        from: string | string[];
+        to: string | string[];
+    };
+}): {
+    condition: SQL;
+} | {
+    missing: string;
+};
 /**
  * Service for handling all relation-related operations.
  * Handles fetching, updating, and managing row relations.

package/dist/services/cdc/CdcListener.d.ts

@@ -1,3 +1,4 @@
+import { type PgNotifyListenerStatus } from "../pg-notify-listener.js";
 /**
  * A single database change captured by the CDC triggers and delivered over the
  * `rebase_cdc` NOTIFY channel.
@@ -7,12 +8,13 @@ export interface CdcChangeEvent {
     table: string;
     op: "INSERT" | "UPDATE" | "DELETE";
     /**
-     * The changed tuple (NEW for insert/update, OLD for delete). May be a
-     * partial identity-only object when the full row overflowed the pg_notify
-     * size cap — see {@link truncated}.
+     * The changed row's identity, by column: its key, and for a junction table
+     * the two ids naming the child list (from NEW for insert/update, OLD for
+     * delete). Never the row's other values — any login can LISTEN; see
+     * `buildCdcFunctionSql`.
      */
     row: Record<string, unknown>;
-    /** True when the row was reduced to its identity because it was too large to notify. */
+    /** True when even the key was too large to notify, so `row` is empty. */
     truncated?: boolean;
 }
 /**
@@ -49,4 +51,7 @@ export declare class CdcListener {
     start(): Promise<void>;
     /** Stop listening and release the connection. */
     stop(): Promise<void>;
+    /** Listening on a connection that answered its last heartbeat — see {@link PgNotifyListener}. */
+    get connected(): boolean;
+    status(): PgNotifyListenerStatus;
 }

package/dist/services/cdc/identity-columns.d.ts

@@ -0,0 +1,19 @@
+import type { CollectionConfig } from "@rebasepro/types";
+import type { PostgresCollectionRegistry } from "../../collections/PostgresCollectionRegistry.js";
+/** One key field of a collection, and the column it is stored in. */
+export interface KeyColumn {
+    fieldName: string;
+    columnName: string;
+}
+/**
+ * The columns a collection's rows are addressed by.
+ *
+ * A change notification names its row by column — that is all a trigger sees —
+ * and an address is built from the key's *field* names. Both ends read the
+ * mapping from here: the provisioner, to attach the trigger with exactly these
+ * columns (and nothing else leaves the database), and the consumer, to turn the
+ * captured columns back into an address. A key declared as `userId` over
+ * `user_id` used to be looked up by field name on the captured row, never
+ * found, and every external write reached no single-row subscriber.
+ */
+export declare function collectionKeyColumns(collection: CollectionConfig, registry: PostgresCollectionRegistry): KeyColumn[];

package/dist/services/cdc/trigger-cdc.d.ts

@@ -27,23 +27,49 @@ export declare const CDC_TRIGGER_FUNCTION = "rebase.rebase_cdc_notify";
 export declare const CDC_TRIGGER_NAME = "rebase_cdc_trigger";
 /**
  * SQL that (re)creates the generic CDC trigger function. Safe to run repeatedly:
- * `CREATE OR REPLACE` updates in place without dropping dependent triggers.
+ * `CREATE OR REPLACE` updates in place without dropping dependent triggers —
+ * which is also how a database instrumented by an older version gets this body
+ * on its next boot, for every table at once, re-attached or not.
  *
- * The function emits `{ schema, table, op, row }`. The `row` is the full changed
- * tuple (NEW for insert/update, OLD for delete) so the consumer can route it to
- * a collection and extract the primary key. It is *not* trusted for delivery:
- * the consumer marks the row invalidated and each subscriber re-reads it under
- * its own RLS context, so a subscriber never receives a row it cannot read.
+ * The function emits `{ schema, table, op, row }`, and `row` is an **identity,
+ * never the tuple**. Postgres puts no privilege on `LISTEN`: any role that can
+ * connect can listen on this channel, whatever it may `SELECT`. When `row` was
+ * `to_jsonb(NEW)`, a login with no grant on anything received every changed row
+ * of every instrumented table — `password_hash` and verification tokens from
+ * the auth table included — past RLS and column grants. The consumer never
+ * read anything but the key: every subscriber re-reads the row under its own
+ * scope.
+ *
+ * The identity is, in order:
+ *  - the columns the trigger was attached with (`TG_ARGV`) — the key the
+ *    consumer addresses the row by, and for a junction table the two ids that
+ *    name the child list it changed; see {@link buildCdcTriggerSql};
+ *  - otherwise the table's primary key, read from the catalogue — a trigger
+ *    attached with no columns, by an older boot or on a table no collection
+ *    maps any more;
+ *  - otherwise `id`, if the table has one, and else nothing: a change the
+ *    consumer can only treat as collection-wide.
  */
 export declare function buildCdcFunctionSql(): string;
 /**
  * SQL that (re)attaches the CDC trigger to a single table. `DROP ... IF EXISTS`
  * before `CREATE` keeps it idempotent and picks up any function signature change.
+ *
+ * `identityColumns` are what the payload names the changed row by — see
+ * {@link buildCdcFunctionSql}. Passed as trigger arguments, so one shared
+ * function serves every table without a catalogue read per row. Empty means
+ * "the primary key".
  */
-export declare function buildCdcTriggerSql(schema: string, table: string): string;
+export declare function buildCdcTriggerSql(schema: string, table: string, identityColumns?: readonly string[]): string;
 export interface CdcTableRef {
     schema: string;
     table: string;
+    /**
+     * The columns a change to this table is announced by — the collection's
+     * key columns, or a junction's two id columns. Absent means the primary
+     * key. Nothing else ever leaves the trigger; see {@link buildCdcFunctionSql}.
+     */
+    identityColumns?: string[];
 }
 export interface ProvisionResult {
     /** Tables the trigger was successfully attached to. */
@@ -53,6 +79,18 @@ export interface ProvisionResult {
         reason: string;
     }>;
 }
+/**
+ * Replace an already-installed trigger function with the current body, and
+ * install nothing where there is none.
+ *
+ * For a process that owns the schema but is not provisioning capture on this
+ * boot — `REALTIME_CDC=off`, or no direct URL to listen on. The triggers an
+ * earlier boot attached keep firing whether anything consumes them or not, so
+ * a database instrumented by a version whose function put whole rows on the
+ * channel kept doing so, for every login that cares to `LISTEN`, until capture
+ * was switched back on. Returns whether a function was there to replace.
+ */
+export declare function refreshInstalledCdcFunction(run: RawSqlRunner): Promise<boolean>;
 /**
  * Idempotently install the CDC trigger function and per-table triggers.
  *

package/dist/services/channel-bus/PostgresChannelBus.d.ts

@@ -6,13 +6,15 @@
  * properties of `NOTIFY` shape everything below:
  *
  *  - **8000 bytes per payload.** Presence and cursors fit with room to spare; a
- *    scene snapshot does not. Rather than truncate or drop, an oversized frame
- *    on a *retained* channel is published as a pointer — the body is already in
- *    `rebase.channel_messages` with a sequence number, so the receiver reads it
- *    back. That is the same trick the entity path uses (notify an address,
- *    refetch the row), applied to a different table. On an ephemeral channel
- *    there is nothing to point at, so the publish is refused loudly instead of
- *    reaching some instances and not others.
+ *    scene snapshot does not. A message on a *retained* channel never travels
+ *    here at all, whatever its size: the statement that numbers it notifies a
+ *    pointer — the body is already in `rebase.channel_messages` with a sequence
+ *    number, so the receiver reads it back (`ChannelHistoryStore.append`). That
+ *    is the same trick the entity path uses (notify an address, refetch the
+ *    row), applied to a different table, and for the same reason: any database
+ *    login can `LISTEN`. On an ephemeral channel there is nothing to point at,
+ *    so the frame carries the message, and an oversized one is refused loudly
+ *    instead of reaching some instances and not others.
  *
  *  - **A notify is a query on the primary database.** Not a slow one, but it
  *    competes with the application's real queries, and that — not throughput —
@@ -26,6 +28,7 @@
  *    than correctness. That is what makes coalescing safe.
  */
 import { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { type PgNotifyListenerStatus } from "../pg-notify-listener.js";
 import { ChannelBus, ChannelBusFrame, ChannelBusHandler } from "./ChannelBus.js";
 /** NOTIFY channel carrying channel-bus frames. */
 export declare const CHANNEL_BUS_NOTIFY_CHANNEL = "rebase_channel_bus";
@@ -79,6 +82,8 @@ export declare class PostgresChannelBus implements ChannelBus {
      * still holds.
      */
     publish(frame: ChannelBusFrame): Promise<void>;
+    /** The LISTEN connection's state, for `/health` — see {@link PgNotifyListener}. */
+    status(): PgNotifyListenerStatus | undefined;
     stop(): Promise<void>;
     private openWindow;
     /** Send everything queued and settle the promises waiting on it. */

package/dist/services/channel-history.d.ts

@@ -53,6 +53,22 @@ export interface ResolvedRetention {
     limit?: number;
     ttlMs?: number;
 }
+/**
+ * A bus frame to send in the statement that numbers a retained message — see
+ * {@link ChannelHistoryStore.append}.
+ *
+ * It is always a pointer, `{ kind: "broadcast_ref", sid, channel, seq }`, and
+ * never the message. Postgres puts no privilege on `LISTEN`, so a NOTIFY payload
+ * reaches every role that can connect to the database; the body stays in
+ * `rebase.channel_messages`, behind the table grants, and each receiving
+ * instance reads it back by `(channel, seq)` — the sender's id with it.
+ */
+export interface RetainedAnnouncement {
+    /** The NOTIFY channel the bus listens on. */
+    notifyChannel: string;
+    /** The sending instance. */
+    sid: string;
+}
 /**
  * Persistence and replay for retained channels.
  *
@@ -91,7 +107,7 @@ export declare class ChannelHistoryStore {
      * broadcasts to one channel line up in a single order — and what keeps
      * different channels from contending with each other at all.
      */
-    append(channel: string, event: string, payload: unknown, senderId?: string): Promise<{
+    append(channel: string, event: string, payload: unknown, senderId?: string, announce?: RetainedAnnouncement): Promise<{
         seq: number;
         at: string;
     }>;

package/dist/services/collection-helpers.d.ts

@@ -1,5 +1,5 @@
 import { PgTable, AnyPgColumn } from "drizzle-orm/pg-core";
-import { SQL } from "drizzle-orm";
+import { type SQL } from "drizzle-orm";
 import { CollectionConfig, ResolvedHasMany, ResolvedHasOne } from "@rebasepro/types";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry.js";
 import { ApiError } from "@rebasepro/server";
@@ -133,6 +133,16 @@ export declare function getPrimaryKeys(collection: CollectionConfig, registry: P
  * wrong and which collection it is wrong about.
  */
 export declare function requirePrimaryKeys(collection: CollectionConfig, registry: PostgresCollectionRegistry): PrimaryKeyInfo[];
+/**
+ * The table's key columns, in key order.
+ *
+ * Throws when there are none, or when the table has no column for one of them:
+ * a WHERE built from fewer columns than the key matches every row that shares
+ * the columns it did find, so there is no partial answer worth returning.
+ *
+ * @param collectionPath named in the error.
+ */
+export declare function primaryKeyColumns(table: PgTable, primaryKeys: PrimaryKeyInfo[], collectionPath: string): AnyPgColumn[];
 /**
  * The column on the *source* table that a `hasOne`/`hasMany` link points at.
  *

package/dist/services/pg-notify-listener.d.ts

@@ -3,11 +3,11 @@
  *
  * Every cross-instance feature in the backend needs the same thing: one
  * connection *outside* the Drizzle pool that stays open, holds a `LISTEN`, and
- * comes back on its own after the database or the network drops it. CDC needed
- * it first; the channel bus needs it too. This is that connection, with the one
- * behaviour that matters to callers preserved: the **first** connect is
- * validated and rethrown, so a caller can fall back to a different strategy,
- * while every later drop is repaired quietly in the background.
+ * comes back on its own after the database or the network drops it. CDC, the
+ * channel bus and the cross-instance broadcast all use this one. By default the
+ * **first** connect is validated and rethrown, so a caller can fall back to a
+ * different strategy, while every later drop is repaired quietly in the
+ * background; `retryInitialConnect` repairs the first one the same way.
  *
  * `LISTEN` is session state, so this connection must not go through a
  * transaction-mode pooler (PgBouncer): give it the direct database URL.
@@ -30,25 +30,107 @@ export interface PgNotifyListenerOptions {
      * gone for good; a caller that mirrors state from the channel resyncs here.
      */
     onReconnect?: () => void;
+    /**
+     * How often the connection proves it is alive with a round trip. `0`
+     * turns the heartbeat off. See {@link PgNotifyListener} for why it exists.
+     */
+    heartbeatIntervalMs?: number;
+    /** How long a heartbeat may take before the connection is declared dead. */
+    heartbeatTimeoutMs?: number;
+    /**
+     * Treat a failed first connect like any later drop: `start()` resolves,
+     * the listener reports itself down, and it keeps dialling in the
+     * background. For a caller with nothing to fall back to, for whom a
+     * database that is unreachable at boot is an outage to wait out rather
+     * than a reason to run without the channel. Off by default: `start()`
+     * rejects, so a caller with a fallback can take it.
+     */
+    retryInitialConnect?: boolean;
+}
+/**
+ * What a listener can say about itself — read by `/health`.
+ *
+ * `connected` is "listening, and the last heartbeat answered", not "a socket
+ * object exists": a half-open connection has a perfectly good socket object.
+ */
+export interface PgNotifyListenerStatus {
+    channel: string;
+    connected: boolean;
+    /** Since when (epoch ms) it has been down, while it is down. */
+    downSince?: number;
+    /** When (epoch ms) it last answered a heartbeat. */
+    lastHeartbeatAt?: number;
 }
+/**
+ * Below every common idle-flow timeout: Azure's load balancer drops an idle
+ * flow at 4 minutes, AWS's NLB at 350 s, and NAT and conntrack tables and
+ * pooler-side reapers are often shorter. A LISTEN connection is idle by
+ * nature, so it is exactly the connection those timeouts kill.
+ */
+export declare const DEFAULT_HEARTBEAT_INTERVAL_MS = 30000;
+export declare const DEFAULT_HEARTBEAT_TIMEOUT_MS = 10000;
+/**
+ * A half-open connection — one whose packets stop arriving, with no FIN and no
+ * RST, which is what an idle-flow timeout on a load balancer, a NAT, a dead
+ * middlebox or a failed-over network looks like — fires no `error` and no
+ * `end`. The connection object stays, `LISTEN` stays registered on a backend
+ * that may no longer exist, and every notification from then on is lost: CDC,
+ * the cross-instance broadcast and the channel bus all went quiet with no
+ * error, no reconnect and a green `/health`, while writes made through this
+ * instance still looked live because they are delivered locally.
+ *
+ * So the connection proves itself: TCP keepalive is on, and every
+ * {@link DEFAULT_HEARTBEAT_INTERVAL_MS} a `SELECT 1` must come back within
+ * {@link DEFAULT_HEARTBEAT_TIMEOUT_MS}. One that does not is torn down and
+ * replaced, and `onReconnect` resyncs whatever was missed.
+ */
 export declare class PgNotifyListener {
     private readonly options;
     private client?;
     private running;
     private reconnectTimer?;
+    private heartbeatTimer?;
+    private heartbeatInFlight;
+    private downSince?;
+    private lastHeartbeatAt?;
     constructor(options: PgNotifyListenerOptions);
     /** Whether the listener is meant to be connected right now. */
     get active(): boolean;
+    /** Whether it is listening on a connection that answered its last heartbeat. */
+    get connected(): boolean;
+    status(): PgNotifyListenerStatus;
     /**
      * Connect and begin listening. Idempotent.
      *
      * Rejects if the *initial* connection or `LISTEN` fails, leaving the
      * listener stopped — callers use that to degrade deliberately instead of
-     * running blind against a channel nothing is delivering.
+     * running blind against a channel nothing is delivering. With
+     * `retryInitialConnect` it resolves instead, reports itself down, and
+     * keeps dialling.
      */
     start(): Promise<void>;
     /** Stop listening and release the connection. Idempotent. */
     stop(): Promise<void>;
+    /**
+     * @param first The connect `start()` makes: never a reconnect, so it owes
+     *        no resync, and — unless `retryInitialConnect` — a failure is
+     *        thrown to the caller rather than retried.
+     */
     private connect;
+    /**
+     * Give up on the current connection: it is no longer the listener's, so
+     * its late events are ignored and `connected` says so at once; it is
+     * ended without waiting on it; and a replacement is scheduled.
+     */
+    private abandon;
+    private startHeartbeat;
+    private stopHeartbeat;
+    /**
+     * One round trip on the LISTEN connection. Not answered in time, it is
+     * treated as dead: the client is ended — which, with the query still
+     * outstanding, destroys the socket rather than waiting on a goodbye that
+     * cannot arrive — and replaced.
+     */
+    private heartbeat;
     private scheduleReconnect;
 }