@rotorsoft/act-pg 1.9.3 → 1.10.1

package/dist/@types/postgres-store.d.ts

@@ -110,18 +110,18 @@ type Config = Readonly<{
  *
  * @example Connection pooling configuration
  * ```typescript
- * // PostgresStore uses node-postgres (pg) connection pooling
- * // Pool is created automatically with default settings
- * // For custom pool config, use environment variables:
- * //   PGHOST, PGPORT, PGDATABASE, PGUSER, PGPASSWORD
- * //   PGMAXCONNECTIONS, PGIDLETIMEOUT, etc.
+ * // PostgresStore uses node-postgres (pg) connection pooling with
+ * // opinionated defaults: max 20, connectionTimeoutMillis 10s,
+ * // idleTimeoutMillis 30s, statement_timeout 60s. Any pg.PoolConfig
+ * // field passed to the constructor overrides the default.
  *
  * const pgStore = new PostgresStore({
  *   host: "db.example.com",
  *   port: 5432,
  *   database: "production",
  *   user: "app_user",
- *   password: process.env.DB_PASSWORD
+ *   password: process.env.DB_PASSWORD,
+ *   max: 40  // lanes × streamLimit + API concurrency + headroom
  * });
  * ```
  *
@@ -212,6 +212,15 @@ export declare class PostgresStore implements Store {
      * @param config Partial configuration (host, port, user, password, schema, table, etc.)
      */
     constructor(config?: Partial<Config>);
+    /**
+     * 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.
+     */
+    private _client;
     /**
      * Dispose of the store and close all database connections.
      * Releases any active LISTEN client first so the pool can drain cleanly.
@@ -303,6 +312,17 @@ export declare class PostgresStore implements Store {
      * @returns Blocked leases.
      */
     block(leases: BlockedLease[]): Promise<BlockedLease[]>;
+    /**
+     * 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.
+     */
+    defer(input: string[] | StreamFilter, deferred_at: number): Promise<number>;
     /**
      * Reset watermarks for the given streams to -1, clearing retry, blocked,
      * error, and lease state so they can be replayed from the beginning.

package/dist/@types/postgres-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"postgres-store.d.ts","sourceRoot":"","sources":["../../src/postgres-store.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"postgres-store.d.ts","sourceRoot":"","sources":["../../src/postgres-store.ts"],"names":[],"mappings":"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"}

package/dist/index.cjs

@@ -74,7 +74,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;
@@ -145,6 +173,21 @@ var PostgresStore = class {
     }
     this._resolve_pii_key = this.config.pii_encryption ? (0, import_act_crypto.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 import_act.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.
@@ -178,7 +221,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(
@@ -231,7 +274,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(
@@ -242,6 +286,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"`
       );
@@ -386,7 +434,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");
@@ -468,7 +516,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` : "";
@@ -482,6 +530,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
@@ -549,7 +598,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;
@@ -609,7 +658,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(
@@ -623,7 +672,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
@@ -654,7 +704,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(
@@ -664,7 +714,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
@@ -690,6 +740,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.
@@ -733,7 +810,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(
@@ -766,7 +843,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(
@@ -858,7 +935,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),
@@ -1088,7 +1165,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;
@@ -1149,7 +1226,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)`, [
@@ -1200,7 +1277,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(