@rotorsoft/act-pg 1.9.3 → 1.10.1

package/dist/index.js

@@ -48,7 +48,35 @@ var DEFAULT_CONFIG = {
   password: "postgres",
   schema: "public",
   table: "events",
-  notify: false
+  notify: false,
+  // Opinionated pool defaults (#1119). node-postgres ships `max: 10`
+  // with no acquisition timeout and no statement timeout — a saturated
+  // pool makes every caller hang indefinitely instead of failing with
+  // a diagnosable error. Nearly every store method holds a client for
+  // a multi-statement transaction, so multi-lane drains plus API
+  // traffic can exhaust a 10-client pool quickly. All four values are
+  // plain `pg.PoolConfig` fields — caller config overrides any of them
+  // via the constructor spread.
+  //
+  // - `max: 20` — floor for the default lane's parallel handler budget
+  //   (streamLimit 10, each commit holds a client) plus API commits,
+  //   the optional LISTEN client, and headroom. Sizing rule in the
+  //   README: Σ per-lane streamLimit + API concurrency + notify + 2–4.
+  // - `connectionTimeoutMillis: 10_000` — fail acquisition fast (the
+  //   pg default of 0 waits forever); surfaces as StoreError via
+  //   `_client()` so operators see *which* operation starved.
+  // - `idleTimeoutMillis: 30_000` — keep idle clients warm across
+  //   drain cycles (cycleMs can exceed the pg default of 10s in
+  //   low-traffic deployments) without pinning connections for long.
+  // - `statement_timeout: 60_000` — per-statement (not per-transaction)
+  //   ceiling; every statement the store issues (claim CTE, seed DDL,
+  //   truncate, restore's per-event inserts) legitimately completes
+  //   orders of magnitude faster, so 60s only fires on a wedged server
+  //   or a lost lock instead of holding the client hostage.
+  max: 20,
+  connectionTimeoutMillis: 1e4,
+  idleTimeoutMillis: 3e4,
+  statement_timeout: 6e4
 };
 var PostgresStore = class {
   _pool;
@@ -119,6 +147,21 @@ var PostgresStore = class {
     }
     this._resolve_pii_key = this.config.pii_encryption ? makeKeyResolver(this.config.pii_encryption) : void 0;
   }
+  /**
+   * Acquire a pooled client, translating acquisition failures into
+   * {@link StoreError} with the calling operation as context. With the
+   * default `connectionTimeoutMillis`, a saturated pool fails here
+   * after 10s with `Store operation "<operation>" failed` (driver
+   * error preserved as `cause`) instead of hanging indefinitely.
+   * Every method that checks out a client routes through this helper.
+   */
+  async _client(operation) {
+    try {
+      return await this._pool.connect();
+    } catch (error) {
+      throw new StoreError(operation, { cause: error });
+    }
+  }
   /**
    * Dispose of the store and close all database connections.
    * Releases any active LISTEN client first so the pool can drain cleanly.
@@ -152,7 +195,7 @@ var PostgresStore = class {
    * @throws Error if seeding fails
    */
   async seed() {
-    const client = await this._pool.connect();
+    const client = await this._client("seed");
     try {
       await client.query("BEGIN");
       await client.query(
@@ -205,7 +248,8 @@ var PostgresStore = class {
           leased_by text,
           leased_until timestamptz,
           priority int NOT NULL DEFAULT 0,
-          lane text NOT NULL DEFAULT 'default'
+          lane text NOT NULL DEFAULT 'default',
+          deferred_at timestamptz
         ) TABLESPACE pg_default;`
       );
       await client.query(
@@ -216,6 +260,10 @@ var PostgresStore = class {
         `ALTER TABLE ${this._fqs}
          ADD COLUMN IF NOT EXISTS lane text NOT NULL DEFAULT 'default';`
       );
+      await client.query(
+        `ALTER TABLE ${this._fqs}
+         ADD COLUMN IF NOT EXISTS deferred_at timestamptz;`
+      );
       await client.query(
         `DROP INDEX IF EXISTS "${this.config.schema}"."${this.config.table}_streams_fetch_ix"`
       );
@@ -360,7 +408,7 @@ var PostgresStore = class {
    */
   async commit(stream, msgs, meta, expectedVersion) {
     if (msgs.length === 0) return [];
-    const client = await this._pool.connect();
+    const client = await this._client("commit");
     let version = -1;
     try {
       await client.query("BEGIN");
@@ -442,7 +490,7 @@ var PostgresStore = class {
    * @returns Leased streams with metadata
    */
   async claim(lagging, leading, by, millis, lane) {
-    const client = await this._pool.connect();
+    const client = await this._client("claim");
     try {
       await client.query("BEGIN");
       const lane_clause = lane !== void 0 ? `AND s.lane = $5` : "";
@@ -456,6 +504,7 @@ var PostgresStore = class {
           WHERE blocked = false
             ${lane_clause}
             AND (leased_by IS NULL OR leased_until <= NOW())
+            AND (deferred_at IS NULL OR deferred_at <= NOW())
             AND (s.at < 0 OR EXISTS (
               SELECT 1 FROM ${this._fqt} e
               WHERE e.id > s.at
@@ -523,7 +572,7 @@ var PostgresStore = class {
    * @returns subscribed count and current max watermark.
    */
   async subscribe(streams) {
-    const client = await this._pool.connect();
+    const client = await this._client("subscribe");
     try {
       await client.query("BEGIN");
       let subscribed = 0;
@@ -583,7 +632,7 @@ var PostgresStore = class {
    * @returns Acked leases.
    */
   async ack(leases) {
-    const client = await this._pool.connect();
+    const client = await this._client("ack");
     try {
       await client.query("BEGIN");
       const { rows } = await client.query(
@@ -597,7 +646,8 @@ var PostgresStore = class {
         at = i.at,
         retry = -1,
         leased_by = NULL,
-        leased_until = NULL
+        leased_until = NULL,
+        deferred_at = NULL
       FROM input i
       WHERE s.stream = i.stream AND s.leased_by = i.by
       RETURNING s.stream, s.source, s.at, i.by, s.retry, i.lagging, s.lane
@@ -628,7 +678,7 @@ var PostgresStore = class {
    * @returns Blocked leases.
    */
   async block(leases) {
-    const client = await this._pool.connect();
+    const client = await this._client("block");
     try {
       await client.query("BEGIN");
       const { rows } = await client.query(
@@ -638,7 +688,7 @@ var PostgresStore = class {
         AS x(stream text, by text, error text, lagging boolean)
       )
       UPDATE ${this._fqs} AS s
-      SET blocked = true, error = i.error
+      SET blocked = true, error = i.error, deferred_at = NULL
       FROM input i
       WHERE s.stream = i.stream AND s.leased_by = i.by AND s.blocked = false
       RETURNING s.stream, s.source, s.at, i.by, s.retry, s.error, i.lagging, s.lane
@@ -664,6 +714,33 @@ var PostgresStore = class {
       client.release();
     }
   }
+  /**
+   * Hold the matched streams out of {@link claim} until `deferred_at`
+   * (ms since epoch) — see {@link Store.defer}. Persists `deferred_at`
+   * (as a `timestamptz`) so the skip is honored by every competing
+   * worker; `claim` filters on `deferred_at <= NOW()`. Accepts an
+   * explicit list of names or a {@link StreamFilter}, mirroring
+   * {@link reset}/{@link prioritize}. Cleared by ack/block/reset/unblock.
+   *
+   * @returns Count of streams whose `deferred_at` was set.
+   */
+  async defer(input, deferred_at) {
+    const set_clause = `SET deferred_at = to_timestamp($1 / 1000.0), retry = -1`;
+    if (Array.isArray(input)) {
+      if (!input.length) return 0;
+      const { rowCount: rowCount2 } = await this._pool.query(
+        `UPDATE ${this._fqs} ${set_clause} WHERE stream = ANY($2)`,
+        [deferred_at, input]
+      );
+      return rowCount2 ?? 0;
+    }
+    const { clause, values } = this._filter_clause(input, 2);
+    const { rowCount } = await this._pool.query(
+      `UPDATE ${this._fqs} ${set_clause} WHERE ${clause}`,
+      [deferred_at, ...values]
+    );
+    return rowCount ?? 0;
+  }
   /**
    * Reset watermarks for the given streams to -1, clearing retry, blocked,
    * error, and lease state so they can be replayed from the beginning.
@@ -707,7 +784,7 @@ var PostgresStore = class {
   }
   async reset(input) {
     const set_clause = `SET at = -1, retry = -1, blocked = false, error = NULL,
-                          leased_by = NULL, leased_until = NULL`;
+                          leased_by = NULL, leased_until = NULL, deferred_at = NULL`;
     if (Array.isArray(input)) {
       if (!input.length) return 0;
       const { rowCount: rowCount2 } = await this._pool.query(
@@ -740,7 +817,7 @@ var PostgresStore = class {
    */
   async unblock(input) {
     const set_clause = `SET retry = -1, blocked = false, error = NULL,
-                          leased_by = NULL, leased_until = NULL`;
+                          leased_by = NULL, leased_until = NULL, deferred_at = NULL`;
     if (Array.isArray(input)) {
       if (!input.length) return 0;
       const { rowCount: rowCount2 } = await this._pool.query(
@@ -832,7 +909,7 @@ var PostgresStore = class {
     if (conditions.length) sql += " WHERE " + conditions.join(" AND ");
     values.push(limit);
     sql += ` ORDER BY stream LIMIT $${values.length}`;
-    const client = await this._pool.connect();
+    const client = await this._client("query_streams");
     try {
       const [streamsResult, maxResult] = await Promise.all([
         client.query(sql, values),
@@ -1062,7 +1139,7 @@ var PostgresStore = class {
    */
   async _subscribe_notifications(handler) {
     await this._teardown_listen();
-    const client = await this._pool.connect();
+    const client = await this._client("notify");
     const on_notification = (msg) => {
       if (msg.channel !== this._channel) return;
       if (!msg.payload) return;
@@ -1123,7 +1200,7 @@ var PostgresStore = class {
   async truncate(targets) {
     if (!targets.length) return /* @__PURE__ */ new Map();
     const streams = targets.map((t) => t.stream);
-    const client = await this._pool.connect();
+    const client = await this._client("truncate");
     try {
       await client.query("BEGIN");
       await client.query(`DELETE FROM ${this._fqs} WHERE stream = ANY($1)`, [
@@ -1174,7 +1251,7 @@ var PostgresStore = class {
    * from 1. `created` is preserved verbatim from the source.
    */
   async restore(driver) {
-    const client = await this._pool.connect();
+    const client = await this._client("restore");
     try {
       await client.query("BEGIN");
       await client.query(