bullmq 6.3.0 → 6.3.2

package/dist/esm/postgres/postgres-connection.d.ts

@@ -88,6 +88,22 @@ export declare class PostgresConnection extends EventEmitter {
      * (owned pool); `false` when it is a pooled client we must `release()`.
      */
     private listenClientIsStandalone;
+    /**
+     * Whether TCP keepalive is known to be enabled on the dedicated `LISTEN`
+     * connection. Only then can a silently dropped connection be detected (as a
+     * socket `'error'`) and rebuilt, which is the premise of the backend's large
+     * {@link PostgresQueueBackend.maximumBlockTimeout}; when it is not, the
+     * backend falls back to a conservative block ceiling instead.
+     */
+    private listenClientKeepAlive;
+    /**
+     * The last `application_name` applied to the `LISTEN` client (via
+     * {@link setListenClientName}). Re-applied whenever that client is rebuilt: a
+     * fresh connection starts unnamed, which would otherwise silently drop the
+     * worker / QueueEvents from `getWorkers()` / `getQueueEvents()` for the rest
+     * of its lifetime.
+     */
+    private listenClientName;
     constructor(connection: PostgresConnectionOptions);
     /**
      * Forwards an underlying pool / LISTEN-client error as this connection's
@@ -117,6 +133,40 @@ export declare class PostgresConnection extends EventEmitter {
      * out of it (so such pools should be sized `>= 2`).
      */
     getListenClient(): Promise<PgListenClient>;
+    /**
+     * Whether TCP keepalive is enabled on the dedicated `LISTEN` connection, so a
+     * silently dropped connection is detected (and the client rebuilt) instead of
+     * lingering unnoticed. Consulted by the backend when deciding how long a
+     * worker may block.
+     */
+    get hasListenClientKeepAlive(): boolean;
+    /**
+     * Sets the `application_name` of the dedicated `LISTEN` connection — the
+     * PostgreSQL analogue of Redis `CLIENT SETNAME` — and remembers it so it is
+     * re-applied to any client rebuilt after a drop.
+     */
+    setListenClientName(name: string): Promise<void>;
+    /**
+     * Re-applies the remembered {@link listenClientName} to a freshly established
+     * `LISTEN` client. Best-effort: discovery must never break the client.
+     */
+    private applyListenClientName;
+    /**
+     * Handles a fatal error on the dedicated `LISTEN` client.
+     *
+     * A `LISTEN` subscription lives on one specific physical connection: once that
+     * connection drops, the memoized client is dead and every re-`LISTEN` issued
+     * on it is silently lost — so a blocked worker would stop receiving NOTIFYs
+     * until its next poll. Invalidate the memo (and tear the dead client down) so
+     * the next {@link getListenClient} establishes a fresh connection, and emit
+     * `'listenerinvalidated'` so subscribed backends re-`LISTEN` and wake any
+     * in-flight blocking wait (which is parked on the now-dead client).
+     *
+     * Guarded so a stale error from an already-replaced client — or one racing an
+     * in-progress {@link close} (which owns teardown) — does not disturb the
+     * current client; the error is still forwarded either way.
+     */
+    private handleListenClientError;
     /**
      * Truthy once {@link PostgresConnection.close} has begun.
      */

package/dist/esm/postgres/postgres-connection.js

@@ -24,6 +24,34 @@ function loadPgModule() {
         'already-constructed `pg.Pool` instance as the connection instead of a ' +
         'config object or connection string.');
 }
+/**
+ * Idle time (ms) before the first TCP keepalive probe is sent on the dedicated
+ * `LISTEN` connection. Short enough that a silently dropped connection is
+ * detected in seconds instead of the OS default (typically two hours) — which,
+ * with a large `maximumBlockTimeout`, is what a blocked worker would otherwise
+ * have to wait for.
+ */
+const LISTEN_KEEPALIVE_INITIAL_DELAY_MS = 10000;
+/**
+ * Best-effort: turns TCP keepalive on for an already-established client's
+ * socket. Needed for the pooled `LISTEN` client, since a user-supplied
+ * `pg.Pool` may have been created without `keepAlive` and a checked-out client
+ * inherits that configuration. Returns whether keepalive is now enabled.
+ */
+function enableSocketKeepAlive(client) {
+    var _a;
+    const stream = (_a = client.connection) === null || _a === void 0 ? void 0 : _a.stream;
+    if (!stream || typeof stream.setKeepAlive !== 'function') {
+        return false;
+    }
+    try {
+        stream.setKeepAlive(true, LISTEN_KEEPALIVE_INITIAL_DELAY_MS);
+        return true;
+    }
+    catch (_b) {
+        return false;
+    }
+}
 /**
  * Owns the PostgreSQL connection resources for a single backend:
  *
@@ -37,6 +65,7 @@ function loadPgModule() {
  */
 export class PostgresConnection extends EventEmitter {
     constructor(connection) {
+        var _a;
         super();
         /**
          * `true` when {@link listenClient} is a standalone `pg.Client` we must `end()`
@@ -51,10 +80,13 @@ export class PostgresConnection extends EventEmitter {
             this.migrateOnConnect = false;
             this.pgModule = undefined;
             this.listenClientConfig = undefined;
+            // A user-supplied pool decides its own `keepAlive`; when it is off we try
+            // to enable it on the checked-out LISTEN socket (see getListenClient).
+            this.listenClientKeepAlive = Boolean((_a = connection.options) === null || _a === void 0 ? void 0 : _a.keepAlive);
         }
         else {
             const pg = loadPgModule();
-            const _a = typeof connection === 'string'
+            const _b = typeof connection === 'string'
                 ? {
                     schema: undefined,
                     skipVersionCheck: undefined,
@@ -62,7 +94,7 @@ export class PostgresConnection extends EventEmitter {
                     skipMigrations: undefined,
                     connectionString: connection,
                 }
-                : connection, { schema, skipVersionCheck, migrate, skipMigrations } = _a, poolConfig = __rest(_a, ["schema", "skipVersionCheck", "migrate", "skipMigrations"]);
+                : connection, { schema, skipVersionCheck, migrate, skipMigrations } = _b, poolConfig = __rest(_b, ["schema", "skipVersionCheck", "migrate", "skipMigrations"]);
             if (migrate !== undefined && skipMigrations !== undefined) {
                 throw new Error('BullMQ: `migrate` and `skipMigrations` are mutually exclusive. Set only one.');
             }
@@ -85,6 +117,8 @@ export class PostgresConnection extends EventEmitter {
             // Keep the means to build a dedicated LISTEN connection on demand.
             this.pgModule = pg;
             this.listenClientConfig = resolvedConfig;
+            // We build the LISTEN client ourselves, always with keepAlive enabled.
+            this.listenClientKeepAlive = true;
         }
         // The pool emits 'error' for idle clients that drop; surface it but never
         // let it crash the process — hence the guarded {@link emitError} (a bare
@@ -153,24 +187,117 @@ export class PostgresConnection extends EventEmitter {
         if (!this.listenClientPromise) {
             this.listenClientPromise = (async () => {
                 if (this.pgModule && this.listenClientConfig) {
-                    const client = new this.pgModule.Client(this.listenClientConfig);
+                    const client = new this.pgModule.Client(Object.assign(Object.assign({}, this.listenClientConfig), { 
+                        // A LISTEN subscription is bound to one physical connection. Enable
+                        // TCP keepalive so a silently dropped connection surfaces as a
+                        // socket `'error'` (and is then rebuilt below) instead of going
+                        // unnoticed until the next poll — which, with a large
+                        // `maximumBlockTimeout`, could be up to an hour away.
+                        keepAlive: true, keepAliveInitialDelayMillis: LISTEN_KEEPALIVE_INITIAL_DELAY_MS }));
                     await client.connect();
-                    client.on('error', err => this.emitError(err));
+                    client.on('error', err => this.handleListenClientError(client, err));
+                    this.listenClientKeepAlive = true;
                     this.listenClientIsStandalone = true;
                     this.listenClient = client;
+                    await this.applyListenClientName(client);
                     return client;
                 }
                 else {
                     const client = await this.pool.connect();
-                    client.on('error', err => this.emitError(err));
+                    client.on('error', err => this.handleListenClientError(client, err));
+                    // The pool is the user's, so its clients may have been created
+                    // without `keepAlive`; enable it on this socket so a silent drop is
+                    // still detected. If that is not possible the connection reports no
+                    // keepalive and the backend caps its block timeout conservatively.
+                    this.listenClientKeepAlive =
+                        this.listenClientKeepAlive || enableSocketKeepAlive(client);
                     this.listenClientIsStandalone = false;
                     this.listenClient = client;
+                    await this.applyListenClientName(client);
                     return client;
                 }
             })();
         }
         return this.listenClientPromise;
     }
+    /**
+     * Whether TCP keepalive is enabled on the dedicated `LISTEN` connection, so a
+     * silently dropped connection is detected (and the client rebuilt) instead of
+     * lingering unnoticed. Consulted by the backend when deciding how long a
+     * worker may block.
+     */
+    get hasListenClientKeepAlive() {
+        return this.listenClientKeepAlive;
+    }
+    /**
+     * Sets the `application_name` of the dedicated `LISTEN` connection — the
+     * PostgreSQL analogue of Redis `CLIENT SETNAME` — and remembers it so it is
+     * re-applied to any client rebuilt after a drop.
+     */
+    async setListenClientName(name) {
+        this.listenClientName = name;
+        const client = await this.getListenClient();
+        await client.query(`SELECT set_config('application_name', $1, false)`, [
+            name,
+        ]);
+    }
+    /**
+     * Re-applies the remembered {@link listenClientName} to a freshly established
+     * `LISTEN` client. Best-effort: discovery must never break the client.
+     */
+    async applyListenClientName(client) {
+        if (!this.listenClientName) {
+            return;
+        }
+        try {
+            await client.query(`SELECT set_config('application_name', $1, false)`, [
+                this.listenClientName,
+            ]);
+        }
+        catch (_a) {
+            // Discovery is best-effort; leave the connection unnamed.
+        }
+    }
+    /**
+     * Handles a fatal error on the dedicated `LISTEN` client.
+     *
+     * A `LISTEN` subscription lives on one specific physical connection: once that
+     * connection drops, the memoized client is dead and every re-`LISTEN` issued
+     * on it is silently lost — so a blocked worker would stop receiving NOTIFYs
+     * until its next poll. Invalidate the memo (and tear the dead client down) so
+     * the next {@link getListenClient} establishes a fresh connection, and emit
+     * `'listenerinvalidated'` so subscribed backends re-`LISTEN` and wake any
+     * in-flight blocking wait (which is parked on the now-dead client).
+     *
+     * Guarded so a stale error from an already-replaced client — or one racing an
+     * in-progress {@link close} (which owns teardown) — does not disturb the
+     * current client; the error is still forwarded either way.
+     */
+    handleListenClientError(client, err) {
+        if (this.listenClient === client && !this.closing) {
+            const wasStandalone = this.listenClientIsStandalone;
+            this.listenClient = undefined;
+            this.listenClientPromise = undefined;
+            // Drop orphaned notification listeners from in-flight waits; keep the
+            // 'error' listener so a follow-up error from the dying client is still
+            // swallowed via `emitError` rather than crashing the process.
+            client.removeAllListeners('notification');
+            try {
+                if (wasStandalone) {
+                    void client.end().catch(() => undefined);
+                }
+                else {
+                    // Destroy (rather than return) the broken pooled client.
+                    client.release(true);
+                }
+            }
+            catch (_a) {
+                // Best-effort teardown of an already-broken client.
+            }
+            this.emit('listenerinvalidated');
+        }
+        this.emitError(err);
+    }
     /**
      * Truthy once {@link PostgresConnection.close} has begun.
      */

package/dist/esm/postgres/postgres-queue-backend.d.ts

@@ -78,6 +78,21 @@ export declare class PostgresQueueBackend extends EventEmitter implements IQueue
      * positive timeout is fine; we mirror the Redis backend's smallest unit.
      */
     get minimumBlockTimeout(): number;
+    /**
+     * PostgreSQL `LISTEN`/`NOTIFY` keeps the connection open and re-arms the wait
+     * to the next due delayed job, so there is no cheap-reconnect reason to cap
+     * the block at 10s like Redis. A large ceiling lets an idle worker go quiet
+     * instead of re-polling every 10s (important for serverless Postgres that
+     * suspends when idle). 3600s stays well under the 32-bit `setTimeout` ms
+     * ceiling (~24.8 days) that a larger delay would overflow.
+     *
+     * This relies on a dropped LISTEN connection being *detected* (TCP keepalive)
+     * and rebuilt; when keepalive could not be enabled — a user-supplied
+     * `pg.Pool` configured without it, whose checked-out client we could not
+     * adjust — a silent drop would go unnoticed for the whole block, so the
+     * ceiling stays at the conservative Redis-like 10s instead.
+     */
+    get maximumBlockTimeout(): number;
     forQueue(queueName: string, _prefix?: string): IQueueBackend;
     /**
      * The queue's qualified name. With a schema-based namespace there is no

package/dist/esm/postgres/postgres-queue-backend.js

@@ -186,6 +186,19 @@ export class PostgresQueueBackend extends EventEmitter {
             this.connection.on('error', err => this.emit('error', err));
             this.connection.on('ready', () => this.emit('ready'));
             this.connection.on('close', () => this.emit('close'));
+            // When the shared LISTEN client drops, the connection rebuilds it and
+            // emits `'listenerinvalidated'`. Re-issue our LISTENs on the fresh client
+            // and wake any in-flight wait (parked on the now-dead client) so the
+            // worker loop re-enters waitForJob/readEvents and re-subscribes. Only the
+            // connection-owning backend blocks (and thus LISTENs); non-owning
+            // `forQueue` siblings never do.
+            this.connection.on('listenerinvalidated', () => {
+                var _a, _b;
+                this.listening = false;
+                this.listeningEvents = false;
+                (_a = this.cancelWait) === null || _a === void 0 ? void 0 : _a.call(this);
+                (_b = this.cancelEventWait) === null || _b === void 0 ? void 0 : _b.call(this);
+            });
         }
     }
     // ============================================================
@@ -243,12 +256,11 @@ export class PostgresQueueBackend extends EventEmitter {
         // PostgreSQL analogue of Redis `CLIENT SETNAME`. This is the long-lived
         // connection a worker / QueueEvents holds, so it appears (under this name)
         // in pg_stat_activity and is therefore discoverable by getWorkers /
-        // getQueueEvents via getClientList.
+        // getQueueEvents via getClientList. The connection remembers the name and
+        // re-applies it whenever it has to rebuild the LISTEN client (a fresh
+        // connection would otherwise start unnamed, i.e. undiscoverable).
         await this.connection.waitUntilReady();
-        const client = await this.connection.getListenClient();
-        await client.query(`SELECT set_config('application_name', $1, false)`, [
-            name,
-        ]);
+        await this.connection.setListenClientName(name);
     }
     /**
      * PostgreSQL `LISTEN`/`NOTIFY` has no minimum block granularity, so any
@@ -257,6 +269,23 @@ export class PostgresQueueBackend extends EventEmitter {
     get minimumBlockTimeout() {
         return 0.001;
     }
+    /**
+     * PostgreSQL `LISTEN`/`NOTIFY` keeps the connection open and re-arms the wait
+     * to the next due delayed job, so there is no cheap-reconnect reason to cap
+     * the block at 10s like Redis. A large ceiling lets an idle worker go quiet
+     * instead of re-polling every 10s (important for serverless Postgres that
+     * suspends when idle). 3600s stays well under the 32-bit `setTimeout` ms
+     * ceiling (~24.8 days) that a larger delay would overflow.
+     *
+     * This relies on a dropped LISTEN connection being *detected* (TCP keepalive)
+     * and rebuilt; when keepalive could not be enabled — a user-supplied
+     * `pg.Pool` configured without it, whose checked-out client we could not
+     * adjust — a silent drop would go unnoticed for the whole block, so the
+     * ceiling stays at the conservative Redis-like 10s instead.
+     */
+    get maximumBlockTimeout() {
+        return this.connection.hasListenClientKeepAlive ? 3600 : 10;
+    }
     forQueue(queueName, _prefix) {
         // The namespace is the connection's schema, shared by all queues, so a
         // sibling backend only needs a different queue name. BullMQ's per-queue