graphile-realtime-subscriptions 1.10.0 → 1.10.2

package/esm/event-gate.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The gate between PostgreSQL's NOTIFY stream and a GraphQL subscription.
+ *
+ * Everything that can decide "this event should not reach the client" lives
+ * here, upstream of grafast, because grafast's `listen` maps each event to a
+ * step and offers no way to suppress one. Deciding downstream forced the
+ * plugin to represent "dropped" as a null payload, which the field resolvers
+ * then had to coalesce (`p?.event ?? 'UNKNOWN'`) — so a filtered event still
+ * reached the client, carrying an invented event name. Filtering here means
+ * the stream only ever yields events that should exist, and every resolver
+ * downstream is total.
+ *
+ * The gate also owns parsing and the overflow throttle, so a payload the
+ * trigger and the plugin disagree about fails loudly instead of arriving as
+ * an `UNKNOWN`-shaped record.
+ */
+import type { GrafastSubscriber } from 'grafast';
+export interface ParsedPayload {
+    event: string;
+    /**
+     * Row ids being reported. Already narrowed to the subscription's `ids` when
+     * it supplied any, so no consumer needs to re-intersect. Empty for
+     * INVALIDATE.
+     */
+    rowIds: string[];
+    overflow: boolean;
+}
+export declare class MalformedNotifyPayloadError extends Error {
+    constructor(raw: string, reason: string);
+}
+/**
+ * Parse the NOTIFY payload from `emit_change`.
+ * Format: `"TG_OP:id1,id2,..."` or `"INVALIDATE"`.
+ *
+ * Throws on anything else: a payload this cannot read means the trigger and
+ * this plugin have diverged, and inventing an event name for it hides a
+ * deployment fault behind data the client will act on.
+ */
+export declare function parseNotifyPayload(raw: string): ParsedPayload;
+/**
+ * Per-subscription event rate tracker. Counts events in a sliding 1-second
+ * window.
+ */
+export 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 interface EventGateOptions {
+    /** Sparse-set subscription: deliver only events touching these row ids. */
+    ids?: readonly string[] | null;
+    /** Events per second before the gate collapses the stream to one INVALIDATE. */
+    threshold: number;
+}
+/**
+ * Wrap a `GrafastSubscriber` so its stream yields parsed, gated payloads.
+ *
+ * Built per subscription (the throttle and `ids` are per-subscriber state), so
+ * one noisy client can no longer throttle every other subscriber to the same
+ * table — which a single build-time throttle instance did.
+ */
+export declare function createGatedSubscriber(inner: GrafastSubscriber<Record<string, string>>, { ids, threshold }: EventGateOptions): GrafastSubscriber<Record<string, ParsedPayload>>;

package/esm/event-gate.js

@@ -0,0 +1,137 @@
+/**
+ * The gate between PostgreSQL's NOTIFY stream and a GraphQL subscription.
+ *
+ * Everything that can decide "this event should not reach the client" lives
+ * here, upstream of grafast, because grafast's `listen` maps each event to a
+ * step and offers no way to suppress one. Deciding downstream forced the
+ * plugin to represent "dropped" as a null payload, which the field resolvers
+ * then had to coalesce (`p?.event ?? 'UNKNOWN'`) — so a filtered event still
+ * reached the client, carrying an invented event name. Filtering here means
+ * the stream only ever yields events that should exist, and every resolver
+ * downstream is total.
+ *
+ * The gate also owns parsing and the overflow throttle, so a payload the
+ * trigger and the plugin disagree about fails loudly instead of arriving as
+ * an `UNKNOWN`-shaped record.
+ */
+/** Operations `emit_change` is allowed to report. */
+const KNOWN_OPERATIONS = new Set(['INSERT', 'UPDATE', 'DELETE']);
+export class MalformedNotifyPayloadError extends Error {
+    constructor(raw, reason) {
+        super(`Malformed realtime NOTIFY payload ${JSON.stringify(raw)}: ${reason}. ` +
+            'Expected "INVALIDATE" or "<INSERT|UPDATE|DELETE>:<uuid>[,<uuid>...]" ' +
+            'as emitted by the emit_change trigger.');
+        this.name = 'MalformedNotifyPayloadError';
+    }
+}
+/**
+ * Parse the NOTIFY payload from `emit_change`.
+ * Format: `"TG_OP:id1,id2,..."` or `"INVALIDATE"`.
+ *
+ * Throws on anything else: a payload this cannot read means the trigger and
+ * this plugin have diverged, and inventing an event name for it hides a
+ * deployment fault behind data the client will act on.
+ */
+export function parseNotifyPayload(raw) {
+    if (raw === 'INVALIDATE') {
+        return { event: 'INVALIDATE', rowIds: [], overflow: true };
+    }
+    const colonIdx = raw.indexOf(':');
+    if (colonIdx === -1) {
+        throw new MalformedNotifyPayloadError(raw, 'no ":" separating the operation from the row ids');
+    }
+    const event = raw.substring(0, colonIdx);
+    if (!KNOWN_OPERATIONS.has(event)) {
+        throw new MalformedNotifyPayloadError(raw, `unknown operation ${JSON.stringify(event)}`);
+    }
+    const idsPart = raw.substring(colonIdx + 1);
+    const rowIds = idsPart.length > 0 ? idsPart.split(',') : [];
+    if (rowIds.length === 0) {
+        throw new MalformedNotifyPayloadError(raw, `${event} carries no row ids`);
+    }
+    return { event, rowIds, overflow: false };
+}
+/**
+ * Per-subscription event rate tracker. Counts events in a sliding 1-second
+ * window.
+ */
+export class EventThrottle {
+    threshold;
+    windowStart = 0;
+    eventCount = 0;
+    overflowSent = false;
+    constructor(threshold) {
+        this.threshold = threshold;
+    }
+    /**
+     * 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() {
+        const now = Date.now();
+        if (now - this.windowStart >= 1000) {
+            this.windowStart = now;
+            this.eventCount = 0;
+            this.overflowSent = false;
+        }
+        this.eventCount++;
+        if (this.eventCount <= this.threshold) {
+            return 'deliver';
+        }
+        if (!this.overflowSent) {
+            this.overflowSent = true;
+            return 'overflow';
+        }
+        return 'drop';
+    }
+}
+/**
+ * Apply the gate to one raw NOTIFY payload.
+ *
+ * Returns the payload to deliver, or `null` meaning *do not emit* — a decision
+ * only this layer is allowed to make, because only this layer can act on it.
+ */
+function gate(raw, ids, throttle) {
+    const parsed = parseNotifyPayload(raw);
+    // An INVALIDATE is the overflow signal itself; throttling it would drop the
+    // one event telling the client to refetch.
+    if (parsed.overflow)
+        return parsed;
+    const action = throttle.check();
+    if (action === 'drop')
+        return null;
+    if (action === 'overflow') {
+        return { event: 'INVALIDATE', rowIds: [], overflow: true };
+    }
+    if (!ids || ids.length === 0)
+        return parsed;
+    const matched = parsed.rowIds.filter(rowId => ids.includes(rowId));
+    if (matched.length === 0)
+        return null;
+    return { ...parsed, rowIds: matched };
+}
+/**
+ * Wrap a `GrafastSubscriber` so its stream yields parsed, gated payloads.
+ *
+ * Built per subscription (the throttle and `ids` are per-subscriber state), so
+ * one noisy client can no longer throttle every other subscriber to the same
+ * table — which a single build-time throttle instance did.
+ */
+export function createGatedSubscriber(inner, { ids, threshold }) {
+    const subscribedIds = ids && ids.length > 0 ? ids : null;
+    const throttle = new EventThrottle(threshold);
+    return {
+        async *subscribe(topic) {
+            const source = await inner.subscribe(topic);
+            for await (const raw of source) {
+                const payload = gate(String(raw), subscribedIds, throttle);
+                if (payload !== null)
+                    yield payload;
+            }
+        }
+        // Deliberately no release(): `inner` is the shared pgSubscriber from the
+        // request context and is not ours to tear down. Ending iteration returns
+        // the underlying iterator, which is the whole of our cleanup.
+    };
+}

package/esm/plugin.d.ts

@@ -17,8 +17,10 @@
  *   1. A row is inserted/updated/deleted
  *   2. The emit_change trigger fires pg_notify with TG_OP:row_ids or INVALIDATE
  *   3. PostGraphile's pgSubscriber receives the NOTIFY
- *   4. The plugin parses the payload and fetches the specific changed row(s)
- *   5. The client receives { event, row, rowId, overflow }
+ *   4. The gate (see event-gate.ts) parses, throttles and filters it — a
+ *      payload this subscription should not see never becomes an event
+ *   5. The plugin fetches the changed row(s)
+ *   6. The client receives { event, row, rowId, overflow }
  *
  * Cursor tracking (at-least-once delivery):
  *   The CursorTracker class provides a complementary polling-based delivery
@@ -31,7 +33,7 @@
  *
  * Overflow protection:
  *   - Database-side: statements affecting > 50 rows send INVALIDATE
- *   - Plugin-side: per-subscriber throttle (default 50 events/second/table)
+ *   - Plugin-side: per-subscription throttle (default 50 events/second/table)
  *     drops individual events and sends a single INVALIDATE when exceeded
  *
  * Security / RLS enforcement:
@@ -49,36 +51,11 @@ import type { GraphileConfig } from 'graphile-config';
 import type { RealtimeSubscriptionsPluginOptions } from './types';
 /** 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 type { ParsedPayload } from './event-gate';
+export { createGatedSubscriber, EventThrottle, MalformedNotifyPayloadError, parseNotifyPayload, } from './event-gate';
 export { RealtimeManager } from './realtime-manager';
 export type { ChangeLogEntry, CursorTrackerOptions, Queryable, RealtimeManagerOptions } from './types';
-export { DEFAULT_OVERFLOW_THRESHOLD, EventThrottle, parseNotifyPayload };
+export { DEFAULT_OVERFLOW_THRESHOLD };

package/esm/plugin.js

@@ -17,8 +17,10 @@
  *   1. A row is inserted/updated/deleted
  *   2. The emit_change trigger fires pg_notify with TG_OP:row_ids or INVALIDATE
  *   3. PostGraphile's pgSubscriber receives the NOTIFY
- *   4. The plugin parses the payload and fetches the specific changed row(s)
- *   5. The client receives { event, row, rowId, overflow }
+ *   4. The gate (see event-gate.ts) parses, throttles and filters it — a
+ *      payload this subscription should not see never becomes an event
+ *   5. The plugin fetches the changed row(s)
+ *   6. The client receives { event, row, rowId, overflow }
  *
  * Cursor tracking (at-least-once delivery):
  *   The CursorTracker class provides a complementary polling-based delivery
@@ -31,7 +33,7 @@
  *
  * Overflow protection:
  *   - Database-side: statements affecting > 50 rows send INVALIDATE
- *   - Plugin-side: per-subscriber throttle (default 50 events/second/table)
+ *   - Plugin-side: per-subscription throttle (default 50 events/second/table)
  *     drops individual events and sends a single INVALIDATE when exceeded
  *
  * Security / RLS enforcement:
@@ -48,61 +50,10 @@
 import { Logger } from '@pgpmjs/logger';
 import { constant, context as grafastContext, lambda, listen, object } from 'grafast';
 import { extendSchema } from 'graphile-utils';
+import { createGatedSubscriber } from './event-gate';
 const log = new Logger('graphile-realtime-subscriptions');
 /** Default overflow threshold: events per second per table per subscriber */
 const DEFAULT_OVERFLOW_THRESHOLD = 50;
-/**
- * Parse the NOTIFY payload from emit_change.
- * Format: "TG_OP:id1,id2,..." or "INVALIDATE"
- */
-function parseNotifyPayload(raw) {
-    if (raw === 'INVALIDATE') {
-        return { event: 'INVALIDATE', rowIds: [], overflow: true };
-    }
-    const colonIdx = raw.indexOf(':');
-    if (colonIdx === -1) {
-        return { event: raw || 'UNKNOWN', rowIds: [], overflow: false };
-    }
-    const event = raw.substring(0, colonIdx);
-    const idsPart = raw.substring(colonIdx + 1);
-    const rowIds = idsPart.length > 0 ? idsPart.split(',') : [];
-    return { event, rowIds, overflow: false };
-}
-/**
- * Per-subscriber, per-table event rate tracker.
- * Counts events in a sliding 1-second window.
- */
-class EventThrottle {
-    threshold;
-    windowStart = 0;
-    eventCount = 0;
-    overflowSent = false;
-    constructor(threshold) {
-        this.threshold = threshold;
-    }
-    /**
-     * 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() {
-        const now = Date.now();
-        if (now - this.windowStart >= 1000) {
-            this.windowStart = now;
-            this.eventCount = 0;
-            this.overflowSent = false;
-        }
-        this.eventCount++;
-        if (this.eventCount <= this.threshold) {
-            return 'deliver';
-        }
-        if (!this.overflowSent) {
-            this.overflowSent = true;
-            return 'overflow';
-        }
-        return 'drop';
-    }
-}
 function discoverRealtimeTables(build) {
     const { pgRegistry } = build.input;
     const resources = pgRegistry.pgResources;
@@ -155,44 +106,44 @@ function buildTypeDefs(tables) {
         .join('\n\n');
     return `extend type Subscription {\n${subscriptionFields}\n}\n\n${payloadTypes}`;
 }
+/**
+ * The gate never emits a null payload, so one here means the plan graph was
+ * rewired wrongly — fail rather than invent an event for the client.
+ */
+function requirePayload(payload) {
+    if (payload === null || payload === undefined) {
+        throw new Error('Realtime subscription payload is missing: the gated subscriber only ever ' +
+            'yields parsed payloads, so this event bypassed createGatedSubscriber.');
+    }
+    return payload;
+}
+/**
+ * The row this event reports. `rowIds` is already narrowed to the
+ * subscription's `ids`, so the first entry is the one to surface; INVALIDATE
+ * carries none, which is a genuine absence rather than a suppressed error.
+ */
+function reportedRowId(payload) {
+    if (payload.overflow)
+        return null;
+    return payload.rowIds[0] ?? null;
+}
 function buildPlans(tables, overflowThreshold) {
     const subscriptionPlans = {};
     const allPlans = {};
     for (const { resource, fieldName, payloadTypeName, rowFieldName, notifyChannel } of tables) {
-        const throttle = new EventThrottle(overflowThreshold);
         subscriptionPlans[fieldName] = {
             subscribePlan(_$root, args) {
                 const $pgSubscriber = grafastContext().get('pgSubscriber');
                 const $topic = constant(notifyChannel);
                 const $ids = args.getRaw('ids');
-                return listen($pgSubscriber, $topic, ($payload) => {
-                    const $parsed = lambda([$payload, $ids], (pair) => {
-                        const [raw, subscribedIds] = pair;
-                        const parsed = parseNotifyPayload(String(raw));
-                        const action = parsed.overflow ? 'deliver' : throttle.check();
-                        if (action === 'drop') {
-                            return null;
-                        }
-                        if (action === 'overflow') {
-                            return {
-                                event: 'INVALIDATE',
-                                rowIds: [],
-                                overflow: true,
-                            };
-                        }
-                        // Sparse set filtering: only deliver events for subscribed row IDs
-                        if (subscribedIds && subscribedIds.length > 0) {
-                            const hasMatch = parsed.rowIds.some((rid) => subscribedIds.includes(rid));
-                            if (!hasMatch)
-                                return null;
-                        }
-                        return parsed;
-                    });
-                    return object({
-                        parsed: $parsed,
-                        subscribedIds: $ids,
-                    });
+                // Parsing, throttling and sparse-set filtering all happen in the gate,
+                // built once per subscription, so the stream below yields only events
+                // that should reach this client — every step after it is total.
+                const $subscriber = lambda([$pgSubscriber, $ids], (pair) => {
+                    const [pgSubscriber, ids] = pair;
+                    return createGatedSubscriber(pgSubscriber, { ids, threshold: overflowThreshold });
                 });
+                return listen($subscriber, $topic, ($payload) => object({ parsed: $payload }));
             },
             plan($event) {
                 return $event;
@@ -200,41 +151,16 @@ function buildPlans(tables, overflowThreshold) {
         };
         allPlans[payloadTypeName] = {
             event($parent) {
-                const $parsed = $parent.get('parsed');
-                return lambda($parsed, (p) => p?.event ?? 'UNKNOWN');
+                return lambda($parent.get('parsed'), (p) => requirePayload(p).event);
             },
             rowId($parent) {
-                const $parsed = $parent.get('parsed');
-                const $subscribedIds = $parent.get('subscribedIds');
-                return lambda([$parsed, $subscribedIds], (pair) => {
-                    const [p, subscribedIds] = pair;
-                    if (!p || p.overflow || p.rowIds.length === 0)
-                        return null;
-                    // When ids are provided, return the first matching row ID
-                    if (subscribedIds && subscribedIds.length > 0) {
-                        return p.rowIds.find((rid) => subscribedIds.includes(rid)) ?? null;
-                    }
-                    return p.rowIds[0];
-                });
+                return lambda($parent.get('parsed'), (p) => reportedRowId(requirePayload(p)));
             },
             overflow($parent) {
-                const $parsed = $parent.get('parsed');
-                return lambda($parsed, (p) => p?.overflow ?? false);
+                return lambda($parent.get('parsed'), (p) => requirePayload(p).overflow);
             },
             [rowFieldName]($parent) {
-                const $parsed = $parent.get('parsed');
-                const $subscribedIds = $parent.get('subscribedIds');
-                const $rowId = lambda([$parsed, $subscribedIds], (tuple) => {
-                    const [p, subscribedIds] = tuple;
-                    if (!p || p.overflow || p.rowIds.length === 0)
-                        return null;
-                    // When ids are provided, return first matching row ID
-                    if (subscribedIds && subscribedIds.length > 0) {
-                        return p.rowIds.find((rid) => subscribedIds.includes(rid)) ?? null;
-                    }
-                    // Full collection mode: return first row ID
-                    return p.rowIds[0];
-                });
+                const $rowId = lambda($parent.get('parsed'), (p) => reportedRowId(requirePayload(p)));
                 return resource.get({ id: $rowId });
             },
         };
@@ -260,6 +186,6 @@ export function createRealtimeSubscriptionsPlugin(options = {}) {
 export { createRealtimeSubscriptionsPlugin as RealtimeSubscriptionsPlugin };
 // Re-export CursorTracker and RealtimeManager for convenience
 export { CursorTracker } from './cursor-tracker';
+export { createGatedSubscriber, EventThrottle, MalformedNotifyPayloadError, parseNotifyPayload, } from './event-gate';
 export { RealtimeManager } from './realtime-manager';
-// Exported for testing
-export { DEFAULT_OVERFLOW_THRESHOLD, EventThrottle, parseNotifyPayload };
+export { DEFAULT_OVERFLOW_THRESHOLD };

package/event-gate.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The gate between PostgreSQL's NOTIFY stream and a GraphQL subscription.
+ *
+ * Everything that can decide "this event should not reach the client" lives
+ * here, upstream of grafast, because grafast's `listen` maps each event to a
+ * step and offers no way to suppress one. Deciding downstream forced the
+ * plugin to represent "dropped" as a null payload, which the field resolvers
+ * then had to coalesce (`p?.event ?? 'UNKNOWN'`) — so a filtered event still
+ * reached the client, carrying an invented event name. Filtering here means
+ * the stream only ever yields events that should exist, and every resolver
+ * downstream is total.
+ *
+ * The gate also owns parsing and the overflow throttle, so a payload the
+ * trigger and the plugin disagree about fails loudly instead of arriving as
+ * an `UNKNOWN`-shaped record.
+ */
+import type { GrafastSubscriber } from 'grafast';
+export interface ParsedPayload {
+    event: string;
+    /**
+     * Row ids being reported. Already narrowed to the subscription's `ids` when
+     * it supplied any, so no consumer needs to re-intersect. Empty for
+     * INVALIDATE.
+     */
+    rowIds: string[];
+    overflow: boolean;
+}
+export declare class MalformedNotifyPayloadError extends Error {
+    constructor(raw: string, reason: string);
+}
+/**
+ * Parse the NOTIFY payload from `emit_change`.
+ * Format: `"TG_OP:id1,id2,..."` or `"INVALIDATE"`.
+ *
+ * Throws on anything else: a payload this cannot read means the trigger and
+ * this plugin have diverged, and inventing an event name for it hides a
+ * deployment fault behind data the client will act on.
+ */
+export declare function parseNotifyPayload(raw: string): ParsedPayload;
+/**
+ * Per-subscription event rate tracker. Counts events in a sliding 1-second
+ * window.
+ */
+export 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 interface EventGateOptions {
+    /** Sparse-set subscription: deliver only events touching these row ids. */
+    ids?: readonly string[] | null;
+    /** Events per second before the gate collapses the stream to one INVALIDATE. */
+    threshold: number;
+}
+/**
+ * Wrap a `GrafastSubscriber` so its stream yields parsed, gated payloads.
+ *
+ * Built per subscription (the throttle and `ids` are per-subscriber state), so
+ * one noisy client can no longer throttle every other subscriber to the same
+ * table — which a single build-time throttle instance did.
+ */
+export declare function createGatedSubscriber(inner: GrafastSubscriber<Record<string, string>>, { ids, threshold }: EventGateOptions): GrafastSubscriber<Record<string, ParsedPayload>>;

package/event-gate.js

@@ -0,0 +1,144 @@
+"use strict";
+/**
+ * The gate between PostgreSQL's NOTIFY stream and a GraphQL subscription.
+ *
+ * Everything that can decide "this event should not reach the client" lives
+ * here, upstream of grafast, because grafast's `listen` maps each event to a
+ * step and offers no way to suppress one. Deciding downstream forced the
+ * plugin to represent "dropped" as a null payload, which the field resolvers
+ * then had to coalesce (`p?.event ?? 'UNKNOWN'`) — so a filtered event still
+ * reached the client, carrying an invented event name. Filtering here means
+ * the stream only ever yields events that should exist, and every resolver
+ * downstream is total.
+ *
+ * The gate also owns parsing and the overflow throttle, so a payload the
+ * trigger and the plugin disagree about fails loudly instead of arriving as
+ * an `UNKNOWN`-shaped record.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventThrottle = exports.MalformedNotifyPayloadError = void 0;
+exports.parseNotifyPayload = parseNotifyPayload;
+exports.createGatedSubscriber = createGatedSubscriber;
+/** Operations `emit_change` is allowed to report. */
+const KNOWN_OPERATIONS = new Set(['INSERT', 'UPDATE', 'DELETE']);
+class MalformedNotifyPayloadError extends Error {
+    constructor(raw, reason) {
+        super(`Malformed realtime NOTIFY payload ${JSON.stringify(raw)}: ${reason}. ` +
+            'Expected "INVALIDATE" or "<INSERT|UPDATE|DELETE>:<uuid>[,<uuid>...]" ' +
+            'as emitted by the emit_change trigger.');
+        this.name = 'MalformedNotifyPayloadError';
+    }
+}
+exports.MalformedNotifyPayloadError = MalformedNotifyPayloadError;
+/**
+ * Parse the NOTIFY payload from `emit_change`.
+ * Format: `"TG_OP:id1,id2,..."` or `"INVALIDATE"`.
+ *
+ * Throws on anything else: a payload this cannot read means the trigger and
+ * this plugin have diverged, and inventing an event name for it hides a
+ * deployment fault behind data the client will act on.
+ */
+function parseNotifyPayload(raw) {
+    if (raw === 'INVALIDATE') {
+        return { event: 'INVALIDATE', rowIds: [], overflow: true };
+    }
+    const colonIdx = raw.indexOf(':');
+    if (colonIdx === -1) {
+        throw new MalformedNotifyPayloadError(raw, 'no ":" separating the operation from the row ids');
+    }
+    const event = raw.substring(0, colonIdx);
+    if (!KNOWN_OPERATIONS.has(event)) {
+        throw new MalformedNotifyPayloadError(raw, `unknown operation ${JSON.stringify(event)}`);
+    }
+    const idsPart = raw.substring(colonIdx + 1);
+    const rowIds = idsPart.length > 0 ? idsPart.split(',') : [];
+    if (rowIds.length === 0) {
+        throw new MalformedNotifyPayloadError(raw, `${event} carries no row ids`);
+    }
+    return { event, rowIds, overflow: false };
+}
+/**
+ * Per-subscription event rate tracker. Counts events in a sliding 1-second
+ * window.
+ */
+class EventThrottle {
+    threshold;
+    windowStart = 0;
+    eventCount = 0;
+    overflowSent = false;
+    constructor(threshold) {
+        this.threshold = threshold;
+    }
+    /**
+     * 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() {
+        const now = Date.now();
+        if (now - this.windowStart >= 1000) {
+            this.windowStart = now;
+            this.eventCount = 0;
+            this.overflowSent = false;
+        }
+        this.eventCount++;
+        if (this.eventCount <= this.threshold) {
+            return 'deliver';
+        }
+        if (!this.overflowSent) {
+            this.overflowSent = true;
+            return 'overflow';
+        }
+        return 'drop';
+    }
+}
+exports.EventThrottle = EventThrottle;
+/**
+ * Apply the gate to one raw NOTIFY payload.
+ *
+ * Returns the payload to deliver, or `null` meaning *do not emit* — a decision
+ * only this layer is allowed to make, because only this layer can act on it.
+ */
+function gate(raw, ids, throttle) {
+    const parsed = parseNotifyPayload(raw);
+    // An INVALIDATE is the overflow signal itself; throttling it would drop the
+    // one event telling the client to refetch.
+    if (parsed.overflow)
+        return parsed;
+    const action = throttle.check();
+    if (action === 'drop')
+        return null;
+    if (action === 'overflow') {
+        return { event: 'INVALIDATE', rowIds: [], overflow: true };
+    }
+    if (!ids || ids.length === 0)
+        return parsed;
+    const matched = parsed.rowIds.filter(rowId => ids.includes(rowId));
+    if (matched.length === 0)
+        return null;
+    return { ...parsed, rowIds: matched };
+}
+/**
+ * Wrap a `GrafastSubscriber` so its stream yields parsed, gated payloads.
+ *
+ * Built per subscription (the throttle and `ids` are per-subscriber state), so
+ * one noisy client can no longer throttle every other subscriber to the same
+ * table — which a single build-time throttle instance did.
+ */
+function createGatedSubscriber(inner, { ids, threshold }) {
+    const subscribedIds = ids && ids.length > 0 ? ids : null;
+    const throttle = new EventThrottle(threshold);
+    return {
+        async *subscribe(topic) {
+            const source = await inner.subscribe(topic);
+            for await (const raw of source) {
+                const payload = gate(String(raw), subscribedIds, throttle);
+                if (payload !== null)
+                    yield payload;
+            }
+        }
+        // Deliberately no release(): `inner` is the shared pgSubscriber from the
+        // request context and is not ours to tear down. Ending iteration returns
+        // the underlying iterator, which is the whole of our cleanup.
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphile-realtime-subscriptions",
-  "version": "1.10.0",
+  "version": "1.10.2",
   "description": "Realtime subscription plugin for PostGraphile v5 — per-table GraphQL subscriptions via LISTEN/NOTIFY",
   "author": "Constructive <developers@constructive.io>",
   "homepage": "https://github.com/constructive-io/constructive",
@@ -41,7 +41,7 @@
   },
   "dependencies": {
     "@pgpmjs/logger": "^2.24.0",
-    "@pgsql/quotes": "^18.2.0"
+    "@pgsql/quotes": "^18.2.1"
   },
   "peerDependencies": {
     "grafast": "1.0.2",
@@ -56,5 +56,5 @@
     "@types/node": "^22.19.11",
     "makage": "^0.3.0"
   },
-  "gitHead": "d508453a32a2f1d70ff6916871046615226e6f33"
+  "gitHead": "43121004a8bedd2c5fcf7bf33208079d55bad01f"
 }

package/plugin.d.ts

@@ -17,8 +17,10 @@
  *   1. A row is inserted/updated/deleted
  *   2. The emit_change trigger fires pg_notify with TG_OP:row_ids or INVALIDATE
  *   3. PostGraphile's pgSubscriber receives the NOTIFY
- *   4. The plugin parses the payload and fetches the specific changed row(s)
- *   5. The client receives { event, row, rowId, overflow }
+ *   4. The gate (see event-gate.ts) parses, throttles and filters it — a
+ *      payload this subscription should not see never becomes an event
+ *   5. The plugin fetches the changed row(s)
+ *   6. The client receives { event, row, rowId, overflow }
  *
  * Cursor tracking (at-least-once delivery):
  *   The CursorTracker class provides a complementary polling-based delivery
@@ -31,7 +33,7 @@
  *
  * Overflow protection:
  *   - Database-side: statements affecting > 50 rows send INVALIDATE
- *   - Plugin-side: per-subscriber throttle (default 50 events/second/table)
+ *   - Plugin-side: per-subscription throttle (default 50 events/second/table)
  *     drops individual events and sends a single INVALIDATE when exceeded
  *
  * Security / RLS enforcement:
@@ -49,36 +51,11 @@ import type { GraphileConfig } from 'graphile-config';
 import type { RealtimeSubscriptionsPluginOptions } from './types';
 /** 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 type { ParsedPayload } from './event-gate';
+export { createGatedSubscriber, EventThrottle, MalformedNotifyPayloadError, parseNotifyPayload, } from './event-gate';
 export { RealtimeManager } from './realtime-manager';
 export type { ChangeLogEntry, CursorTrackerOptions, Queryable, RealtimeManagerOptions } from './types';
-export { DEFAULT_OVERFLOW_THRESHOLD, EventThrottle, parseNotifyPayload };
+export { DEFAULT_OVERFLOW_THRESHOLD };

package/plugin.js

@@ -18,8 +18,10 @@
  *   1. A row is inserted/updated/deleted
  *   2. The emit_change trigger fires pg_notify with TG_OP:row_ids or INVALIDATE
  *   3. PostGraphile's pgSubscriber receives the NOTIFY
- *   4. The plugin parses the payload and fetches the specific changed row(s)
- *   5. The client receives { event, row, rowId, overflow }
+ *   4. The gate (see event-gate.ts) parses, throttles and filters it — a
+ *      payload this subscription should not see never becomes an event
+ *   5. The plugin fetches the changed row(s)
+ *   6. The client receives { event, row, rowId, overflow }
  *
  * Cursor tracking (at-least-once delivery):
  *   The CursorTracker class provides a complementary polling-based delivery
@@ -32,7 +34,7 @@
  *
  * Overflow protection:
  *   - Database-side: statements affecting > 50 rows send INVALIDATE
- *   - Plugin-side: per-subscriber throttle (default 50 events/second/table)
+ *   - Plugin-side: per-subscription throttle (default 50 events/second/table)
  *     drops individual events and sends a single INVALIDATE when exceeded
  *
  * Security / RLS enforcement:
@@ -47,70 +49,17 @@
  *     preventing cross-tenant event leaks.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EventThrottle = exports.DEFAULT_OVERFLOW_THRESHOLD = exports.RealtimeManager = exports.CursorTracker = void 0;
+exports.DEFAULT_OVERFLOW_THRESHOLD = exports.RealtimeManager = exports.parseNotifyPayload = exports.MalformedNotifyPayloadError = exports.EventThrottle = exports.createGatedSubscriber = exports.CursorTracker = void 0;
 exports.createRealtimeSubscriptionsPlugin = createRealtimeSubscriptionsPlugin;
 exports.RealtimeSubscriptionsPlugin = createRealtimeSubscriptionsPlugin;
-exports.parseNotifyPayload = parseNotifyPayload;
 const logger_1 = require("@pgpmjs/logger");
 const grafast_1 = require("grafast");
 const graphile_utils_1 = require("graphile-utils");
+const event_gate_1 = require("./event-gate");
 const log = new logger_1.Logger('graphile-realtime-subscriptions');
 /** Default overflow threshold: events per second per table per subscriber */
 const DEFAULT_OVERFLOW_THRESHOLD = 50;
 exports.DEFAULT_OVERFLOW_THRESHOLD = DEFAULT_OVERFLOW_THRESHOLD;
-/**
- * Parse the NOTIFY payload from emit_change.
- * Format: "TG_OP:id1,id2,..." or "INVALIDATE"
- */
-function parseNotifyPayload(raw) {
-    if (raw === 'INVALIDATE') {
-        return { event: 'INVALIDATE', rowIds: [], overflow: true };
-    }
-    const colonIdx = raw.indexOf(':');
-    if (colonIdx === -1) {
-        return { event: raw || 'UNKNOWN', rowIds: [], overflow: false };
-    }
-    const event = raw.substring(0, colonIdx);
-    const idsPart = raw.substring(colonIdx + 1);
-    const rowIds = idsPart.length > 0 ? idsPart.split(',') : [];
-    return { event, rowIds, overflow: false };
-}
-/**
- * Per-subscriber, per-table event rate tracker.
- * Counts events in a sliding 1-second window.
- */
-class EventThrottle {
-    threshold;
-    windowStart = 0;
-    eventCount = 0;
-    overflowSent = false;
-    constructor(threshold) {
-        this.threshold = threshold;
-    }
-    /**
-     * 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() {
-        const now = Date.now();
-        if (now - this.windowStart >= 1000) {
-            this.windowStart = now;
-            this.eventCount = 0;
-            this.overflowSent = false;
-        }
-        this.eventCount++;
-        if (this.eventCount <= this.threshold) {
-            return 'deliver';
-        }
-        if (!this.overflowSent) {
-            this.overflowSent = true;
-            return 'overflow';
-        }
-        return 'drop';
-    }
-}
-exports.EventThrottle = EventThrottle;
 function discoverRealtimeTables(build) {
     const { pgRegistry } = build.input;
     const resources = pgRegistry.pgResources;
@@ -163,44 +112,44 @@ function buildTypeDefs(tables) {
         .join('\n\n');
     return `extend type Subscription {\n${subscriptionFields}\n}\n\n${payloadTypes}`;
 }
+/**
+ * The gate never emits a null payload, so one here means the plan graph was
+ * rewired wrongly — fail rather than invent an event for the client.
+ */
+function requirePayload(payload) {
+    if (payload === null || payload === undefined) {
+        throw new Error('Realtime subscription payload is missing: the gated subscriber only ever ' +
+            'yields parsed payloads, so this event bypassed createGatedSubscriber.');
+    }
+    return payload;
+}
+/**
+ * The row this event reports. `rowIds` is already narrowed to the
+ * subscription's `ids`, so the first entry is the one to surface; INVALIDATE
+ * carries none, which is a genuine absence rather than a suppressed error.
+ */
+function reportedRowId(payload) {
+    if (payload.overflow)
+        return null;
+    return payload.rowIds[0] ?? null;
+}
 function buildPlans(tables, overflowThreshold) {
     const subscriptionPlans = {};
     const allPlans = {};
     for (const { resource, fieldName, payloadTypeName, rowFieldName, notifyChannel } of tables) {
-        const throttle = new EventThrottle(overflowThreshold);
         subscriptionPlans[fieldName] = {
             subscribePlan(_$root, args) {
                 const $pgSubscriber = (0, grafast_1.context)().get('pgSubscriber');
                 const $topic = (0, grafast_1.constant)(notifyChannel);
                 const $ids = args.getRaw('ids');
-                return (0, grafast_1.listen)($pgSubscriber, $topic, ($payload) => {
-                    const $parsed = (0, grafast_1.lambda)([$payload, $ids], (pair) => {
-                        const [raw, subscribedIds] = pair;
-                        const parsed = parseNotifyPayload(String(raw));
-                        const action = parsed.overflow ? 'deliver' : throttle.check();
-                        if (action === 'drop') {
-                            return null;
-                        }
-                        if (action === 'overflow') {
-                            return {
-                                event: 'INVALIDATE',
-                                rowIds: [],
-                                overflow: true,
-                            };
-                        }
-                        // Sparse set filtering: only deliver events for subscribed row IDs
-                        if (subscribedIds && subscribedIds.length > 0) {
-                            const hasMatch = parsed.rowIds.some((rid) => subscribedIds.includes(rid));
-                            if (!hasMatch)
-                                return null;
-                        }
-                        return parsed;
-                    });
-                    return (0, grafast_1.object)({
-                        parsed: $parsed,
-                        subscribedIds: $ids,
-                    });
+                // Parsing, throttling and sparse-set filtering all happen in the gate,
+                // built once per subscription, so the stream below yields only events
+                // that should reach this client — every step after it is total.
+                const $subscriber = (0, grafast_1.lambda)([$pgSubscriber, $ids], (pair) => {
+                    const [pgSubscriber, ids] = pair;
+                    return (0, event_gate_1.createGatedSubscriber)(pgSubscriber, { ids, threshold: overflowThreshold });
                 });
+                return (0, grafast_1.listen)($subscriber, $topic, ($payload) => (0, grafast_1.object)({ parsed: $payload }));
             },
             plan($event) {
                 return $event;
@@ -208,41 +157,16 @@ function buildPlans(tables, overflowThreshold) {
         };
         allPlans[payloadTypeName] = {
             event($parent) {
-                const $parsed = $parent.get('parsed');
-                return (0, grafast_1.lambda)($parsed, (p) => p?.event ?? 'UNKNOWN');
+                return (0, grafast_1.lambda)($parent.get('parsed'), (p) => requirePayload(p).event);
             },
             rowId($parent) {
-                const $parsed = $parent.get('parsed');
-                const $subscribedIds = $parent.get('subscribedIds');
-                return (0, grafast_1.lambda)([$parsed, $subscribedIds], (pair) => {
-                    const [p, subscribedIds] = pair;
-                    if (!p || p.overflow || p.rowIds.length === 0)
-                        return null;
-                    // When ids are provided, return the first matching row ID
-                    if (subscribedIds && subscribedIds.length > 0) {
-                        return p.rowIds.find((rid) => subscribedIds.includes(rid)) ?? null;
-                    }
-                    return p.rowIds[0];
-                });
+                return (0, grafast_1.lambda)($parent.get('parsed'), (p) => reportedRowId(requirePayload(p)));
             },
             overflow($parent) {
-                const $parsed = $parent.get('parsed');
-                return (0, grafast_1.lambda)($parsed, (p) => p?.overflow ?? false);
+                return (0, grafast_1.lambda)($parent.get('parsed'), (p) => requirePayload(p).overflow);
             },
             [rowFieldName]($parent) {
-                const $parsed = $parent.get('parsed');
-                const $subscribedIds = $parent.get('subscribedIds');
-                const $rowId = (0, grafast_1.lambda)([$parsed, $subscribedIds], (tuple) => {
-                    const [p, subscribedIds] = tuple;
-                    if (!p || p.overflow || p.rowIds.length === 0)
-                        return null;
-                    // When ids are provided, return first matching row ID
-                    if (subscribedIds && subscribedIds.length > 0) {
-                        return p.rowIds.find((rid) => subscribedIds.includes(rid)) ?? null;
-                    }
-                    // Full collection mode: return first row ID
-                    return p.rowIds[0];
-                });
+                const $rowId = (0, grafast_1.lambda)($parent.get('parsed'), (p) => reportedRowId(requirePayload(p)));
                 return resource.get({ id: $rowId });
             },
         };
@@ -268,5 +192,10 @@ function createRealtimeSubscriptionsPlugin(options = {}) {
 // Re-export CursorTracker and RealtimeManager for convenience
 var cursor_tracker_1 = require("./cursor-tracker");
 Object.defineProperty(exports, "CursorTracker", { enumerable: true, get: function () { return cursor_tracker_1.CursorTracker; } });
+var event_gate_2 = require("./event-gate");
+Object.defineProperty(exports, "createGatedSubscriber", { enumerable: true, get: function () { return event_gate_2.createGatedSubscriber; } });
+Object.defineProperty(exports, "EventThrottle", { enumerable: true, get: function () { return event_gate_2.EventThrottle; } });
+Object.defineProperty(exports, "MalformedNotifyPayloadError", { enumerable: true, get: function () { return event_gate_2.MalformedNotifyPayloadError; } });
+Object.defineProperty(exports, "parseNotifyPayload", { enumerable: true, get: function () { return event_gate_2.parseNotifyPayload; } });
 var realtime_manager_1 = require("./realtime-manager");
 Object.defineProperty(exports, "RealtimeManager", { enumerable: true, get: function () { return realtime_manager_1.RealtimeManager; } });