@sguild/dispatcher 2.0.0

package/dist/postgres-consumer.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Postgres-queue transport: consumer-side polling worker.
+ *
+ * Implements the consume path of the bus dispatcher per ADR-0009
+ * §"Decision". Long-lived process (typically run from
+ * `<repo>/scripts/<consumer>-subscriber.ts` per the per-domain module
+ * pattern) that polls `dispatcher_event` past a per-(consumer,
+ * event_type) cursor, dedups against `dispatcher_dedup`, invokes the
+ * registered handler, retries on exception with exponential backoff and
+ * jitter, dead-letters on exhaustion, and advances the cursor atomically
+ * with the dedup write on success (or the dead-letter write on
+ * exhaustion).
+ *
+ * Phase 2 Slice 3 (this file): poll-only consumer. The LISTEN/NOTIFY
+ * wake-up primitive ADR-0009 §"Decision" calls for is the Slice 3b
+ * deliverable; Slice 3 ships poll-only because the polling loop is the
+ * durable fallback regardless of whether LISTEN/NOTIFY is wired, and
+ * shipping poll-only first gives consumers a working subscriber surface
+ * to scaffold against. Consumers cut over to the same call shape when
+ * LISTEN/NOTIFY lands; only the latency profile changes (sub-second on
+ * the happy path, polling cadence as the fallback under either model).
+ *
+ * Per-consumer scope: each consumer instance is identified by a
+ * stable string (e.g., "coaching-availability-subscriber") that goes
+ * onto the cursor and dedup rows. A given consumer string MUST be
+ * unique across deployments; running two processes against the same
+ * consumer string causes them to compete for cursor advancement and
+ * the dedup window collapses to per-consumer-id rather than
+ * per-process. Per the build plan §3, the typical shape is one
+ * consumer string per long-lived worker process per domain.
+ *
+ * Per-event-type fan-out: a single ConsumerLoop instance processes
+ * all subscribed event_types serially within a poll cycle (one
+ * batch per event_type, in registration order). For workloads where
+ * one event_type has substantially higher volume than others and the
+ * serial drain becomes a latency bottleneck, run multiple
+ * ConsumerLoop instances against the same database with different
+ * consumer strings — but typical Sguild volume per consumer fits
+ * comfortably inside a single loop's drain cadence.
+ */
+import { Pool } from "pg";
+import type { SubscribeHandler } from "./types";
+export type ConsumerLoopOptions = {
+    /**
+     * Stable identifier for this consumer. Goes onto cursor, dedup, and
+     * dead-letter rows. MUST be unique across deployments; the convention
+     * is one consumer string per long-lived worker process per domain
+     * (e.g., "coaching-availability-subscriber",
+     * "delivery-customer-tracking-subscriber").
+     */
+    consumer: string;
+    /** Default 50. Larger values amortize cursor I/O over more rows; smaller values reduce per-cycle latency at the tail. */
+    batchSize?: number;
+    /** Default 5000 ms. Slice 3b's LISTEN/NOTIFY wake-up will make this the fallback cadence rather than the typical wake-up time. */
+    pollIntervalMs?: number;
+    /** Default [1000, 5000, 15000] ms. Each value is the base; actual sleep adds 0-30 percent jitter. */
+    retryDelaysMs?: number[];
+    /**
+     * pg.Pool this loop reads cursor/event/dedup/dead-letter rows from
+     * via raw SQL. Raw SQL (unqualified table names) lets Postgres
+     * resolve the schema via the connection's search_path, which
+     * `pgConfigWithSearchPath` derives from the producer DSN's
+     * `?schema=<domain>` query param. This
+     * keeps the loop schema-agnostic so the same code works against
+     * Platform's `public` schema, Growth's `growth` schema, Sales' `sales`
+     * schema, etc., without Prisma's hard-coded `public.` qualification
+     * getting in the way.
+     *
+     * Defaults to a pool constructed against `process.env.DATABASE_URL` so
+     * the in-process Platform dispatcher path keeps working unchanged. The
+     * multi-producer fanout overrides with a producer-specific pool from
+     * `producer-db.ts`.
+     */
+    pool?: Pool;
+    /**
+     * DSN used for the LISTEN/NOTIFY wake-up connection. The pg.Client
+     * created here MUST connect to the same database as `pool` above so
+     * the NOTIFY payload corresponds to the dispatcher_event rows the
+     * polling path reads. Defaults to `process.env.DATABASE_URL`; the
+     * multi-producer fanout overrides with the producer's DSN.
+     */
+    databaseUrl?: string;
+    /**
+     * Schema name parsed from the DSN's `?schema=<name>` query param
+     * (null/undefined means use the default search_path, typically `public`).
+     * When set, ConsumerLoop schema-qualifies every SQL query
+     * (`"<schema>".dispatcher_cursor` instead of `dispatcher_cursor`).
+     *
+     * Required for Supabase pooler DSNs because the pgbouncer transaction-mode
+     * pooler silently drops the libpq `options=-c search_path=...` startup
+     * parameter — meaning search_path is effectively whatever the connection's
+     * role default is, not what the DSN declared. Schema-qualified table names
+     * bypass search_path entirely.
+     */
+    schema?: string | null;
+};
+export type RegisteredHandler = {
+    eventType: string;
+    handler: SubscribeHandler<unknown>;
+};
+export declare class ConsumerLoop {
+    private readonly handlers;
+    private running;
+    private inflight;
+    private readonly options;
+    private readonly pool;
+    private readonly ownsPool;
+    private readonly databaseUrl;
+    /**
+     * Quoted table-name prefix. Empty string when no schema is configured;
+     * `"<schema>".` (with trailing dot) when a schema is set. Prepended to
+     * every dispatcher_X table reference in the SQL queries so they work
+     * even when Supabase's pooler drops the search_path option.
+     */
+    private readonly tablePrefix;
+    private readonly subscribedEventTypes;
+    private listenClient;
+    private listenReconnectScheduled;
+    private listenReconnectAttempt;
+    private sleepAbort;
+    constructor(handlers: ReadonlyArray<RegisteredHandler>, options: ConsumerLoopOptions);
+    /**
+     * Start the polling loop with LISTEN/NOTIFY wake-up. Resolves when
+     * `stop()` is called and the current in-flight batch (if any) finishes
+     * draining; otherwise runs forever.
+     *
+     * The LISTEN connection is best-effort: if it fails to set up or drops
+     * mid-flight, the polling loop still drains at the configured cadence
+     * and reconnect attempts run with backoff. Sub-second wake-up is the
+     * happy path; degraded poll-cadence wake-up is the durable fallback.
+     */
+    start(): Promise<void>;
+    /**
+     * Graceful shutdown. Sets the running flag false, wakes the polling
+     * loop early so it exits the current sleep without waiting for the
+     * full poll interval, then waits for the in-flight batch to drain
+     * before resolving. Closes the LISTEN connection on the way out.
+     */
+    stop(): Promise<void>;
+    private getCursorLastSeq;
+    private findEventsAfter;
+    private getDedupHit;
+    /**
+     * Single-transaction dedup-insert + cursor-advance. The pg.PoolClient
+     * is checked out for the transaction so the BEGIN/COMMIT pair is
+     * scoped to one connection. Errors trigger a ROLLBACK and the loop
+     * retries via the normal retry path.
+     */
+    private commitSuccessfulDelivery;
+    private commitDeadLetter;
+    private processBatchForEventType;
+    private deliverEvent;
+    private advanceCursor;
+    private sleep;
+    /**
+     * Detect whether a DSN points at a transaction-mode pooler (Supabase's
+     * pgbouncer at port 6543). LISTEN holds a connection open waiting for
+     * NOTIFY; transaction-mode pooling reuses connections across queries
+     * and rejects LISTEN with ENOIDENTIFIER. The fix is to skip the LISTEN
+     * client entirely against pooler URLs and rely on polling. Operators
+     * who want sub-second wake-up can either provide a session-mode URL
+     * (port 5432 / direct connection) via a future databaseUrl override
+     * or run a non-pooler DSN.
+     *
+     * Signal: `pgbouncer=true` query param OR port 6543 anywhere in the
+     * URL. Both are conventions Supabase generates for pooled URLs.
+     */
+    private isPoolerDsn;
+    private startListenConnection;
+    private scheduleListenReconnect;
+    private stopListenConnection;
+    private onNotification;
+    private wakeUp;
+    private sleepOrWakeUp;
+}