mail-time 5.2.0 → 5.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mail-time",
-  "version": "5.2.0",
+  "version": "5.3.0",
   "description": "📮 Email queue extending nodemailer with multi-SMTP transports and horizontally scaled apps support",
   "main": "index.js",
   "types": "./index.d.ts",
@@ -134,7 +134,7 @@
   "author": "dr.dimitru (https://veliovgroup.com)",
   "license": "BSD-3-Clause",
   "engines": {
-    "node": ">=20.9.0",
+    "node": ">=14.19.3",
     "bun": ">=1.1.0"
   },
   "meteor": {
@@ -149,16 +149,17 @@
     }
   },
   "dependencies": {
-    "josk": "^6.4.0"
+    "josk": "^6.5.0"
   },
   "devDependencies": {
     "@jest/globals": "^30.4.1",
     "@types/node": "^25.9.0",
+    "acorn": "^8.18.0",
     "chai": "^6.2.2",
     "jest": "^30.4.2",
     "mocha": "^11.8.0",
     "mongodb": "^7.2.0",
-    "nodemailer": "^9.0.5",
+    "nodemailer": "^10.0.9",
     "pg": "^8.21.0",
     "redis": "^5.12.1",
     "rollup": "^4.60.4",

package/presets.js

@@ -60,12 +60,12 @@ const PRESETS = Object.freeze({
   transactional: Object.freeze({
     concatEmails: false,
     retries: 30,
-    retryDelay: 10_000,
+    retryDelay: 10000,
     mode: 'batch',
     concurrency: 1,
     onError: defaultPresetOnError,
     josk: Object.freeze({
-      zombieTime: 120_000,
+      zombieTime: 120000,
     }),
   }),
   otp: Object.freeze({
@@ -73,52 +73,52 @@ const PRESETS = Object.freeze({
     retries: 5,
     retryDelay: 2000,
     revolvingInterval: 1024,
-    sendingTimeout: 120_000,
+    sendingTimeout: 120000,
     mode: 'batch',
     concurrency: 4,
     onError: defaultPresetOnError,
     josk: Object.freeze({
       minRevolvingDelay: 256,
       maxRevolvingDelay: 1024,
-      zombieTime: 60_000,
+      zombieTime: 60000,
     }),
   }),
   newsletter: Object.freeze({
     concatEmails: true,
-    concatDelay: 5 * 60_000,
+    concatDelay: 5 * 60000,
     concatSubject: 'Your updates',
     retries: 5,
-    retryDelay: 60_000,
-    sendingTimeout: 600_000,
+    retryDelay: 60000,
+    sendingTimeout: 600000,
     mode: 'batch',
     concurrency: 2,
     onError: defaultPresetOnError,
     josk: Object.freeze({
-      zombieTime: 300_000,
+      zombieTime: 300000,
     }),
   }),
   marketing: Object.freeze({
     concatEmails: false,
     retries: 10,
-    retryDelay: 30_000,
+    retryDelay: 30000,
     mode: 'batch',
     concurrency: 5,
     onError: defaultPresetOnError,
     josk: Object.freeze({
-      zombieTime: 180_000,
+      zombieTime: 180000,
     }),
   }),
   notifications: Object.freeze({
     concatEmails: true,
-    concatDelay: 60_000,
+    concatDelay: 60000,
     concatSubject: 'New activity',
     retries: 8,
-    retryDelay: 30_000,
+    retryDelay: 30000,
     mode: 'batch',
     concurrency: 3,
     onError: defaultPresetOnError,
     josk: Object.freeze({
-      zombieTime: 180_000,
+      zombieTime: 180000,
     }),
   }),
   alerts: Object.freeze({
@@ -126,14 +126,14 @@ const PRESETS = Object.freeze({
     retries: 20,
     retryDelay: 5000,
     revolvingInterval: 1024,
-    sendingTimeout: 120_000,
+    sendingTimeout: 120000,
     mode: 'batch',
     concurrency: 2,
     onError: defaultPresetOnError,
     josk: Object.freeze({
       minRevolvingDelay: 256,
       maxRevolvingDelay: 1024,
-      zombieTime: 60_000,
+      zombieTime: 60000,
     }),
   }),
 });

package/recipient-policy-lease.js

@@ -1,5 +1,9 @@
 class RecipientPolicyLease {
-  constructor({ task, queue, interval, maxRenewals, shouldAbort, report }) {
+  constructor({ task, queue, interval, maxRenewals, sendingTimeout, shouldAbort, report }) {
+    if (typeof sendingTimeout !== 'number' || !(sendingTimeout > 0)) throw new TypeError('[mail-time] [recipientPolicies] RecipientPolicyLease requires a positive sendingTimeout');
+    this.__sendingTimeout = sendingTimeout;
+    this.__renewStale = false;
+    this.__liveAtAttempt = false;
     this.__task = task;
     this.__queue = queue;
     this.__shouldAbort = shouldAbort;
@@ -7,6 +11,8 @@ class RecipientPolicyLease {
     this.__closed = false;
     this.__finishing = false;
     this.__tail = Promise.resolve();
+    this.__renewUncertain = false;
+    this.__attemptedAt = 0;
     this.__timer = null;
     let pending = false;
     let renewals = 0;
@@ -21,6 +27,8 @@ class RecipientPolicyLease {
         renewals++;
         this.__enqueue(async (guard) => {
           const fields = { isSending: true, sendingAt: Math.max(Date.now(), this.__task.sendingAt + 1) };
+          this.__attemptedAt = fields.sendingAt;
+          this.__liveAtAttempt = this.__task.sendingAt > fields.sendingAt - this.__sendingTimeout;
           return await this.__write(fields, guard);
         }).finally(() => { pending = false; });
       }, interval);
@@ -40,17 +48,41 @@ class RecipientPolicyLease {
     this.__closed = true;
   }
 
-  __enqueue(operation) {
+  __enqueue(operation, phase = 'renew') {
     const pending = this.__tail.then(async () => {
       if (!this.active) return false;
       const guard = { leaseTries: this.__task.tries, leaseSendingAt: this.__task.sendingAt };
       try {
-        const ok = await operation(guard);
-        if (!ok) this.__halt();
+        let ok = await operation(guard);
+        if (!ok) {
+          // A renewal write that threw may have been applied by storage, which leaves the
+          // guard stale. Retry once with the attempted stamp: a peer takeover bumps tries or
+          // stamps a later sendingAt while the lease is live, so the retry cannot match a
+          // taken-over row. Report if it still fails.
+          if (this.__renewStale && phase !== 'renew') {
+            // The claim was already stale when the renewal threw: no retry, report the loss.
+            this.__renewStale = false;
+            this.__report(new Error('outcome write lost (renewal outcome uncertain or lease taken over)'), phase);
+          } else if (this.__renewUncertain && phase !== 'renew') {
+            this.__renewUncertain = false;
+            if (this.__shouldAbort()) {
+              this.__report(new Error('outcome write lost (renewal outcome uncertain or lease taken over)'), phase);
+              this.__halt();
+              return false;
+            }
+            ok = await operation({ ...guard, leaseSendingAt: this.__attemptedAt });
+            if (ok && phase === 'checkpoint') this.__task.sendingAt = this.__attemptedAt;
+            if (!ok) this.__report(new Error('outcome write lost (renewal outcome uncertain or lease taken over)'), phase);
+          }
+          if (!ok) this.__halt();
+        }
         return ok;
       } catch (error) {
-        this.__halt();
-        if (!this.__shouldAbort()) this.__report(error);
+        // A thrown renewal write only stops further renewals. The lease stays open so
+        // finish() still records the outcome; storage-side CAS protects row ownership.
+        if (phase === 'renew') { this.__clearTimer(); this.__renewUncertain = this.__liveAtAttempt; this.__renewStale = !this.__liveAtAttempt; }
+        else this.__halt();
+        this.__report(error, phase);
         return false;
       }
     });
@@ -66,7 +98,7 @@ class RecipientPolicyLease {
 
   update(fields) {
     if (this.__finishing) return Promise.resolve(false);
-    return this.__enqueue((guard) => this.__write(fields, guard));
+    return this.__enqueue((guard) => this.__write(fields, guard), 'checkpoint');
   }
 
   finish(fields, remove) {
@@ -78,7 +110,7 @@ class RecipientPolicyLease {
       if (ok) Object.assign(this.__task, fields);
       this.__halt();
       return ok;
-    });
+    }, 'complete');
   }
 
   async stop() {

package/recipient-policy.js

@@ -2,29 +2,113 @@ import { hasOwnProp, isPlainObject } from './helpers.js';
 
 const policyError = (message) => new Error(`[mail-time] [recipientPolicies] ${message}`);
 const SIMPLE_MAILBOX = /^[^\s<>,;:"()\\\[\]@]+@[^\s<>,;:"()\\\[\]@]+$/u;
+// Unquoted display-name characters that are auto-quoted in the sent header; `,` `;` `:` `<` `>` stay rejected.
+const QUOTABLE_SPECIALS = /[()[\]@\\]/u;
+const UNSAFE_CHARS = /[\r\n\u0000]/u;
 
-const normalizePolicyAddress = (value) => {
-  const input = typeof value === 'string' ? value : (!Array.isArray(value) && value?.address);
-  if (typeof input !== 'string' || /[\r\n]/u.test(input)) {
-    throw policyError('recipient requires a simple address without line breaks');
+/**
+ * Error for an address that cannot be parsed into exactly one mailbox. The message names
+ * the field and the rule that failed, never the address or display name itself.
+ */
+const addressError = (field, reason) => {
+  const error = policyError(`\`${field}\` ${reason}`);
+  error.code = 'MAIL_TIME_INVALID_ADDRESS';
+  error.field = field;
+  return error;
+};
+
+const isAddressError = (error) => error?.code === 'MAIL_TIME_INVALID_ADDRESS';
+
+const toMailbox = (address, field) => {
+  const trimmed = address.trim();
+  if (!SIMPLE_MAILBOX.test(trimmed)) throw addressError(field, 'must contain one address such as user@example.com; quoted local parts are not supported');
+  return trimmed.toLowerCase();
+};
+
+/**
+ * Parse one Nodemailer mailbox string: `addr`, `<addr>`, or `display name <addr>`, where the
+ * display name is any mix of atoms and quoted strings with backslash escapes. Unquoted
+ * `( ) [ ] @ \\` in a display name set `quote`, so the sent header carries the name quoted.
+ * Groups, comma-separated lists, and text after `>` are rejected rather than guessed at.
+ * @returns {{ name: string, address: string, quote: boolean }} `address` keeps its case.
+ */
+const parseMailboxString = (input, field) => {
+  let display = '';
+  let name = '';
+  let angle = null;
+  let quoted = false;
+  for (let i = 0; i < input.length; i++) {
+    const char = input[i];
+    if (quoted) {
+      if (char === '\\') {
+        if (++i >= input.length) break;
+        name += input[i];
+      } else if (char === '"') {
+        quoted = false;
+      } else {
+        name += char;
+      }
+      continue;
+    }
+    if (char === '"') {
+      quoted = true;
+    } else if (char === '<') {
+      const close = input.indexOf('>', i + 1);
+      if (close === -1) throw addressError(field, 'has an unclosed angle bracket');
+      angle = input.slice(i + 1, close);
+      if (input.slice(close + 1).trim()) throw addressError(field, 'must end after the angle-bracket address; use an array for multiple recipients');
+      break;
+    } else if (char === ',') {
+      throw addressError(field, 'must contain one mailbox; use an array for multiple recipients or quote a display name that contains a comma');
+    } else if (char === ';' || char === ':') {
+      throw addressError(field, 'must not use group syntax');
+    } else if (char === '>') {
+      throw addressError(field, 'has an unquoted `>` in its display name; wrap the name in double quotes');
+    } else {
+      display += char;
+      name += char;
+    }
+  }
+  if (quoted) throw addressError(field, 'has an unterminated quoted display name');
+  if (angle === null) {
+    if (display !== input) throw addressError(field, 'must contain one address such as user@example.com; quoted local parts are not supported');
+    toMailbox(input, field);
+    return { name: '', address: input, quote: false };
+  }
+  toMailbox(angle, field);
+  return { name: name.replace(/\s+/gu, ' ').trim(), address: angle.trim(), quote: QUOTABLE_SPECIALS.test(display) };
+};
+
+/**
+ * Normalize exactly one mailbox (string or `{ name?, address }`) to its lowercase address.
+ * @param {unknown} value
+ * @param {string} [field] - Field label used in errors, e.g. `to[1]` or `envelope.from`.
+ * @returns {string}
+ */
+const normalizePolicyAddress = (value, field = 'address') => {
+  if (typeof value === 'string') {
+    if (UNSAFE_CHARS.test(value)) throw addressError(field, 'must not contain line breaks or NUL characters');
+    if (!value.trim()) throw addressError(field, 'must not be empty');
+    return parseMailboxString(value.trim(), field).address.toLowerCase();
   }
-  let address = input.trim();
-  if (address.includes('<') || address.includes('>')) {
-    const match = address.match(/^[^<>,;:"\r\n]*<([^<>]+)>$/u);
-    if (!match) throw policyError('use a simple explicit envelope.to');
-    address = match[1].trim();
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw addressError(field, 'must be an address string or a { name, address } object');
+  if (typeof value.address !== 'string') throw addressError(field, 'object requires a string `address`');
+  if (value.name !== void 0 && typeof value.name !== 'string') throw addressError(field, 'object `name` must be a string');
+  if (UNSAFE_CHARS.test(value.address) || (value.name && UNSAFE_CHARS.test(value.name))) {
+    throw addressError(field, 'must not contain line breaks or NUL characters');
   }
-  if (!SIMPLE_MAILBOX.test(address)) throw policyError('use a simple explicit envelope.to');
-  return address.toLowerCase();
+  return toMailbox(value.address, field);
 };
 
 const preparePolicyEnvelope = (compiled, previousResults = []) => {
   const recipients = new Map();
   const explicit = compiled.envelope && hasOwnProp(compiled.envelope, 'to');
-  const add = (value, source, authoritative) => {
-    for (const entry of Array.isArray(value) ? value : [value]) {
+  const add = (value, source, authoritative, label = source) => {
+    const list = Array.isArray(value);
+    const entries = list ? value : [value];
+    for (let i = 0; i < entries.length; i++) {
       let address;
-      try { address = normalizePolicyAddress(entry); }
+      try { address = normalizePolicyAddress(entries[i], list ? `${label}[${i}]` : label); }
       catch (error) { if (authoritative) throw error; else continue; }
       if (!recipients.has(address)) {
         if (!authoritative) continue;
@@ -34,7 +118,7 @@ const preparePolicyEnvelope = (compiled, previousResults = []) => {
       if (!sources.includes(source)) sources.push(source);
     }
   };
-  if (explicit) add(compiled.envelope.to, 'envelope', true);
+  if (explicit) add(compiled.envelope.to, 'envelope', true, 'envelope.to');
   for (const source of ['to', 'cc', 'bcc']) {
     if (hasOwnProp(compiled, source) && compiled[source] !== void 0) add(compiled[source], source, !explicit);
   }
@@ -44,14 +128,61 @@ const preparePolicyEnvelope = (compiled, previousResults = []) => {
   }
   const envelope = { to: [...recipients.keys()] };
   if (compiled.envelope && hasOwnProp(compiled.envelope, 'from')) {
-    envelope.from = compiled.envelope.from === '' ? '' : normalizePolicyAddress(compiled.envelope.from);
+    envelope.from = compiled.envelope.from === '' ? '' : normalizePolicyAddress(compiled.envelope.from, 'envelope.from');
   } else {
-    const from = compiled.from || compiled.sender || compiled.replyTo;
-    if (from) envelope.from = normalizePolicyAddress(from);
+    // Same precedence as Nodemailer's getEnvelope(): From, then Sender, then Reply-To.
+    const field = ['from', 'sender', 'replyTo'].find((key) => compiled[key]);
+    if (field) envelope.from = normalizePolicyAddress(compiled[field], field);
   }
   return { envelope, recipients: [...recipients.values()] };
 };
 
+/**
+ * Return `compiled` with every header mailbox string whose display name needs quoting replaced by
+ * `{ name, address }`, so Nodemailer renders the same mailbox the policy checked. Other entries,
+ * including ones that do not parse, are left as they are. The input is never mutated.
+ */
+const rewritePolicyHeaders = (compiled) => {
+  let result = compiled;
+  const rewrite = (value) => {
+    if (typeof value !== 'string' || UNSAFE_CHARS.test(value)) return value;
+    try {
+      const { name, address, quote } = parseMailboxString(value.trim(), 'header');
+      return quote ? { name, address } : value;
+    } catch { return value; }
+  };
+  for (const key of ['from', 'sender', 'replyTo', 'to', 'cc', 'bcc']) {
+    if (!hasOwnProp(compiled, key)) continue;
+    const value = compiled[key];
+    const next = Array.isArray(value) ? value.map(rewrite) : rewrite(value);
+    if (Array.isArray(value) ? next.some((entry, i) => entry !== value[i]) : next !== value) {
+      if (result === compiled) result = { ...compiled };
+      result[key] = next;
+    }
+  }
+  return result;
+};
+
+/**
+ * Validate every address field present in a letter with the policy parser, so an unparseable
+ * address is rejected at `sendMail()` instead of after a queue round trip. Absent fields are
+ * skipped. Throws the same `MAIL_TIME_INVALID_ADDRESS` error the send path would.
+ * @param {object} mailOptions
+ * @returns {void}
+ */
+const validatePolicyMailOptions = (mailOptions) => {
+  const check = (value, label) => {
+    if (value === void 0) return;
+    if (Array.isArray(value)) value.forEach((entry, i) => normalizePolicyAddress(entry, `${label}[${i}]`));
+    else normalizePolicyAddress(value, label);
+  };
+  for (const key of ['from', 'sender', 'replyTo', 'to', 'cc', 'bcc']) check(mailOptions[key], key);
+  if (isPlainObject(mailOptions.envelope)) {
+    check(mailOptions.envelope.to, 'envelope.to');
+    if (mailOptions.envelope.from !== '') check(mailOptions.envelope.from, 'envelope.from');
+  }
+};
+
 const validateRecipientPolicies = (value, queue) => {
   if (value === void 0) return null;
   if (!Array.isArray(value) || !value.length) throw policyError('recipientPolicies must be a nonempty array');
@@ -88,7 +219,7 @@ const validatePolicyResult = (raw, hook, context) => {
   const decisions = new Map();
   for (const item of raw.decisions) {
     if (!isPlainObject(item)) throw policyError('decision must be an object');
-    const address = normalizePolicyAddress(item.address);
+    const address = normalizePolicyAddress(item.address, 'decision.address');
     if (!batch.has(address)) throw policyError('decision address is outside the input batch');
     const allowed = hook === 'beforeSend' ? item.status === 'suppressed' : (item.status === 'retry' || item.status === 'rejected');
     if (!allowed) throw policyError('invalid decision status for this phase');
@@ -163,4 +294,4 @@ const summarizePolicyTask = (task, isSettled) => {
   return { uuid: task.uuid, tries: task.tries, isSettled, recipients };
 };
 
-export { policyError, normalizePolicyAddress, preparePolicyEnvelope, validateRecipientPolicies, evaluatePolicyPhase, mergePolicyResults, summarizePolicyTask };
+export { policyError, isAddressError, normalizePolicyAddress, rewritePolicyHeaders, preparePolicyEnvelope, validatePolicyMailOptions, validateRecipientPolicies, evaluatePolicyPhase, mergePolicyResults, summarizePolicyTask };