graphile-realtime-subscriptions 0.3.0 → 0.4.0

package/realtime-manager.js

@@ -0,0 +1,140 @@
+"use strict";
+/**
+ * RealtimeManager — bridges CursorTracker (polling drain_changes) into
+ * PostGraphile's PgSubscriber so cursor-tracked events flow through the
+ * same subscription plans as NOTIFY events.
+ *
+ * Architecture:
+ *   PgSubscriber uses an internal EventEmitter. NOTIFY payloads arrive via
+ *   pg's `notification` event and are emitted as `eventEmitter.emit(channel, payload)`.
+ *   The `listen()` step in grafast subscribes to the same EventEmitter.
+ *
+ *   RealtimeManager converts ChangeLogEntry objects from drain_changes() into
+ *   the same NOTIFY payload format ("OP:rowId1,rowId2,...") and emits them on
+ *   the PgSubscriber's EventEmitter, so existing subscription plans handle
+ *   them identically to real NOTIFY events.
+ *
+ *   This provides at-least-once delivery: NOTIFY is instant but best-effort;
+ *   cursor polling catches up on anything missed (disconnects, restarts).
+ *   Duplicates are expected and acceptable — clients should be idempotent.
+ *
+ * Lifecycle:
+ *   1. start() → registers listener node, begins polling + heartbeat
+ *   2. drain_changes() results are converted and emitted on PgSubscriber
+ *   3. stop() → cleans up ephemeral subscriptions, removes listener node
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RealtimeManager = void 0;
+exports.extractRowId = extractRowId;
+exports.entryToNotifyPayload = entryToNotifyPayload;
+exports.entryToChannel = entryToChannel;
+const logger_1 = require("@pgpmjs/logger");
+const cursor_tracker_1 = require("./cursor-tracker");
+const log = new logger_1.Logger('realtime-manager');
+/**
+ * Extract row IDs from a ChangeLogEntry.
+ *
+ * For INSERT/UPDATE the row ID lives in payload_after.id;
+ * for DELETE it lives in payload_before.id.
+ * Falls back to the change_log entry's own id if payloads are missing.
+ */
+function extractRowId(entry) {
+    if (entry.operation === 'DELETE') {
+        return entry.payload_before?.id ?? null;
+    }
+    return entry.payload_after?.id ?? null;
+}
+/**
+ * Convert a ChangeLogEntry into the NOTIFY payload format used by emit_change.
+ * Format: "OPERATION:rowId" (e.g. "INSERT:550e8400-...")
+ */
+function entryToNotifyPayload(entry) {
+    const rowId = extractRowId(entry);
+    if (!rowId) {
+        return entry.operation;
+    }
+    return `${entry.operation}:${rowId}`;
+}
+/**
+ * Build the NOTIFY channel name for a change_log entry.
+ * Matches the channel format used by emit_change: "realtime:{schema}.{table}"
+ */
+function entryToChannel(entry) {
+    return `realtime:${entry.source_schema}.${entry.source_table}`;
+}
+class RealtimeManager {
+    cursorTracker;
+    subscriber;
+    started = false;
+    constructor(options) {
+        const { pgSubscriber, withPgClient, ...cursorOpts } = options;
+        this.subscriber = pgSubscriber;
+        this.cursorTracker = new cursor_tracker_1.CursorTracker({
+            nodeId: cursorOpts.nodeId,
+            schema: cursorOpts.schema,
+            pollIntervalMs: cursorOpts.pollIntervalMs,
+            heartbeatIntervalMs: cursorOpts.heartbeatIntervalMs,
+            batchLimit: cursorOpts.batchLimit,
+            withPgClient,
+            onChanges: (entries) => this.dispatchEntries(entries),
+            onError: cursorOpts.onError ?? ((err) => {
+                log.error(`RealtimeManager error: ${err.message}`);
+            }),
+        });
+    }
+    get nodeId() {
+        return this.cursorTracker.nodeId;
+    }
+    get isRunning() {
+        return this.started && this.cursorTracker.isRunning;
+    }
+    async start() {
+        if (this.started)
+            return;
+        this.started = true;
+        log.info(`Starting RealtimeManager: node=${this.nodeId}`);
+        await this.cursorTracker.start();
+    }
+    async stop() {
+        if (!this.started)
+            return;
+        this.started = false;
+        log.info(`Stopping RealtimeManager: node=${this.nodeId}`);
+        await this.cursorTracker.stop();
+    }
+    /**
+     * Convert ChangeLogEntry objects to NOTIFY-format payloads and emit
+     * them on the PgSubscriber's internal EventEmitter.
+     */
+    dispatchEntries(entries) {
+        const emitter = this.getEventEmitter();
+        if (!emitter) {
+            log.warn('PgSubscriber has no eventEmitter; cursor events cannot be dispatched');
+            return;
+        }
+        for (const entry of entries) {
+            const channel = entryToChannel(entry);
+            const payload = entryToNotifyPayload(entry);
+            emitter.emit(channel, payload);
+        }
+        log.info(`Dispatched ${entries.length} cursor-tracked event(s) to PgSubscriber`);
+    }
+    /**
+     * Access PgSubscriber's internal EventEmitter.
+     *
+     * PgSubscriber from @dataplan/pg stores an EventEmitter3 instance as
+     * `this.eventEmitter`. It is private but stable across v1.x releases.
+     * This is the same emitter that NOTIFY events are dispatched through.
+     */
+    getEventEmitter() {
+        const sub = this.subscriber;
+        if (sub && typeof sub === 'object' && 'eventEmitter' in sub) {
+            const ee = sub.eventEmitter;
+            if (typeof ee?.emit === 'function') {
+                return ee;
+            }
+        }
+        return null;
+    }
+}
+exports.RealtimeManager = RealtimeManager;

package/types.d.ts

@@ -12,3 +12,135 @@ export interface RealtimeSubscriptionsPluginOptions {
      */
     overflowThreshold?: number;
 }
+/**
+ * A minimal PostgreSQL client interface used by CursorTracker.
+ * Compatible with node-postgres (pg) Client or PoolClient.
+ */
+export interface PgClient {
+    query<R = Record<string, unknown>>(text: string, values?: unknown[]): Promise<{
+        rows: R[];
+    }>;
+}
+/**
+ * Callback that provides a PgClient for executing queries.
+ * The client is released after the callback returns.
+ */
+export type WithPgClient = <T>(callback: (client: PgClient) => Promise<T>) => Promise<T>;
+/**
+ * A single entry from drain_changes(), representing a change_log row
+ * matched against subscriber tables.
+ */
+export interface ChangeLogEntry {
+    id: string;
+    occurred_at: string;
+    source_schema: string;
+    source_table: string;
+    operation: string;
+    payload_after: Record<string, unknown> | null;
+    payload_before: Record<string, unknown> | null;
+    payload_diff: Record<string, unknown> | null;
+    subscriber_ids: string[];
+}
+/**
+ * Configuration for the CursorTracker background poller.
+ */
+export interface CursorTrackerOptions {
+    /**
+     * Unique identifier for this listener node.
+     * Should be stable across restarts if you want cursor continuity.
+     * If not provided, a random ID is generated (ephemeral mode).
+     */
+    nodeId?: string;
+    /**
+     * The realtime_public schema name where drain_changes(),
+     * touch_listener(), and cleanup_ephemeral() live.
+     *
+     * Default: 'realtime_public'
+     */
+    schema?: string;
+    /**
+     * How often to poll drain_changes() for new events (milliseconds).
+     *
+     * Default: 5000 (5 seconds)
+     */
+    pollIntervalMs?: number;
+    /**
+     * How often to send a heartbeat via touch_listener() (milliseconds).
+     *
+     * Default: 30000 (30 seconds)
+     */
+    heartbeatIntervalMs?: number;
+    /**
+     * Maximum number of change_log rows to fetch per drain_changes() call.
+     *
+     * Default: 500
+     */
+    batchLimit?: number;
+    /**
+     * Function to acquire a PgClient for executing queries.
+     * The cursor tracker calls this for every poll and heartbeat cycle.
+     */
+    withPgClient: WithPgClient;
+    /**
+     * Called when drain_changes() returns new change_log entries.
+     * The entries include subscriber_ids for fan-out routing.
+     */
+    onChanges?: (entries: ChangeLogEntry[]) => void;
+    /**
+     * Called when an error occurs during polling, heartbeat, or cleanup.
+     * If not provided, errors are logged to the console.
+     */
+    onError?: (error: Error) => void;
+}
+/**
+ * Configuration for the RealtimeManager, which bridges CursorTracker
+ * events into PostGraphile's PgSubscriber for at-least-once delivery.
+ */
+export interface RealtimeManagerOptions {
+    /**
+     * The PgSubscriber instance from PostGraphile's context.
+     * RealtimeManager emits cursor-tracked events on its internal EventEmitter
+     * so they flow through existing subscription plans.
+     */
+    pgSubscriber: unknown;
+    /**
+     * Function to acquire a PgClient for executing cursor tracking queries.
+     */
+    withPgClient: WithPgClient;
+    /**
+     * Unique identifier for this listener node.
+     * Should be stable across restarts if you want cursor continuity.
+     * If not provided, a random ID is generated (ephemeral mode).
+     */
+    nodeId?: string;
+    /**
+     * The realtime_public schema name where drain_changes(),
+     * touch_listener(), and cleanup_ephemeral() live.
+     *
+     * Default: 'realtime_public'
+     */
+    schema?: string;
+    /**
+     * How often to poll drain_changes() for new events (milliseconds).
+     *
+     * Default: 5000 (5 seconds)
+     */
+    pollIntervalMs?: number;
+    /**
+     * How often to send a heartbeat via touch_listener() (milliseconds).
+     *
+     * Default: 30000 (30 seconds)
+     */
+    heartbeatIntervalMs?: number;
+    /**
+     * Maximum number of change_log rows to fetch per drain_changes() call.
+     *
+     * Default: 500
+     */
+    batchLimit?: number;
+    /**
+     * Called when an error occurs during polling, heartbeat, or cleanup.
+     * If not provided, errors are logged via @pgpmjs/logger.
+     */
+    onError?: (error: Error) => void;
+}