@rebasepro/server-postgres 0.23.0 → 0.24.1-canary.g56af4a4

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.
  *
@@ -63,10 +79,21 @@ export interface ResolvedRetention {
 export declare class ChannelHistoryStore {
     private db;
     private rules;
-    /** Resolved rule per channel name, so the match runs once per channel. */
-    private resolved;
-    /** Channel → timestamp of its last prune, for {@link PRUNE_THROTTLE_MS}. */
+    /**
+     * Each rule with its retention resolved, once. Matched per call rather
+     * than cached per channel name: a cache keyed by the names clients invent
+     * grew by every one of them for the life of the process, and matching a
+     * handful of prefixes costs less than the hashing a lookup does.
+     */
+    private resolvedRules;
+    /**
+     * Channel → timestamp of its last prune, for {@link PRUNE_THROTTLE_MS}.
+     * An entry older than the window throttles nothing, so they are swept once
+     * a window: the map holds the channels pruned recently, not every channel
+     * ever pruned.
+     */
     private lastPruned;
+    private nextPruneSweepAt;
     private tablesReady;
     constructor(db: NodePgDatabase<Record<string, unknown>>, rules?: ChannelRetentionRule[]);
     /** Whether any channel retains anything at all. */
@@ -91,7 +118,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;
     }>;
@@ -124,6 +151,6 @@ export declare class ChannelHistoryStore {
      * volume, which is what makes retention affordable on a hot channel.
      */
     prune(channel: string, retention: ResolvedRetention): Promise<number>;
-    /** Forget throttle and match caches. Called on shutdown. */
+    /** Forget the prune throttle. Called on shutdown. */
     clear(): void;
 }

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,31 @@ 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 a `joinPath` step names, on a table that may key it either way.
+ *
+ * A `JoinStep` is written in database terms — `on: { from: "author_id" }` —
+ * because there is no collection to translate through: the step names a raw
+ * table. A table the boot reads back out of the catalogue is keyed by the
+ * *wire* name, `authorId`, while a hand-written Drizzle schema may key it by
+ * the column name. Looking the step's name up as a key therefore found
+ * nothing on every booted table, and a `via` relation loaded nothing at all.
+ *
+ * The key first, as the step may already name one; then the column whose SQL
+ * name it is. `undefined` when the table has neither, which the caller turns
+ * into an error naming the step.
+ */
+export declare function columnNamed(table: PgTable, name: string): AnyPgColumn | undefined;
 /**
  * The column on the *source* table that a `hasOne`/`hasMany` link points at.
  *

package/dist/services/field-viewer.d.ts

@@ -1,4 +1,5 @@
-import type { FieldViewer } from "@rebasepro/common";
+import { type FieldViewer } from "@rebasepro/common";
+import type { CollectionConfig } from "@rebasepro/types";
 /**
  * Run `fn` with `viewer` as the caller every row strip judges against.
  *
@@ -17,3 +18,16 @@ export declare function withFieldViewer<T>(viewer: FieldViewer | undefined, fn:
  * that is what establishes the viewer.
  */
 export declare function currentFieldViewer(): FieldViewer | undefined;
+/**
+ * The names an API caller's query may not see on `collection`: its
+ * `excludeFromApi` fields, in every spelling. Empty on the trusted server plane
+ * (no viewer), which may filter and sort on those columns — the auth adapter
+ * looks rows up by them — and empty with no collection in hand.
+ *
+ * A query naming one of these is answered exactly as a query naming a column
+ * the table does not have. The REST check passes such a name through to this
+ * driver rather than refusing it itself, so the two answers come from one throw
+ * and cannot drift: a "not readable" there would confirm a column OpenAPI and
+ * `list_collections` hide.
+ */
+export declare function namesHiddenFromCaller(collection: CollectionConfig | undefined): ReadonlySet<string>;

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,114 @@ 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;
+    /**
+     * The `application_name` the connection reports in `pg_stat_activity`.
+     * Visible to every role, which is what lets one instance count the others
+     * (see `RealtimeService.warnIfMemoryBusOnMultiplePods`). A connection
+     * string that sets its own `application_name` wins.
+     */
+    applicationName?: string;
+}
+/**
+ * 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;
 }