mail-time 5.0.0 → 5.1.0

package/README.md

@@ -537,12 +537,16 @@ For deeper JoSk semantics, install the JoSk skill: **`npx skills add veliovgroup
 
 | Constructor                              | Required option                                      | Optional                                                                                                     |
 | ---------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| `new RedisQueue({ client, prefix? })`    | connected `redis@^4/^5` client with `watch()` + `multi()` | `prefix` — inherited from `MailTime` when omitted. Redis Cluster prefixes must map to one hash slot.        |
+| `new RedisQueue({ client, prefix?, useHashTags? })` | connected `redis@^4/^5` standalone or Cluster client | `prefix` — inherited from `MailTime` when omitted. Set `useHashTags: true` on Redis/KeyDB Cluster; set same option on JoSk Redis adapter. |
 | `new MongoQueue({ db, prefix? })`        | `db` from `MongoClient#db()`                         | `prefix` — inherited from `MailTime` when omitted. Indexes auto-created on first `ready()`.                  |
 | `new PostgresQueue({ client, prefix? })` | `pg.Pool` (recommended) or `pg.Client`               | `prefix` — inherited from `MailTime` when omitted. `mail_time_queue` table auto-migrated on first `ready()`. |
 
 For custom adapters see [docs/queue-api.md](https://github.com/veliovgroup/mail-time/blob/master/docs/queue-api.md).
 
+### Redis Cluster
+
+Set `useHashTags: true` on both `RedisQueue` and its JoSk Redis adapter. Queue state then uses `mailtime:{prefix}:letters` plus a tagged sorted-set schedule, so node-redis `createCluster()` can route every Lua operation to one slot. One prefix is one slot; shard high-volume traffic across prefixes. Tagged `iterate` returns at most 100 due rows per tick. Existing standalone keys are not read in this mode. Follow [Redis Cluster migration](https://github.com/veliovgroup/mail-time/blob/master/docs/migration-v5-v5.1.md) before cutover.
+
 ### Module functions
 
 - `mailTimePreset(name, overrides?)` → fresh MailTime constructor config. Deep-clones the named [preset](#settings-presets) and deep-merges your overrides (scalars win, nested `josk` composes). Throws on unknown `name` or non-object `overrides`.
@@ -563,6 +567,7 @@ Upgrade checklists, adapter contract changes, and rollout notes live in the docs
 | 3.x  | 4.1 | [v3 → v4](https://github.com/veliovgroup/mail-time/blob/master/docs/migration-v3-v4.md) |
 | 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) |
 
 New in v4 (opt-in): `mailTimePreset`, `concurrency`/`mode`, `sendingTimeout`, `drain()`/`pause()`/`resume()`, per-recipient handling, AI skills bundle.
 

package/adapters/redis.d.ts

@@ -4,7 +4,17 @@ export type RedisClient = {
     set: (key: string, value: string, options?: object) => Promise<unknown>;
     del: (key: string | string[]) => Promise<number>;
     ping: () => Promise<string>;
-    scanIterator: (options: object) => AsyncIterable<string | string[]>;
+    scanIterator?: ((options: object) => AsyncIterable<string | string[]>) | undefined;
+    hGet?: ((key: string, field: string) => Promise<string | null>) | undefined;
+    eval?: ((script: string, options: {
+        keys: string[];
+        arguments: string[];
+    }) => Promise<unknown>) | undefined;
+    evalSha?: ((sha: string, options: {
+        keys: string[];
+        arguments: string[];
+    }) => Promise<unknown>) | undefined;
+    scriptLoad?: ((script: string) => Promise<string>) | undefined;
     watch?: ((key: string) => Promise<unknown>) | undefined;
     unwatch?: (() => Promise<unknown>) | undefined;
     multi?: (() => object) | undefined;
@@ -12,6 +22,10 @@ export type RedisClient = {
 export type RedisQueueOption = {
     client: RedisClient;
     prefix?: string | undefined;
+    /**
+     * - Use Redis Cluster hash-tag keys (`mailtime:{prefix}:*`). Default keeps existing standalone keys.
+     */
+    useHashTags?: boolean | undefined;
 };
 /** Class representing Redis Queue for MailTime */
 export class RedisQueue {
@@ -22,8 +36,12 @@ export class RedisQueue {
     constructor(opts: RedisQueueOption);
     name: string;
     client: RedisClient;
+    useHashTags: boolean;
     prefix: any;
     uniqueName: string | undefined;
+    lettersKey: string | undefined;
+    scheduleKey: string | undefined;
+    concatKeysKey: string | undefined;
     /**
      * @async
      * @memberOf RedisQueue

package/adapters/redis.js

@@ -7,6 +7,7 @@ import {
   stripInternalUpdateMeta,
   isSendLeaseRemove,
 } from '../helpers.js';
+import { createHash } from 'crypto';
 
 /**
  * @typedef {object} RedisClient
@@ -15,7 +16,11 @@ import {
  * @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 {(options: object) => AsyncIterable<string|string[]>} [scanIterator]
+ * @property {(key: string, field: string) => Promise<string|null>} [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 +30,168 @@ 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 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 tonumber(task.tries or 0) >= maxTries 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, task)
+        end
+      elseif tonumber(task.sendAt or 0) <= now then
+        table.insert(tasks, task)
+      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 mode == 'claim' then
+    if task.isSent or task.isFailed or task.isCancelled 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.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
+
+  for key, value in pairs(update) do
+    task[key] = value
+  end
+  redis.call('HSET', KEYS[1], ARGV[1], cjson.encode(task))
+
+  if task.isSent or task.isFailed or task.isCancelled 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 then
+    return 0
+  end
+  task.mailOptions = task.mailOptions or {}
+  table.insert(task.mailOptions, cjson.decode(ARGV[2]))
+  redis.call('HSET', KEYS[1], ARGV[1], cjson.encode(task))
+  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] == 'lease' and (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 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
@@ -102,7 +265,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 +287,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 +311,49 @@ 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.__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
@@ -203,6 +431,25 @@ 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 candidate of candidates) {
+          if (isIterateCandidate(candidate, now, sendingTimeout, maxTries)) {
+            await this.mailTimeInstance.___dispatch(candidate);
+          }
+        }
+        return;
+      }
       let dispatched = 0;
 
       const matchPattern = this.__getKey('*', 'sendat');
@@ -259,14 +506,15 @@ 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;
     }
@@ -297,6 +545,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);
@@ -337,9 +598,14 @@ class RedisQueue {
       return false;
     }
 
-    await this.client.del(this.__getKey(uuid, 'sendat'));
-    const letterKey = this.__getKey(uuid, 'letter');
-    const taskJSON = await this.client.get(letterKey);
+    if (this.useHashTags) {
+      this.__ensurePrefix();
+    } else {
+      await this.client.del(this.__getKey(uuid, 'sendat'));
+    }
+    const taskJSON = this.useHashTags
+      ? await this.client.hGet(this.lettersKey, uuid)
+      : await this.client.get(this.__getKey(uuid, 'letter'));
     if (!taskJSON) {
       return false;
     }
@@ -373,6 +639,30 @@ class RedisQueue {
       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') {
@@ -447,6 +737,36 @@ class RedisQueue {
     const sendingTimeout = this.mailTimeInstance?.sendingTimeout || 300000;
 
     try {
+      if (this.useHashTags) {
+        if (isAppend) {
+          const result = await this.__runScript('append', {
+            keys: [this.lettersKey],
+            arguments: [task.uuid, JSON.stringify(updateObj.appendMailOption)],
+          });
+          return Number(result) >= 1;
+        }
+
+        const mode = isClaim ? 'claim' : (isLeaseRelease ? 'lease' : 'plain');
+        const keys = [this.lettersKey, this.scheduleKey];
+        if (task.to) {
+          keys.push(this.__getTaggedConcatKey(task.to));
+          keys.push(this.concatKeysKey);
+        }
+        const result = await this.__runScript('update', {
+          keys,
+          arguments: [
+            task.uuid,
+            JSON.stringify(stripInternalUpdateMeta(updateObj)),
+            mode,
+            `${now}`,
+            `${sendingTimeout}`,
+            `${isClaim ? task.tries : (updateObj.leaseTries || 0)}`,
+            `${updateObj.leaseSendingAt || 0}`,
+          ],
+        });
+        return Number(result) >= 1;
+      }
+
       if (isAppend) {
         if (typeof this.client.watch !== 'function' || typeof this.client.multi !== 'function') {
           if (!RedisQueue.__atomicAppendWarned) {
@@ -558,6 +878,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}`;
   }
 }

package/index.cjs

@@ -729,7 +729,11 @@ class MongoQueue {
  * @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 {(options: object) => AsyncIterable<string|string[]>} [scanIterator]
+ * @property {(key: string, field: string) => Promise<string|null>} [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]
@@ -739,10 +743,168 @@ class MongoQueue {
  * @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$1 = 'default';
+const VALID_PREFIX = /^[A-Za-z0-9_\-:.]+$/;
+const TAGGED_ITERATE_LIMIT = 100;
+
+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 tonumber(task.tries or 0) >= maxTries 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, task)
+        end
+      elseif tonumber(task.sendAt or 0) <= now then
+        table.insert(tasks, task)
+      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 mode == 'claim' then
+    if task.isSent or task.isFailed or task.isCancelled 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.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
+
+  for key, value in pairs(update) do
+    task[key] = value
+  end
+  redis.call('HSET', KEYS[1], ARGV[1], cjson.encode(task))
+
+  if task.isSent or task.isFailed or task.isCancelled 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 then
+    return 0
+  end
+  task.mailOptions = task.mailOptions or {}
+  table.insert(task.mailOptions, cjson.decode(ARGV[2]))
+  redis.call('HSET', KEYS[1], ARGV[1], cjson.encode(task))
+  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] == 'lease' and (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 sha1Hex = (string) => crypto.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
@@ -816,7 +978,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);
     }
@@ -824,8 +1000,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 */
@@ -840,6 +1024,49 @@ 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.__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
@@ -917,6 +1144,25 @@ 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 candidate of candidates) {
+          if (isIterateCandidate(candidate, now, sendingTimeout, maxTries)) {
+            await this.mailTimeInstance.___dispatch(candidate);
+          }
+        }
+        return;
+      }
       let dispatched = 0;
 
       const matchPattern = this.__getKey('*', 'sendat');
@@ -973,14 +1219,15 @@ 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;
     }
@@ -1011,6 +1258,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);
@@ -1051,9 +1311,14 @@ class RedisQueue {
       return false;
     }
 
-    await this.client.del(this.__getKey(uuid, 'sendat'));
-    const letterKey = this.__getKey(uuid, 'letter');
-    const taskJSON = await this.client.get(letterKey);
+    if (this.useHashTags) {
+      this.__ensurePrefix();
+    } else {
+      await this.client.del(this.__getKey(uuid, 'sendat'));
+    }
+    const taskJSON = this.useHashTags
+      ? await this.client.hGet(this.lettersKey, uuid)
+      : await this.client.get(this.__getKey(uuid, 'letter'));
     if (!taskJSON) {
       return false;
     }
@@ -1087,6 +1352,30 @@ class RedisQueue {
       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') {
@@ -1161,6 +1450,36 @@ class RedisQueue {
     const sendingTimeout = this.mailTimeInstance?.sendingTimeout || 300000;
 
     try {
+      if (this.useHashTags) {
+        if (isAppend) {
+          const result = await this.__runScript('append', {
+            keys: [this.lettersKey],
+            arguments: [task.uuid, JSON.stringify(updateObj.appendMailOption)],
+          });
+          return Number(result) >= 1;
+        }
+
+        const mode = isClaim ? 'claim' : (isLeaseRelease ? 'lease' : 'plain');
+        const keys = [this.lettersKey, this.scheduleKey];
+        if (task.to) {
+          keys.push(this.__getTaggedConcatKey(task.to));
+          keys.push(this.concatKeysKey);
+        }
+        const result = await this.__runScript('update', {
+          keys,
+          arguments: [
+            task.uuid,
+            JSON.stringify(stripInternalUpdateMeta(updateObj)),
+            mode,
+            `${now}`,
+            `${sendingTimeout}`,
+            `${isClaim ? task.tries : (updateObj.leaseTries || 0)}`,
+            `${updateObj.leaseSendingAt || 0}`,
+          ],
+        });
+        return Number(result) >= 1;
+      }
+
       if (isAppend) {
         if (typeof this.client.watch !== 'function' || typeof this.client.multi !== 'function') {
           if (!RedisQueue.__atomicAppendWarned) {
@@ -1272,6 +1591,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}`;
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mail-time",
-  "version": "5.0.0",
+  "version": "5.1.0",
   "description": "📮 Email queue extending nodemailer with multi-SMTP transports and horizontally scaled apps support",
   "main": "index.js",
   "types": "./index.d.ts",
@@ -18,7 +18,8 @@
     "index.d.ts",
     "index.js",
     "presets.d.ts",
-    "presets.js"
+    "presets.js",
+    "scripts/migrate-redis-queue-to-cluster.mjs"
   ],
   "exports": {
     ".": {
@@ -63,6 +64,7 @@
     "test:jest": "node --experimental-vm-modules ./node_modules/jest/bin/jest.js --config jest.config.mjs",
     "test:mocha": "mocha ./test/npm.js",
     "test:mocha:redis": "mocha ./test/npm-redis-redis.js",
+    "test:mocha:redis-cluster": "mocha ./test/npm-redis-cluster.js",
     "test:mocha:mongo": "mocha ./test/npm-redis-mongo.js ./test/npm-mongo-redis.js ./test/npm-ha-mongo-redis.js",
     "test:mocha:postgres": "mocha ./test/npm-postgres.js",
     "test:types": "tsc -p ./tsconfig.types.json",

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

@@ -0,0 +1,108 @@
+import { createClient, createCluster } from 'redis';
+
+const args = process.argv.slice(2);
+const readArg = (name) => {
+  const index = args.indexOf(name);
+  return index === -1 ? void 0 : args[index + 1];
+};
+const sourceUrl = readArg('--source');
+const targetUrl = readArg('--target');
+const prefix = readArg('--prefix');
+const sendingTimeout = Number(readArg('--sending-timeout') || 300000);
+const overwrite = args.includes('--overwrite');
+
+if (!sourceUrl || !targetUrl || !prefix || !Number.isFinite(sendingTimeout) || sendingTimeout <= 0) {
+  throw new Error('Usage: node scripts/migrate-redis-queue-to-cluster.mjs --source <redis-url> --target <cluster-url> --prefix <prefix> [--sending-timeout <ms>] [--overwrite]');
+}
+
+if (!/^[A-Za-z0-9_\-:.]+$/.test(prefix)) {
+  throw new Error(`{prefix} must match /^[A-Za-z0-9_\\-:.]+$/ (received: "${prefix}")`);
+}
+
+const legacyName = `mailtime:${prefix}`;
+const taggedName = `mailtime:{${prefix}}`;
+const lettersKey = `${taggedName}:letters`;
+const scheduleKey = `${taggedName}:schedule`;
+const concatKeysKey = `${taggedName}:concatkeys`;
+const source = await createClient({ url: sourceUrl }).connect();
+const target = createCluster({ rootNodes: [{ url: targetUrl }] });
+
+const scan = async function * (client, pattern) {
+  for await (const batch of client.scanIterator({ TYPE: 'string', MATCH: pattern, COUNT: 9999 })) {
+    for (const key of (Array.isArray(batch) ? batch : [batch])) {
+      yield key;
+    }
+  }
+};
+
+const nextEligibleAt = (task) => {
+  if (task.isSent === true || task.isFailed === true || task.isCancelled === true) {
+    return null;
+  }
+  if (task.isSending === true) {
+    return (typeof task.sendingAt === 'number' ? task.sendingAt : 0) + sendingTimeout;
+  }
+  return +task.sendAt;
+};
+
+try {
+  await target.connect();
+  const trackedConcatKeys = await target.zRange(concatKeysKey, 0, -1);
+  for (const key of trackedConcatKeys) {
+    if (await target.pTTL(key) === -2) {
+      await target.zRem(concatKeysKey, key);
+    }
+  }
+  const targetHasData = (await target.hLen(lettersKey)) > 0
+    || (await target.zCard(scheduleKey)) > 0
+    || (await target.zCard(concatKeysKey)) > 0;
+  if (targetHasData && !overwrite) {
+    throw new Error(`Target queue "${taggedName}" is not empty. Pass --overwrite only after verifying its contents can be replaced.`);
+  }
+  if (targetHasData) {
+    const concatKeys = await target.zRange(concatKeysKey, 0, -1);
+    if (concatKeys.length) {
+      await target.del(concatKeys);
+    }
+    await target.del([lettersKey, scheduleKey, concatKeysKey]);
+  }
+
+  let migrated = 0;
+  for await (const key of scan(source, `${legacyName}:letter:*`)) {
+    const payload = await source.get(key);
+    if (!payload) {
+      continue;
+    }
+    const task = JSON.parse(payload);
+    if (!task || typeof task.uuid !== 'string') {
+      continue;
+    }
+    await target.hSet(lettersKey, task.uuid, payload);
+    const eligibleAt = nextEligibleAt(task);
+    if (eligibleAt !== null && Number.isFinite(eligibleAt)) {
+      await target.zAdd(scheduleKey, { score: eligibleAt, value: task.uuid });
+    }
+    migrated++;
+  }
+
+  for await (const key of scan(source, `${legacyName}:concatletter:*`)) {
+    const uuid = await source.get(key);
+    if (!uuid) {
+      continue;
+    }
+    const ttl = await source.pTTL(key);
+    const to = key.slice(`${legacyName}:concatletter:`.length);
+    const targetKey = `${taggedName}:concatletter:${to}`;
+    if (ttl > 0) {
+      await target.set(targetKey, uuid, { PX: ttl });
+      await target.zAdd(concatKeysKey, { score: Date.now() + ttl, value: targetKey });
+    } else if (ttl === -1) {
+      await target.set(targetKey, uuid);
+      await target.zAdd(concatKeysKey, { score: Number.MAX_SAFE_INTEGER, value: targetKey });
+    }
+  }
+
+  console.info(`Migrated ${migrated} RedisQueue tasks from "${legacyName}" to "${taggedName}".`);
+} finally {
+  await Promise.all([source.close(), target.close()]);
+}