node-red-contrib-qrusty 0.19.20 → 0.20.0

package/README.md

@@ -1,28 +1,135 @@
 # node-red-contrib-qrusty
 
-Node-RED Function node snippets for interacting with a Qrusty server.
-
-## Notes
-
-- Default server URL in examples assumes Docker Compose service name `queue-server` on port `6784`.
-- Qrusty expects `payload` to be a JSON string for `POST /publish`, so the publish snippet uses `JSON.stringify(msg.payload)`.
-
-## Included snippets
-
-- `qrusty-publish.js` (POST `/publish`)
-- `qrusty-consume.js` (POST `/consume/{queue}`)
-- `qrusty-ack.js` (POST `/ack/{queue}/{id}`)
-- `qrusty-nack.js` (POST `/nack/{queue}/{id}`)
-- `qrusty-create-queue.js` (POST `/create-queue`)
-- `qrusty-update-queue.js` (POST `/update-queue`)
-- `qrusty-delete-queue.js` (DELETE `/delete-queue/{queue}`)
-- `qrusty-purge-queue.js` (POST `/purge-queue/{queue}`)
-- `qrusty-stats.js` (GET `/stats`)
-- `qrusty-queue-stats.js` (GET `/queue-stats/{queue}`)
-- `qrusty-queue-metrics.js` (GET `/queues/{queue}/metrics`)
-- `qrusty-list-queues.js` (GET `/queues`)
-- `qrusty-purge-all.js` (POST `/purge-all`)
-- `qrusty-delete-all.js` (POST `/delete-all`)
-- `qrusty-ack-batch.js` (POST `/ack-batch/{queue}`)
-- `qrusty-nack-batch.js` (POST `/nack-batch/{queue}`)
-- `qrusty-health.js` (GET `/health`)
+Node-RED custom nodes for the [Qrusty](https://github.com/greeng3/qrusty)
+priority queue server.
+
+Wraps the [`qrusty-client`](https://www.npmjs.com/package/qrusty-client)
+Node.js client in fully-typed, HTML-templated Node-RED nodes so you can
+drag-and-drop queue operations into your flows instead of hand-rolling
+`function` nodes.
+
+## Install
+
+From the Node-RED palette manager, search for `node-red-contrib-qrusty`
+and install. Or from the command line in your Node-RED user directory
+(typically `~/.node-red`):
+
+```bash
+npm install node-red-contrib-qrusty
+```
+
+Requires Node.js 18 or newer and Node-RED 3.0 or newer.
+
+## Nodes
+
+One config node plus 17 action nodes. All action nodes reference a
+shared `qrusty-server` config node so you only enter the host/port once
+per environment.
+
+### Config node
+
+| Node            | Purpose                                                                                         |
+| --------------- | ----------------------------------------------------------------------------------------------- |
+| `qrusty-server` | Holds host, port, and `useHttps` for a Qrusty server. Computes `baseUrl = http(s)://host:port`. |
+
+### Message operations
+
+| Node                | HTTP endpoint             | Purpose                                |
+| ------------------- | ------------------------- | -------------------------------------- |
+| `qrusty-publish`    | `POST /publish`           | Publish `msg.payload` to a queue.      |
+| `qrusty-consume`    | `POST /consume/:queue`    | Pop one message (or null).             |
+| `qrusty-ack`        | `POST /ack/:queue/:id`    | Acknowledge a message.                 |
+| `qrusty-nack`       | `POST /nack/:queue/:id`   | Negatively acknowledge (retry or DLQ). |
+| `qrusty-ack-batch`  | `POST /ack-batch/:queue`  | Ack many ids in one request.           |
+| `qrusty-nack-batch` | `POST /nack-batch/:queue` | Nack many ids in one request.          |
+
+### Queue management
+
+| Node                  | HTTP endpoint                 | Purpose                                          |
+| --------------------- | ----------------------------- | ------------------------------------------------ |
+| `qrusty-create-queue` | `POST /create-queue`          | Create a queue with ordering / duplicate policy. |
+| `qrusty-update-queue` | `POST /update-queue`          | Rename or toggle duplicate protection.           |
+| `qrusty-delete-queue` | `DELETE /delete-queue/:queue` | Delete a queue and its messages.                 |
+| `qrusty-purge-queue`  | `POST /purge-queue/:queue`    | Empty a queue without deleting it.               |
+| `qrusty-purge-all`    | `POST /purge-all`             | Empty every queue.                               |
+| `qrusty-delete-all`   | `POST /delete-all`            | Delete every queue.                              |
+
+### Observability
+
+| Node                   | HTTP endpoint                | Purpose                          |
+| ---------------------- | ---------------------------- | -------------------------------- |
+| `qrusty-stats`         | `GET /stats`                 | Aggregate stats for every queue. |
+| `qrusty-queue-stats`   | `GET /queue-stats/:queue`    | Detailed stats for one queue.    |
+| `qrusty-queue-metrics` | `GET /queues/:queue/metrics` | Per-second time-series metrics.  |
+| `qrusty-list-queues`   | `GET /queues`                | Names of all existing queues.    |
+| `qrusty-health`        | `GET /health`                | Server health check.             |
+
+## Config-vs-msg fallback
+
+Every action node supports two ways of supplying its parameters:
+
+1. **In the editor panel** — values set on the node itself (e.g. a hard-coded
+   `queue` field) take precedence.
+2. **At runtime via the incoming `msg`** — leave the field blank on the node
+   and supply `msg.queue`, `msg.priority`, etc.
+
+This lets you build generic flows (`msg.queue` decided upstream) or
+explicit flows (queue pinned in the editor), or a mix of both.
+
+## Error handling
+
+- A green status dot with `"ok"` means the HTTP call succeeded.
+- A blue dot with `"requesting"` shows the call is in flight.
+- A red ring with `"HTTP 4xx"` / `"HTTP 5xx"` / `"no server config"` means
+  the node failed; the error is forwarded via `done(err)` so a downstream
+  `catch` node will pick it up.
+
+## Example flow
+
+```json
+[
+  {
+    "id": "srv",
+    "type": "qrusty-server",
+    "name": "dev",
+    "host": "localhost",
+    "port": "6784",
+    "useHttps": false
+  },
+  {
+    "id": "inject",
+    "type": "inject",
+    "payload": "hello from node-red",
+    "payloadType": "str",
+    "wires": [["pub"]]
+  },
+  {
+    "id": "pub",
+    "type": "qrusty-publish",
+    "name": "",
+    "server": "srv",
+    "queue": "orders",
+    "priority": "10",
+    "wires": [[]]
+  }
+]
+```
+
+## Development
+
+```bash
+cd integrations/node-red
+npm install
+npm test            # runs mocha against node-red-node-test-helper
+```
+
+The test suite in `test/` uses the official
+[`node-red-node-test-helper`](https://www.npmjs.com/package/node-red-node-test-helper)
+to load every node into a real Node-RED runtime and exercise it end-to-end
+against a mocked HTTP server.
+
+## Versioning
+
+This package tracks the Qrusty server version. When the server bumps
+(e.g. `0.19.x`), this package is bumped in lockstep and its
+`qrusty-client` dependency is pinned to the matching major.minor.

package/lib/common.js

@@ -0,0 +1,94 @@
+// lib/common.js
+//
+// Shared helpers for all Qrusty Node-RED action nodes.
+// Wraps the qrusty-client HTTP client with standard Node-RED patterns:
+// status updates, async error handling, and config-vs-msg fallback.
+
+const { QrustyClient } = require("qrusty-client");
+
+/**
+ * Pick a value: prefer the node config, fall back to `msg.<name>`, then
+ * to `fallback`.  Treats empty string / null / undefined as "not set".
+ *
+ * @param {*} configVal   value from the Node-RED node config (may be "")
+ * @param {*} msgVal      value from the incoming msg
+ * @param {*} [fallback]  optional default when neither is set
+ * @returns {*}
+ */
+function fromConfigOrMsg(configVal, msgVal, fallback) {
+  if (configVal !== undefined && configVal !== null && configVal !== "") {
+    return configVal;
+  }
+  if (msgVal !== undefined && msgVal !== null) {
+    return msgVal;
+  }
+  return fallback;
+}
+
+/**
+ * Coerce a value to a number if it looks numeric, else return undefined.
+ * Used for priority / maxRetries / timeoutSeconds config fields which are
+ * rendered as `<input type="number">` but arrive as strings.
+ */
+function toNumberOrUndefined(value) {
+  if (value === undefined || value === null || value === "") return undefined;
+  const n = Number(value);
+  return Number.isNaN(n) ? undefined : n;
+}
+
+/**
+ * Register an async input handler on `node` that:
+ *   1. instantiates a QrustyClient from the server config's baseUrl,
+ *   2. runs the supplied `action(client, msg)` function,
+ *   3. stores the result in msg.payload and emits the msg,
+ *   4. updates node.status with blue → green (ok) / red (error),
+ *   5. forwards errors via `done(err)` for proper Node-RED catch semantics.
+ *
+ * If the server config is missing or invalid, the node enters a permanent
+ * "no server config" red-ring status and every subsequent input fails fast
+ * without making HTTP calls.
+ *
+ * @param {object}   node         the Node-RED node instance
+ * @param {object}   serverConfig the resolved qrusty-server config node
+ * @param {Function} action       async (client, msg) => any
+ */
+function setupActionNode(node, serverConfig, action) {
+  if (!serverConfig || !serverConfig.baseUrl) {
+    node.status({ fill: "red", shape: "ring", text: "no server config" });
+    node.on("input", function (msg, send, done) {
+      const err = new Error(
+        "qrusty-server config is required but not configured",
+      );
+      if (done) {
+        done(err);
+      } else {
+        node.error(err, msg);
+      }
+    });
+    return;
+  }
+
+  node.on("input", async function (msg, send, done) {
+    node.status({ fill: "blue", shape: "dot", text: "requesting" });
+    try {
+      const client = new QrustyClient(serverConfig.baseUrl);
+      const result = await action(client, msg);
+      msg.payload = result;
+      node.status({ fill: "green", shape: "dot", text: "ok" });
+      send(msg);
+      if (done) done();
+    } catch (err) {
+      const statusText = err?.response?.status
+        ? `HTTP ${err.response.status}`
+        : err?.message || String(err);
+      node.status({ fill: "red", shape: "ring", text: statusText });
+      if (done) {
+        done(err);
+      } else {
+        node.error(err, msg);
+      }
+    }
+  });
+}
+
+module.exports = { setupActionNode, fromConfigOrMsg, toNumberOrUndefined };

package/package.json

@@ -1,33 +1,63 @@
 {
   "name": "node-red-contrib-qrusty",
-  "version": "0.19.20",
-  "description": "Node-RED nodes for Qrusty priority queue server",
+  "version": "0.20.0",
+  "description": "Node-RED nodes for the Qrusty priority queue server",
   "author": "Gordon Greene <greeng3@obscure-reference.com>",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/greeng3/qrusty.git",
+    "directory": "integrations/node-red"
+  },
   "keywords": [
     "node-red",
     "qrusty",
     "queue",
-    "priority"
+    "priority-queue",
+    "message-queue"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "qrusty-client": "^0.20.0"
+  },
+  "devDependencies": {
+    "mocha": "^11.0.0",
+    "nock": "^14.0.0",
+    "node-red": "^4.0.0",
+    "node-red-node-test-helper": "^0.3.4"
+  },
+  "scripts": {
+    "test": "mocha \"test/**/*_spec.js\" --timeout 10000"
+  },
+  "files": [
+    "lib/",
+    "qrusty-*.js",
+    "qrusty-*.html",
+    "README.md",
+    "LICENSE"
   ],
   "node-red": {
+    "version": ">=3.0.0",
     "nodes": {
+      "qrusty-server": "qrusty-server.js",
       "qrusty-publish": "qrusty-publish.js",
       "qrusty-consume": "qrusty-consume.js",
       "qrusty-ack": "qrusty-ack.js",
       "qrusty-nack": "qrusty-nack.js",
+      "qrusty-ack-batch": "qrusty-ack-batch.js",
+      "qrusty-nack-batch": "qrusty-nack-batch.js",
       "qrusty-create-queue": "qrusty-create-queue.js",
       "qrusty-update-queue": "qrusty-update-queue.js",
       "qrusty-delete-queue": "qrusty-delete-queue.js",
       "qrusty-purge-queue": "qrusty-purge-queue.js",
+      "qrusty-purge-all": "qrusty-purge-all.js",
+      "qrusty-delete-all": "qrusty-delete-all.js",
       "qrusty-stats": "qrusty-stats.js",
       "qrusty-queue-stats": "qrusty-queue-stats.js",
       "qrusty-queue-metrics": "qrusty-queue-metrics.js",
       "qrusty-list-queues": "qrusty-list-queues.js",
-      "qrusty-purge-all": "qrusty-purge-all.js",
-      "qrusty-delete-all": "qrusty-delete-all.js",
-      "qrusty-ack-batch": "qrusty-ack-batch.js",
-      "qrusty-nack-batch": "qrusty-nack-batch.js",
       "qrusty-health": "qrusty-health.js"
     }
   }

package/qrusty-ack-batch.html

@@ -0,0 +1,68 @@
+<script type="text/javascript">
+  RED.nodes.registerType("qrusty-ack-batch", {
+    category: "qrusty",
+    color: "#d78a4e",
+    defaults: {
+      name: { value: "" },
+      server: { value: "", type: "qrusty-server", required: true },
+      queue: { value: "" },
+      consumerId: { value: "" },
+    },
+    inputs: 1,
+    outputs: 1,
+    icon: "font-awesome/fa-check-square",
+    label: function () {
+      return this.name || "qrusty ack batch";
+    },
+    paletteLabel: "ack batch",
+  });
+</script>
+
+<script type="text/html" data-template-name="qrusty-ack-batch">
+  <div class="form-row">
+    <label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
+    <input type="text" id="node-input-name" placeholder="optional" />
+  </div>
+  <div class="form-row">
+    <label for="node-input-server"><i class="fa fa-server"></i> Server</label>
+    <input type="text" id="node-input-server" />
+  </div>
+  <div class="form-row">
+    <label for="node-input-queue"><i class="fa fa-list"></i> Queue</label>
+    <input
+      type="text"
+      id="node-input-queue"
+      placeholder="leave blank to use msg.queue"
+    />
+  </div>
+  <div class="form-row">
+    <label for="node-input-consumerId"
+      ><i class="fa fa-user"></i> Consumer ID</label
+    >
+    <input
+      type="text"
+      id="node-input-consumerId"
+      placeholder="default node-red-consumer"
+    />
+  </div>
+</script>
+
+<script type="text/html" data-help-name="qrusty-ack-batch">
+  <p>Acknowledges multiple messages at once.</p>
+  <h3>Inputs</h3>
+  <dl class="message-properties">
+    <dt>messageIds <span class="property-type">string[]</span></dt>
+    <dd>
+      The ids to ack.  Supplied via <code>msg.messageIds</code>,
+      <code>msg.message_ids</code>, or <code>msg.payload</code> (if it
+      is itself an array).
+    </dd>
+    <dt class="optional">queue <span class="property-type">string</span></dt>
+    <dd>Queue holding the messages.</dd>
+  </dl>
+  <h3>Outputs</h3>
+  <dl class="message-properties">
+    <dt>payload <span class="property-type">object</span></dt>
+    <dd>Server response with counts of acked / not-found ids.</dd>
+  </dl>
+</script>

package/qrusty-ack-batch.js

@@ -1,10 +1,38 @@
-// Function node for batch-acknowledging messages in qrusty
-msg.url =
-  "http://queue-server:6784/ack-batch/" + (msg.queue || "default_queue");
-msg.method = "POST";
-msg.payload = {
-  consumer_id: msg.consumer_id || "node-red-consumer",
-  message_ids: msg.messageIds || [],
+// qrusty-ack-batch.js
+//
+// Batch-acknowledges multiple messages in one HTTP round trip.
+
+const { setupActionNode, fromConfigOrMsg } = require("./lib/common");
+
+module.exports = function (RED) {
+  function QrustyAckBatchNode(n) {
+    RED.nodes.createNode(this, n);
+    const node = this;
+    const server = RED.nodes.getNode(n.server);
+
+    setupActionNode(node, server, async (client, msg) => {
+      const queue = fromConfigOrMsg(n.queue, msg.queue);
+      if (!queue) throw new Error("queue is required");
+
+      const ids = Array.isArray(msg.messageIds)
+        ? msg.messageIds
+        : Array.isArray(msg.message_ids)
+          ? msg.message_ids
+          : Array.isArray(msg.payload)
+            ? msg.payload
+            : null;
+      if (!ids || ids.length === 0) {
+        throw new Error(
+          "messageIds array is required (set msg.messageIds, msg.message_ids, or msg.payload)",
+        );
+      }
+
+      const consumerId =
+        fromConfigOrMsg(n.consumerId, msg.consumer_id) || "node-red-consumer";
+
+      return await client.ackBatch(queue, consumerId, ids);
+    });
+  }
+
+  RED.nodes.registerType("qrusty-ack-batch", QrustyAckBatchNode);
 };
-msg.headers = { "Content-Type": "application/json" };
-return msg;

package/qrusty-ack.html

@@ -0,0 +1,66 @@
+<script type="text/javascript">
+  RED.nodes.registerType("qrusty-ack", {
+    category: "qrusty",
+    color: "#d78a4e",
+    defaults: {
+      name: { value: "" },
+      server: { value: "", type: "qrusty-server", required: true },
+      queue: { value: "" },
+      consumerId: { value: "" },
+    },
+    inputs: 1,
+    outputs: 1,
+    icon: "font-awesome/fa-check",
+    label: function () {
+      return this.name || "qrusty ack";
+    },
+    paletteLabel: "ack",
+  });
+</script>
+
+<script type="text/html" data-template-name="qrusty-ack">
+  <div class="form-row">
+    <label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
+    <input type="text" id="node-input-name" placeholder="optional" />
+  </div>
+  <div class="form-row">
+    <label for="node-input-server"><i class="fa fa-server"></i> Server</label>
+    <input type="text" id="node-input-server" />
+  </div>
+  <div class="form-row">
+    <label for="node-input-queue"><i class="fa fa-list"></i> Queue</label>
+    <input
+      type="text"
+      id="node-input-queue"
+      placeholder="leave blank to use msg.queue"
+    />
+  </div>
+  <div class="form-row">
+    <label for="node-input-consumerId"
+      ><i class="fa fa-user"></i> Consumer ID</label
+    >
+    <input
+      type="text"
+      id="node-input-consumerId"
+      placeholder="default node-red-consumer"
+    />
+  </div>
+</script>
+
+<script type="text/html" data-help-name="qrusty-ack">
+  <p>Acknowledges a Qrusty message.</p>
+  <h3>Inputs</h3>
+  <dl class="message-properties">
+    <dt>messageId / id <span class="property-type">string</span></dt>
+    <dd>The id of the message to ack (either <code>msg.messageId</code> or <code>msg.id</code>).</dd>
+    <dt class="optional">queue <span class="property-type">string</span></dt>
+    <dd>Queue holding the message (if not set on the node).</dd>
+    <dt class="optional">consumer_id <span class="property-type">string</span></dt>
+    <dd>Consumer identity that originally locked the message.</dd>
+  </dl>
+  <h3>Outputs</h3>
+  <dl class="message-properties">
+    <dt>payload <span class="property-type">boolean</span></dt>
+    <dd><code>true</code> on success, <code>false</code> if the server returned 404.</dd>
+  </dl>
+</script>

package/qrusty-ack.js

@@ -1,12 +1,33 @@
-// Function node for acknowledging a message in qrusty
-msg.url =
-  "http://queue-server:6784/ack/" +
-  (msg.queue || "default_queue") +
-  "/" +
-  msg.messageId;
-msg.method = "POST";
-msg.payload = {
-  consumer_id: msg.consumer_id || "node-red-consumer",
+// qrusty-ack.js
+//
+// Acknowledges a previously-consumed message.  msg.payload becomes
+// `true` on success or `false` if the server returned 404 (message
+// already acked, lock expired, or id unknown).
+
+const { setupActionNode, fromConfigOrMsg } = require("./lib/common");
+
+module.exports = function (RED) {
+  function QrustyAckNode(n) {
+    RED.nodes.createNode(this, n);
+    const node = this;
+    const server = RED.nodes.getNode(n.server);
+
+    setupActionNode(node, server, async (client, msg) => {
+      const queue = fromConfigOrMsg(n.queue, msg.queue);
+      if (!queue) throw new Error("queue is required");
+      const messageId = fromConfigOrMsg(
+        undefined,
+        msg.messageId ?? msg.id ?? msg.message_id,
+      );
+      if (!messageId) {
+        throw new Error("messageId is required (set msg.messageId or msg.id)");
+      }
+      const consumerId =
+        fromConfigOrMsg(n.consumerId, msg.consumer_id) || "node-red-consumer";
+
+      return await client.ack(queue, messageId, consumerId);
+    });
+  }
+
+  RED.nodes.registerType("qrusty-ack", QrustyAckNode);
 };
-msg.headers = { "Content-Type": "application/json" };
-return msg;

package/qrusty-consume.html

@@ -0,0 +1,76 @@
+<script type="text/javascript">
+  RED.nodes.registerType("qrusty-consume", {
+    category: "qrusty",
+    color: "#d78a4e",
+    defaults: {
+      name: { value: "" },
+      server: { value: "", type: "qrusty-server", required: true },
+      queue: { value: "" },
+      consumerId: { value: "" },
+      timeoutSeconds: { value: "" },
+    },
+    inputs: 1,
+    outputs: 1,
+    icon: "font-awesome/fa-inbox",
+    label: function () {
+      return this.name || "qrusty consume";
+    },
+    paletteLabel: "consume",
+  });
+</script>
+
+<script type="text/html" data-template-name="qrusty-consume">
+  <div class="form-row">
+    <label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
+    <input type="text" id="node-input-name" placeholder="optional" />
+  </div>
+  <div class="form-row">
+    <label for="node-input-server"><i class="fa fa-server"></i> Server</label>
+    <input type="text" id="node-input-server" />
+  </div>
+  <div class="form-row">
+    <label for="node-input-queue"><i class="fa fa-list"></i> Queue</label>
+    <input
+      type="text"
+      id="node-input-queue"
+      placeholder="leave blank to use msg.queue"
+    />
+  </div>
+  <div class="form-row">
+    <label for="node-input-consumerId"
+      ><i class="fa fa-user"></i> Consumer ID</label
+    >
+    <input
+      type="text"
+      id="node-input-consumerId"
+      placeholder="default node-red-consumer"
+    />
+  </div>
+  <div class="form-row">
+    <label for="node-input-timeoutSeconds"
+      ><i class="fa fa-clock-o"></i> Lock timeout (s)</label
+    >
+    <input type="number" id="node-input-timeoutSeconds" placeholder="30" />
+  </div>
+</script>
+
+<script type="text/html" data-help-name="qrusty-consume">
+  <p>Pops one message from a Qrusty queue.</p>
+  <h3>Inputs</h3>
+  <dl class="message-properties">
+    <dt class="optional">queue <span class="property-type">string</span></dt>
+    <dd>Queue to read from (if not set on the node).</dd>
+    <dt class="optional">consumer_id <span class="property-type">string</span></dt>
+    <dd>Consumer identity used by the lock ownership check.</dd>
+    <dt class="optional">timeout_seconds <span class="property-type">number</span></dt>
+    <dd>How long the server locks the popped message before auto-unlock.</dd>
+  </dl>
+  <h3>Outputs</h3>
+  <dl class="message-properties">
+    <dt>payload <span class="property-type">object | null</span></dt>
+    <dd>
+      The popped message (<code>{ id, payload, retry_count }</code>) or
+      <code>null</code> when the queue is empty.
+    </dd>
+  </dl>
+</script>