graphile-realtime-subscriptions 0.2.0 → 0.4.0

package/cursor-tracker.d.ts

@@ -0,0 +1,42 @@
+/**
+ * CursorTracker — manages the listener_node lifecycle and periodic
+ * drain_changes() polling for at-least-once event delivery.
+ *
+ * Lifecycle:
+ *   1. start() → calls touch_listener() to register/heartbeat the node
+ *   2. Periodically polls drain_changes() for new change_log entries
+ *   3. Periodically heartbeats via touch_listener()
+ *   4. stop() → calls cleanup_ephemeral() to remove ephemeral subscriptions
+ *              and delete the listener_node row
+ *
+ * The caller provides a withPgClient callback that acquires a PgClient
+ * for each operation. This keeps connection management external.
+ */
+import type { CursorTrackerOptions, ChangeLogEntry } from './types';
+declare const DEFAULT_POLL_INTERVAL_MS = 5000;
+declare const DEFAULT_HEARTBEAT_INTERVAL_MS = 30000;
+declare const DEFAULT_BATCH_LIMIT = 500;
+declare const DEFAULT_SCHEMA = "realtime_public";
+export declare class CursorTracker {
+    readonly nodeId: string;
+    private readonly schema;
+    private readonly pollIntervalMs;
+    private readonly heartbeatIntervalMs;
+    private readonly batchLimit;
+    private readonly withPgClient;
+    private readonly onChanges;
+    private readonly onError;
+    private pollTimer;
+    private heartbeatTimer;
+    private running;
+    private draining;
+    constructor(options: CursorTrackerOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    drain(): Promise<ChangeLogEntry[]>;
+    touchListener(): Promise<void>;
+    cleanupEphemeral(): Promise<void>;
+    get isRunning(): boolean;
+    private quoteIdent;
+}
+export { DEFAULT_POLL_INTERVAL_MS, DEFAULT_HEARTBEAT_INTERVAL_MS, DEFAULT_BATCH_LIMIT, DEFAULT_SCHEMA, };

package/cursor-tracker.js

@@ -0,0 +1,139 @@
+"use strict";
+/**
+ * CursorTracker — manages the listener_node lifecycle and periodic
+ * drain_changes() polling for at-least-once event delivery.
+ *
+ * Lifecycle:
+ *   1. start() → calls touch_listener() to register/heartbeat the node
+ *   2. Periodically polls drain_changes() for new change_log entries
+ *   3. Periodically heartbeats via touch_listener()
+ *   4. stop() → calls cleanup_ephemeral() to remove ephemeral subscriptions
+ *              and delete the listener_node row
+ *
+ * The caller provides a withPgClient callback that acquires a PgClient
+ * for each operation. This keeps connection management external.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_SCHEMA = exports.DEFAULT_BATCH_LIMIT = exports.DEFAULT_HEARTBEAT_INTERVAL_MS = exports.DEFAULT_POLL_INTERVAL_MS = exports.CursorTracker = void 0;
+const crypto_1 = require("crypto");
+const logger_1 = require("@pgpmjs/logger");
+const quotes_1 = require("@pgsql/quotes");
+const log = new logger_1.Logger('cursor-tracker');
+const DEFAULT_POLL_INTERVAL_MS = 5000;
+exports.DEFAULT_POLL_INTERVAL_MS = DEFAULT_POLL_INTERVAL_MS;
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 30000;
+exports.DEFAULT_HEARTBEAT_INTERVAL_MS = DEFAULT_HEARTBEAT_INTERVAL_MS;
+const DEFAULT_BATCH_LIMIT = 500;
+exports.DEFAULT_BATCH_LIMIT = DEFAULT_BATCH_LIMIT;
+const DEFAULT_SCHEMA = 'realtime_public';
+exports.DEFAULT_SCHEMA = DEFAULT_SCHEMA;
+class CursorTracker {
+    nodeId;
+    schema;
+    pollIntervalMs;
+    heartbeatIntervalMs;
+    batchLimit;
+    withPgClient;
+    onChanges;
+    onError;
+    pollTimer = null;
+    heartbeatTimer = null;
+    running = false;
+    draining = false;
+    constructor(options) {
+        this.nodeId = options.nodeId ?? (0, crypto_1.randomUUID)();
+        this.schema = options.schema ?? DEFAULT_SCHEMA;
+        this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+        this.heartbeatIntervalMs = options.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
+        this.batchLimit = options.batchLimit ?? DEFAULT_BATCH_LIMIT;
+        this.withPgClient = options.withPgClient;
+        this.onChanges = options.onChanges ?? (() => { });
+        this.onError = options.onError ?? ((err) => {
+            log.error(`CursorTracker error: ${err.message}`);
+        });
+    }
+    async start() {
+        if (this.running)
+            return;
+        this.running = true;
+        log.info(`Starting cursor tracker: node=${this.nodeId}, schema=${this.schema}`);
+        await this.touchListener();
+        // Initial drain immediately after registration
+        await this.drain();
+        this.pollTimer = setInterval(() => {
+            void this.drain();
+        }, this.pollIntervalMs);
+        this.heartbeatTimer = setInterval(() => {
+            void this.touchListener();
+        }, this.heartbeatIntervalMs);
+    }
+    async stop() {
+        if (!this.running)
+            return;
+        this.running = false;
+        log.info(`Stopping cursor tracker: node=${this.nodeId}`);
+        if (this.pollTimer) {
+            clearInterval(this.pollTimer);
+            this.pollTimer = null;
+        }
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+        await this.cleanupEphemeral();
+    }
+    async drain() {
+        if (this.draining)
+            return [];
+        this.draining = true;
+        try {
+            const entries = await this.withPgClient(async (client) => {
+                const sql = `SELECT * FROM ${this.quoteIdent(this.schema)}.drain_changes($1, $2)`;
+                const result = await client.query(sql, [this.nodeId, this.batchLimit]);
+                return result.rows.map((row) => row.drain_changes);
+            });
+            if (entries.length > 0) {
+                log.info(`Drained ${entries.length} change(s) for node=${this.nodeId}`);
+                this.onChanges(entries);
+            }
+            return entries;
+        }
+        catch (err) {
+            this.onError(err instanceof Error ? err : new Error(String(err)));
+            return [];
+        }
+        finally {
+            this.draining = false;
+        }
+    }
+    async touchListener() {
+        try {
+            await this.withPgClient(async (client) => {
+                const sql = `SELECT ${this.quoteIdent(this.schema)}.touch_listener($1)`;
+                await client.query(sql, [this.nodeId]);
+            });
+        }
+        catch (err) {
+            this.onError(err instanceof Error ? err : new Error(String(err)));
+        }
+    }
+    async cleanupEphemeral() {
+        try {
+            await this.withPgClient(async (client) => {
+                const sql = `SELECT ${this.quoteIdent(this.schema)}.cleanup_ephemeral($1)`;
+                await client.query(sql, [this.nodeId]);
+            });
+            log.info(`Cleaned up ephemeral subscriptions for node=${this.nodeId}`);
+        }
+        catch (err) {
+            this.onError(err instanceof Error ? err : new Error(String(err)));
+        }
+    }
+    get isRunning() {
+        return this.running;
+    }
+    quoteIdent(identifier) {
+        return quotes_1.QuoteUtils.quoteIdentifier(identifier);
+    }
+}
+exports.CursorTracker = CursorTracker;

package/esm/cursor-tracker.d.ts

@@ -0,0 +1,42 @@
+/**
+ * CursorTracker — manages the listener_node lifecycle and periodic
+ * drain_changes() polling for at-least-once event delivery.
+ *
+ * Lifecycle:
+ *   1. start() → calls touch_listener() to register/heartbeat the node
+ *   2. Periodically polls drain_changes() for new change_log entries
+ *   3. Periodically heartbeats via touch_listener()
+ *   4. stop() → calls cleanup_ephemeral() to remove ephemeral subscriptions
+ *              and delete the listener_node row
+ *
+ * The caller provides a withPgClient callback that acquires a PgClient
+ * for each operation. This keeps connection management external.
+ */
+import type { CursorTrackerOptions, ChangeLogEntry } from './types';
+declare const DEFAULT_POLL_INTERVAL_MS = 5000;
+declare const DEFAULT_HEARTBEAT_INTERVAL_MS = 30000;
+declare const DEFAULT_BATCH_LIMIT = 500;
+declare const DEFAULT_SCHEMA = "realtime_public";
+export declare class CursorTracker {
+    readonly nodeId: string;
+    private readonly schema;
+    private readonly pollIntervalMs;
+    private readonly heartbeatIntervalMs;
+    private readonly batchLimit;
+    private readonly withPgClient;
+    private readonly onChanges;
+    private readonly onError;
+    private pollTimer;
+    private heartbeatTimer;
+    private running;
+    private draining;
+    constructor(options: CursorTrackerOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    drain(): Promise<ChangeLogEntry[]>;
+    touchListener(): Promise<void>;
+    cleanupEphemeral(): Promise<void>;
+    get isRunning(): boolean;
+    private quoteIdent;
+}
+export { DEFAULT_POLL_INTERVAL_MS, DEFAULT_HEARTBEAT_INTERVAL_MS, DEFAULT_BATCH_LIMIT, DEFAULT_SCHEMA, };

package/esm/cursor-tracker.js

@@ -0,0 +1,132 @@
+/**
+ * CursorTracker — manages the listener_node lifecycle and periodic
+ * drain_changes() polling for at-least-once event delivery.
+ *
+ * Lifecycle:
+ *   1. start() → calls touch_listener() to register/heartbeat the node
+ *   2. Periodically polls drain_changes() for new change_log entries
+ *   3. Periodically heartbeats via touch_listener()
+ *   4. stop() → calls cleanup_ephemeral() to remove ephemeral subscriptions
+ *              and delete the listener_node row
+ *
+ * The caller provides a withPgClient callback that acquires a PgClient
+ * for each operation. This keeps connection management external.
+ */
+import { randomUUID } from 'crypto';
+import { Logger } from '@pgpmjs/logger';
+import { QuoteUtils } from '@pgsql/quotes';
+const log = new Logger('cursor-tracker');
+const DEFAULT_POLL_INTERVAL_MS = 5000;
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 30000;
+const DEFAULT_BATCH_LIMIT = 500;
+const DEFAULT_SCHEMA = 'realtime_public';
+export class CursorTracker {
+    nodeId;
+    schema;
+    pollIntervalMs;
+    heartbeatIntervalMs;
+    batchLimit;
+    withPgClient;
+    onChanges;
+    onError;
+    pollTimer = null;
+    heartbeatTimer = null;
+    running = false;
+    draining = false;
+    constructor(options) {
+        this.nodeId = options.nodeId ?? randomUUID();
+        this.schema = options.schema ?? DEFAULT_SCHEMA;
+        this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+        this.heartbeatIntervalMs = options.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
+        this.batchLimit = options.batchLimit ?? DEFAULT_BATCH_LIMIT;
+        this.withPgClient = options.withPgClient;
+        this.onChanges = options.onChanges ?? (() => { });
+        this.onError = options.onError ?? ((err) => {
+            log.error(`CursorTracker error: ${err.message}`);
+        });
+    }
+    async start() {
+        if (this.running)
+            return;
+        this.running = true;
+        log.info(`Starting cursor tracker: node=${this.nodeId}, schema=${this.schema}`);
+        await this.touchListener();
+        // Initial drain immediately after registration
+        await this.drain();
+        this.pollTimer = setInterval(() => {
+            void this.drain();
+        }, this.pollIntervalMs);
+        this.heartbeatTimer = setInterval(() => {
+            void this.touchListener();
+        }, this.heartbeatIntervalMs);
+    }
+    async stop() {
+        if (!this.running)
+            return;
+        this.running = false;
+        log.info(`Stopping cursor tracker: node=${this.nodeId}`);
+        if (this.pollTimer) {
+            clearInterval(this.pollTimer);
+            this.pollTimer = null;
+        }
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+        await this.cleanupEphemeral();
+    }
+    async drain() {
+        if (this.draining)
+            return [];
+        this.draining = true;
+        try {
+            const entries = await this.withPgClient(async (client) => {
+                const sql = `SELECT * FROM ${this.quoteIdent(this.schema)}.drain_changes($1, $2)`;
+                const result = await client.query(sql, [this.nodeId, this.batchLimit]);
+                return result.rows.map((row) => row.drain_changes);
+            });
+            if (entries.length > 0) {
+                log.info(`Drained ${entries.length} change(s) for node=${this.nodeId}`);
+                this.onChanges(entries);
+            }
+            return entries;
+        }
+        catch (err) {
+            this.onError(err instanceof Error ? err : new Error(String(err)));
+            return [];
+        }
+        finally {
+            this.draining = false;
+        }
+    }
+    async touchListener() {
+        try {
+            await this.withPgClient(async (client) => {
+                const sql = `SELECT ${this.quoteIdent(this.schema)}.touch_listener($1)`;
+                await client.query(sql, [this.nodeId]);
+            });
+        }
+        catch (err) {
+            this.onError(err instanceof Error ? err : new Error(String(err)));
+        }
+    }
+    async cleanupEphemeral() {
+        try {
+            await this.withPgClient(async (client) => {
+                const sql = `SELECT ${this.quoteIdent(this.schema)}.cleanup_ephemeral($1)`;
+                await client.query(sql, [this.nodeId]);
+            });
+            log.info(`Cleaned up ephemeral subscriptions for node=${this.nodeId}`);
+        }
+        catch (err) {
+            this.onError(err instanceof Error ? err : new Error(String(err)));
+        }
+    }
+    get isRunning() {
+        return this.running;
+    }
+    quoteIdent(identifier) {
+        return QuoteUtils.quoteIdentifier(identifier);
+    }
+}
+export { DEFAULT_POLL_INTERVAL_MS, DEFAULT_HEARTBEAT_INTERVAL_MS, DEFAULT_BATCH_LIMIT, DEFAULT_SCHEMA, };

package/esm/index.d.ts

@@ -18,4 +18,7 @@
  */
 export { createRealtimeSubscriptionsPlugin, RealtimeSubscriptionsPlugin } from './plugin';
 export { RealtimeSubscriptionsPreset } from './preset';
+export { CursorTracker } from './cursor-tracker';
+export { RealtimeManager } from './realtime-manager';
 export type { RealtimeSubscriptionsPluginOptions } from './types';
+export type { CursorTrackerOptions, ChangeLogEntry, PgClient, WithPgClient, RealtimeManagerOptions, } from './types';

package/esm/index.js

@@ -18,3 +18,5 @@
  */
 export { createRealtimeSubscriptionsPlugin, RealtimeSubscriptionsPlugin } from './plugin';
 export { RealtimeSubscriptionsPreset } from './preset';
+export { CursorTracker } from './cursor-tracker';
+export { RealtimeManager } from './realtime-manager';

package/esm/plugin.d.ts

@@ -5,21 +5,80 @@
  * subscription fields (onXxxChanged) that use PostgreSQL LISTEN/NOTIFY
  * for real-time event delivery.
  *
- * Subscription modes (Phase 3a):
- *   - Single record: onXxxChanged(id: UUID!) — subscribe to changes on one row
+ * Subscription modes:
+ *   - Specific rows: onXxxChanged(ids: [UUID!]) — subscribe to changes on specific rows
  *   - Full collection: onXxxChanged (no args) — subscribe to any change on the table
  *
+ * NOTIFY payload format (from emit_change trigger):
+ *   - Normal: "INSERT:uuid1,uuid2,..."  or "UPDATE:uuid1" or "DELETE:uuid1"
+ *   - Overflow: "INVALIDATE" (when a single statement affects > 50 rows)
+ *
  * Event flow:
  *   1. A row is inserted/updated/deleted
- *   2. The emit_change trigger fires pg_notify('realtime:{schema}.{table}', TG_OP)
+ *   2. The emit_change trigger fires pg_notify with TG_OP:row_ids or INVALIDATE
  *   3. PostGraphile's pgSubscriber receives the NOTIFY
- *   4. The subscription re-queries the source table with RLS enforced
- *   5. The client receives { event, row } where row reflects the current state
+ *   4. The plugin parses the payload and fetches the specific changed row(s)
+ *   5. The client receives { event, row, rowId, overflow }
+ *
+ * Cursor tracking (at-least-once delivery):
+ *   The CursorTracker class provides a complementary polling-based delivery
+ *   path via drain_changes(). It manages the listener_node lifecycle:
+ *   - start() registers the node via touch_listener()
+ *   - Periodic polling via drain_changes() fetches change_log entries
+ *   - Periodic heartbeat via touch_listener() keeps the node alive
+ *   - stop() calls cleanup_ephemeral() to remove ephemeral subscriptions
+ *   This enables at-least-once semantics by tracking cursor position.
  *
- * RLS enforcement is automatic — resource.get() queries through the
- * authenticated user's connection with their JWT role applied.
+ * Overflow protection:
+ *   - Database-side: statements affecting > 50 rows send INVALIDATE
+ *   - Plugin-side: per-subscriber throttle (default 50 events/second/table)
+ *     drops individual events and sends a single INVALIDATE when exceeded
+ *
+ * Security / RLS enforcement:
+ *   - Row data is always fetched via resource.get() which runs through the
+ *     authenticated user's connection with their JWT role and pgSettings applied.
+ *   - For INSERT/UPDATE events, if RLS denies access (resource.get returns null),
+ *     the rowId is masked (set to null) to prevent metadata leaks.
+ *   - For DELETE events, row is naturally null (the row no longer exists).
+ *   - For INVALIDATE (overflow), the client should refetch via a normal query
+ *     which is also RLS-gated.
+ *   - When ids are provided, only events for those specific rows are delivered,
+ *     preventing cross-tenant event leaks.
  */
 import type { GraphileConfig } from 'graphile-config';
 import type { RealtimeSubscriptionsPluginOptions } from './types';
-export declare function createRealtimeSubscriptionsPlugin(_options?: RealtimeSubscriptionsPluginOptions): GraphileConfig.Plugin;
+/** Default overflow threshold: events per second per table per subscriber */
+declare const DEFAULT_OVERFLOW_THRESHOLD = 50;
+interface ParsedPayload {
+    event: string;
+    rowIds: string[];
+    overflow: boolean;
+}
+/**
+ * Parse the NOTIFY payload from emit_change.
+ * Format: "TG_OP:id1,id2,..." or "INVALIDATE"
+ */
+declare function parseNotifyPayload(raw: string): ParsedPayload;
+/**
+ * Per-subscriber, per-table event rate tracker.
+ * Counts events in a sliding 1-second window.
+ */
+declare class EventThrottle {
+    private readonly threshold;
+    private windowStart;
+    private eventCount;
+    private overflowSent;
+    constructor(threshold: number);
+    /**
+     * Record an event and return whether it should be delivered.
+     * Returns 'deliver' for normal events, 'overflow' when the threshold
+     * is first exceeded, or 'drop' for subsequent events in the same window.
+     */
+    check(): 'deliver' | 'overflow' | 'drop';
+}
+export declare function createRealtimeSubscriptionsPlugin(options?: RealtimeSubscriptionsPluginOptions): GraphileConfig.Plugin;
 export { createRealtimeSubscriptionsPlugin as RealtimeSubscriptionsPlugin };
+export { CursorTracker } from './cursor-tracker';
+export { RealtimeManager } from './realtime-manager';
+export type { CursorTrackerOptions, ChangeLogEntry, WithPgClient, PgClient, RealtimeManagerOptions } from './types';
+export { parseNotifyPayload, EventThrottle, DEFAULT_OVERFLOW_THRESHOLD };