@rebasepro/server-postgres 0.22.0 → 0.24.0

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,4 +1,5 @@
 import { PgTable, AnyPgColumn } from "drizzle-orm/pg-core";
+import { type SQL } from "drizzle-orm";
 import { CollectionConfig, ResolvedHasMany, ResolvedHasOne } from "@rebasepro/types";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry.js";
 import { ApiError } from "@rebasepro/server";
@@ -34,6 +35,16 @@ export declare function getColumnMeta(col: AnyPgColumn): DrizzleColumnMeta;
  * statement into an unrelated-looking `25P02`.
  */
 export declare function idCanAddressTable(id: string | number, table: PgTable, idInfoArray: PrimaryKeyInfo[]): boolean;
+/**
+ * The condition that names one row: every key column equal to its part of the
+ * address.
+ *
+ * Every key column, not the first. A composite-key read that matched only the
+ * leading column answered `p1:::bob` with whichever `p1` row Postgres reached
+ * first, and a delete then judged that row's `beforeDelete` while deleting bob —
+ * the writes have always matched the whole key, so the reads must too.
+ */
+export declare function rowIdentityCondition(table: PgTable, idInfoArray: PrimaryKeyInfo[], id: string | number, collectionPath: string): SQL;
 export declare function getCollectionByPath(collectionPath: string, registry: PostgresCollectionRegistry): CollectionConfig;
 /**
  * Reject a write naming something that is not a column of the table.
@@ -122,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/dataService.d.ts

@@ -3,7 +3,7 @@ import type { VectorSearchParams } from "@rebasepro/types";
 import { FetchService } from "./FetchService.js";
 import type { ReadCallContextProvider } from "./read-scope.js";
 import type { WithDeleted } from "./soft-delete.js";
-import { PersistService } from "./PersistService.js";
+import { PersistService, type PersistSaveOptions } from "./PersistService.js";
 import { RelationService } from "./RelationService.js";
 import { DataRepository, DrizzleClient } from "../interfaces.js";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry.js";
@@ -52,21 +52,7 @@ export declare class DataService implements DataRepository {
     /**
      * Fetch a collection of rows with optional filtering, ordering, and pagination
      */
-    fetchCollection<M extends Record<string, unknown>>(collectionPath: string, options?: {
-        filter?: FilterValues<Extract<keyof M, string>>;
-        /** An `or(...)`/`and(...)` group, applied alongside `filter`. */
-        logical?: LogicalCondition;
-        orderBy?: string | OrderByTuple[];
-        order?: "desc" | "asc";
-        limit?: number;
-        offset?: number;
-        startAfter?: Record<string, unknown>;
-        searchString?: string;
-        databaseId?: string;
-        vectorSearch?: VectorSearchParams;
-        /** See `FetchCollectionProps.withDeleted`. */
-        withDeleted?: WithDeleted;
-    }): Promise<Record<string, unknown>[]>;
+    fetchCollection<M extends Record<string, unknown>>(collectionPath: string, options?: Parameters<FetchService["fetchCollection"]>[1]): Promise<Record<string, unknown>[]>;
     /**
      * The REST read pipeline: flat rows, with exactly the relations `include`
      * names — see {@link FetchService.fetchCollectionForRest}.
@@ -132,10 +118,7 @@ export declare class DataService implements DataRepository {
     /**
      * Save an row (create or update)
      */
-    save<M extends Record<string, unknown>>(collectionPath: string, values: Partial<M>, id?: string | number, databaseId?: string, options?: {
-        upsert?: boolean;
-        onConflict?: readonly string[];
-    }): Promise<Record<string, unknown>>;
+    save<M extends Record<string, unknown>>(collectionPath: string, values: Partial<M>, id?: string | number, databaseId?: string, options?: PersistSaveOptions): Promise<Record<string, unknown>>;
     /**
      * Delete an row by ID
      */

package/dist/services/field-op-sql.d.ts

@@ -1,6 +1,9 @@
 import { SQL } from "drizzle-orm";
 import { PgTable } from "drizzle-orm/pg-core";
+import { ApiError } from "@rebasepro/server";
 import type { ParsedFieldOp } from "@rebasepro/server";
+import type { Properties } from "@rebasepro/types";
+import type { DrizzleClient } from "../interfaces.js";
 /**
  * The expression one operation compiles to, or a 400 saying why it cannot.
  *
@@ -14,3 +17,71 @@ export declare function compileFieldOp(table: PgTable, field: string, op: Parsed
 export declare function compileFieldOps(table: PgTable, fieldOps: Record<string, ParsedFieldOp>, context: {
     collectionPath: string;
 }): Record<string, SQL>;
+/**
+ * One declared bound an operation's result has to stay inside.
+ *
+ * `code` and `message` are what a plain value breaking the same rule reports
+ * (see `write-validation.ts`), so `{ stock: { $inc: -1000 } }` and
+ * `{ stock: -5 }` are refused with one answer.
+ */
+export interface FieldOpBound {
+    /** The property key. */
+    field: string;
+    code: "min" | "max" | "more_than" | "less_than" | "positive" | "negative" | "min_items" | "max_items";
+    /**
+     * TRUE when the value the operation writes keeps to the rule, evaluated
+     * against the row the statement is changing. Never NULL: an unset column
+     * reads as `0` or empty wherever the operation itself reads it so, and an
+     * array the operation leaves unset has no size for a bound to judge.
+     */
+    holds: SQL;
+    message: string;
+}
+/**
+ * The declared bounds each operation's *result* must satisfy, as conditions
+ * for the UPDATE that applies it.
+ *
+ * `{ stock: -5 }` on `stock: { validation: { min: 0 } }` is refused before the
+ * statement is built, because the value is in the request. What
+ * `{ stock: { $inc: -1000 } }` produces depends on the stored row, which the
+ * request never sees, so it can only be judged where the row is: in the WHERE
+ * of the UPDATE that does the arithmetic, over the row that statement holds
+ * locked. Reading the row first and judging the sum would reopen the race the
+ * operation exists to close — two decrements of a stock of 1 would each read
+ * `1`, each find room for one more, and both go through. A condition on the
+ * UPDATE cannot be raced that way: under READ COMMITTED an UPDATE blocked on a
+ * concurrent writer re-evaluates its WHERE against the row that writer
+ * committed, so the second decrement sees `0 - 1` and matches nothing.
+ *
+ * The bound is the whole declared range, applied to the result the way it
+ * applies to a value: a number's `min`, `max`, `moreThan`, `lessThan`,
+ * `positive` and `negative`, an array's `min` and `max` items. `integer` is not
+ * here: a whole increment of a whole number stays whole, and the request
+ * already refuses a fractional one. `$merge` has no bounds to hold.
+ */
+export declare function compileFieldOpBounds(table: PgTable, fieldOps: Record<string, ParsedFieldOp>, properties: Properties, context: {
+    collectionPath: string;
+}): FieldOpBound[];
+/**
+ * Which bounds the row, as it now stands, would break — for an UPDATE that
+ * carried bounds and matched nothing.
+ *
+ * A guarded UPDATE matching zero rows means one of three things: the row is not
+ * there for this caller (404), a row-level security policy refused the write
+ * (403), or the operation's result broke a bound (400). The first two are
+ * `explainZeroRowWrite`'s; this answers the third, by evaluating each bound
+ * against the row over the same handle and the same key conditions. An empty
+ * answer — the row is not visible, or every bound holds — leaves the decision to
+ * `explainZeroRowWrite`.
+ *
+ * It is a second statement, so the row can change in between. A row deleted in
+ * between is a 404 here as it would have been anyway. A row changed so that the
+ * operation now fits reads as "every bound holds" and falls through to the
+ * row-level-security answer; the write was refused either way, and the
+ * refusal is never turned into a write.
+ *
+ * Only booleans come back — whether each bound holds — never the stored value.
+ */
+export declare function brokenFieldOpBounds(handle: DrizzleClient, table: PgTable, conditions: SQL[], bounds: FieldOpBound[]): Promise<FieldOpBound[]>;
+/** The 400 a write gets when an operation's result breaks a bound. */
+export declare function fieldOpBoundsError(collectionSlug: string, broken: FieldOpBound[]): ApiError;

package/dist/services/junction-writes.d.ts

@@ -1,3 +1,4 @@
+import { type SQL } from "drizzle-orm";
 import { AnyPgColumn, PgTable } from "drizzle-orm/pg-core";
 import type { Properties, ResolvedVia } from "@rebasepro/types";
 import { DrizzleClient } from "../interfaces.js";
@@ -49,6 +50,19 @@ export interface JunctionLinkWrite {
     /** Payload values keyed by property key, already serialized for the driver. */
     pivot?: Record<string, unknown>;
 }
+/**
+ * The target rows a membership write can see, when that is not all of them —
+ * the target's `beforeQuery` scope and its soft delete.
+ *
+ * The diff reads "what is linked now" through it, so a link to a row the caller
+ * was never shown is in neither list and is left alone rather than unlinked.
+ */
+export interface VisibleTargets {
+    table: PgTable;
+    /** The target column the junction's `targetColumn` holds values of. */
+    idColumn: AnyPgColumn;
+    condition: SQL;
+}
 /** The junction a `manyToMany` names outright. */
 export declare function bindThroughJunction(registry: PostgresCollectionRegistry, through: {
     table: string;
@@ -91,8 +105,10 @@ export declare function removeJunctionLink(tx: DrizzleClient, binding: JunctionB
  *    the form runs under RLS, so a user who may edit the parent but cannot see
  *    some of the linked rows gets a shorter list — and writing it back deleted
  *    the links they were never shown. The select that drives the diff runs in
- *    this same transaction under the same policies, so a link the caller cannot
- *    read is in neither list and survives the save.
+ *    this same transaction under the same policies, and through
+ *    `visibleTargets` — the target's `beforeQuery` scope and soft delete, which
+ *    RLS knows nothing of — so a link the caller cannot read is in neither list
+ *    and survives the save.
  *  - **Junction payload columns.** A junction carrying its own columns
  *    (`position`, `role`, `created_at`) lost them on every save, because every
  *    row was re-inserted with only the two keys. Untouched links are left alone.
@@ -115,7 +131,7 @@ export declare function removeJunctionLink(tx: DrizzleClient, binding: JunctionB
  * that is what keeps a plain `[1, 2, 3]` membership write from wiping the
  * `role`s off the links it did not mention.
  */
-export declare function applyJunctionMembership(tx: DrizzleClient, binding: JunctionBinding, parentId: unknown, links: JunctionLinkWrite[]): Promise<void>;
+export declare function applyJunctionMembership(tx: DrizzleClient, binding: JunctionBinding, parentId: unknown, links: JunctionLinkWrite[], visibleTargets?: VisibleTargets): Promise<void>;
 /**
  * Set the columns of ONE existing link, without touching the membership.
  *

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.
@@ -23,25 +23,114 @@ export interface PgNotifyListenerOptions {
     logLabel: string;
     /** Delay before a reconnect attempt. */
     reconnectDelayMs?: number;
+    /**
+     * Called once the connection is listening again after a drop — never after
+     * the first connect. Postgres keeps no NOTIFY for a session that is not
+     * listening, so whatever was published while the connection was down is
+     * 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;
 }

package/dist/services/read-field-access.d.ts

@@ -0,0 +1,19 @@
+import type { CollectionConfig, FetchCollectionProps } from "@rebasepro/types";
+import type { FieldViewer } from "@rebasepro/common";
+/**
+ * Refuse a read that names a field its caller may not read, for the doors that
+ * take a driver-shaped request rather than a query string: the socket's
+ * `FETCH_COLLECTION`, `COUNT` and `CHECK_UNIQUE_FIELD`, and `subscribe_collection`.
+ * Callers hand it the request itself, not a re-listed copy of some of its keys.
+ *
+ * The row strip keeps a withheld value off the wire; this is the other half, and
+ * without it the value is still readable one predicate at a time — a `COUNT`
+ * filtered on `passwordHash like '$2b$10$A%'` answers 1 or 0. `GET /api/data`
+ * refuses the same request with `FIELD_NOT_READABLE`, and this is that rule, not
+ * a copy of it: only the request's shape is translated here.
+ *
+ * The shape arrives as whatever JSON the client sent, so it is read defensively.
+ * A malformed `orderBy` or `fields` is not this check's to reject; the entries
+ * that name a field are checked and the rest are left for the driver to refuse.
+ */
+export declare function assertReadRequestReadable(request: Pick<FetchCollectionProps, "filter" | "logical" | "orderBy" | "fields" | "include" | "vectorSearch">, collection: CollectionConfig, viewer: FieldViewer): void;