qrusty-client 0.3.0 → 0.5.0

package/index.js

@@ -23,7 +23,7 @@ class QrustyClient {
   }
 
   /**
-   * Create or configure a queue
+   * Create a new queue. Throws an error if the queue already exists.
    * @param {string} name
    * @param {string} [ordering="MaxFirst"] - One of: Fifo | MinFirst | MaxFirst
    * @param {boolean} [allowDuplicates=true]
@@ -189,4 +189,246 @@ class QrustyClient {
   }
 }
 
-module.exports = QrustyClient;
+// ---------------------------------------------------------------------------
+// WsSession – WebSocket client (WS-0019)
+// ---------------------------------------------------------------------------
+
+/**
+ * DeliveredMessage – a message pushed by the server over a WebSocket subscription.
+ * @typedef {Object} DeliveredMessage
+ * @property {string} queue
+ * @property {string} id
+ * @property {string} payload
+ * @property {number} priority
+ * @property {string} createdAt
+ */
+
+/**
+ * Persistent WebSocket session to a Qrusty server.
+ *
+ * @example
+ * const session = new WsSession('ws://localhost:6784');
+ * await session.connect();
+ *
+ * // Publish
+ * const id = await session.publish('orders', 'hello', 10);
+ *
+ * // Subscribe (AsyncIterable)
+ * for await (const msg of session.subscribe('orders')) {
+ *   console.log(msg.payload);
+ *   await session.ack(msg.queue, msg.id);
+ *   break;
+ * }
+ *
+ * await session.close();
+ *
+ * @requires ws  (npm install ws)
+ */
+class WsSession {
+  /**
+   * @param {string} addr - Server WebSocket base URL, e.g. 'ws://localhost:6784'
+   */
+  constructor(addr) {
+    this.addr = addr.replace(/\/$/, "");
+    this._ws = null;
+    this._reqCounter = 0;
+    this._pending = new Map(); // req_id → { resolve, reject }
+    this._deliverQueues = new Map(); // queue → Array of waiting resolvers
+  }
+
+  // -------------------------------------------------------------------------
+  // connect / close
+  // -------------------------------------------------------------------------
+
+  /** Establish the WebSocket connection. */
+  async connect() {
+    const WebSocket = require("ws");
+    return new Promise((resolve, reject) => {
+      this._ws = new WebSocket(`${this.addr}/ws`);
+      this._ws.once("open", resolve);
+      this._ws.once("error", reject);
+      this._ws.on("message", (raw) => this._onMessage(raw));
+    });
+  }
+
+  /** Close the connection gracefully. */
+  async close() {
+    return new Promise((resolve) => {
+      if (!this._ws) return resolve();
+      this._ws.once("close", resolve);
+      this._ws.close();
+    });
+  }
+
+  // -------------------------------------------------------------------------
+  // Internal helpers
+  // -------------------------------------------------------------------------
+
+  _nextReqId() {
+    return `req-${++this._reqCounter}`;
+  }
+
+  _onMessage(raw) {
+    let frame;
+    try {
+      frame = JSON.parse(raw.toString());
+    } catch {
+      return;
+    }
+
+    const reqId = frame.req_id;
+    if (reqId && this._pending.has(reqId)) {
+      const { resolve, reject } = this._pending.get(reqId);
+      this._pending.delete(reqId);
+      if (frame.type === "error") {
+        reject(new Error(`server error [${frame.code}]: ${frame.message}`));
+      } else {
+        resolve(frame);
+      }
+      return;
+    }
+
+    if (frame.type === "deliver") {
+      const queue = frame.queue || "";
+      if (this._deliverQueues.has(queue)) {
+        const { resolve } = this._deliverQueues.get(queue).shift() || {};
+        if (resolve) {
+          resolve({
+            queue,
+            id: frame.id,
+            payload: frame.payload,
+            priority: frame.priority,
+            createdAt: frame.created_at,
+          });
+        }
+      }
+    }
+  }
+
+  async _request(frame) {
+    const reqId = this._nextReqId();
+    frame.req_id = reqId;
+    return new Promise((resolve, reject) => {
+      this._pending.set(reqId, { resolve, reject });
+      this._ws.send(JSON.stringify(frame), (err) => {
+        if (err) {
+          this._pending.delete(reqId);
+          reject(err);
+        }
+      });
+    });
+  }
+
+  // -------------------------------------------------------------------------
+  // Public API (WS-0019)
+  // -------------------------------------------------------------------------
+
+  /**
+   * Publish a message to a queue.
+   * @param {string} queue
+   * @param {string} payload
+   * @param {number} [priority=0]
+   * @returns {Promise<string>} The assigned message id.
+   */
+  async publish(queue, payload, priority = 0) {
+    const resp = await this._request({
+      type: "publish",
+      queue,
+      payload,
+      priority,
+    });
+    return resp.id;
+  }
+
+  /**
+   * Subscribe to a queue.
+   * Returns an AsyncIterable that yields DeliveredMessage objects.
+   * @param {string} queue
+   * @returns {AsyncIterable<DeliveredMessage>}
+   */
+  subscribe(queue) {
+    // Ensure delivery queue exists.
+    if (!this._deliverQueues.has(queue)) {
+      this._deliverQueues.set(queue, []);
+    }
+    // Send subscribe frame (fire-and-forget; ok response is consumed internally).
+    this._request({ type: "subscribe", queue }).catch(() => {});
+
+    const self = this;
+    return {
+      [Symbol.asyncIterator]() {
+        return {
+          next() {
+            return new Promise((resolve, reject) => {
+              const waiters = self._deliverQueues.get(queue) || [];
+              waiters.push({
+                resolve: (msg) => resolve({ value: msg, done: false }),
+                reject,
+              });
+              if (!self._deliverQueues.has(queue)) {
+                self._deliverQueues.set(queue, waiters);
+              }
+            });
+          },
+          return() {
+            return Promise.resolve({ value: undefined, done: true });
+          },
+        };
+      },
+    };
+  }
+
+  /**
+   * Unsubscribe from a queue.
+   * @param {string} queue
+   * @returns {Promise<void>}
+   */
+  async unsubscribe(queue) {
+    await this._request({ type: "unsubscribe", queue });
+    this._deliverQueues.delete(queue);
+  }
+
+  /**
+   * Acknowledge a message.
+   * @param {string} queue
+   * @param {string} id
+   * @returns {Promise<void>}
+   */
+  async ack(queue, id) {
+    await this._request({ type: "ack", queue, id });
+  }
+
+  /**
+   * Negative-acknowledge a message.
+   * @param {string} queue
+   * @param {string} id
+   * @returns {Promise<void>}
+   */
+  async nack(queue, id) {
+    await this._request({ type: "nack", queue, id });
+  }
+
+  /**
+   * Batch-acknowledge multiple messages.
+   * @param {string} queue
+   * @param {string[]} ids
+   * @returns {Promise<number>} Count of acked messages.
+   */
+  async batchAck(queue, ids) {
+    const resp = await this._request({ type: "batch-ack", queue, ids });
+    return resp.acked;
+  }
+
+  /**
+   * Batch-negative-acknowledge multiple messages.
+   * @param {string} queue
+   * @param {string[]} ids
+   * @returns {Promise<{unlocked: number, dropped: number}>}
+   */
+  async batchNack(queue, ids) {
+    const resp = await this._request({ type: "batch-nack", queue, ids });
+    return { unlocked: resp.unlocked, dropped: resp.dropped };
+  }
+}
+
+module.exports = { QrustyClient, WsSession };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qrusty-client",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Node.js client for the qrusty priority queue server API.",
   "main": "index.js",
   "author": "Gordon Greene <greeng3@obscure-reference.com>",
@@ -10,7 +10,7 @@
     "docs": "jsdoc -c jsdoc.json"
   },
   "dependencies": {
-    "axios": "^1.13.2"
+    "axios": "^1.13.5"
   },
   "devDependencies": {
     "jest": "30.2.0",