@rebasepro/server-postgres 0.10.0 → 0.10.1-canary.0a881d4

package/src/services/channel-bus/index.ts

@@ -0,0 +1,123 @@
+/**
+ * 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 { isChannelBusInstance, type ChannelBus, type ChannelBusConfig, type ChannelBusSetting } from "@rebasepro/types";
+import { logger } from "@rebasepro/server";
+import { MemoryChannelBus } from "./ChannelBus";
+import { PostgresChannelBus } from "./PostgresChannelBus";
+
+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 function resolveChannelBusSetting(configured?: ChannelBusSetting): ChannelBusSetting {
+    const raw = (process.env.REALTIME_CHANNEL_BUS || "").trim().toLowerCase();
+
+    if (isChannelBusInstance(configured)) {
+        if (raw && raw !== configured.kind) {
+            logger.warn(
+                `⚠️ [ChannelBus] REALTIME_CHANNEL_BUS="${raw}" is ignored because realtime.bus was given a ` +
+                `"${configured.kind}" transport instance directly. Remove one of the two to make the intent clear.`
+            );
+        }
+        return configured;
+    }
+
+    if (!raw) return configured ?? { type: "memory" };
+
+    if (raw !== "memory" && raw !== "postgres") {
+        logger.warn(
+            `⚠️ [ChannelBus] Unknown REALTIME_CHANNEL_BUS value "${raw}" — expected memory|postgres, or pass a ` +
+            "ChannelBus instance as realtime.bus for a transport that ships separately. Falling back to the " +
+            "configured bus."
+        );
+        return configured ?? { type: "memory" };
+    }
+
+    // Keep the configured options (an explicit connection string) when the env
+    // var only restates the type it was already set to.
+    if (configured?.type === raw) return configured;
+    return raw === "memory" ? { type: "memory" } : { type: "postgres" };
+}
+
+/**
+ * @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 function resolveChannelBusConfig(configured?: ChannelBusConfig): ChannelBusConfig {
+    return resolveChannelBusSetting(configured) as 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 function createChannelBus(setting: ChannelBusSetting, deps: ChannelBusDeps): ChannelBus {
+    if (isChannelBusInstance(setting)) return setting;
+
+    switch (setting.type) {
+        case "postgres": {
+            const connectionString = setting.connectionString || deps.directUrl;
+            if (!connectionString) {
+                logger.warn(
+                    "⚠️ [ChannelBus] realtime.bus is \"postgres\" but no direct database URL is available " +
+                    "(set DATABASE_DIRECT_URL or realtime.bus.connectionString) — channel broadcast and presence " +
+                    "stay per-instance."
+                );
+                return new MemoryChannelBus();
+            }
+            return new PostgresChannelBus(deps.db, connectionString, {
+                batchWindowMs: setting.batchWindowMs
+            });
+        }
+        case "memory":
+        default:
+            return new MemoryChannelBus();
+    }
+}

package/src/services/channel-history.ts

@@ -290,6 +290,41 @@ export class ChannelHistoryStore {
         return { messages, latestSeq };
     }
 
+    /**
+     * 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.
+     */
+    async getBySeq(channel: string, seq: number): Promise<ChannelHistoryEntry | null> {
+        const result = await this.db.execute(sql`
+            SELECT seq, event, payload, sender_id, created_at
+            FROM rebase.channel_messages
+            WHERE channel = ${channel} AND seq = ${seq}
+        `);
+
+        const row = result.rows[0] as {
+            seq: string | number;
+            event: string;
+            payload: unknown;
+            sender_id: string | null;
+            created_at: Date | string;
+        } | undefined;
+        if (!row) return null;
+
+        return {
+            seq: Number(row.seq),
+            event: row.event,
+            payload: row.payload,
+            senderId: row.sender_id ?? undefined,
+            at: row.created_at instanceof Date ? row.created_at.toISOString() : String(row.created_at)
+        };
+    }
+
     /**
      * Enforce a channel's retention bounds.
      *

package/src/services/channel-presence.ts

@@ -0,0 +1,148 @@
+/**
+ * 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 { sql } from "drizzle-orm";
+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 class ChannelPresenceStore {
+    private tablesReady = false;
+
+    constructor(
+        private readonly db: NodePgDatabase<Record<string, unknown>>,
+        private readonly instanceId: string
+    ) {}
+
+    /** Create the roster table. Idempotent. */
+    async ensureTables(): Promise<void> {
+        if (this.tablesReady) return;
+
+        await this.db.execute(sql`CREATE SCHEMA IF NOT EXISTS rebase`);
+
+        // Keyed by (channel, client_id): a client id is globally unique, so the
+        // instance is a column rather than part of the identity — a client that
+        // reconnects onto another replica replaces its own row instead of
+        // appearing twice in the roster.
+        await this.db.execute(sql`
+            CREATE TABLE IF NOT EXISTS rebase.channel_presence (
+                channel TEXT NOT NULL,
+                client_id TEXT NOT NULL,
+                instance_id TEXT NOT NULL,
+                state JSONB NOT NULL DEFAULT '{}'::jsonb,
+                last_seen TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+                PRIMARY KEY (channel, client_id)
+            )
+        `);
+
+        // The sweep's access path; the roster read rides the primary key.
+        await this.db.execute(sql`
+            CREATE INDEX IF NOT EXISTS idx_channel_presence_last_seen
+            ON rebase.channel_presence (last_seen)
+        `);
+
+        this.tablesReady = true;
+    }
+
+    /** Record (or refresh) a client's presence. */
+    async track(channel: string, clientId: string, state: Record<string, unknown>): Promise<void> {
+        await this.db.execute(sql`
+            INSERT INTO rebase.channel_presence (channel, client_id, instance_id, state, last_seen)
+            VALUES (${channel}, ${clientId}, ${this.instanceId}, ${JSON.stringify(state ?? {})}::jsonb, NOW())
+            ON CONFLICT (channel, client_id) DO UPDATE
+            SET state = EXCLUDED.state,
+                instance_id = EXCLUDED.instance_id,
+                last_seen = NOW()
+        `);
+    }
+
+    /** Drop one client's presence in one channel. */
+    async remove(channel: string, clientId: string): Promise<void> {
+        await this.db.execute(sql`
+            DELETE FROM rebase.channel_presence
+            WHERE channel = ${channel} AND client_id = ${clientId}
+        `);
+    }
+
+    /** Drop a client from every channel — used when its socket closes. */
+    async removeClient(clientId: string): Promise<void> {
+        await this.db.execute(sql`
+            DELETE FROM rebase.channel_presence WHERE client_id = ${clientId}
+        `);
+    }
+
+    /** The global roster for a channel. */
+    async roster(channel: string): Promise<Record<string, Record<string, unknown>>> {
+        const result = await this.db.execute(sql`
+            SELECT client_id, state FROM rebase.channel_presence WHERE channel = ${channel}
+        `);
+
+        const presences: Record<string, Record<string, unknown>> = {};
+        for (const row of result.rows as Array<{ client_id: string; state: Record<string, unknown> | null }>) {
+            presences[row.client_id] = row.state ?? {};
+        }
+        return presences;
+    }
+
+    /**
+     * 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.
+     */
+    async sweepStale(ttlMs: number): Promise<PresenceRow[]> {
+        const result = await this.db.execute(sql`
+            DELETE FROM rebase.channel_presence
+            WHERE instance_id <> ${this.instanceId}
+              AND last_seen < NOW() - MAKE_INTERVAL(secs => ${ttlMs / 1000})
+            RETURNING channel, client_id, state
+        `);
+
+        return (result.rows as Array<{ channel: string; client_id: string; state: Record<string, unknown> | null }>)
+            .map(row => ({ channel: row.channel, clientId: row.client_id, state: row.state ?? {} }));
+    }
+
+    /**
+     * 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.
+     */
+    async removeInstance(): Promise<void> {
+        await this.db.execute(sql`
+            DELETE FROM rebase.channel_presence WHERE instance_id = ${this.instanceId}
+        `);
+    }
+}

package/src/services/pg-notify-listener.ts

@@ -0,0 +1,137 @@
+/**
+ * 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.
+ */
+
+import { Client as PgClient } from "pg";
+import { logger } from "@rebasepro/server";
+
+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;
+}
+
+const DEFAULT_RECONNECT_DELAY_MS = 3000;
+/** Guards the identifier interpolated into `LISTEN`. */
+const SAFE_CHANNEL = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+export class PgNotifyListener {
+    private client?: PgClient;
+    private running = false;
+    private reconnectTimer?: ReturnType<typeof setTimeout>;
+
+    constructor(private readonly options: PgNotifyListenerOptions) {
+        if (!SAFE_CHANNEL.test(options.channel)) {
+            throw new Error(`Unsafe NOTIFY channel name "${options.channel}" — expected a plain SQL identifier.`);
+        }
+    }
+
+    /** Whether the listener is meant to be connected right now. */
+    get active(): boolean {
+        return this.running;
+    }
+
+    /**
+     * 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.
+     */
+    async start(): Promise<void> {
+        if (this.running) return;
+        this.running = true;
+        try {
+            await this.connect({ initial: true });
+        } catch (err) {
+            this.running = false;
+            throw err;
+        }
+    }
+
+    /** Stop listening and release the connection. Idempotent. */
+    async stop(): Promise<void> {
+        this.running = false;
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = undefined;
+        }
+        if (this.client) {
+            try {
+                await this.client.end();
+            } catch { /* ignore close errors */ }
+            this.client = undefined;
+        }
+    }
+
+    private async connect({ initial = false }: { initial?: boolean } = {}): Promise<void> {
+        const { connectionString, channel, onPayload, logLabel } = this.options;
+        try {
+            const client = new PgClient({ connectionString });
+
+            client.on("error", (err) => {
+                logger.error(`❌ ${logLabel} LISTEN client error`, { detail: err.message });
+                this.scheduleReconnect();
+            });
+
+            client.on("end", () => {
+                if (this.running) {
+                    logger.warn(`⚠️ ${logLabel} LISTEN client disconnected unexpectedly.`);
+                    this.scheduleReconnect();
+                }
+            });
+
+            client.on("notification", (msg) => {
+                if (!msg.payload) return;
+                // A handler rejection must never surface as an unhandled
+                // rejection inside the pg client's event emitter.
+                Promise.resolve(onPayload(msg.payload)).catch((err) =>
+                    logger.error(`❌ ${logLabel} Error handling notification`, { error: err })
+                );
+            });
+
+            await client.connect();
+            await client.query(`LISTEN ${channel}`);
+            this.client = client;
+            logger.info(`📡 ${logLabel} Listening on channel "${channel}".`);
+        } catch (err) {
+            // Surface the initial failure so callers can choose to fall back;
+            // for reconnects, keep retrying quietly in the background.
+            if (initial) throw err;
+            logger.error(`❌ ${logLabel} Failed to connect LISTEN client`, { error: err });
+            this.scheduleReconnect();
+        }
+    }
+
+    private scheduleReconnect(): void {
+        if (!this.running || this.reconnectTimer) return;
+
+        this.reconnectTimer = setTimeout(async () => {
+            this.reconnectTimer = undefined;
+            if (!this.running) return;
+            if (this.client) {
+                try { await this.client.end(); } catch { /* ignore */ }
+                this.client = undefined;
+            }
+            await this.connect();
+        }, this.options.reconnectDelayMs ?? DEFAULT_RECONNECT_DELAY_MS);
+    }
+}