@pauldeng/node-red-contrib-bullmq 1.0.0 → 1.0.2

package/README.md

@@ -8,11 +8,14 @@
 
 Node-RED nodes for BullMQ-backed Redis job queues.
 
-This package targets BullMQ 5.78.0, Node-RED 4.1, and Node.js 18 or newer. It preserves the legacy `bull-queue-server`, `bull cmd`, and `bull run` node types where BullMQ has compatible behavior, and adds `bull job`, `bull events`, and `bull flow`.
+This package targets BullMQ 5.80.2 and Node-RED 4.1 or 5.x. It preserves the legacy `bull-queue-server`, `bull cmd`, and `bull run` node types where BullMQ has compatible behavior, and adds `bull job`, `bull events`, and `bull flow`.
 
 ## Installation
 
+To install - either use the manage palette option in the editor, or change to your Node-RED user directory.
+
 ```sh
+cd ~/.node-red
 npm install @pauldeng/node-red-contrib-bullmq
 ```
 
@@ -20,10 +23,10 @@ Repository: <https://github.com/pauldeng/node-red-contrib-bullmq>
 
 ## Requirements
 
-- Node.js 18+
-- Node-RED 4.1.x
+- Node-RED 4.1.x or 5.x
+- Node.js 18+ with Node-RED 4.1.x, or Node.js 22.9+ with Node-RED 5.x
 - Redis with `maxmemory-policy=noeviction`
-- BullMQ 5.78.0
+- BullMQ 5.80.2
 
 Bull v4 Redis data is not automatically migrated. Drain, retire, or otherwise handle old Bull queues before upgrading the runtime dependency.
 
@@ -45,7 +48,7 @@ Supported deployment modes:
 - AWS MemoryDB, configured as Redis Cluster with TLS
 - Redis Sentinel
 
-Authentication can use Redis ACL username/password. TLS supports CA, client certificate, client key, server name, and certificate verification. Cluster and MemoryDB deployments should use a BullMQ prefix with a hash tag, such as `{bull}`, to keep queue keys in one Redis Cluster slot for atomic operations.
+Authentication can use Redis ACL username/password. TLS supports CA, client certificate, client key, server name, and certificate verification. Cluster and MemoryDB prefixes must contain a hash tag, such as `{bull}`, to keep queue keys in one Redis Cluster slot for atomic operations.
 
 ## Legacy Repeat Cron Compatibility
 
@@ -122,3 +125,4 @@ Use [docs/TESTING.md](docs/TESTING.md) for Docker, Playwright, and MemoryDB test
 - [Connection Guide](docs/CONNECTIONS.md)
 - [Migration Guide](docs/MIGRATION.md)
 - [Troubleshooting](docs/TROUBLESHOOTING.md)
+- [Changelog](CHANGELOG.md)

package/bull-queue.html

@@ -161,7 +161,7 @@
     <li><b>CA</b>: PEM certificate authority text for validating private Redis certificates. Stored as a Node-RED credential.</li>
     <li><b>Client Cert</b>: PEM client certificate for mutual TLS deployments. Stored as a Node-RED credential.</li>
     <li><b>Client Key</b>: PEM client private key for mutual TLS deployments. Stored as a Node-RED credential.</li>
-    <li><b>Prefix</b>: BullMQ key prefix. For Redis Cluster and MemoryDB, use a hash tag such as <code>{bull}</code> so BullMQ keys stay in one hash slot for atomic operations.</li>
+    <li><b>Prefix</b>: BullMQ key prefix. Redis Cluster and MemoryDB prefixes must contain a hash tag such as <code>{bull}</code> so BullMQ keys stay in one hash slot for atomic operations.</li>
   </ul>
 
   <h3>Example</h3>

package/bull-queue.js

@@ -8,6 +8,7 @@ const {
   Worker,
 } = require("bullmq");
 const IORedis = require("ioredis");
+const { setTimeout: sleep } = require("node:timers/promises");
 
 const {
   AcknowledgementRegistry,
@@ -41,20 +42,83 @@ const DEFAULT_EVENTS = [
   "waiting-children",
 ];
 
-async function closeResource(resource) {
+// How long a graceful close may take before the underlying sockets are
+// force-disconnected so Node-RED shutdown and redeploy are never blocked by
+// an unreachable Redis server.
+const CLOSE_GRACE_MS = 1000;
+
+async function settleWithin(promise, ms) {
+  let settled = false;
+  (async () => {
+    try {
+      await promise;
+    } catch (err) {
+      // a failed graceful close still counts as settled
+    }
+    settled = true;
+  })();
+
+  const deadline = Date.now() + ms;
+  while (!settled && Date.now() < deadline) {
+    await sleep(25);
+  }
+  return settled ? "settled" : "timeout";
+}
+
+function disconnectClient(client) {
+  if (client && typeof client.disconnect === "function") {
+    try {
+      client.disconnect(false);
+    } catch (err) {
+      // best effort: the socket may already be gone
+    }
+  }
+}
+
+function forceDisconnect(resource) {
   if (!resource) {
     return;
   }
-  if (typeof resource.close === "function") {
-    await resource.close();
+  if (typeof resource.status === "string") {
+    // Raw ioredis connection.
+    disconnectClient(resource);
     return;
   }
-  if (typeof resource.quit === "function") {
-    await resource.quit();
+  // BullMQ resource. Its public disconnect() awaits a connection promise that
+  // never settles while Redis is unreachable, so reach for the underlying
+  // ioredis clients directly (BullMQ is pinned to exactly 5.80.2).
+  if (resource.connection) {
+    disconnectClient(resource.connection._client);
+  }
+  if (resource.blockingConnection) {
+    disconnectClient(resource.blockingConnection._client);
+  }
+}
+
+async function closeResource(resource) {
+  if (!resource) {
     return;
   }
-  if (typeof resource.disconnect === "function") {
-    resource.disconnect();
+
+  if (typeof resource.close !== "function") {
+    // Raw ioredis connection: quit() never settles (or leaves a reconnect
+    // loop running) while the server is unreachable, so only quit ready
+    // connections and force-disconnect everything else.
+    if (resource.status === "ready" && typeof resource.quit === "function") {
+      if ((await settleWithin(resource.quit(), CLOSE_GRACE_MS)) === "timeout") {
+        forceDisconnect(resource);
+      }
+    } else {
+      forceDisconnect(resource);
+    }
+    return;
+  }
+
+  // BullMQ resource: QueueEvents.close() blocks forever on a connection that
+  // never became ready, so cap the graceful close and force-disconnect the
+  // sockets when it does not settle in time.
+  if ((await settleWithin(resource.close(), CLOSE_GRACE_MS)) === "timeout") {
+    forceDisconnect(resource);
   }
 }
 
@@ -91,12 +155,26 @@ function parseEventFilter(value) {
     .filter(Boolean);
 }
 
-function attachErrorListener(resource, node, label) {
+// One status vocabulary for every queue-backed node: connecting (yellow),
+// connected (green), disconnected (red).
+function setConnecting(node) {
+  node.status({ fill: "yellow", shape: "ring", text: "connecting" });
+}
+
+function setConnected(node) {
+  node.status({ fill: "green", shape: "dot", text: "connected" });
+}
+
+function setDisconnected(node) {
+  node.status({ fill: "red", shape: "ring", text: "disconnected" });
+}
+
+function attachErrorListener(resource, node) {
   if (!resource || typeof resource.on !== "function") {
     return;
   }
   resource.on("error", (err) => {
-    node.status({ fill: "red", shape: "ring", text: `${label}: error` });
+    setDisconnected(node);
     node.error(err);
   });
 }
@@ -150,7 +228,7 @@ module.exports = function registerBullMQNodes(RED) {
     node.createConnection = function createConnection(role, owner = node) {
       const descriptor = buildRedisDescriptor(node.config, role);
       const connection = createRedisConnection(descriptor, IORedis);
-      attachErrorListener(connection, owner, `Redis ${role}`);
+      attachErrorListener(connection, owner);
       node.resources.add(connection);
       return connection;
     };
@@ -162,11 +240,18 @@ module.exports = function registerBullMQNodes(RED) {
           node.config.queueName,
           buildBullMQOptions(node.config, node.producerConnection)
         );
-        attachErrorListener(node.queue, node, "BullMQ queue");
+        attachErrorListener(node.queue, node);
       }
       return node.queue;
     };
 
+    // The producer connection backs the shared queue used by bull cmd nodes;
+    // exposing it lets those nodes mirror the real connection state.
+    node.getProducerConnection = function getProducerConnection() {
+      node.getQueue();
+      return node.producerConnection;
+    };
+
     // Runtime nodes pass themselves as owner and attach their own resource
     // error listener, so worker/events/flow errors surface on the visible
     // runtime node rather than the hidden config node.
@@ -239,7 +324,23 @@ module.exports = function registerBullMQNodes(RED) {
     }
 
     node.bullConn.register(node);
-    node.status({ fill: "green", shape: "dot", text: "configured" });
+
+    // Watch the shared producer connection so the visible status reflects
+    // whether Redis is actually reachable instead of a static "configured".
+    const connection = node.bullConn.getProducerConnection();
+    const connectionListeners = {
+      ready: () => setConnected(node),
+      error: () => setDisconnected(node),
+      close: () => setDisconnected(node),
+    };
+    for (const [event, listener] of Object.entries(connectionListeners)) {
+      connection.on(event, listener);
+    }
+    if (connection.status === "ready") {
+      setConnected(node);
+    } else {
+      setConnecting(node);
+    }
 
     node.on("input", async function onInput(msg, send, done) {
       try {
@@ -253,6 +354,9 @@ module.exports = function registerBullMQNodes(RED) {
     });
 
     node.on("close", function onClose(removed, done) {
+      for (const [event, listener] of Object.entries(connectionListeners)) {
+        connection.removeListener(event, listener);
+      }
       node.bullConn.deregister(node, done);
     });
   }
@@ -309,14 +413,10 @@ module.exports = function registerBullMQNodes(RED) {
     };
 
     node.worker = node.bullQueue.createWorker(processor, workerOptions, node);
-    attachErrorListener(node.worker, node, "BullMQ worker");
-    node.worker.on("ready", () =>
-      node.status({ fill: "green", shape: "dot", text: "connected" })
-    );
-    node.worker.on("closed", () =>
-      node.status({ fill: "red", shape: "ring", text: "closed" })
-    );
-    node.status({ fill: "yellow", shape: "ring", text: "connecting" });
+    attachErrorListener(node.worker, node);
+    node.worker.on("ready", () => setConnected(node));
+    node.worker.on("closed", () => setDisconnected(node));
+    setConnecting(node);
 
     node.on("close", async function onClose(removed, done) {
       acknowledgements.rejectByRunNode(
@@ -426,7 +526,7 @@ module.exports = function registerBullMQNodes(RED) {
 
     node.bullConn.register(node);
     node.queueEvents = node.bullConn.createQueueEvents(node);
-    attachErrorListener(node.queueEvents, node, "BullMQ events");
+    attachErrorListener(node.queueEvents, node);
     const events = parseEventFilter(n.events);
     for (const event of events) {
       node.queueEvents.on(event, (payload, eventId) => {
@@ -443,9 +543,11 @@ module.exports = function registerBullMQNodes(RED) {
     }
     async function updateReadyStatus() {
       try {
+        setConnecting(node);
         await node.queueEvents.waitUntilReady();
-        node.status({ fill: "green", shape: "dot", text: "connected" });
+        setConnected(node);
       } catch (err) {
+        setDisconnected(node);
         node.error(err);
       }
     }
@@ -476,14 +578,14 @@ module.exports = function registerBullMQNodes(RED) {
 
     node.bullConn.register(node);
     node.flowProducer = node.bullConn.createFlowProducer(node);
-    attachErrorListener(node.flowProducer, node, "BullMQ flow");
+    attachErrorListener(node.flowProducer, node);
     async function updateReadyStatus() {
       try {
-        node.status({ fill: "yellow", shape: "ring", text: "connecting" });
+        setConnecting(node);
         await node.flowProducer.waitUntilReady();
-        node.status({ fill: "green", shape: "dot", text: "connected" });
+        setConnected(node);
       } catch (err) {
-        node.status({ fill: "red", shape: "ring", text: "connection error" });
+        setDisconnected(node);
         node.error(err);
       }
     }

package/docs/COMMANDS.md

@@ -82,6 +82,8 @@ Legacy lookup/removal is exact-id based.
 - `getRateLimitTtl`
 - `removeRateLimitKey`
 
+`setGlobalRateLimit` requires `msg.max` and `msg.duration`; the documented `{ max, duration }` object in `msg.payload` is also accepted.
+
 ## Logs And Metrics
 
 - `addJobLog`

package/docs/CONNECTIONS.md

@@ -12,7 +12,7 @@ Use deployment `cluster` and provide startup nodes as comma or newline separated
 
 Cluster auth and TLS are applied through ioredis `redisOptions`. The runtime sets a DNS lookup passthrough for TLS-enabled cluster discovery.
 
-Use a BullMQ prefix with a hash tag, normally `{bull}`.
+The BullMQ prefix must contain a Redis hash tag, normally `{bull}`. Untagged Cluster prefixes are rejected to prevent `CROSSSLOT` failures.
 
 ## AWS MemoryDB
 

package/docs/MIGRATION.md

@@ -9,7 +9,7 @@
 
 ## What Changes
 
-- Runtime dependency is BullMQ 5.78.0.
+- Runtime dependency is BullMQ 5.80.2.
 - `bull` and `sprintf-js` are removed.
 - Repeatable jobs use BullMQ Job Schedulers.
 - Scheduled jobs require a stable scheduler id.

package/docs/NODE_GUIDE.md

@@ -10,7 +10,7 @@ Deployment modes:
 - `cluster`: Redis Cluster and AWS MemoryDB.
 - `sentinel`: Redis Sentinel.
 
-Use `{bull}` for Cluster and MemoryDB unless you have a tested prefix strategy.
+Cluster and MemoryDB prefixes must contain a Redis hash tag; use `{bull}` unless you have a tested custom hash tag.
 
 ## `bull cmd`
 

package/docs/RELEASE.md

@@ -13,7 +13,7 @@ used here only for the one-time first publish.)
 
 1. Confirm `package.json` has the intended `version` and the name `@pauldeng/node-red-contrib-bullmq`.
 2. Confirm the GitHub repository is `https://github.com/pauldeng/node-red-contrib-bullmq`.
-3. Confirm BullMQ is pinned to exactly `5.78.0`.
+3. Confirm BullMQ is pinned to exactly `5.80.2`.
 4. Confirm no examples, docs, fixtures, or logs contain Redis, Sentinel, or MemoryDB secrets.
 5. Update `CHANGELOG.md` for the new version.
 

package/lib/acknowledgements.js

@@ -5,7 +5,7 @@ const { EventEmitter, once } = require("node:events");
 class AcknowledgementEntry {
   constructor(context, timeoutMs) {
     this.events = new EventEmitter();
-    this.settled = false;
+    this.settlement = undefined;
     this.job = context.job;
     this.queue = context.queue;
     this.queueName = context.queueName;
@@ -24,7 +24,8 @@ class AcknowledgementEntry {
   }
 
   async wait() {
-    const [settlement] = await once(this.events, "settled");
+    const settlement =
+      this.settlement || (await once(this.events, "settled"))[0];
     if (settlement.type === "reject") {
       throw settlement.error;
     }
@@ -40,10 +41,10 @@ class AcknowledgementEntry {
   }
 
   settle(settlement) {
-    if (this.settled) {
+    if (this.settlement) {
       return;
     }
-    this.settled = true;
+    this.settlement = settlement;
     clearTimeout(this.timeout);
     this.events.emit("settled", settlement);
   }

package/lib/commands.js

@@ -56,7 +56,7 @@ async function dispatchStopAndRemoveAllJobs(queue) {
 
   const cleaned = {};
   for (const state of CLEAN_STATES) {
-    cleaned[state] = await queue.clean(0, 1000, state);
+    cleaned[state] = await queue.clean(0, 0, state);
   }
 
   return { removedSchedulers, cleaned };
@@ -102,7 +102,6 @@ async function dispatchCommand(queue, msg = {}) {
         await queue.getDelayed(
           valueOrDefault(msg.start, 0),
           valueOrDefault(msg.end, -1),
-          valueOrDefault(msg.asc, false),
         )
       ).map(serializeJob);
     case "changeDelay": {
@@ -195,9 +194,15 @@ async function dispatchCommand(queue, msg = {}) {
       return queue.getGlobalConcurrency();
     case "removeGlobalConcurrency":
       return queue.removeGlobalConcurrency();
-    case "setGlobalRateLimit":
-      await queue.setGlobalRateLimit(msg.max, msg.duration);
+    case "setGlobalRateLimit": {
+      const max = msg.max ?? msg.payload?.max;
+      const duration = msg.duration ?? msg.payload?.duration;
+      if (max == null || duration == null) {
+        throw new Error("msg.max and msg.duration are required");
+      }
+      await queue.setGlobalRateLimit(max, duration);
       return true;
+    }
     case "getGlobalRateLimit":
       return queue.getGlobalRateLimit();
     case "removeGlobalRateLimit":

package/lib/connections.js

@@ -148,6 +148,11 @@ function normalizeQueueConfig(config = {}, credentials = {}) {
       ];
     }
     normalized.prefix = normalized.prefix || CLUSTER_PREFIX;
+    if (!/\{[^}]+\}/.test(normalized.prefix)) {
+      throw new Error(
+        "Cluster BullMQ prefix must contain a Redis hash tag such as {bull}",
+      );
+    }
   }
 
   if (deployment === "sentinel") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pauldeng/node-red-contrib-bullmq",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "BullMQ-backed Redis job queue nodes for Node-RED",
   "main": "bull-queue.js",
   "files": [
@@ -25,7 +25,7 @@
     "validate": "npx --yes node-red-dev validate"
   },
   "dependencies": {
-    "bullmq": "5.78.0",
+    "bullmq": "5.80.2",
     "ioredis": "5.10.1"
   },
   "license": "MIT",
@@ -40,7 +40,7 @@
     "jobs"
   ],
   "node-red": {
-    "version": ">=4.1.0 <5",
+    "version": ">=4.1.0 <6",
     "nodes": {
       "bull-queue": "bull-queue.js"
     }
@@ -62,9 +62,9 @@
     "email": "dengpeng.cn@gmail.com"
   },
   "devDependencies": {
-    "@playwright/test": "1.60.0",
-    "node-red": "4.1.11",
+    "@playwright/test": "1.61.1",
+    "node-red": "5.0.1",
     "node-red-node-test-helper": "^0.3.6",
-    "prettier": "3.8.3"
+    "prettier": "3.9.4"
   }
 }