@voltro/sql-postgres 0.55.0 → 0.56.0

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { ChangeEvent } from '@voltro/database';
 import { ChangeStrategy } from '@voltro/database';
+import { ChangeStreamGap } from '@voltro/database';
 import { ConfigError } from 'effect';
 import { ConnectionConfig } from '@voltro/database';
 import { Context } from 'effect';
@@ -20,6 +21,51 @@ import { SqlDialect } from '@voltro/database';
 import { SqlError } from '@effect/sql';
 import { TransactionConnection } from '@effect/sql/SqlClient';
 
+/** Marker payload for the heartbeat, on the same channel as the changes.
+ *
+ *  A separate channel would need a second `LISTEN` — and a second thing that can
+ *  be registered on a connection whose FIRST registration is the one in doubt.
+ *  Sharing the channel means the probe exercises exactly the subscription the
+ *  changes ride on, which is the whole point of probing. */
+export declare const CDC_HEARTBEAT_MARKER = "__voltro_cdc_heartbeat";
+
+export declare interface CdcLivenessState {
+    /** Wall-clock ms of the last notification of ANY kind on the channel. */
+    readonly lastHeardAtMs: number;
+    /** When the outstanding probe was sent; `null` when none is outstanding. */
+    readonly probeSentAtMs: number | null;
+}
+
+export declare interface CdcLivenessTunables {
+    /** Silence on the channel before a probe is sent. */
+    readonly idleMs: number;
+    /** How long a sent probe may go unheard before the consumer is declared dead. */
+    readonly timeoutMs: number;
+}
+
+/** What the watchdog should do on this tick. */
+export declare type CdcLivenessVerdict = 
+/** Traffic is recent (or a probe is still within its deadline) — do nothing. */
+'healthy'
+/** Nothing heard for `idleMs` — send a heartbeat and start the deadline. */
+| 'probe'
+/** A probe went unanswered for `timeoutMs` — the consumer is deaf; reconnect. */
+| 'reconnect';
+
+/**
+ * Pure verdict for one watchdog tick.
+ *
+ * The ordering of the two branches is load-bearing: an outstanding probe is
+ * resolved FIRST. Checking idleness first would re-arm the probe on every tick
+ * of a dead connection and the deadline would never expire — the watchdog would
+ * beat forever at a corpse and never once conclude anything.
+ */
+export declare const cdcLivenessVerdict: (state: CdcLivenessState, nowMs: number, tunables?: CdcLivenessTunables) => CdcLivenessVerdict;
+
+/** Reconnect backoff: 250ms doubling to a 10s ceiling. Uncapped attempts —
+ *  a consumer that gives up is the defect this file exists to remove. */
+export declare const cdcReconnectDelayMs: (attempt: number) => number;
+
 /**
  * Every number the CDC consumer would otherwise pick on your behalf, with its
  * default. Each is also readable from the environment, so an operator can tune
@@ -66,6 +112,8 @@ export declare type DatabaseConnectionLayer = ReturnType<typeof makePostgresSqlL
 
 export declare type DatabaseConnectionLayerInput = Parameters<typeof makePostgresSqlLayer>[0];
 
+export declare const DEFAULT_CDC_LIVENESS: CdcLivenessTunables;
+
 /** Encode one row as a COPY TEXT line (no trailing newline). */
 export declare const encodeCopyRow: (row: Readonly<Record<string, unknown>>, columns: ReadonlyArray<string>, columnTypes?: Readonly<Record<string, string>>) => string;
 
@@ -242,8 +290,23 @@ export declare class PostgresDataStore implements DataStore {
     private readonly changeStrategy;
     private readonly cdcChannel;
     private readonly cdcRehydrate;
+    private readonly cdcLiveness;
     private readonly emitter;
     private cdcFiber;
+    /** Watchdog state for the LISTEN consumer — see `cdcLiveness.ts` for why a
+     *  dropped LISTEN connection cannot be detected by waiting for an error. */
+    private cdcWatchdog;
+    private cdcLastHeardAt;
+    /** Notifications received on this channel, ever. A COUNTER and not the
+     *  timestamp, because "did anything arrive since I asked" is not answerable
+     *  from a clock two events can share a millisecond of. */
+    private cdcHeardCount;
+    private cdcProbeSentAt;
+    /** Serialises the watchdog's reconnect with any later one, so a slow
+     *  re-listen cannot be raced into two live consumers on one channel. */
+    private cdcReconnecting;
+    private cdcStopped;
+    private readonly cdcGapListeners;
     /** In-flight count of `transactional()` calls. `close()` waits for
      *  this to drop to 0 (or its grace period to expire) before disposing
      *  the runtime — preventing connection-pool teardown mid-COMMIT. */
@@ -255,7 +318,7 @@ export declare class PostgresDataStore implements DataStore {
     /** PERF-23 — counts EVERY eager JSON-agg → walker degradation and logs a
      *  rate-limited line. Instance-scoped for the same reason as above. */
     private readonly reportEagerFallback;
-    constructor(sql: SqlClient.SqlClient, runtime: ManagedRuntime.ManagedRuntime<SqlClient.SqlClient | PgClient.PgClient, never>, changeStrategy: ChangeStrategy, cdcChannel: string, cdcRehydrate?: CdcRehydrateTunables);
+    constructor(sql: SqlClient.SqlClient, runtime: ManagedRuntime.ManagedRuntime<SqlClient.SqlClient | PgClient.PgClient, never>, changeStrategy: ChangeStrategy, cdcChannel: string, cdcRehydrate?: CdcRehydrateTunables, cdcLiveness?: CdcLivenessTunables);
     /**
      * The DIALECT half of the shared transaction bracket
      * (`runStoreTransaction` / `runRetryingTransaction` in `@voltro/database`).
@@ -569,6 +632,41 @@ export declare class PostgresDataStore implements DataStore {
      * what re-hydration can and cannot recover.
      */
     startCdcConsumer(): Promise<void>;
+    /**
+     * Wait until the consumer can PROVE it receives — by hearing its own
+     * heartbeat come back.
+     *
+     * `runFork` returns before the stream's `LISTEN` has executed, so a consumer
+     * that has merely been started is not yet a consumer that hears anything.
+     * That window is small and it is real: this test suite caught a change written
+     * 20ms after a "reconnected" log line being lost, which is the very failure the
+     * reconnect exists to end — reintroduced one level down, and reported as
+     * success. An echo is the only evidence that settles it.
+     */
+    private proveCdcListening;
+    /**
+     * Register the gap listener the reactive layer recovers with.
+     *
+     * Fires AFTER the consumer is listening again, never while it is down: the
+     * recovery is "re-run every live query", and re-running them against a
+     * connection that is still deaf just produces a second stale answer.
+     */
+    onChangeStreamGap(listener: (gap: ChangeStreamGap) => void): () => void;
+    private emitCdcGap;
+    /** Open (or re-open) the LISTEN stream and fork the consumer onto it. */
+    private attachCdcStream;
+    /** Probe an idle channel, and reconnect a consumer that stops answering. */
+    private startCdcWatchdog;
+    private cdcWatchdogTick;
+    /**
+     * Tear the consumer down and open a new one, retrying until it succeeds.
+     *
+     * Reports a gap on success. That second half is what makes the recovery
+     * correct rather than merely alive: every NOTIFY sent while the connection was
+     * down is gone — postgres queues nothing for a listener that is not there — so
+     * a consumer that reconnects silently keeps serving whatever it last saw.
+     */
+    private reconnectCdc;
 }
 
 export declare interface PostgresDataStoreOptions {
@@ -626,6 +724,11 @@ export declare const postgresReplicationAdapter: () => DialectReplicationAdapter
 /** `SqlDialect.retryFilter` implementation for postgres. */
 export declare const postgresRetryFilter: (err: unknown) => RetryDecision;
 
+/** Read the tunables from env, ignoring values that would disable the watchdog.
+ *  A zero or negative `idleMs` would probe on every tick; a zero `timeoutMs`
+ *  would declare every probe dead before its echo could arrive. */
+export declare const resolveCdcLiveness: (env?: Record<string, string | undefined>, overrides?: Partial<CdcLivenessTunables>) => CdcLivenessTunables;
+
 /**
  * Captured inside `transactional()`'s `withTransaction` scope. Holds the
  * `TransactionConnection` context tuple `[Connection, depth]` so we can