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

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

@@ -23,19 +23,14 @@ export declare function parseCdcPayload(payload: string): CdcChangeEvent | null;
 /**
  * Dedicated Postgres LISTEN client for database-level CDC.
  *
- * Mirrors the resilience of the RealtimeService cross-instance LISTEN client: a
- * standalone `pg.Client` (outside the Drizzle pool) that stays connected, and
- * transparently reconnects on error/disconnect. Each backend instance runs one,
- * so every instance observes every committed change regardless of which
- * instance (or external process) made the write.
+ * A {@link PgNotifyListener} — a connection outside the Drizzle pool that stays
+ * open and repairs itself — plus the parsing that turns a `rebase_cdc` payload
+ * into a change event. Each backend instance runs one, so every instance
+ * observes every committed change regardless of which instance (or external
+ * process) made the write.
  */
 export declare class CdcListener {
-    private readonly connectionString;
-    private readonly onEvent;
-    private client?;
-    private running;
-    private reconnectTimer?;
-    private static readonly RECONNECT_DELAY_MS;
+    private readonly listener;
     constructor(connectionString: string, onEvent: (event: CdcChangeEvent) => void | Promise<void>);
     /**
      * Connect and begin listening. Idempotent.
@@ -44,11 +39,9 @@ export declare class CdcListener {
      * established (or `LISTEN` is refused), this rejects so callers — notably
      * `REALTIME_CDC=auto` — can detect an unusable connection and fall back to
      * app-level realtime. Once the initial connection succeeds, later drops
-     * self-heal via {@link scheduleReconnect}.
+     * self-heal in the background.
      */
     start(): Promise<void>;
     /** Stop listening and release the connection. */
     stop(): Promise<void>;
-    private connect;
-    private scheduleReconnect;
 }

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

@@ -0,0 +1,29 @@
+/**
+ * Runtime pieces of the channel bus that are not the contract itself.
+ *
+ * The interface, the frame shape and the implementer's contract live in
+ * `@rebasepro/types` (`types/channel_bus.ts`), so a transport shipped as its own
+ * package — a Redis one, say — depends on the contract and not on this database
+ * adapter. They are re-exported here for convenience: code already importing
+ * from the adapter should not have to know where the types are declared.
+ */
+import type { ChannelBusFrame } from "@rebasepro/types";
+export type { ChannelBus, ChannelBusFrame, ChannelBusHandler, ChannelBusConfig, ChannelBusSetting } from "@rebasepro/types";
+export { isChannelBusInstance } from "@rebasepro/types";
+/**
+ * The default: no cross-instance delivery at all.
+ *
+ * This is what every deployment ran before the bus existed, and what a
+ * single-instance deployment should keep running — `publish` resolves without
+ * touching the network, so the broadcast path is the same handful of `ws.send`
+ * calls it always was.
+ */
+export declare class MemoryChannelBus {
+    readonly kind: "memory";
+    readonly maxFrameBytes: number;
+    start(): Promise<void>;
+    publish(): Promise<void>;
+    stop(): Promise<void>;
+}
+/** Encoded size of a frame, for a transport's size check. */
+export declare function frameByteLength(frame: ChannelBusFrame): number;

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

@@ -0,0 +1,111 @@
+/**
+ * Channel bus over Postgres LISTEN/NOTIFY.
+ *
+ * Chosen because it needs nothing that a Rebase deployment does not already
+ * have — the same database, the same direct URL the CDC listener uses. Three
+ * 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.
+ *
+ *  - **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 —
+ *    is what actually limits this transport. Measured, it carried ~10k
+ *    cross-instance messages/second and stayed flat out to eight instances; what
+ *    it should not do is spend 10k queries/second of the database's budget on
+ *    cursor movement. Hence the batching below.
+ *
+ *  - **Delivery is best-effort.** Retained channels repair themselves through
+ *    the client's history replay, so a lost frame costs a live update rather
+ *    than correctness. That is what makes coalescing safe.
+ */
+import { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { ChannelBus, ChannelBusFrame, ChannelBusHandler } from "./ChannelBus";
+/** NOTIFY channel carrying channel-bus frames. */
+export declare const CHANNEL_BUS_NOTIFY_CHANNEL = "rebase_channel_bus";
+/**
+ * Postgres refuses a NOTIFY payload of 8000 bytes or more. The margin below it
+ * is for nothing in particular — it is there so that a payload which passes this
+ * check cannot fail at the server for being a few bytes over.
+ */
+export declare const PG_NOTIFY_MAX_PAYLOAD_BYTES = 7500;
+/**
+ * How long a batching window stays open.
+ *
+ * Ten milliseconds is below the threshold where a human notices a cursor lag,
+ * and it is the difference between one query per message and one query per
+ * window under load. Set to 0 to disable coalescing entirely.
+ */
+export declare const DEFAULT_BATCH_WINDOW_MS = 10;
+export declare class PostgresChannelBus implements ChannelBus {
+    private readonly db;
+    private readonly connectionString;
+    readonly kind: "postgres";
+    readonly maxFrameBytes = 7500;
+    private listener?;
+    private readonly batchWindowMs;
+    /**
+     * Frames waiting for the current window to close.
+     *
+     * The window is opened by a publish that found none open, and that publish
+     * is sent *immediately* rather than joining a batch — see {@link publish}.
+     */
+    private pending;
+    private pendingBytes;
+    private windowTimer?;
+    private stopped;
+    constructor(db: NodePgDatabase<Record<string, unknown>>, connectionString: string, options?: {
+        batchWindowMs?: number;
+    });
+    start(handler: ChannelBusHandler): Promise<void>;
+    /**
+     * Publish, coalescing under load.
+     *
+     * The window is *leading edge*: a publish arriving when no window is open is
+     * sent straight away and opens one, so an idle channel pays no added latency
+     * at all. Frames arriving while it is open are collected and leave together
+     * when it closes. The effect is that cost tracks elapsed time rather than
+     * message count — one query per window instead of one per message — which is
+     * the same shape as the retention pruning throttle, for the same reason.
+     *
+     * The returned promise settles when the frame has actually left, not when it
+     * was queued, so the contract ("reaches the other instances, or rejects")
+     * still holds.
+     */
+    publish(frame: ChannelBusFrame): Promise<void>;
+    stop(): Promise<void>;
+    private openWindow;
+    /** Send everything queued and settle the promises waiting on it. */
+    private flush;
+    /**
+     * One NOTIFY.
+     *
+     * A single frame goes out in the plain, unwrapped shape. That is not just
+     * economy: during a rolling deploy an instance running the previous build
+     * understands only that shape, and low-rate traffic — presence, the tail of
+     * a session — is exactly what is flowing while pods restart. Batching only
+     * appears under load, which shrinks the mixed-version window to almost
+     * nothing.
+     */
+    private send;
+}
+/**
+ * Parse a bus payload into the frames it carries.
+ *
+ * Accepts both wire shapes — a bare frame and a `{ batch: [...] }` envelope —
+ * so an instance on the new build understands one on the old. Returns an empty
+ * array for anything unrecognisable: a malformed or future-versioned message
+ * must never take the listener down.
+ */
+export declare function parseChannelBusPayload(payload: string): ChannelBusFrame[];
+/**
+ * Parse a single bus frame, returning null for anything that is not a frame we
+ * understand.
+ */
+export declare function parseChannelBusFrame(payload: string): ChannelBusFrame | null;

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

@@ -0,0 +1,55 @@
+/**
+ * Resolution of the channel bus from config, environment, or a supplied instance.
+ *
+ * Opt-in, like every other cross-cutting realtime switch here: with nothing
+ * configured a deployment gets the memory bus and behaves exactly as it did
+ * before this existed. Unlike `REALTIME_CDC=auto`, there is no "try it and see"
+ * default — a bus changes where messages go, and quietly turning on a Postgres
+ * NOTIFY per broadcast because a direct URL happened to be set is not a
+ * decision to make on the user's behalf.
+ *
+ * Two transports ship, and neither adds a service to a deployment. A third is
+ * not a code change here: `realtime.bus` also accepts an already-constructed
+ * {@link ChannelBus}, so a transport published as its own package plugs in
+ * without this file learning about it. See `@rebasepro/types` →
+ * `types/channel_bus.ts` for the contract such a package implements.
+ */
+import { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { type ChannelBus, type ChannelBusConfig, type ChannelBusSetting } from "@rebasepro/types";
+export * from "./ChannelBus";
+export { PostgresChannelBus, CHANNEL_BUS_NOTIFY_CHANNEL, PG_NOTIFY_MAX_PAYLOAD_BYTES, DEFAULT_BATCH_WINDOW_MS, parseChannelBusFrame, parseChannelBusPayload } from "./PostgresChannelBus";
+export interface ChannelBusDeps {
+    db: NodePgDatabase<Record<string, unknown>>;
+    /**
+     * Direct (non-pooled) Postgres URL for the LISTEN client. `LISTEN` is
+     * session state, so behind PgBouncer in transaction mode this must be the
+     * database itself and not the pooler.
+     */
+    directUrl?: string;
+}
+/**
+ * Merge `REALTIME_CHANNEL_BUS` into the configured bus.
+ *
+ * The environment wins over a *named* built-in, so the transport can be changed
+ * per deployment without a rebuild — the same reason `REALTIME_CDC` is an env
+ * var. It does **not** win over a supplied instance: the env var can only name
+ * transports this package knows how to construct, so honouring it there would
+ * mean silently discarding the object the application handed us.
+ */
+export declare function resolveChannelBusSetting(configured?: ChannelBusSetting): ChannelBusSetting;
+/**
+ * @deprecated Use {@link resolveChannelBusSetting}, which also accepts a
+ * supplied {@link ChannelBus} instance. Kept as a narrow alias so existing
+ * config-only callers keep their exact types.
+ */
+export declare function resolveChannelBusConfig(configured?: ChannelBusConfig): ChannelBusConfig;
+/**
+ * Produce the bus a setting asks for.
+ *
+ * An instance is handed straight back — constructing it was the application's
+ * job, and this function has nothing to add. A named built-in that turns out to
+ * be unusable degrades to the memory bus, with the reason logged, rather than
+ * throwing: a misconfigured bus should cost a deployment its cross-instance
+ * fan-out, not its ability to boot.
+ */
+export declare function createChannelBus(setting: ChannelBusSetting, deps: ChannelBusDeps): ChannelBus;

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

@@ -105,6 +105,17 @@ export declare class ChannelHistoryStore {
         messages: ChannelHistoryEntry[];
         latestSeq: number;
     }>;
+    /**
+     * One retained message by its address.
+     *
+     * This is what makes the cross-instance pointer path work: a broadcast too
+     * large to travel inside a `pg_notify` payload is already stored here, so
+     * the notification carries `(channel, seq)` and each receiving instance
+     * reads the body back. Returns null when the message has since been pruned
+     * — a receiver that is that far behind has nothing useful to deliver, and
+     * the client's own `channel_history` replay is the repair path.
+     */
+    getBySeq(channel: string, seq: number): Promise<ChannelHistoryEntry | null>;
     /**
      * Enforce a channel's retention bounds.
      *

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

@@ -0,0 +1,66 @@
+/**
+ * The shared presence roster.
+ *
+ * Broadcast only ever needed *fan-out* to work across instances — a frame goes
+ * out, whoever is connected receives it. Presence needs more than that, because
+ * `presence_state` is a question ("who is in this document?") and a per-process
+ * `Map` can only answer for the clients that happen to share a replica with the
+ * asker. Two people editing the same scene through different pods would each
+ * see an empty room while broadcasting cursors at each other perfectly.
+ *
+ * So presence gets one row per tracked client, in Postgres, readable by every
+ * instance. Three consequences worth stating:
+ *
+ *  - **The table is the roster; the in-process map is a cache of our own
+ *    clients.** Reads answer from the table when this store is active, so the
+ *    answer is the same whichever instance is asked.
+ *
+ *  - **`last_seen` is the liveness signal, and it is already there.** The client
+ *    heartbeats presence every ~20 s against a 30 s window; the sweep that has
+ *    always reaped local stale entries now also reaps rows belonging to
+ *    instances that stopped writing — which is exactly what a crashed pod looks
+ *    like. Crash recovery is a property of the TTL, not a separate mechanism.
+ *
+ *  - **The sweep deletes with `RETURNING`.** Whichever instance wins the delete
+ *    is the one that announces the departures, so a stale client produces one
+ *    `presence_diff` for the cluster rather than one per replica.
+ */
+import { NodePgDatabase } from "drizzle-orm/node-postgres";
+/** A tracked client, as any instance sees it. */
+export interface PresenceRow {
+    channel: string;
+    clientId: string;
+    state: Record<string, unknown>;
+}
+export declare class ChannelPresenceStore {
+    private readonly db;
+    private readonly instanceId;
+    private tablesReady;
+    constructor(db: NodePgDatabase<Record<string, unknown>>, instanceId: string);
+    /** Create the roster table. Idempotent. */
+    ensureTables(): Promise<void>;
+    /** Record (or refresh) a client's presence. */
+    track(channel: string, clientId: string, state: Record<string, unknown>): Promise<void>;
+    /** Drop one client's presence in one channel. */
+    remove(channel: string, clientId: string): Promise<void>;
+    /** Drop a client from every channel — used when its socket closes. */
+    removeClient(clientId: string): Promise<void>;
+    /** The global roster for a channel. */
+    roster(channel: string): Promise<Record<string, Record<string, unknown>>>;
+    /**
+     * Reap rows this instance is not responsible for and that have gone quiet.
+     *
+     * Own rows are excluded because the in-process sweep already handles them —
+     * and handles them better, since it can tell "the socket is gone" from "the
+     * heartbeat is late". What is left is precisely the interesting case: rows
+     * written by an instance that is no longer writing.
+     *
+     * Returns what was removed, so the caller can announce it.
+     */
+    sweepStale(ttlMs: number): Promise<PresenceRow[]>;
+    /**
+     * Remove every row this instance owns. Called on graceful shutdown so a
+     * rolling deploy does not leave a TTL window of ghosts in every roster.
+     */
+    removeInstance(): Promise<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;
@@ -245,6 +271,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 +330,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.
      *

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/server-postgres",
   "type": "module",
-  "version": "0.10.1-canary.6f89f77",
+  "version": "0.10.1-canary.7609565",
   "description": "PostgreSQL data source backend implementation for Rebase with Drizzle ORM",
   "funding": {
     "url": "https://github.com/sponsors/rebaseco"
@@ -47,11 +47,11 @@
     "execa": "^9.6.1",
     "pg": "^8.21.0",
     "ws": "^8.21.0",
-    "@rebasepro/codegen": "0.10.1-canary.6f89f77",
-    "@rebasepro/server": "0.10.1-canary.6f89f77",
-    "@rebasepro/common": "0.10.1-canary.6f89f77",
-    "@rebasepro/utils": "0.10.1-canary.6f89f77",
-    "@rebasepro/types": "0.10.1-canary.6f89f77"
+    "@rebasepro/codegen": "0.10.1-canary.7609565",
+    "@rebasepro/common": "0.10.1-canary.7609565",
+    "@rebasepro/server": "0.10.1-canary.7609565",
+    "@rebasepro/utils": "0.10.1-canary.7609565",
+    "@rebasepro/types": "0.10.1-canary.7609565"
   },
   "devDependencies": {
     "@hono/node-server": "^2.0.9",

package/src/PostgresBootstrapper.ts

@@ -37,6 +37,8 @@ import { buildCollectionsFromSchema, introspectSchema, readRlsStatus } from "./s
 import { buildDrizzleTablesFromSchema, buildDrizzleRelationsFromSchema } from "./schema/dynamic-tables";
 import { detectConnectionPosture, ensureAppRole, validatePolicyPgRoles, warnOnAnonymousGrants, REBASE_USER_ROLE, type RawSqlRunner } from "./security/rls-enforcement";
 import { provisionTriggerCdc, type CdcTableRef } from "./services/cdc/trigger-cdc";
+import { createChannelBus, resolveChannelBusSetting } from "./services/channel-bus";
+import { isChannelBusInstance } from "@rebasepro/types";
 
 export interface PostgresDriverConfig {
     connectionString?: string;
@@ -54,9 +56,13 @@ export interface PostgresDriverConfig {
      */
     introspectionSchema?: string;
     /**
-     * Realtime options. Currently only channel retention, which is opt-in:
-     * without rules here no channel keeps any history and broadcast stays
-     * fire-and-forget. See {@link ChannelRetentionRule}.
+     * Realtime options, both opt-in:
+     *
+     *  - `channels` — retention. Without rules no channel keeps any history and
+     *    broadcast stays fire-and-forget. See {@link ChannelRetentionRule}.
+     *  - `bus` — the cross-instance transport for channel broadcast and
+     *    presence. Defaults to in-process only, which is correct for a single
+     *    instance and wrong for two. See {@link ChannelBusConfig}.
      */
     realtime?: RealtimeChannelsConfig;
 }
@@ -337,6 +343,29 @@ export function createPostgresBootstrapper(pgConfig: PostgresDriverConfig): Back
             // Prefer DATABASE_DIRECT_URL to bypass PgBouncer for LISTEN/NOTIFY.
             const directUrl = process.env.DATABASE_DIRECT_URL || pgConfig.connectionString;
 
+            // ── Cross-instance channel bus ───────────────────────────────────
+            // Entity changes already span instances (CDC / LISTEN below).
+            // Channel broadcast and presence did not — they lived in per-process
+            // maps, so behind two replicas the clients of one were invisible to
+            // the other. Opt-in, and a no-op when left at "memory".
+            try {
+                const busSetting = resolveChannelBusSetting(pgConfig.realtime?.bus);
+                // A supplied instance is always installed; a named built-in only
+                // when it is not the in-process default, so the common case
+                // touches none of this machinery.
+                const wantsBus = isChannelBusInstance(busSetting) || busSetting.type !== "memory";
+                if (wantsBus) {
+                    await realtimeService.configureChannelBus(
+                        createChannelBus(busSetting, {
+                            db: schemaAwareDb as unknown as NodePgDatabase<Record<string, unknown>>,
+                            directUrl
+                        })
+                    );
+                }
+            } catch (err) {
+                logger.warn("⚠️ [ChannelBus] Could not configure the channel bus — channel broadcast and presence stay per-instance", { error: err });
+            }
+
             // Database-level Change Data Capture. When active, realtime events are
             // emitted for EVERY committed write — including ones that bypass the
             // Rebase API (psql, another service's cron, raw SQL, the Studio SQL

package/src/index.ts

@@ -7,6 +7,10 @@ export * from "./schema/generate-drizzle-schema-logic";
 export * from "./schema/generate-drizzle-schema";
 export * from "./utils/drizzle-conditions";
 export * from "./services/realtimeService";
+// The channel bus is a public extension point: a transport published as its own
+// package implements `ChannelBus` (declared in @rebasepro/types and re-exported
+// here) and is passed to `realtime.bus`. Without this export it would be one.
+export * from "./services/channel-bus";
 export * from "./websocket";
 export * from "./collections/PostgresCollectionRegistry";
 export * from "./services/BranchService";