@rebasepro/server-postgres 0.0.1-canary.4829d6e

package/dist/services/realtimeService.d.ts

@@ -0,0 +1,298 @@
+import { WebSocket } from "ws";
+import { EventEmitter } from "events";
+import { DataDriver, WebSocketMessage } from "@rebasepro/types";
+import { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { RealtimeProvider, CollectionSubscriptionConfig, SingleSubscriptionConfig } from "../interfaces";
+import { PostgresCollectionRegistry } from "../collections/PostgresCollectionRegistry";
+/**
+ * Auth context stored per-subscription so real-time refetches respect RLS.
+ * Mirrors the session variables set by PostgresBackendDriver.withAuth().
+ */
+export interface SubscriptionAuthContext {
+    userId: string;
+    roles: string[];
+}
+/**
+ * PostgreSQL-specific realtime service.
+ * Handles WebSocket connections and subscriptions for real-time row updates.
+ *
+ * Implements the RealtimeProvider interface for database abstraction.
+ */
+export declare class RealtimeService extends EventEmitter implements RealtimeProvider {
+    private db;
+    private registry;
+    private clients;
+    private channels;
+    private presence;
+    private presenceInterval?;
+    private static readonly PRESENCE_TIMEOUT_MS;
+    private dataService;
+    private _subscriptions;
+    private subscriptionCallbacks;
+    private driver?;
+    /** Unique identifier for this process instance, used to skip own notifications. */
+    private readonly instanceId;
+    /** Dedicated pg.Client for LISTEN (outside the Drizzle pool). */
+    private listenClient?;
+    /** Connection string used for reconnecting the LISTEN client. */
+    private listenConnectionString?;
+    /** Whether cross-instance broadcasting is active. */
+    private broadcasting;
+    /** Reconnection timer handle. */
+    private reconnectTimer?;
+    /** Debounce timers for collection refetches to prevent refetch storms. */
+    private refetchTimers;
+    /** Debounce window (ms) for coalescing rapid row updates into a single correctness refetch. */
+    private static readonly REFETCH_DEBOUNCE_MS;
+    /** Dedicated LISTEN client for DB-level change events (undefined unless CDC is enabled). */
+    private cdcListener?;
+    /** Whether database-level CDC is the active cross-instance change source. */
+    private cdcActive;
+    /** Reverse lookup: `schema.table` (and bare `table`) → collection, built when CDC starts. */
+    private cdcTableMap?;
+    /**
+     * Short-lived record of `path/id` keys this instance just fanned out via the
+     * app path (a Rebase-API mutation). When CDC echoes the same committed change
+     * back to *this* instance, we suppress the duplicate — the change was already
+     * delivered locally. Other instances have no such record, so they still
+     * deliver the CDC event. External writes (psql, cron, SQL editor) never match
+     * and always flow through. Keyed → expiry timestamp (ms).
+     */
+    private recentAppEmits;
+    /** How long an app-emit key suppresses its own CDC echo. Covers NOTIFY round-trip latency. */
+    private static readonly CDC_DEDUP_WINDOW_MS;
+    constructor(db: NodePgDatabase<any>, registry: PostgresCollectionRegistry);
+    /**
+     * Restricted role that auth-scoped refetches run as (via `SET LOCAL ROLE`)
+     * so RLS `select` policies bind. Set by the bootstrapper alongside
+     * `PostgresBackendDriver.rlsUserRole`; undefined when the connection
+     * is already subject to RLS natively. Without this, realtime refetches
+     * would leak rows the initial (isolated) fetch correctly hid.
+     */
+    rlsUserRole?: string;
+    /** Whether to emit verbose debug logs (disabled in production). */
+    private static readonly DEBUG;
+    private debugLog;
+    setDataDriver(driver: DataDriver): void;
+    get subscriptions(): Map<string, {
+        clientId: string;
+        type: "collection" | "single";
+        path: string;
+        id?: string | number;
+        collectionRequest?: {
+            filter?: Record<string, unknown>;
+            orderBy?: string;
+            order?: "desc" | "asc";
+            limit?: number;
+            offset?: number;
+            startAfter?: Record<string, unknown>;
+            databaseId?: string;
+            searchString?: string;
+        };
+        authContext?: SubscriptionAuthContext;
+    }>;
+    registerDataDriverSubscription(subscriptionId: string, subscription: {
+        clientId: string;
+        type: "collection" | "single";
+        path: string;
+        id?: string | number;
+        collectionRequest?: {
+            filter?: Record<string, unknown>;
+            orderBy?: string;
+            order?: "desc" | "asc";
+            limit?: number;
+            offset?: number;
+            startAfter?: Record<string, unknown>;
+            databaseId?: string;
+            searchString?: string;
+        };
+        authContext?: SubscriptionAuthContext;
+    }): void;
+    addSubscriptionCallback(subscriptionId: string, callback: (data: Record<string, unknown>[] | Record<string, unknown> | null) => void): void;
+    removeSubscriptionCallback(subscriptionId: string): void;
+    /**
+     * Subscribe to collection changes (RealtimeProvider interface)
+     */
+    subscribeToCollection(subscriptionId: string, config: CollectionSubscriptionConfig, callback?: (rows: Record<string, unknown>[]) => void): void;
+    /**
+     * Subscribe to single row changes (RealtimeProvider interface)
+     */
+    subscribeToOne(subscriptionId: string, config: SingleSubscriptionConfig, callback?: (row: Record<string, unknown> | null) => void): void;
+    /**
+     * Unsubscribe from a subscription (RealtimeProvider interface)
+     */
+    unsubscribe(subscriptionId: string): void;
+    addClient(clientId: string, ws: WebSocket): void;
+    handleClientMessage(clientId: string, message: WebSocketMessage, authContext?: SubscriptionAuthContext): Promise<void>;
+    removeClient(clientId: string): Promise<void>;
+    private handleMessage;
+    private handleCollectionSubscription;
+    private handleEntitySubscription;
+    private handleUnsubscribe;
+    /**
+     * Enhanced notification method that handles nested relation updates.
+     * @param broadcast When true (default), also sends a pg_notify so other instances
+     *                  pick up the change. Set to false when handling an incoming
+     *                  cross-instance notification to avoid infinite loops.
+     * @param origin `"app"` (default) — a Rebase-API mutation on this instance;
+     *               `"cdc"` — a database-level change observed via CDC (any writer,
+     *               any instance). The origin drives de-duplication: an app emit
+     *               records the change so this instance can suppress the matching
+     *               CDC echo, while an unmatched CDC event is delivered normally.
+     */
+    notifyUpdate(path: string, id: string, row: Record<string, unknown> | null, databaseId?: string, broadcast?: boolean, origin?: "app" | "cdc"): Promise<void>;
+    /**
+     * Notify subscriptions for a specific path
+     */
+    private notifyPathUpdate;
+    /**
+     * Debounce a collection refetch for a WebSocket subscription.
+     * Coalesces rapid row mutations into a single database query.
+     */
+    private debouncedCollectionRefetch;
+    /**
+     * Debounce a collection refetch for a DataDriver callback subscription.
+     */
+    private debouncedDriverRefetch;
+    /**
+     * Fetch a collection with optional RLS auth context.
+     * When authContext is provided, the fetch runs inside a transaction
+     * with set_config calls so PostgreSQL RLS policies are enforced.
+     */
+    private fetchCollectionWithAuth;
+    /**
+     * Debounce an row refetch for a WebSocket subscription.
+     */
+    private debouncedSingleRefetch;
+    /**
+     * Debounce an row refetch for a Driver callback subscription.
+     */
+    private debouncedSingleDriverRefetch;
+    /**
+     * Fetch a single row with optional RLS auth context.
+     */
+    private fetchEntityWithAuth;
+    private sendCollectionUpdate;
+    private sendSingleUpdate;
+    /**
+     * Send a lightweight row-level patch to a collection subscriber.
+     * The client can merge this into its cached data for instant feedback.
+     */
+    private sendCollectionPatch;
+    private sendError;
+    private sendMessage;
+    /**
+     * Extract parent paths from a nested path like "posts/70/tags"
+     * Returns ["posts", "posts/70"] for the example above
+     */
+    private getParentPaths;
+    /** Join a broadcast channel */
+    joinChannel(clientId: string, channel: string): void;
+    /** Leave a broadcast channel */
+    leaveChannel(clientId: string, channel: string): void;
+    /** Broadcast a message to all clients in a channel except sender */
+    broadcastToChannel(clientId: string, channel: string, event: string, payload: unknown): void;
+    /** Track presence in a channel */
+    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 */
+    sendPresenceState(clientId: string, channel: string): void;
+    /** Broadcast presence diff (joins/leaves) to channel */
+    private broadcastPresenceDiff;
+    /** Periodic cleanup for stale presences */
+    private ensurePresenceCleanup;
+    /**
+     * Gracefully tear down all realtime resources.
+     *
+     * This MUST be called during process shutdown, **before** `pool.end()`.
+     * It ensures:
+     *  1. All debounced refetch timers are cancelled (prevents queries after pool closes).
+     *  2. All subscription state and callbacks are cleared.
+     *  3. The dedicated LISTEN client (outside the pool) is disconnected.
+     *  4. All WebSocket clients are removed (but not forcefully closed — the
+     *     HTTP server close will handle that).
+     */
+    destroy(): Promise<void>;
+    /** Whether database-level change capture is currently the active source. */
+    isCdcActive(): boolean;
+    /**
+     * Enable database-level change capture as the realtime source.
+     *
+     * A dedicated LISTEN client consumes committed changes from the `rebase_cdc`
+     * channel (fed by CDC triggers — see {@link provisionTriggerCdc}) and routes
+     * them into the same {@link notifyUpdate} pipeline used by API mutations. The
+     * effect: subscribers see a change no matter how it was written — psql, a
+     * cron in another service, raw SQL, or the Studio SQL editor — exactly like
+     * Supabase Realtime tailing the WAL.
+     *
+     * Because CDC observes every commit on every instance, it also *replaces* the
+     * legacy per-mutation cross-instance broadcast (see the guard in
+     * {@link notifyUpdate}); callers should not also call {@link startListening}.
+     *
+     * @param connectionString Direct Postgres connection for the LISTEN client
+     *                         (bypass PgBouncer — LISTEN needs a session connection).
+     */
+    enableCdc(connectionString: string): Promise<void>;
+    /** Stop the CDC listener and clear its state. */
+    stopCdc(): Promise<void>;
+    /**
+     * Build the reverse map from database table → collection. A change event
+     * carries `schema` + `table`; realtime subscriptions are keyed by collection
+     * path (slug). We index by both `schema.table` and bare `table` so the lookup
+     * works whether or not the collection declares an explicit schema.
+     */
+    private buildCdcTableMap;
+    private resolveCollectionForTable;
+    /**
+     * Route a captured database change into the realtime pipeline.
+     *
+     * Delivery is RLS-safe by construction: the raw tuple from the WAL/trigger is
+     * NOT forwarded to subscribers. Instead the change is marked invalidated, so
+     * every matching subscription re-reads the row under its own auth context via
+     * {@link fetchCollectionWithAuth} / {@link fetchEntityWithAuth}. A subscriber
+     * therefore only ever receives rows its RLS policies permit — filtering is per
+     * subscriber, never per publisher.
+     */
+    private handleCdcEvent;
+    /** Compute the canonical (possibly composite) id string from a captured row. */
+    private extractIdFromCdcRow;
+    private dedupKey;
+    /** Record that this instance just delivered `key` via the app path. */
+    private markAppEmit;
+    /** Consume a matching app-emit record if present and unexpired; true ⇒ suppress the CDC echo. */
+    private consumeAppEmit;
+    /**
+     * Enable cross-instance realtime broadcasting via Postgres LISTEN/NOTIFY.
+     * Creates a dedicated pg.Client (outside the Drizzle pool) that stays
+     * connected and listens for change notifications from other instances.
+     *
+     * This is an **optional** feature — if never called, the backend operates
+     * in single-instance mode (the default, perfectly fine for most setups).
+     *
+     * @param connectionString Raw Postgres connection string for the LISTEN client.
+     */
+    startListening(connectionString: string): Promise<void>;
+    /**
+     * Stop listening and clean up the dedicated LISTEN connection.
+     */
+    stopListening(): Promise<void>;
+    /**
+     * Broadcast a change notification to other instances via pg_notify.
+     * Uses the main Drizzle connection (pooled) — NOT the LISTEN client.
+     */
+    private broadcastChange;
+    /**
+     * Create and connect the dedicated LISTEN client with auto-reconnect.
+     */
+    private connectListenClient;
+    /**
+     * Schedule a reconnection attempt with a fixed 3s delay.
+     */
+    private scheduleReconnect;
+}
+/**
+ * Alias for RealtimeService for consistent naming with other database implementations.
+ * This allows code to use PostgresRealtimeProvider alongside future MongoRealtimeProvider, etc.
+ */
+export declare const PostgresRealtimeProvider: typeof RealtimeService;