@rebasepro/server-postgres 0.10.1-canary.6f89f77 → 0.10.1-canary.7801eed

package/dist/services/nested-path.d.ts

@@ -0,0 +1,59 @@
+import { CollectionConfig, ResolvedRelation } from "@rebasepro/types";
+import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
+/**
+ * The last hop of a nested collection path, e.g. `authors/1/posts`.
+ *
+ * The walk that produces this was written out four separate times — in
+ * `FetchService.fetchCollectionFromPath`, `FetchService.countEntitiesFromPath`,
+ * `PersistService.save` and `CollectionRegistry.getCollectionByPath` — and had
+ * drifted, so the read path and the write path did not agree on which relation
+ * a path named. It lives here once now.
+ */
+export interface NestedPathHop {
+    /** The collection the final relation is declared on (e.g. `authors`). */
+    parentCollection: CollectionConfig;
+    /** The parent's id as it appeared in the path, unparsed. */
+    parentId: string;
+    /** The path segment that named the relation (e.g. `posts`). */
+    relationKey: string;
+    relation: ResolvedRelation;
+    /** `relation.target()`, resolved once. */
+    targetCollection: CollectionConfig;
+}
+/**
+ * True when `path` addresses rows through a relation rather than a root
+ * collection.
+ *
+ * Any separator at all counts — a root collection slug never contains one — so
+ * a malformed path like `collection/id` is a *broken* nested path and gets
+ * reported as one by {@link resolveNestedPath}, rather than being looked up as
+ * a root collection whose slug happens to contain a slash.
+ */
+export declare function isNestedPath(path: string): boolean;
+export declare function splitPathSegments(path: string): string[];
+/**
+ * Walk a nested collection path down to the relation it ends in.
+ *
+ * Returns `undefined` for a plain root-collection path so callers can keep the
+ * root case on its existing code path. Throws when the path is malformed, or
+ * when a segment names a relation that does not exist — the same errors the
+ * individual walks used to raise, with the available names attached.
+ */
+export declare function resolveNestedPath(path: string, registry: PostgresCollectionRegistry): NestedPathHop | undefined;
+/**
+ * A relation reached through a junction table — many-to-many, or a multi-hop
+ * `joinPath`. The target row is shared with other parents, so writing "through"
+ * such a path addresses the *link*, not the row.
+ */
+export declare function isJunctionBackedRelation(relation: ResolvedRelation): boolean;
+/**
+ * Reject a nested write whose final segment is a to-one relation.
+ *
+ * There is no column on the target row that records a to-one parent — the
+ * foreign key lives on the *parent* table. The write path used to fall through
+ * to `relation.localKey` here and stamp the parent's own FK column onto the
+ * target row, which either raised an opaque "column does not exist" or, when a
+ * column of that name happened to exist on the target, silently wrote the wrong
+ * one.
+ */
+export declare function assertWritableThrough(hop: NestedPathHop, path: string): void;

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

@@ -0,0 +1,47 @@
+/**
+ * A dedicated, self-healing Postgres `LISTEN` connection.
+ *
+ * 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.
+ *
+ * `LISTEN` is session state, so this connection must not go through a
+ * transaction-mode pooler (PgBouncer): give it the direct database URL.
+ */
+export interface PgNotifyListenerOptions {
+    /** Direct Postgres connection string (must bypass a transaction-mode pooler). */
+    connectionString: string;
+    /** NOTIFY channel to LISTEN on. Must be a plain identifier — it is interpolated. */
+    channel: string;
+    /** Called for every notification payload received. */
+    onPayload: (payload: string) => void | Promise<void>;
+    /** Prefix for log lines, e.g. `"[CDC]"`. */
+    logLabel: string;
+    /** Delay before a reconnect attempt. */
+    reconnectDelayMs?: number;
+}
+export declare class PgNotifyListener {
+    private readonly options;
+    private client?;
+    private running;
+    private reconnectTimer?;
+    constructor(options: PgNotifyListenerOptions);
+    /** Whether the listener is meant to be connected right now. */
+    get active(): boolean;
+    /**
+     * 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.
+     */
+    start(): Promise<void>;
+    /** Stop listening and release the connection. Idempotent. */
+    stop(): Promise<void>;
+    private connect;
+    private scheduleReconnect;
+}

package/dist/services/realtimeService.d.ts

@@ -4,6 +4,7 @@ import { DataDriver, WebSocketMessage } from "@rebasepro/types";
 import { NodePgDatabase } from "drizzle-orm/node-postgres";
 import { RealtimeProvider, CollectionSubscriptionConfig, SingleSubscriptionConfig } from "../interfaces";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
+import { ChannelBus } from "./channel-bus";
 import type { ChannelRetentionRule } from "@rebasepro/types";
 /**
  * Auth context stored per-subscription so real-time refetches respect RLS.
@@ -45,8 +46,33 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      * wait on each other.
      */
     private channelSendQueues;
+    /**
+     * Cross-instance transport for channel frames and presence.
+     *
+     * Defaults to the memory bus, which publishes nowhere — so a single-instance
+     * deployment runs the same fan-out it always did, with one resolved promise
+     * per broadcast for company. See `channel-bus/ChannelBus.ts`.
+     */
+    private bus;
+    /**
+     * The shared presence roster, present only when a real bus is active.
+     *
+     * Fan-out alone is not enough for presence: `presence_state` has to answer
+     * with everyone in the channel, and per-process maps can only answer for
+     * this replica's clients. See `channel-presence.ts`.
+     */
+    private presenceStore?;
+    /** Sweeps roster rows left behind by instances that stopped heartbeating. */
+    private presenceSweepInterval?;
+    /**
+     * Channels whose oversized ephemeral broadcasts have already been reported,
+     * so a hot channel logs the problem once rather than once per message.
+     */
+    private oversizedBroadcastWarned;
     private presenceInterval?;
     private static readonly PRESENCE_TIMEOUT_MS;
+    /** How often stale roster rows from other instances are reaped. */
+    private static readonly PRESENCE_SWEEP_INTERVAL_MS;
     private dataService;
     private _subscriptions;
     private subscriptionCallbacks;
@@ -69,6 +95,8 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
     private cdcListener?;
     /** Whether database-level CDC is the active cross-instance change source. */
     private cdcActive;
+    /** Junction table → the child lists its rows belong to, built when CDC starts. */
+    private junctionLinkMap?;
     /** Reverse lookup: `schema.table` (and bare `table`) → collection, built when CDC starts. */
     private cdcTableMap?;
     /**
@@ -245,6 +273,44 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
     private persistAndFanOut;
     /** Deliver a broadcast frame to every member of a channel but the sender. */
     private fanOutBroadcast;
+    /**
+     * Install the transport that carries channel frames between instances.
+     *
+     * Called once at boot. A bus that cannot start is reported and replaced with
+     * the memory bus: losing cross-instance fan-out degrades collaboration to
+     * what it was before this existed, whereas refusing to boot takes the whole
+     * backend down for it.
+     */
+    configureChannelBus(bus: ChannelBus): Promise<void>;
+    /** Which transport is in use — `"memory"` means per-instance only. */
+    getChannelBusKind(): ChannelBus["kind"];
+    /**
+     * Send a broadcast to the other instances.
+     *
+     * Fire-and-forget by design: the clients on this instance have already been
+     * served, and a bus that is briefly unreachable must not turn a broadcast
+     * into an error for the sender.
+     */
+    private publishBroadcast;
+    private publishFrame;
+    /**
+     * Tell the sender that a message was delivered locally but nowhere else.
+     *
+     * Staying quiet here would be the worst option available: on one instance
+     * the app works, on two it works for half the users, and nothing in the
+     * logs connects the two. The fix is a one-liner in config — give the
+     * channel a retention rule and the message travels as a pointer instead —
+     * so the message says exactly that.
+     */
+    private reportOversizedBroadcast;
+    /**
+     * Deliver a frame published by another instance to this one's clients.
+     *
+     * Frames we published ourselves are dropped on arrival — the local fan-out
+     * happened before the publish — exactly as the entity-change handler skips
+     * its own `sid`.
+     */
+    private handleBusFrame;
     /**
      * Install retention rules and create the tables they need.
      *
@@ -266,16 +332,60 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      */
     private handleChannelHistoryRequest;
     private sendChannelHistory;
-    /** Track presence in a channel */
+    /**
+     * Track presence in a channel.
+     *
+     * The client re-sends this every ~20s as a heartbeat against the 30s
+     * timeout, so most calls carry the state that is already recorded. Those
+     * refresh `last_seen` and stop there: re-announcing an unchanged state to
+     * every instance would put a bus message per client per heartbeat on the
+     * wire to tell everyone nothing happened.
+     */
     trackPresence(clientId: string, channel: string, state: Record<string, unknown>): void;
-    /** Remove presence from a channel */
-    removePresence(clientId: string, channel: string): void;
-    /** Send full presence state to a specific client */
+    /**
+     * Remove presence from a channel.
+     *
+     * `skipStore` is for the socket-close path, which clears every channel at
+     * once and then deletes the client's rows in a single statement instead of
+     * one per channel.
+     */
+    removePresence(clientId: string, channel: string, options?: {
+        skipStore?: boolean;
+    }): void;
+    /**
+     * Send the full roster for a channel to one client.
+     *
+     * Answered from the shared table when there is one, because "who is in this
+     * document?" has a single answer that must not depend on which replica the
+     * asker happens to be connected to. Without a bus there is nothing to share
+     * and the local map *is* the roster — that path stays synchronous, which is
+     * what it always was.
+     */
     sendPresenceState(clientId: string, channel: string): void;
-    /** Broadcast presence diff (joins/leaves) to channel */
-    private broadcastPresenceDiff;
+    /** Presence of the clients connected to this instance. */
+    private localPresences;
+    private sendPresenceStateMessage;
+    /** Deliver a presence diff to this instance's members of the channel. */
+    private deliverPresenceDiff;
+    /** Tell the other instances about a presence change. */
+    private publishPresenceDiff;
+    /** Run a roster write when there is a roster, and never let it throw. */
+    private presenceStoreOp;
     /** Periodic cleanup for stale presences */
     private ensurePresenceCleanup;
+    /**
+     * Reap roster rows whose owning instance stopped heartbeating.
+     *
+     * This is the cross-instance half of the sweep above, and it doubles as
+     * crash recovery: a pod that dies takes its clients with it but leaves
+     * their rows behind, and after one TTL window they look exactly like any
+     * other client that went quiet. The delete returns what it removed, so
+     * whichever instance wins the race is the one that announces the
+     * departures — once for the cluster, not once per replica.
+     */
+    private ensurePresenceSweep;
+    /** One pass of the stale-roster sweep. See {@link ensurePresenceSweep}. */
+    private sweepStalePresence;
     /**
      * Gracefully tear down all realtime resources.
      *
@@ -329,6 +439,23 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      * subscriber, never per publisher.
      */
     private handleCdcEvent;
+    /**
+     * Deliver a change on a many-to-many junction table as a change to the child
+     * lists it belongs to.
+     *
+     * Linking a tag to a post writes only `posts_tags`. That table backs no
+     * collection, so change capture dropped the event as unmapped and the
+     * subscribers of `posts/1/tags` never heard about it — every other write in
+     * the system was realtime, and this one silently was not. The junction row
+     * carries both ids, so it names its own paths exactly.
+     *
+     * Notifies the nested path rather than either endpoint collection, because
+     * invalidation walks *parent* paths and never child ones: telling `tags` it
+     * changed would not reach a subscription on `posts/1/tags`.
+     *
+     * Returns whether the table was recognised as a junction.
+     */
+    private handleJunctionCdcEvent;
     /** Compute the canonical (possibly composite) id string from a captured row. */
     private extractIdFromCdcRow;
     private dedupKey;

package/dist/services/row-pipeline.d.ts

@@ -1,4 +1,4 @@
-import { CollectionConfig, Relation } from "@rebasepro/types";
+import { CollectionConfig, ResolvedRelation } from "@rebasepro/types";
 import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
 /**
  * Turning a drizzle result into a row we serve.
@@ -26,7 +26,7 @@ export type RelationStyle = "ref" | "inline";
  * the query has to nest one level deeper for a junction, and the row walk has
  * to unwrap that same level back out.
  */
-export declare function isJunctionRelation(relation: Relation): boolean;
+export declare function isJunctionRelation(relation: ResolvedRelation): boolean;
 /**
  * The address a relation ref points at.
  *