mail-time 5.0.0 → 5.2.0

package/adapters/redis.js

@@ -1,12 +1,14 @@
 import {
   debug,
   logError,
+  hasOwnProp,
   isSendClaimUpdate,
   isSendLeaseGuardedUpdate,
   isAppendMailOptionUpdate,
   stripInternalUpdateMeta,
   isSendLeaseRemove,
 } from '../helpers.js';
+import { createHash } from 'crypto';
 
 /**
  * @typedef {object} RedisClient
@@ -14,8 +16,15 @@ import {
  * @property {(key: string) => Promise<string|null>} get
  * @property {(key: string, value: string, options?: object) => Promise<unknown>} set
  * @property {(key: string|string[]) => Promise<number>} del
- * @property {() => Promise<string>} ping
- * @property {(options: object) => AsyncIterable<string|string[]>} scanIterator
+ * @property {() => Promise<string>} [ping]
+ * @property {() => unknown} [getRandomNode]
+ * @property {(...args: any[]) => any} [nodeClient]
+ * @property {(firstKey: string, isReadonly: boolean, args: string[]) => 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]
+ * @property {(sha: string, options: { keys: string[], arguments: string[] }) => Promise<unknown>} [evalSha]
+ * @property {(script: string) => Promise<string>} [scriptLoad]
  * @property {(key: string) => Promise<unknown>} [watch]
  * @property {() => Promise<unknown>} [unwatch]
  * @property {() => object} [multi]
@@ -25,10 +34,189 @@ import {
  * @typedef {object} RedisQueueOption
  * @property {RedisClient} client
  * @property {string} [prefix]
+ * @property {boolean} [useHashTags] - Use Redis Cluster hash-tag keys (`mailtime:{prefix}:*`). Default keeps existing standalone keys.
  */
 
 const KEY_TYPES = new Set(['letter', 'sendat', 'concatletter']);
 const DEFAULT_PREFIX = 'default';
+const VALID_PREFIX = /^[A-Za-z0-9_\-:.]+$/;
+const TAGGED_ITERATE_LIMIT = 100;
+const clientTransactions = new WeakMap();
+
+const PUSH_TAGGED_TASK_SCRIPT = `
+  redis.call('HSET', KEYS[1], ARGV[1], ARGV[2])
+  redis.call('ZADD', KEYS[2], tonumber(ARGV[3]), ARGV[1])
+  if #KEYS > 3 then
+    redis.call('SET', KEYS[3], ARGV[1], 'PXAT', tonumber(ARGV[4]))
+    redis.call('ZADD', KEYS[4], tonumber(ARGV[4]), KEYS[3])
+  end
+  return 1
+`;
+
+const ITERATE_TAGGED_TASKS_SCRIPT = `
+  local now = tonumber(ARGV[1])
+  local maxTries = tonumber(ARGV[2])
+  local sendingTimeout = tonumber(ARGV[3])
+  local limit = tonumber(ARGV[4])
+  local scanLimit = tonumber(ARGV[5])
+  local tasks = {}
+  if #KEYS > 2 then
+    local expiredPointers = redis.call('ZRANGEBYSCORE', KEYS[3], '-inf', now, 'LIMIT', 0, 100)
+    for _, pointerKey in ipairs(expiredPointers) do
+      redis.call('DEL', pointerKey)
+      redis.call('ZREM', KEYS[3], pointerKey)
+    end
+  end
+  local due = redis.call('ZRANGEBYSCORE', KEYS[2], '-inf', now, 'LIMIT', 0, scanLimit)
+  for _, uuid in ipairs(due) do
+    local payload = redis.call('HGET', KEYS[1], uuid)
+    if not payload then
+      redis.call('ZREM', KEYS[2], uuid)
+    else
+      local task = cjson.decode(payload)
+      if task.isSent or task.isFailed or task.isCancelled or task.isSettled then
+        redis.call('ZREM', KEYS[2], uuid)
+      elseif tonumber(task.tries or 0) >= maxTries and not (type(task.recipientResults) == 'table' and task.isSending) then
+        redis.call('ZREM', KEYS[2], uuid)
+      elseif task.isSending then
+        local eligibleAt = tonumber(task.sendingAt or 0) + sendingTimeout
+        if eligibleAt > now then
+          redis.call('ZADD', KEYS[2], eligibleAt, uuid)
+        else
+          table.insert(tasks, payload)
+        end
+      elseif tonumber(task.sendAt or 0) <= now then
+        table.insert(tasks, payload)
+      else
+        redis.call('ZADD', KEYS[2], tonumber(task.sendAt), uuid)
+      end
+      if #tasks >= limit then
+        break
+      end
+    end
+  end
+
+  return cjson.encode(tasks)
+`;
+
+const UPDATE_TAGGED_TASK_SCRIPT = `
+  local payload = redis.call('HGET', KEYS[1], ARGV[1])
+  if not payload then
+    redis.call('ZREM', KEYS[2], ARGV[1])
+    return 0
+  end
+
+  local task = cjson.decode(payload)
+  local update = cjson.decode(ARGV[2])
+  local mode = ARGV[3]
+  local now = tonumber(ARGV[4])
+  local sendingTimeout = tonumber(ARGV[5])
+  local expectedTries = tonumber(ARGV[6])
+  local leaseSendingAt = tonumber(ARGV[7])
+  if payload ~= ARGV[8] then return -1 end
+
+  if mode == 'claim' then
+    if task.isSent or task.isFailed or task.isCancelled or task.isSettled or tonumber(task.tries or 0) ~= expectedTries then
+      return 0
+    end
+    if task.isSending and tonumber(task.sendingAt or 0) > now - sendingTimeout then
+      return 0
+    end
+  elseif mode == 'lease' then
+    if task.isSent or task.isSettled or task.isCancelled or task.isFailed or not task.isSending
+      or tonumber(task.tries or 0) ~= expectedTries
+      or tonumber(task.sendingAt or 0) ~= leaseSendingAt then
+      return 0
+    end
+  end
+
+  if mode == 'cancel' and (task.isSent or task.isSettled or task.isCancelled
+    or (type(task.recipientResults) == 'table' and task.isFailed)) then
+    return 0
+  end
+  for key, value in pairs(update) do
+    task[key] = value
+  end
+  redis.call('HSET', KEYS[1], ARGV[1], ARGV[9])
+
+  if task.isSent or task.isFailed or task.isCancelled or task.isSettled then
+    redis.call('ZREM', KEYS[2], ARGV[1])
+    if #KEYS > 3 then
+      local concatUuid = redis.call('GET', KEYS[3])
+      if concatUuid == ARGV[1] then
+        redis.call('DEL', KEYS[3])
+        redis.call('ZREM', KEYS[4], KEYS[3])
+      elseif not concatUuid then
+        redis.call('ZREM', KEYS[4], KEYS[3])
+      end
+    end
+  elseif task.isSending then
+    redis.call('ZADD', KEYS[2], tonumber(task.sendingAt or now) + sendingTimeout, ARGV[1])
+  else
+    redis.call('ZADD', KEYS[2], tonumber(task.sendAt), ARGV[1])
+  end
+  return 1
+`;
+
+const APPEND_TAGGED_MAIL_OPTION_SCRIPT = `
+  local payload = redis.call('HGET', KEYS[1], ARGV[1])
+  if not payload then
+    return 0
+  end
+  local task = cjson.decode(payload)
+  if task.isSending or task.isSent or task.isFailed or task.isCancelled or task.isSettled or type(task.recipientResults) == 'table' then
+    return 0
+  end
+  if payload ~= ARGV[3] then return -1 end
+  redis.call('HSET', KEYS[1], ARGV[1], ARGV[4])
+  return 1
+`;
+
+const REMOVE_TAGGED_TASK_SCRIPT = `
+  local payload = redis.call('HGET', KEYS[1], ARGV[1])
+  if not payload then
+    redis.call('ZREM', KEYS[2], ARGV[1])
+    return 0
+  end
+  local task = cjson.decode(payload)
+  if ARGV[2] == 'cancel' and (task.isSent or task.isSettled or task.isCancelled
+    or (type(task.recipientResults) == 'table' and task.isFailed)) then return 0 end
+  if ARGV[2] == 'lease' and (task.isSent or task.isSettled or task.isCancelled or task.isFailed or not task.isSending
+    or tonumber(task.tries or 0) ~= tonumber(ARGV[3])
+    or tonumber(task.sendingAt or 0) ~= tonumber(ARGV[4])) then
+    return 0
+  end
+  redis.call('HDEL', KEYS[1], ARGV[1])
+  redis.call('ZREM', KEYS[2], ARGV[1])
+  if #KEYS > 3 then
+    local concatUuid = redis.call('GET', KEYS[3])
+    if concatUuid == ARGV[1] then
+      redis.call('DEL', KEYS[3])
+      redis.call('ZREM', KEYS[4], KEYS[3])
+    elseif not concatUuid then
+      redis.call('ZREM', KEYS[4], KEYS[3])
+    end
+  end
+  return 1
+`;
+
+const normalizePolicyArrays = (task) => {
+  if (task.recipientResults && !Array.isArray(task.recipientResults) && Object.keys(task.recipientResults).length === 0) task.recipientResults = [];
+  if (Array.isArray(task.recipientResults)) {
+    for (const result of task.recipientResults) {
+      for (const field of ['sources', 'reasons']) {
+        if (result[field] && !Array.isArray(result[field]) && Object.keys(result[field]).length === 0) result[field] = [];
+      }
+    }
+  }
+  return task;
+};
+
+const sha1Hex = (string) => createHash('sha1').update(string).digest('hex');
+
+const isNoScriptError = (error) => {
+  return !!error && (error.code === 'NOSCRIPT' || (typeof error.message === 'string' && error.message.includes('NOSCRIPT')));
+};
 
 const canReleaseLease = (currentTask, updateObj) => {
   return currentTask
@@ -36,6 +224,8 @@ const canReleaseLease = (currentTask, updateObj) => {
     && currentTask.isSending === true
     && (typeof currentTask.sendingAt === 'number' ? currentTask.sendingAt : 0) === updateObj.leaseSendingAt
     && currentTask.isCancelled !== true
+    && currentTask.isSent !== true
+    && currentTask.isSettled !== true
     && currentTask.isFailed !== true;
 };
 
@@ -43,7 +233,7 @@ const canClaimTask = (currentTask, task, now, sendingTimeout) => {
   if (!currentTask) {
     return false;
   }
-  if (currentTask.isSent === true || currentTask.isFailed === true || currentTask.isCancelled === true) {
+  if (currentTask.isSent === true || currentTask.isFailed === true || currentTask.isCancelled === true || currentTask.isSettled === true) {
     return false;
   }
   if (currentTask.tries !== task.tries) {
@@ -62,11 +252,11 @@ const isIterateCandidate = (candidate, now, sendingTimeout, maxTries) => {
   if (!candidate || typeof candidate !== 'object') {
     return false;
   }
-  if (candidate.isSent === true || candidate.isFailed === true || candidate.isCancelled === true) {
+  if (candidate.isSent === true || candidate.isFailed === true || candidate.isCancelled === true || candidate.isSettled === true) {
     return false;
   }
   const tries = typeof candidate.tries === 'number' ? candidate.tries : 0;
-  if (tries >= maxTries) {
+  if (tries >= maxTries && !(Array.isArray(candidate.recipientResults) && candidate.isSending === true)) {
     return false;
   }
   if (candidate.isSending === true) {
@@ -94,6 +284,7 @@ class RedisQueue {
    */
   constructor (opts) {
     this.name = 'redis-queue';
+    this.supportsRecipientPolicies = true;
     if (!opts || typeof opts !== 'object') {
       throw new TypeError('[mail-time] Configuration object must be passed into RedisQueue constructor');
     }
@@ -102,7 +293,21 @@ class RedisQueue {
       throw new Error('[mail-time] [RedisQueue] required {client} option is missing, e.g. returned from `redis.createClient()` or `redis.createCluster()` method');
     }
 
+    if (opts.useHashTags !== undefined && typeof opts.useHashTags !== 'boolean') {
+      throw new TypeError(`[mail-time] [RedisQueue] {useHashTags} option must be a boolean (received: ${typeof opts.useHashTags})`);
+    }
+
     this.client = opts.client;
+    this.useHashTags = opts.useHashTags === true;
+    this.__scriptSources = {
+      push: PUSH_TAGGED_TASK_SCRIPT,
+      iterate: ITERATE_TAGGED_TASKS_SCRIPT,
+      update: UPDATE_TAGGED_TASK_SCRIPT,
+      append: APPEND_TAGGED_MAIL_OPTION_SCRIPT,
+      remove: REMOVE_TAGGED_TASK_SCRIPT,
+    };
+    this.__scriptShas = Object.fromEntries(Object.entries(this.__scriptSources).map(([name, source]) => [name, sha1Hex(source)]));
+    this.__loadedShas = new Set();
     if (typeof opts.prefix === 'string') {
       this.__applyPrefix(opts.prefix);
     }
@@ -110,8 +315,16 @@ class RedisQueue {
 
   /** @internal */
   __applyPrefix(prefix) {
+    if (this.useHashTags && !VALID_PREFIX.test(prefix)) {
+      throw new Error(`[mail-time] [RedisQueue] {prefix} option must match ${VALID_PREFIX} when {useHashTags} is true (received: "${prefix}")`);
+    }
     this.prefix = prefix;
-    this.uniqueName = `mailtime:${prefix}`;
+    this.uniqueName = this.useHashTags ? `mailtime:{${prefix}}` : `mailtime:${prefix}`;
+    if (this.useHashTags) {
+      this.lettersKey = `${this.uniqueName}:letters`;
+      this.scheduleKey = `${this.uniqueName}:schedule`;
+      this.concatKeysKey = `${this.uniqueName}:concatkeys`;
+    }
   }
 
   /** @internal */
@@ -126,6 +339,60 @@ class RedisQueue {
     debug(this.mailTimeInstance?.debug === true, `[${this.name}]`, ...args);
   }
 
+  /** @internal */
+  async __runScript(scriptKey, options) {
+    const source = this.__scriptSources[scriptKey];
+    const sha = this.__scriptShas[scriptKey];
+    if (!source || !sha) {
+      throw new Error(`[mail-time] [RedisQueue] unknown script "${scriptKey}"`);
+    }
+
+    if (this.useHashTags && typeof this.client.nodeClient === 'function' && typeof this.client.sendCommand === 'function') {
+      const key = options.keys[0];
+      const args = [`${options.keys.length}`, ...options.keys, ...options.arguments];
+      try {
+        return await this.client.sendCommand(key, false, ['EVALSHA', sha, ...args]);
+      } catch (error) {
+        if (!isNoScriptError(error)) throw error;
+      }
+      return await this.client.sendCommand(key, false, ['EVAL', source, ...args]);
+    }
+
+    if (this.__loadedShas.has(sha) && typeof this.client.evalSha === 'function') {
+      try {
+        return await this.client.evalSha(sha, options);
+      } catch (error) {
+        if (!isNoScriptError(error)) {
+          throw error;
+        }
+        this.__loadedShas.delete(sha);
+      }
+    }
+
+    if (typeof this.client.scriptLoad === 'function' && typeof this.client.evalSha === 'function') {
+      try {
+        await this.client.scriptLoad(source);
+        this.__loadedShas.add(sha);
+        return await this.client.evalSha(sha, options);
+      } catch (error) {
+        if (!isNoScriptError(error)) {
+          this.__debug(`[script:${scriptKey}] scriptLoad failed; falling back to EVAL`, error);
+        }
+      }
+    }
+
+    if (typeof this.client.eval !== 'function') {
+      throw new Error('[mail-time] [RedisQueue] Redis Cluster client must support EVAL');
+    }
+    return await this.client.eval(source, options);
+  }
+
+  /** @internal */
+  __getTaggedConcatKey(to) {
+    this.__ensurePrefix();
+    return `${this.uniqueName}:concatletter:${to}`;
+  }
+
   /**
    * @async
    * @memberOf RedisQueue
@@ -158,7 +425,9 @@ class RedisQueue {
     }
 
     try {
-      const ping = await this.client.ping();
+      const pingClient = typeof this.client.ping === 'function' ? this.client
+        : await this.client.nodeClient(this.client.getRandomNode());
+      const ping = await pingClient.ping();
       if (ping === 'PONG') {
         return {
           status: 'OK',
@@ -203,6 +472,26 @@ class RedisQueue {
       const maxTries = (this.mailTimeInstance && typeof this.mailTimeInstance.maxTries === 'number')
         ? this.mailTimeInstance.maxTries
         : 60;
+
+      if (this.useHashTags) {
+        this.__ensurePrefix();
+        const dispatchLimit = Number.isFinite(limit) && limit > 0 ? Math.floor(limit) : TAGGED_ITERATE_LIMIT;
+        const payload = await this.__runScript('iterate', {
+          keys: [this.lettersKey, this.scheduleKey, this.concatKeysKey],
+          arguments: [`${now}`, `${maxTries}`, `${sendingTimeout}`, `${dispatchLimit}`, `${Math.max(dispatchLimit * 20, 100)}`],
+        });
+        const candidates = payload ? JSON.parse(String(payload)) : [];
+        if (!Array.isArray(candidates)) {
+          return;
+        }
+        for (const value of candidates) {
+          const candidate = normalizePolicyArrays(typeof value === 'string' ? JSON.parse(value) : value);
+          if (isIterateCandidate(candidate, now, sendingTimeout, maxTries)) {
+            await this.mailTimeInstance.___dispatch(candidate);
+          }
+        }
+        return;
+      }
       let dispatched = 0;
 
       const matchPattern = this.__getKey('*', 'sendat');
@@ -259,20 +548,21 @@ class RedisQueue {
       return null;
     }
 
-    const concatKey = this.__getKey(to, 'concatletter');
+    const concatKey = this.useHashTags ? this.__getTaggedConcatKey(to) : this.__getKey(to, 'concatletter');
     const uuid = await this.client.get(concatKey);
     if (!uuid) {
       return null;
     }
 
-    const letterKey = this.__getKey(uuid, 'letter');
-    const taskJSON = await this.client.get(letterKey);
+    const taskJSON = this.useHashTags
+      ? await this.client.hGet(this.lettersKey, uuid)
+      : await this.client.get(this.__getKey(uuid, 'letter'));
     if (!taskJSON) {
       return null;
     }
 
     const task = JSON.parse(taskJSON);
-    if (!task || task.isSent === true || task.isCancelled === true || task.isFailed === true || task.sendAt > sendAt || task.isSending === true || task.tries >= this.mailTimeInstance.maxTries) {
+    if (!task || task.isSettled === true || task.recipientResults != null || task.isSent === true || task.isCancelled === true || task.isFailed === true || task.sendAt > sendAt || task.isSending === true || task.tries >= this.mailTimeInstance.maxTries) {
       return null;
     }
 
@@ -297,6 +587,19 @@ class RedisQueue {
       task.sendAt = +task.sendAt;
     }
 
+    if (this.useHashTags) {
+      this.__ensurePrefix();
+      const keys = [this.lettersKey, this.scheduleKey];
+      const args = [task.uuid, JSON.stringify(task), `${+task.sendAt}`];
+      if (task.to) {
+        keys.push(this.__getTaggedConcatKey(task.to));
+        keys.push(this.concatKeysKey);
+        args.push(`${task.sendAt - 128}`);
+      }
+      await this.__runScript('push', { keys, arguments: args });
+      return;
+    }
+
     const letterKey = this.__getKey(task.uuid, 'letter');
     const sendatKey = this.__getKey(task.uuid, 'sendat');
     const taskJSON = JSON.stringify(task);
@@ -332,30 +635,59 @@ class RedisQueue {
    * @returns {Promise<boolean>} returns `true` if cancelled or `false` if not found, was sent, or was cancelled previously
    */
   async cancel(uuid) {
+    return await this.__serialize(() => this.__cancel(uuid));
+  }
+
+  /** @internal */
+  async __serialize(operation) {
+    if (this.useHashTags) return await operation();
+    const previous = clientTransactions.get(this.client) || Promise.resolve();
+    const pending = previous.then(operation);
+    const settled = pending.catch(() => void 0);
+    clientTransactions.set(this.client, settled);
+    try { return await pending; }
+    finally { if (clientTransactions.get(this.client) === settled) clientTransactions.delete(this.client); }
+  }
+
+  /** @internal */
+  async __cancel(uuid) {
     this.__debug('[cancel]', uuid);
     if (typeof uuid !== 'string') {
       return false;
     }
 
-    await this.client.del(this.__getKey(uuid, 'sendat'));
-    const letterKey = this.__getKey(uuid, 'letter');
-    const taskJSON = await this.client.get(letterKey);
-    if (!taskJSON) {
-      return false;
-    }
-
-    const task = JSON.parse(taskJSON);
-    if (!task || task.isSent === true || task.isCancelled === true) {
+    this.__ensurePrefix();
+    const atomic = typeof this.client.watch === 'function' && typeof this.client.multi === 'function';
+    const letterKey = this.__getKey(uuid);
+    try {
+      if (!this.useHashTags && atomic) await this.client.watch(letterKey);
+      const payload = this.useHashTags ? await this.client.hGet(this.lettersKey, uuid) : await this.client.get(letterKey);
+      const task = payload ? JSON.parse(payload) : null;
+      if (!task || task.isSent || task.isCancelled || task.isSettled || (task.recipientResults != null && task.isFailed)) return false;
+      if (this.useHashTags) {
+        const keys = [this.lettersKey, this.scheduleKey];
+        if (task.to) keys.push(this.__getTaggedConcatKey(task.to), this.concatKeysKey);
+        const keep = this.mailTimeInstance.keepHistory;
+        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;
+      }
+      if (!atomic) {
+        if (task.recipientResults != null) return false;
+        return this.mailTimeInstance.keepHistory ? await this.__update(task, { isCancelled: true }) : await this.__remove(task);
+      }
+      const multi = this.client.multi();
+      if (this.mailTimeInstance.keepHistory) multi.set(letterKey, JSON.stringify({ ...task, isCancelled: true }));
+      else multi.del(letterKey);
+      multi.del(this.__getKey(uuid, 'sendat'));
+      return (await multi.exec()) !== null;
+    } catch (error) {
+      logError('[cancel] storage error', error);
       return false;
+    } finally {
+      if (!this.useHashTags && atomic) await this.client.unwatch?.();
     }
-
-    if (!this.mailTimeInstance.keepHistory) {
-      return await this.remove(task);
-    }
-
-    return await this.update(task, {
-      isCancelled: true,
-    });
   }
 
   /**
@@ -368,11 +700,40 @@ class RedisQueue {
    * @returns {Promise<boolean>} returns `true` if removed or `false` if not found
    */
   async remove(task, opts) {
+    return await this.__serialize(() => this.__remove(task, opts));
+  }
+
+  /** @internal */
+  async __remove(task, opts) {
     this.__debug('[remove]', task?.uuid);
     if (!task || typeof task !== 'object' || typeof task.uuid !== 'string') {
       return false;
     }
 
+    if (this.useHashTags) {
+      this.__ensurePrefix();
+      try {
+        const keys = [this.lettersKey, this.scheduleKey];
+        if (task.to) {
+          keys.push(this.__getTaggedConcatKey(task.to));
+          keys.push(this.concatKeysKey);
+        }
+        const result = await this.__runScript('remove', {
+          keys,
+          arguments: [
+            task.uuid,
+            isSendLeaseRemove(opts) ? 'lease' : 'plain',
+            `${opts?.leaseTries || 0}`,
+            `${opts?.leaseSendingAt || 0}`,
+          ],
+        });
+        return Number(result) >= 1;
+      } catch (opError) {
+        logError('[remove] [tagged] [opError]', opError);
+        return false;
+      }
+    }
+
     const letterKey = this.__getKey(task.uuid, 'letter');
     if (isSendLeaseRemove(opts)) {
       if (typeof this.client.watch !== 'function' || typeof this.client.multi !== 'function') {
@@ -390,6 +751,8 @@ class RedisQueue {
           || currentTask.isSending !== true
           || (typeof currentTask.sendingAt === 'number' ? currentTask.sendingAt : 0) !== opts.leaseSendingAt
           || currentTask.isCancelled === true
+          || currentTask.isSent === true
+          || currentTask.isSettled === true
           || currentTask.isFailed === true) {
           await this.client.unwatch?.();
           return false;
@@ -433,6 +796,11 @@ class RedisQueue {
    * @returns {Promise<boolean>} returns `true` if updated or `false` if not found or no changes was made
    */
   async update(task, updateObj) {
+    return await this.__serialize(() => this.__update(task, updateObj));
+  }
+
+  /** @internal */
+  async __update(task, updateObj) {
     this.__debug('[update]', task?.uuid);
     if (!task || typeof task !== 'object' || typeof task.uuid !== 'string' || !updateObj || typeof updateObj !== 'object') {
       return false;
@@ -443,10 +811,43 @@ class RedisQueue {
     const isClaim = isSendClaimUpdate(updateObj);
     const isAppend = isAppendMailOptionUpdate(updateObj);
     const isLeaseRelease = isSendLeaseGuardedUpdate(updateObj);
+    if ((hasOwnProp(updateObj, 'recipientResults') || hasOwnProp(updateObj, 'isSettled')) && !isClaim && !isLeaseRelease) return false;
     const now = isClaim && typeof updateObj.sendingAt === 'number' ? updateObj.sendingAt : Date.now();
     const sendingTimeout = this.mailTimeInstance?.sendingTimeout || 300000;
 
     try {
+      if (this.useHashTags) {
+        // JS serialization preserves empty arrays and scalar values that Lua cjson changes.
+        // The script compares the exact payload as well as the claim/lease predicates.
+        for (let attempt = 0; attempt < 3; attempt++) {
+          const payload = await this.client.hGet(this.lettersKey, task.uuid);
+          if (!payload) return false;
+          const current = normalizePolicyArrays(JSON.parse(payload));
+          const persist = stripInternalUpdateMeta(updateObj);
+          const next = isAppend
+            ? { ...current, mailOptions: [...(current.mailOptions || []), updateObj.appendMailOption] }
+            : { ...current, ...persist };
+          if (isAppend) {
+            const result = Number(await this.__runScript('append', {
+              keys: [this.lettersKey],
+              arguments: [task.uuid, JSON.stringify(updateObj.appendMailOption), payload, JSON.stringify(next)],
+            }));
+            if (result === -1) continue;
+            return result >= 1;
+          }
+          const keys = [this.lettersKey, this.scheduleKey];
+          if (current.to) keys.push(this.__getTaggedConcatKey(current.to), this.concatKeysKey);
+          const result = Number(await this.__runScript('update', {
+            keys,
+            arguments: [task.uuid, JSON.stringify(persist), isClaim ? 'claim' : (isLeaseRelease ? 'lease' : 'plain'),
+              `${now}`, `${sendingTimeout}`, `${isClaim ? task.tries : (updateObj.leaseTries || 0)}`,
+              `${updateObj.leaseSendingAt || 0}`, payload, JSON.stringify(next)],
+          }));
+          if (result !== -1) return result >= 1;
+        }
+        return false;
+      }
+
       if (isAppend) {
         if (typeof this.client.watch !== 'function' || typeof this.client.multi !== 'function') {
           if (!RedisQueue.__atomicAppendWarned) {
@@ -458,7 +859,7 @@ class RedisQueue {
             return false;
           }
           const currentTask = JSON.parse(taskJSON);
-          if (currentTask.isSending === true || currentTask.isSent === true || currentTask.isFailed === true || currentTask.isCancelled === true) {
+          if (currentTask.isSending === true || currentTask.isSent === true || currentTask.isFailed === true || currentTask.isCancelled === true || currentTask.isSettled === true || Array.isArray(currentTask.recipientResults)) {
             return false;
           }
           currentTask.mailOptions = [...(currentTask.mailOptions || []), updateObj.appendMailOption];
@@ -473,7 +874,7 @@ class RedisQueue {
           return false;
         }
         const currentTask = JSON.parse(taskJSON);
-        if (currentTask.isSending === true || currentTask.isSent === true || currentTask.isFailed === true || currentTask.isCancelled === true) {
+        if (currentTask.isSending === true || currentTask.isSent === true || currentTask.isFailed === true || currentTask.isCancelled === true || currentTask.isSettled === true || Array.isArray(currentTask.recipientResults)) {
           await this.client.unwatch?.();
           return false;
         }
@@ -513,7 +914,7 @@ class RedisQueue {
         const updatedTask = { ...currentTask, ...stripInternalUpdateMeta(updateObj) };
         const multi = this.client.multi();
         multi.set(letterKey, JSON.stringify(updatedTask));
-        if (updatedTask.isSent === true || updatedTask.isFailed === true || updatedTask.isCancelled === true) {
+        if (updatedTask.isSent === true || updatedTask.isFailed === true || updatedTask.isCancelled === true || updatedTask.isSettled === true) {
           multi.del(sendatKey);
         } else if (updatedTask.sendAt) {
           multi.set(sendatKey, `${+updatedTask.sendAt}`);
@@ -532,7 +933,7 @@ class RedisQueue {
       const updatedTask = { ...currentTask, ...stripInternalUpdateMeta(updateObj) };
       await this.client.set(letterKey, JSON.stringify(updatedTask));
 
-      if (updatedTask.isSent === true || updatedTask.isFailed === true || updatedTask.isCancelled === true) {
+      if (updatedTask.isSent === true || updatedTask.isFailed === true || updatedTask.isCancelled === true || updatedTask.isSettled === true) {
         await this.client.del(sendatKey);
       } else if (updatedTask.sendAt) {
         await this.client.set(sendatKey, `${+updatedTask.sendAt}`);
@@ -558,6 +959,15 @@ class RedisQueue {
       throw new Error(`[mail-time] [RedisQueue] [__getKey] unsupported key "${type}" passed into the second argument`);
     }
     this.__ensurePrefix();
+    if (this.useHashTags) {
+      if (type === 'letter') {
+        return this.lettersKey;
+      }
+      if (type === 'sendat') {
+        return this.scheduleKey;
+      }
+      return this.__getTaggedConcatKey(uuid);
+    }
     return `${this.uniqueName}:${type}:${uuid}`;
   }
 }