mail-time 5.1.0 → 5.2.1

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

@@ -0,0 +1,90 @@
+class RecipientPolicyLease {
+  constructor({ task, queue, interval, maxRenewals, shouldAbort, report }) {
+    this.__task = task;
+    this.__queue = queue;
+    this.__shouldAbort = shouldAbort;
+    this.__report = report;
+    this.__closed = false;
+    this.__finishing = false;
+    this.__tail = Promise.resolve();
+    this.__timer = null;
+    let pending = false;
+    let renewals = 0;
+    if (interval && maxRenewals) {
+      this.__timer = setInterval(() => {
+        if (!this.active || this.__finishing || renewals >= maxRenewals) {
+          this.__clearTimer();
+          return;
+        }
+        if (pending) return;
+        pending = true;
+        renewals++;
+        this.__enqueue(async (guard) => {
+          const fields = { isSending: true, sendingAt: Math.max(Date.now(), this.__task.sendingAt + 1) };
+          return await this.__write(fields, guard);
+        }).finally(() => { pending = false; });
+      }, interval);
+      this.__timer.unref?.();
+    }
+  }
+
+  get active() { return !this.__closed && !this.__shouldAbort(); }
+
+  __clearTimer() {
+    if (this.__timer) clearInterval(this.__timer);
+    this.__timer = null;
+  }
+
+  __halt() {
+    this.__clearTimer();
+    this.__closed = true;
+  }
+
+  __enqueue(operation) {
+    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();
+        return ok;
+      } catch (error) {
+        this.__halt();
+        if (!this.__shouldAbort()) this.__report(error);
+        return false;
+      }
+    });
+    this.__tail = pending.then(() => void 0);
+    return pending;
+  }
+
+  async __write(fields, guard) {
+    const ok = await this.__queue.update(this.__task, { ...fields, ...guard });
+    if (ok) Object.assign(this.__task, fields);
+    return ok;
+  }
+
+  update(fields) {
+    if (this.__finishing) return Promise.resolve(false);
+    return this.__enqueue((guard) => this.__write(fields, guard));
+  }
+
+  finish(fields, remove) {
+    if (this.__finishing) return Promise.resolve(false);
+    this.__finishing = true;
+    this.__clearTimer();
+    return this.__enqueue(async (guard) => {
+      const ok = remove ? await this.__queue.remove(this.__task, guard) : await this.__queue.update(this.__task, { ...fields, ...guard });
+      if (ok) Object.assign(this.__task, fields);
+      this.__halt();
+      return ok;
+    });
+  }
+
+  async stop() {
+    this.__halt();
+    await this.__tail;
+  }
+}
+
+export { RecipientPolicyLease };

package/recipient-policy.js

@@ -0,0 +1,166 @@
+import { hasOwnProp, isPlainObject } from './helpers.js';
+
+const policyError = (message) => new Error(`[mail-time] [recipientPolicies] ${message}`);
+const SIMPLE_MAILBOX = /^[^\s<>,;:"()\\\[\]@]+@[^\s<>,;:"()\\\[\]@]+$/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');
+  }
+  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 (!SIMPLE_MAILBOX.test(address)) throw policyError('use a simple explicit envelope.to');
+  return address.toLowerCase();
+};
+
+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]) {
+      let address;
+      try { address = normalizePolicyAddress(entry); }
+      catch (error) { if (authoritative) throw error; else continue; }
+      if (!recipients.has(address)) {
+        if (!authoritative) continue;
+        recipients.set(address, { address, sources: [] });
+      }
+      const sources = recipients.get(address).sources;
+      if (!sources.includes(source)) sources.push(source);
+    }
+  };
+  if (explicit) add(compiled.envelope.to, 'envelope', true);
+  for (const source of ['to', 'cc', 'bcc']) {
+    if (hasOwnProp(compiled, source) && compiled[source] !== void 0) add(compiled[source], source, !explicit);
+  }
+  if (!recipients.size) throw policyError('envelope must contain at least one recipient');
+  if (previousResults.length && (previousResults.length !== recipients.size || previousResults.some((r) => !recipients.has(r.address)))) {
+    throw policyError('envelope recipient set changed between attempts');
+  }
+  const envelope = { to: [...recipients.keys()] };
+  if (compiled.envelope && hasOwnProp(compiled.envelope, 'from')) {
+    envelope.from = compiled.envelope.from === '' ? '' : normalizePolicyAddress(compiled.envelope.from);
+  } else {
+    const from = compiled.from || compiled.sender || compiled.replyTo;
+    if (from) envelope.from = normalizePolicyAddress(from);
+  }
+  return { envelope, recipients: [...recipients.values()] };
+};
+
+const validateRecipientPolicies = (value, queue) => {
+  if (value === void 0) return null;
+  if (!Array.isArray(value) || !value.length) throw policyError('recipientPolicies must be a nonempty array');
+  if (queue.supportsRecipientPolicies !== true) throw policyError('queue must declare recipient policy support');
+  const names = new Set();
+  return value.map((provider) => {
+    if (!isPlainObject(provider)) throw policyError('each provider must be a plain object');
+    const name = typeof provider.name === 'string' ? provider.name.trim() : '';
+    if (!name || name.length > 128 || names.has(name)) throw policyError('provider names must be unique and contain 1-128 characters');
+    names.add(name);
+    const failureMode = provider.failureMode === void 0 ? 'retry' : provider.failureMode;
+    if (failureMode !== 'retry' && failureMode !== 'continue') throw policyError('failureMode must be retry or continue');
+    const normalized = { name, failureMode };
+    let count = 0;
+    for (const hook of ['beforeSend', 'classifyRejections', 'observeAttempt']) {
+      if (hasOwnProp(provider, hook)) {
+        if (typeof provider[hook] !== 'function') throw policyError(`${hook} must be a function`);
+        normalized[hook] = provider[hook].bind(provider);
+        count++;
+      }
+    }
+    if (!count) throw policyError('provider requires at least one supported hook');
+    return normalized;
+  });
+};
+
+const validatePolicyResult = (raw, hook, context) => {
+  if (raw === void 0) return [];
+  if (!isPlainObject(raw)) throw policyError('hook must return a result object or nothing');
+  if (raw.decisions === void 0) return [];
+  if (!Array.isArray(raw.decisions)) throw policyError('decisions must be an array');
+  const batch = new Set(context.recipients.map((r) => r.address));
+  const attributable = new Set((context.rejections || []).map((r) => r.address).filter(Boolean));
+  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);
+    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');
+    if (item.status === 'rejected' && !attributable.has(address)) throw policyError('permanent rejection requires an attributable record');
+    if (typeof item.reason !== 'string' || !item.reason.trim() || item.reason.length > 512) throw policyError('reason must contain 1-512 characters');
+    const previous = decisions.get(address);
+    if (previous && (previous.status !== item.status || previous.reason !== item.reason)) throw policyError('conflicting duplicate decisions');
+    decisions.set(address, { address, status: item.status, reason: item.reason });
+  }
+  return [...decisions.values()];
+};
+
+const evaluatePolicyPhase = async (providers, hook, context, report) => {
+  const decisions = [];
+  let retryFailure = false;
+  for (const provider of providers) {
+    if (typeof provider[hook] !== 'function') continue;
+    try {
+      const validated = validatePolicyResult(await provider[hook](context), hook, context);
+      for (const decision of validated) decisions.push({ ...decision, provider: provider.name });
+    } catch (error) {
+      report(error, provider.name, hook);
+      if (provider.failureMode !== 'continue') retryFailure = true;
+    }
+  }
+  return { retryFailure, decisions };
+};
+
+const mergePolicyResults = (previous, recipients, evaluated, details) => {
+  const results = new Map(previous.map((r) => [r.address, r]));
+  const accepted = new Set(details.accepted || []);
+  const decisions = new Map();
+  for (const decision of evaluated.decisions) {
+    if (!decisions.has(decision.address)) decisions.set(decision.address, []);
+    decisions.get(decision.address).push(decision);
+  }
+  const diagnostics = new Map();
+  for (const record of details.rejections || []) {
+    if (record.address && !diagnostics.has(record.address)) diagnostics.set(record.address, record);
+  }
+  for (const recipient of recipients) {
+    const prior = results.get(recipient.address);
+    if (prior && prior.status !== 'error') continue;
+    const candidates = decisions.get(recipient.address) || [];
+    const terminal = details.phase === 'beforeSend' ? 'suppressed' : 'rejected';
+    let status = 'error';
+    if (accepted.has(recipient.address)) status = 'sent';
+    else if (!evaluated.retryFailure && candidates.some((d) => d.status === terminal)) status = terminal;
+    const reasons = [];
+    if (!evaluated.retryFailure && status !== 'sent') {
+      for (const candidate of candidates) {
+        if (candidate.status === (status === 'error' ? 'retry' : status)) reasons.push({ provider: candidate.provider, reason: candidate.reason });
+      }
+    }
+    const result = { address: recipient.address, status, sources: [...recipient.sources], reasons, attempt: details.attempt, transportIndex: details.transportIndex };
+    if (typeof details.transportName === 'string') result.transportName = details.transportName.slice(0, 128);
+    const record = diagnostics.get(recipient.address);
+    if (record) {
+      for (const key of ['command', 'response', 'message']) {
+        if (typeof record[key] === 'string') result[key] = record[key].slice(0, 2048);
+      }
+      if (Number.isFinite(record.responseCode)) result.responseCode = record.responseCode;
+    }
+    results.set(recipient.address, result);
+  }
+  return [...results.values()];
+};
+
+const summarizePolicyTask = (task, isSettled) => {
+  const recipients = { sent: [], error: [], suppressed: [], rejected: [] };
+  for (const result of task.recipientResults || []) recipients[result.status].push(result);
+  return { uuid: task.uuid, tries: task.tries, isSettled, recipients };
+};
+
+export { policyError, normalizePolicyAddress, preparePolicyEnvelope, validateRecipientPolicies, evaluatePolicyPhase, mergePolicyResults, summarizePolicyTask };

package/recipient-rejections.js

@@ -0,0 +1,62 @@
+import { hasOwnProp } from './helpers.js';
+import { normalizePolicyAddress } from './recipient-policy.js';
+
+const diagnosticFields = (record) => {
+  const result = {};
+  for (const key of ['command', 'response', 'message']) {
+    if (typeof record?.[key] === 'string') result[key] = record[key].slice(0, 2048);
+  }
+  if (Number.isFinite(record?.responseCode)) result.responseCode = record.responseCode;
+  return result;
+};
+
+const normalizeRejections = (error, info, transport) => {
+  const records = [];
+  const ancestors = new WeakSet();
+  const addressOf = (value) => {
+    try { return normalizePolicyAddress(value); }
+    catch { return null; }
+  };
+  const append = (node, address) => {
+    const record = { address, ...diagnosticFields(node), transportIndex: transport.index };
+    if (typeof transport.name === 'string') record.transportName = transport.name.slice(0, 128);
+    if (typeof node === 'string') record.message = node.slice(0, 2048);
+    records.push(record);
+  };
+  const visit = (node, positional = null, root = false, errorRoot = false) => {
+    if (node === null || node === void 0) {
+      if (!root) append(node, positional);
+      return;
+    }
+    if (typeof node !== 'object') {
+      append(node, positional);
+      return;
+    }
+    if (ancestors.has(node)) return;
+    ancestors.add(node);
+    const start = records.length;
+    const rejected = Array.isArray(node.rejected) ? node.rejected.map(addressOf) : [];
+    for (const key of ['errors', 'rejectedErrors']) {
+      if (Array.isArray(node[key])) {
+        for (let i = 0; i < node[key].length; i++) visit(node[key][i], rejected[i] || null);
+      }
+    }
+    if (records.length === start) {
+      let address = positional;
+      for (const key of ['recipient', 'address', 'to']) {
+        if (hasOwnProp(node, key)) { address = addressOf(node[key]); break; }
+      }
+      if (!root || errorRoot || address || Object.keys(diagnosticFields(node)).length) append(node, address);
+    }
+    const attributed = new Set(records.slice(start).map((r) => r.address));
+    for (const address of rejected) {
+      if (address && !attributed.has(address)) append({ message: 'Recipient rejected by transport' }, address);
+    }
+    ancestors.delete(node);
+  };
+  visit(error, null, true, true);
+  visit(info, null, true);
+  return records;
+};
+
+export { normalizeRejections, diagnosticFields };

package/scripts/migrate-redis-queue-to-cluster.mjs

@@ -26,6 +26,10 @@ const scheduleKey = `${taggedName}:schedule`;
 const concatKeysKey = `${taggedName}:concatkeys`;
 const source = await createClient({ url: sourceUrl }).connect();
 const target = createCluster({ rootNodes: [{ url: targetUrl }] });
+const disconnect = async (client) => {
+  if (typeof client.close === 'function') await client.close();
+  else await client.quit();
+};
 
 const scan = async function * (client, pattern) {
   for await (const batch of client.scanIterator({ TYPE: 'string', MATCH: pattern, COUNT: 9999 })) {
@@ -104,5 +108,5 @@ try {
 
   console.info(`Migrated ${migrated} RedisQueue tasks from "${legacyName}" to "${taggedName}".`);
 } finally {
-  await Promise.all([source.close(), target.close()]);
+  await Promise.all([disconnect(source), disconnect(target)]);
 }