mail-time 5.2.1 → 5.3.1

package/README.md

@@ -35,7 +35,7 @@ Many clients + one or more servers coexist behind the same `prefix` in the same
 - 📮 **Email concatenation** — fold same-`to` emails arriving inside a window into one letter.
 - 🎛️ **One-line setup** — built-in [presets](#settings-presets) for `transactional`, `otp`, `newsletter`, `marketing`, `notifications`, `alerts`.
 - 🛢️ **Three first-party storages** — MongoDB, Redis, PostgreSQL. Plus a [custom-adapter contract](https://github.com/veliovgroup/mail-time/blob/master/docs/queue-api.md).
-- 📦 **Bun ≥ 1.1.0 & Node ≥ 20.9.0** — same code, both runtimes.
+- 📦 **Bun ≥ 1.1.0 & Node ≥ 14.19.3** — same code, both runtimes. See [supported runtimes](#supported-runtimes).
 - 🤖 **Ships with AI agent skills** — see [AI agent skills](#ai-agent-skills) below.
 - 📐 **Hand-tuned ESM + CJS + TypeScript declarations**.
 - 🧪 **99%+ Jest line coverage** (85% threshold enforced) + Mocha integration tests for every adapter.
@@ -176,7 +176,7 @@ Three things every MailTime needs: a connected storage **client**, one or more *
 // ESM
 import { MailTime, MongoQueue, PostgresQueue, RedisQueue, mailTimePreset } from 'mail-time';
 
-// CommonJS
+// CommonJS (subpaths such as require('mail-time/presets') resolve too, 5.3.1+)
 const { MailTime, MongoQueue, PostgresQueue, RedisQueue, mailTimePreset } = require('mail-time');
 ```
 
@@ -374,13 +374,13 @@ Defaults fit moderate traffic in a single region. Reach for a [preset](#settings
 | `mode`                                         | `'batch'`        | `'one'` to claim a single row per tick (fairness over throughput across cluster nodes)                                             |
 | `concurrency`                                  | `1`              | Raise to send N emails in parallel per instance. CAS blocks concurrent claims; SMTP rate limits still apply.                     |
 | `sendingTimeout`                               | `300000` (5 min) | Stale-lock recovery window. Must exceed worst-case SMTP roundtrip; MailTime logs a warning below `120000`. |
-| `renewClaim`                                   | `sendingTimeout / 3` | Set `false` to go back to a single stamp at claim time. Lower it if your storage round-trip is slow relative to `sendingTimeout`. |
+| `renewClaim`                                   | `sendingTimeout / 3` (min 1000 ms) | Set `false` to go back to a single stamp at claim time. Lower it if your storage round-trip is slow relative to `sendingTimeout`. |
 | `maxRenewals`                                  | `10`             | Renewal-attempt ceiling. Recovery begins `sendingTimeout` after last successful stamp; with responsive storage this is roughly `sendingTimeout + maxRenewals × renewClaim`. |
 | `shouldFailOver`                               | —                | Set when your transport can tell "never delivered" from "may have been delivered" — see [Transport fail-over](#transport-fail-over). |
 | `strictPayload`                                | `false`          | Turn on when anything other than your own app can write to the queue storage. |
 | `revolvingInterval`                            | `1536` ms        | Lower → faster pickup; higher → less scheduler I/O                                                                                 |
 | `josk.minRevolvingDelay` / `maxRevolvingDelay` | `512` / `2048`   | Lower both → snappier polls, more storage load                                                                                     |
-| `josk.zombieTime`                              | `60000`          | **Never below 60s.** After an unclean stop during a claimed scan, JoSk 6.4 preserves the claim until `zombieTime`; use graceful destroy on redeploy. |
+| `josk.zombieTime`                              | `60000`          | **Never below 60s.** After an unclean stop during a claimed scan, JoSk 6.4+ preserves the claim until `zombieTime`; use graceful destroy on redeploy. |
 | `josk.concurrency`                             | `Infinity`       | Set `1` if scheduler ticks overlap while `iterate` still runs                                                                      |
 | `josk.execute`                                 | `'batch'`        | Usually leave default; MailTime only registers one JoSk task per instance                                                          |
 | `josk.lockOwnerId`                             | random           | Set in production for observability                                                                                                |
@@ -425,7 +425,7 @@ new MailTime({
 });
 ```
 
-Only the SMTP envelope is filtered. Headers remain unchanged; some transports retain BCC in generated MIME. If suppressed addresses must not appear in message content, remove them from headers before enqueueing. See [recipient policy hooks, outcomes, recovery, and rollout](https://github.com/veliovgroup/mail-time/blob/master/docs/recipient-policies.md).
+Each `to`, `cc`, `bcc`, and `from` entry must hold one mailbox, for example `"Doe, John" <user@example.com>` or `{ name, address }`; use arrays for several recipients. An address MailTime cannot parse fails the task without SMTP or further retries, with `error.code === 'MAIL_TIME_INVALID_ADDRESS'` and `error.field` naming the field. Only the SMTP envelope is filtered. Headers remain unchanged; some transports retain BCC in generated MIME. If suppressed addresses must not appear in message content, remove them from headers before enqueueing. See [recipient policy hooks, outcomes, recovery, and rollout](https://github.com/veliovgroup/mail-time/blob/master/docs/recipient-policies.md).
 
 ## Queue payload trust
 
@@ -514,19 +514,20 @@ await mailQueue.sendMail({
 | `mode`                        | `'one' \| 'batch'`                                  | `'batch'`                  | `'batch'` claims every due row per tick; `'one'` claims a single row per tick.                                                                                                              |
 | `concurrency`                 | `number`                                            | `1`                        | Parallel SMTPs per instance. CAS blocks concurrent claims for one row.                                                                                                                      |
 | `sendingTimeout`              | `number` (ms)                                       | `300000`                   | Window after which a stuck `isSending=true` row becomes eligible again. Must exceed worst-case SMTP roundtrip; values below `120000` log a warning.                                          |
-| `renewClaim`                  | `boolean \| number` (ms)                            | `sendingTimeout / 3`       | Re-stamp `sendingAt` on the claimed row while its SMTP roundtrip runs, so a slow-but-healthy send never loses its lock to a recovery worker. `false` restores the v4 single-stamp behaviour. |
+| `renewClaim`                  | `boolean \| number` (ms)                            | `sendingTimeout / 3` (min 1000 ms) | Re-stamp `sendingAt` on the claimed row while its SMTP roundtrip runs, so a slow-but-healthy send never loses its lock to a recovery worker. `false` restores the v4 single-stamp behaviour. |
 | `maxRenewals`                 | `number`                                            | `10`                       | Renewal-attempt budget per send. Recovery begins `sendingTimeout` after last successful stamp; slow renewal writes can extend elapsed time beyond the nominal interval calculation.          |
 | `shouldFailOver`              | `(error, info, email) => boolean`                   | —                          | Veto rotating to the next transport for this failure. Default: rotate unless the error carries `mayFailOver === false`. See [Transport fail-over](#transport-fail-over).                     |
 | `strictPayload`               | `boolean`                                           | `false`                    | Narrow every queued letter to `allowedMailFields` and force nodemailer's `disableFileAccess` / `disableUrlAccess`. See [Queue payload trust](#queue-payload-trust).                          |
 | `allowedMailFields`           | `string[]`                                          | —                          | Extra field names permitted under `strictPayload` (added to the built-in allowlist).                                                                                                        |
-| `verifyTransports`            | `boolean`                                           | `true`                     | Probe each transport via `transport.verify()` once at `ready()`. Failing transports are marked unusable, surfaced through `onError(error, null, { transportIndex, phase: 'verify' })`, and skipped during rotation/fallback. Throws from `ready()` if **every** transport fails. Transports without a `verify()` method are treated as healthy. |
+| `verifyTransports`            | `boolean`                                           | `true`                     | Probe each transport with `transport.verify()` at `ready()`. A failing transport is quarantined (skipped in rotation and fallback) and reported once through `onError(error, null, { transportIndex, phase: 'verify' })`; `ready()` throws only if every transport fails. Quarantined transports are re-probed in the background (60 s, doubling to 15 min) and return to rotation on success. Verdict rules, timeouts and recovery: [transport verification](https://github.com/veliovgroup/mail-time/blob/master/docs/transport-verification.md). |
+| `verifyTimeout`               | `number`                                            | `30000`                    | Milliseconds `ready()` waits per `transport.verify()`; also the budget of each background re-probe. On timeout `ready()` stops waiting and the transport keeps its current health; a late verdict still applies. Values above `2147483647` (including `Infinity`) are clamped; anything else invalid uses `30000`. |
 | `template`                    | `string`                                            | `'{{{html}}}'`             | Default envelope.                                                                                                                                                                           |
 | `prefix`                      | `string`                                            | `''`                       | Queue namespace. **Same** on every `client` and `server` for one logical queue; **different** per email class. Inherited by the queue adapter; JoSk scheduler uses `mailTimeQueue<prefix>`. |
 | `from`                        | `string \| (transport, details) => string`          | —                          | Strongly recommended for spam-passing `From:` formatting. `details` is `{ index, from }` — see [Resolving the sender](#resolving-the-sender).                                                |
 | `debug`                       | `boolean`                                           | `false`                    | Verbose logs.                                                                                                                                                                               |
 | `onSent(email, info)`         | `function`                                          | —                          | Without policies, called once the task is fully delivered. Policy mode adds grouped `recipients, summary` arguments. `email.mailOptions[i].accepted` lists every address that got through (across all attempts).                                                        |
-| `onError(error, email, info)` | `function`                                          | —                          | Without policies, called once the retry budget is exhausted with at least one un-accepted recipient. Policy mode adds grouped `recipients, summary` arguments. `email.mailOptions[i].rejected` lists each un-delivered address with its last error. Also fires once per transport that fails `verify()` at startup with `email === null` and `info = { transportIndex, phase: 'verify' }`. |
-| `recipientPolicies` | `MailTimeRecipientPolicy[]` | — | Optional nonempty provider list. See [Recipient policies](#recipient-policies). |
+| `onError(error, email, details)` | `function`                                       | —                          | `details` is typed `MailTimeErrorDetails`: `{ phase?, transportIndex?, attempt? }` plus the SMTP `info` keys of a failed attempt. Without policies, called once the retry budget is exhausted with at least one un-accepted recipient. Policy mode adds grouped `recipients, summary` arguments. `email.mailOptions[i].rejected` lists each un-delivered address with its last error. Also fires once per transport that fails `verify()` at startup with `email === null` and `details = { transportIndex, phase: 'verify' }`. Also fires once when a storage write that records a send outcome throws, with `details.phase` of `'complete'` (final or retry-release write) or `'checkpoint'` (policy mode, recipient results after SMTP). |
+| `recipientPolicies` | `MailTimeRecipientPolicy[]` | — | Optional nonempty provider list. When set, `sendMail()` rejects an unparseable address (`MAIL_TIME_INVALID_ADDRESS`, `error.field` such as `to[1]`) before enqueue, and a `server` constructor throws for an unparseable string `from` or transport `from` (`transports[i].from`). See [Recipient policies](#recipient-policies). |
 | `onSuppressed(task, recipients, summary)` | `function` | — | Terminal suppressed group in policy mode. |
 | `onRejected(task, recipients, summary)` | `function` | — | Terminal permanently rejected group in policy mode. |
 
@@ -557,9 +558,9 @@ For deeper JoSk semantics, install the JoSk skill: **`npx skills add veliovgroup
 - `cancelMail(uuidOrPromise)` → `Promise<boolean>`. Accepts the `uuid` or the `Promise<string>` from `sendMail`.
 - `cancel(uuid)` — alias of `cancelMail`.
 - `ping()` → `Promise<{status, code, statusCode, paused?, error?}>`. Pings scheduler then queue; `paused` reflects `isPaused`.
-- `ready()` → `Promise<MailTime>`. Awaits all startup work; rejects with `.cause` on storage failure.
+- `ready()` → `Promise<MailTime>`. Awaits all startup work; rejects on storage failure with the original error in `.cause` (`Error` `cause` is ignored below Node 16.9).
 - `destroy(opts?)` → `boolean` or `Promise<boolean>` when `{ drain: true }`. Graceful shutdown waits for JoSk's scan and the SMTP pool; sends not yet started are dropped and stay queued; `schedulerTimeout` defaults to 10000 ms; a timed-out scan or failed JoSk shutdown resolves `false` (never rejects). Plain `destroy()` aborts completion writes.
-- `drain()` → `Promise<void>`. Resolves once every in-flight SMTP attempt finishes. Useful in tests and graceful-shutdown paths.
+- `drain()` → `Promise<{ failedWrites }>`. Resolves once every in-flight SMTP attempt finishes. `failedWrites` counts outcome writes that failed since instance creation; each is also reported through `onError` with `details.phase` `'complete'` or `'checkpoint'`. A non-zero value after `destroy({ drain: true })` means a row may stay `sending` and be re-sent after `sendingTimeout`. Details: [completion writes and drain](https://github.com/veliovgroup/mail-time/blob/master/docs/tuning.md#completion-writes-and-drain).
 - `pause()` / `resume()` → `boolean`. Server-only reversible backpressure; no-ops on `client` or after `destroy()`. See [Shutdown](#6-shutdown).
 - `isPaused` → `boolean`. Read-only; always `false` on `client`.
 
@@ -598,6 +599,8 @@ Upgrade checklists, adapter contract changes, and rollout notes live in the docs
 | 4.0  | 4.1 | [v4.0 → v4.1](https://github.com/veliovgroup/mail-time/blob/master/docs/migration-v4-v4.1.md) |
 | 4.1  | 5.0 | [v4.1 → v5](https://github.com/veliovgroup/mail-time/blob/master/docs/migration-v4.1-v5.md) |
 | 5.0  | 5.1 | [v5 → v5.1 Redis Cluster](https://github.com/veliovgroup/mail-time/blob/master/docs/migration-v5-v5.1.md) |
+| 5.1  | 5.2 | [v5.1 → v5.2 recipient policies rollout](https://github.com/veliovgroup/mail-time/blob/master/docs/recipient-policies.md#recovery-and-rollout) |
+| 5.2  | 5.3 | [v5.2 → v5.3](https://github.com/veliovgroup/mail-time/blob/master/docs/migration-v5.2-v5.3.md) |
 
 New in v4 (opt-in): `mailTimePreset`, `concurrency`/`mode`, `sendingTimeout`, `drain()`/`pause()`/`resume()`, per-recipient handling, AI skills bundle.
 
@@ -622,9 +625,18 @@ bun test ./test/jest
 
 `npm test` runs Jest unit tests, then Mocha integration tests, then TypeScript declaration tests. Jest coverage threshold is **85%** across statements, branches, functions, and lines. GitHub Actions runs the matrix against `redis@^4` and `redis@^5`.
 
+## Supported runtimes
+
+`engines.node` is `>=14.19.3`. The published package (ESM `index.js` and CJS `index.cjs`) is tested from a packed tarball with `test/runtime-matrix/run.sh` on Node 14.19.3, 14.21.3, 16.20.2, 18.19.1, 20.11.1, 22.21.1, 24.16.0 and Bun. Each run sends through a stub transport with `MongoQueue`, and checks load, shutdown, `pause()`/`resume()` and drain behavior (12 checks, all passing).
+
+- Node 12 fails to parse the package (optional chaining). Node 14.0 to 14.16 lack `crypto.randomUUID`; 14.17 to 14.18 are untested.
+- The dependency `josk@6.5.0` declares `engines.node >=14.21.3`. Package managers that enforce `engines` (`npm --engine-strict`, Yarn 1) reject the install on Node 14.19.3 to 14.21.2.
+- Store drivers set their own floor. `mongodb` 7 needs Node 20.19+, `mongodb` 6 needs 16.20.1+, `mongodb` 5 needs 14.20.1+; `redis` 5 needs 18.19+; `pg` 8 needs 16+. The Node 14 and 16 runs used `mongodb@3.7.4`. Only `MongoQueue` is tested below Node 18. `RedisQueue` and `PostgresQueue` load on those versions but are untested there.
+- The repository's own test suite (Jest 30, Mocha 11, TypeScript 6) needs Node 20 or later (dev toolchain). CI runs it on Node 20.9, 22 and LTS, and runs the packed-artifact matrix on Node 14.19.3, 16.20.2 and 18.19.1.
+
 ## Bun
 
-MailTime ships pure ESM with a generated CJS bundle. Both runtimes (Bun ≥ 1.1.0, Node ≥ 20.9.0) load it directly:
+MailTime ships pure ESM with a generated CJS bundle. Both runtimes (Bun ≥ 1.1.0, Node ≥ 14.19.3) load it directly:
 
 ```js
 import { MailTime } from 'mail-time'; // works in both

package/adapters/mongo.d.ts

@@ -1,24 +1,25 @@
 export type MongoCollection = {
     collectionName?: string | undefined;
-    createIndex: (keys: object, opts?: object) => Promise<unknown>;
+    createIndex: (keys: any, opts?: any) => Promise<unknown>;
     indexes: () => Promise<{
-        name: string;
+        name?: string;
         key: Record<string, unknown>;
     }[]>;
     dropIndex: (name: string) => Promise<unknown>;
-    find: (query: object, opts?: object) => unknown;
-    findOne: (query: object, opts?: object) => Promise<object | null>;
-    insertOne: (doc: object) => Promise<unknown>;
-    deleteOne: (query: object) => Promise<{
+    find: (query: any, opts?: any) => unknown;
+    findOne: (query: any, opts?: any) => Promise<object | null>;
+    insertOne: (doc: any) => Promise<unknown>;
+    deleteOne: (query: any) => Promise<{
         deletedCount?: number;
     }>;
-    updateOne: (query: object, update: object) => Promise<{
+    updateOne: (query: any, update: any) => Promise<{
         modifiedCount?: number;
+        matchedCount?: number;
     }>;
 };
 export type Db = {
     collection: (name: string) => MongoCollection;
-    command: (cmd: object) => Promise<{
+    command: (cmd: any) => Promise<{
         ok?: number;
     }>;
 };

package/adapters/mongo.js

@@ -14,20 +14,20 @@ const DEFAULT_PREFIX = '';
 /**
  * @typedef {object} MongoCollection
  * @property {string} [collectionName]
- * @property {(keys: object, opts?: object) => Promise<unknown>} createIndex
- * @property {() => Promise<{ name: string, key: Record<string, unknown> }[]>} indexes
+ * @property {(keys: any, opts?: any) => Promise<unknown>} createIndex
+ * @property {() => Promise<{ name?: string, key: Record<string, unknown> }[]>} indexes
  * @property {(name: string) => Promise<unknown>} dropIndex
- * @property {(query: object, opts?: object) => unknown} find
- * @property {(query: object, opts?: object) => Promise<object|null>} findOne
- * @property {(doc: object) => Promise<unknown>} insertOne
- * @property {(query: object) => Promise<{ deletedCount?: number }>} deleteOne
- * @property {(query: object, update: object) => Promise<{ modifiedCount?: number }>} updateOne
+ * @property {(query: any, opts?: any) => unknown} find
+ * @property {(query: any, opts?: any) => Promise<object|null>} findOne
+ * @property {(doc: any) => Promise<unknown>} insertOne
+ * @property {(query: any) => Promise<{ deletedCount?: number }>} deleteOne
+ * @property {(query: any, update: any) => Promise<{ modifiedCount?: number, matchedCount?: number }>} updateOne
  */
 
 /**
  * @typedef {object} Db
  * @property {(name: string) => MongoCollection} collection
- * @property {(cmd: object) => Promise<{ ok?: number }>} command
+ * @property {(cmd: any) => Promise<{ ok?: number }>} command
  */
 
 /**

package/adapters/postgres.d.ts

@@ -4,6 +4,11 @@ export type PostgresQueryResult = {
 };
 export type PostgresClient = {
     query: (queryText: string, values?: unknown[]) => Promise<PostgresQueryResult>;
+    /**
+     * - a client whose constructor name ends in `Pool` or that has a numeric `totalCount` (`pg.Pool`) is treated as a pool; setup checks out one connection
+     */
+    connect?: ((...args: any[]) => any) | undefined;
+    totalCount?: number | undefined;
 };
 export type PostgresQueueOption = {
     client: PostgresClient;

package/adapters/postgres.js

@@ -19,6 +19,8 @@ import {
 /**
  * @typedef {object} PostgresClient
  * @property {(queryText: string, values?: unknown[]) => Promise<PostgresQueryResult>} query
+ * @property {(...args: any[]) => any} [connect] - a client whose constructor name ends in `Pool` or that has a numeric `totalCount` (`pg.Pool`) is treated as a pool; setup checks out one connection
+ * @property {number} [totalCount]
  */
 
 /**
@@ -119,8 +121,18 @@ class PostgresQueue {
   /** @internal */
   __applyPrefix(prefix) {
     this.prefix = prefix;
-    this.__readyPromise = this.__setup();
-    this.__readyPromise.catch(() => void 0);
+    this.__startSetup();
+  }
+
+  /** @internal */
+  __startSetup() {
+    const setup = this.__setup();
+    this.__readyPromise = setup;
+    // A failed setup (database still booting) must not poison every later call; the next
+    // ready() retries it. The awaiting caller still sees this attempt's rejection.
+    setup.catch(() => {
+      if (this.__readyPromise === setup) this.__readyPromise = null;
+    });
   }
 
   /** @internal */
@@ -145,16 +157,25 @@ class PostgresQueue {
   async ready() {
     this.__ensurePrefix();
     this.__debug('[ready]');
+    if (!this.__readyPromise) this.__startSetup();
     await this.__readyPromise;
   }
 
   /** @internal */
   async __setup() {
     const advisoryLockKey = advisoryLockKeyFor(this.prefix);
-    await this.client.query('SELECT pg_advisory_lock($1, $2)', [ADVISORY_LOCK_NAMESPACE, advisoryLockKey]);
+    // `pg_advisory_lock` is session-scoped. Through a `pg.Pool` each `query()` may use a
+    // different connection, so lock, DDL and unlock must share one checked-out client;
+    // otherwise the lock stays on an idle pooled connection and blocks peer startups.
+    const pooled = typeof this.client.connect === 'function'
+      && (typeof this.client.totalCount === 'number' || /Pool$/.test(this.client.constructor?.name || ''));
+    const conn = pooled ? await this.client.connect() : this.client;
+    let locked = false;
 
     try {
-      await this.client.query(`CREATE TABLE IF NOT EXISTS mail_time_queue (
+      await conn.query('SELECT pg_advisory_lock($1, $2)', [ADVISORY_LOCK_NAMESPACE, advisoryLockKey]);
+      locked = true;
+      await conn.query(`CREATE TABLE IF NOT EXISTS mail_time_queue (
           id BIGSERIAL PRIMARY KEY,
           prefix TEXT NOT NULL DEFAULT 'default',
           uuid TEXT NOT NULL,
@@ -175,18 +196,22 @@ class PostgresQueue {
           created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
           updated_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP
         )`);
-      await this.client.query('ALTER TABLE mail_time_queue ADD COLUMN IF NOT EXISTS is_settled BOOLEAN NOT NULL DEFAULT false');
-      await this.client.query('ALTER TABLE mail_time_queue ADD COLUMN IF NOT EXISTS recipient_results JSONB');
-      await this.client.query(`CREATE UNIQUE INDEX IF NOT EXISTS idx_mail_time_queue_prefix_uuid
+      await conn.query('ALTER TABLE mail_time_queue ADD COLUMN IF NOT EXISTS is_settled BOOLEAN NOT NULL DEFAULT false');
+      await conn.query('ALTER TABLE mail_time_queue ADD COLUMN IF NOT EXISTS recipient_results JSONB');
+      await conn.query(`CREATE UNIQUE INDEX IF NOT EXISTS idx_mail_time_queue_prefix_uuid
         ON mail_time_queue (prefix, uuid)`);
 
-      await this.client.query(`CREATE INDEX IF NOT EXISTS idx_mail_time_queue_policy_due_v1
+      await conn.query(`CREATE INDEX IF NOT EXISTS idx_mail_time_queue_policy_due_v1
         ON mail_time_queue (prefix, is_settled, is_sent, is_failed, is_cancelled, is_sending, sending_at, send_at, tries)`);
 
-      await this.client.query(`CREATE INDEX IF NOT EXISTS idx_mail_time_queue_policy_pending_to_v1
+      await conn.query(`CREATE INDEX IF NOT EXISTS idx_mail_time_queue_policy_pending_to_v1
         ON mail_time_queue (prefix, to_address, is_settled, is_sent, is_failed, is_cancelled, send_at)`);
     } finally {
-      await this.client.query('SELECT pg_advisory_unlock($1, $2)', [ADVISORY_LOCK_NAMESPACE, advisoryLockKey]);
+      try {
+        if (locked) await conn.query('SELECT pg_advisory_unlock($1, $2)', [ADVISORY_LOCK_NAMESPACE, advisoryLockKey]);
+      } finally {
+        if (pooled) conn.release();
+      }
     }
   }
 

package/adapters/redis.d.ts

@@ -6,7 +6,7 @@ export type RedisClient = {
     ping?: (() => Promise<string>) | undefined;
     getRandomNode?: (() => unknown) | undefined;
     nodeClient?: ((...args: any[]) => any) | undefined;
-    sendCommand?: ((firstKey: string, isReadonly: boolean, args: string[]) => Promise<unknown>) | undefined;
+    sendCommand?: ((...args: any[]) => Promise<unknown>) | undefined;
     scanIterator?: ((options: object) => AsyncIterable<string | string[]>) | undefined;
     hGet?: ((key: string, field: string) => Promise<string | null | undefined>) | undefined;
     eval?: ((script: string, options: {

package/adapters/redis.js

@@ -19,7 +19,7 @@ import { createHash } from 'crypto';
  * @property {() => Promise<string>} [ping]
  * @property {() => unknown} [getRandomNode]
  * @property {(...args: any[]) => any} [nodeClient]
- * @property {(firstKey: string, isReadonly: boolean, args: string[]) => Promise<unknown>} [sendCommand]
+ * @property {(...args: any[]) => Promise<unknown>} [sendCommand]
  * @property {(options: object) => AsyncIterable<string|string[]>} [scanIterator]
  * @property {(key: string, field: string) => Promise<string|null|undefined>} [hGet]
  * @property {(script: string, options: { keys: string[], arguments: string[] }) => Promise<unknown>} [eval]
@@ -218,6 +218,12 @@ const isNoScriptError = (error) => {
   return !!error && (error.code === 'NOSCRIPT' || (typeof error.message === 'string' && error.message.includes('NOSCRIPT')));
 };
 
+// node-redis 4/5 throw `WatchError` from `exec()` when a watched key changed; that is the
+// expected outcome of a lost CAS race, not a storage failure.
+const isWatchError = (error) => {
+  return !!error && (error.name === 'WatchError' || error.constructor?.name === 'WatchError');
+};
+
 const canReleaseLease = (currentTask, updateObj) => {
   return currentTask
     && currentTask.tries === updateObj.leaseTries
@@ -611,15 +617,19 @@ class RedisQueue {
     const taskJSON = JSON.stringify(task);
 
     if (typeof this.client.multi === 'function') {
-      const multi = this.client.multi();
-      multi.set(letterKey, taskJSON);
-      multi.set(sendatKey, `${task.sendAt}`);
-      if (task.to) {
-        multi.set(this.__getKey(task.to, 'concatletter'), task.uuid, {
-          PXAT: task.sendAt - 128,
-        });
-      }
-      await multi.exec();
+      // EXEC discards every WATCH on the connection, so an unserialized push would turn a
+      // concurrent claim's guarded MULTI into an unconditional write (duplicate send).
+      await this.__serialize(async () => {
+        const multi = this.client.multi();
+        multi.set(letterKey, taskJSON);
+        multi.set(sendatKey, `${task.sendAt}`);
+        if (task.to) {
+          multi.set(this.__getKey(task.to, 'concatletter'), task.uuid, {
+            PXAT: task.sendAt - 128,
+          });
+        }
+        await multi.exec();
+      });
       return;
     }
 
@@ -656,7 +666,7 @@ class RedisQueue {
   }
 
   /** @internal */
-  async __cancel(uuid) {
+  async __cancel(uuid, attempt = 0) {
     this.__debug('[cancel]', uuid);
     if (typeof uuid !== 'string') {
       return false;
@@ -677,7 +687,10 @@ class RedisQueue {
         const args = keep
           ? [uuid, JSON.stringify({ isCancelled: true }), 'cancel', `${Date.now()}`, `${this.mailTimeInstance.sendingTimeout || 300000}`, '0', '0', payload, JSON.stringify({ ...task, isCancelled: true })]
           : [uuid, 'cancel', '0', '0'];
-        return Number(await this.__runScript(keep ? 'update' : 'remove', { keys, arguments: args })) >= 1;
+        const result = Number(await this.__runScript(keep ? 'update' : 'remove', { keys, arguments: args }));
+        // -1: the payload changed between hGet and the script (a claim renewal, for example); retry on a fresh snapshot
+        if (result === -1 && attempt < 2) return await this.__cancel(uuid, attempt + 1);
+        return result >= 1;
       }
       if (!atomic) {
         if (task.recipientResults != null) return false;
@@ -689,7 +702,7 @@ class RedisQueue {
       multi.del(this.__getKey(uuid, 'sendat'));
       return (await multi.exec()) !== null;
     } catch (error) {
-      logError('[cancel] storage error', error);
+      if (!isWatchError(error)) logError('[cancel] storage error', error);
       return false;
     } finally {
       if (!this.useHashTags && atomic) await this.client.unwatch?.();
@@ -746,7 +759,9 @@ class RedisQueue {
         return false;
       }
       try {
+        const concatKey = task.to ? this.__getKey(task.to, 'concatletter') : null;
         await this.client.watch(letterKey);
+        if (concatKey) await this.client.watch(concatKey);
         const taskJSON = await this.client.get(letterKey);
         if (!taskJSON) {
           await this.client.unwatch?.();
@@ -764,8 +779,9 @@ class RedisQueue {
           return false;
         }
         const keysToDelete = [letterKey, this.__getKey(task.uuid, 'sendat')];
-        if (task.to) {
-          keysToDelete.push(this.__getKey(task.to, 'concatletter'));
+        // The pointer may already name a newer letter folded for the same recipient.
+        if (concatKey && (await this.client.get(concatKey)) === task.uuid) {
+          keysToDelete.push(concatKey);
         }
         const multi = this.client.multi();
         for (const key of keysToDelete) {
@@ -774,7 +790,7 @@ class RedisQueue {
         const result = await multi.exec();
         return result !== null;
       } catch (opError) {
-        logError('[remove] [lease] [opError]', opError);
+        if (!isWatchError(opError)) logError('[remove] [lease] [opError]', opError);
         return false;
       }
     }
@@ -786,7 +802,10 @@ class RedisQueue {
 
     const keysToDelete = [letterKey, this.__getKey(task.uuid, 'sendat')];
     if (task.to) {
-      keysToDelete.push(this.__getKey(task.to, 'concatletter'));
+      const concatKey = this.__getKey(task.to, 'concatletter');
+      if ((await this.client.get(concatKey)) === task.uuid) {
+        keysToDelete.push(concatKey);
+      }
     }
     await this.client.del(keysToDelete);
     return true;
@@ -946,7 +965,7 @@ class RedisQueue {
       }
       return true;
     } catch (opError) {
-      logError('[update] [try/catch] [opError]', opError);
+      if (!isWatchError(opError)) logError('[update] [try/catch] [opError]', opError);
       return false;
     }
   }