@usermetrics/queuebit 1.0.6 → 1.0.8

package/README.md

@@ -1,8 +1,11 @@
 # QueueBit
 
 A high performance socket-based message queue server with guaranteed delivery, compatible with NATS queue patterns.  
+
 Built-in Load Balancer with round-robin delivery. (see examples).  
 
+If you need a pubsub between client and server, or server to server, this is a good choice.
+
 It can run in-process in an existing Node.js app, separately as a standalone server, or run clients 
 in the backend and/or frontend.
 A frontend in examples (qpanel.html) can help test the server.
@@ -33,13 +36,27 @@ npm install @usermetrics/queuebit
 
 ## Quick Start
 
-### Start the Server
+### Start the Server in-process with a node app
+#### QueueBit runs with the main app. This can reduce costs for simple apps running the cloud.
 
 ```javascript
 const { QueueBitServer } = require('./src/server');
 const server = new QueueBitServer({ port: 3333 });
 ```
 
+### Start the Server with monitoring
+```javascript
+const { QueueBitServer } = require('../../src/server');
+const PORT = 3333;
+new QueueBitServer({ port: PORT, 
+    monitorInterval: 1000, 
+    monitorCallback: (data) => {
+    console.log(data);
+} });
+```
+
+### Start the Server as a standalone process
+#### The server runs standalone
 On Windows:
 ```cmd
 start_server.cmd
@@ -93,6 +110,9 @@ setTimeout(async () => {
 
 See [`examples/inprocessserver.js`](./examples/inprocessserver.js) for a full example.
 
+## Testing Control Panel
+![QueueBit Control Panel](./docs/screen.jpg)
+
 ## API Overview
 
 ### Server Options

package/examples/{server2server.js → client/server2server.js}

@@ -5,7 +5,7 @@
  * run the server with /start_server.cmd and then run this example with /examples/start_node_client.cmd
  */
 const http = require('http');
-const { QueueBitClient } = require('../src/client-node');
+const { QueueBitClient } = require('../../src/client-node');
 
 const webserverPORT = 3000;
 const queuebitPORT = 3333;

package/examples/client/start.cmd

@@ -0,0 +1,2 @@
+echo Ensure QueueBit server is running on port 3333 before starting this client.
+node ./server2server.js

package/examples/{inprocessserver.js → inprocess/inprocessserver.js}

@@ -1,13 +1,16 @@
 /**
  * In-process QueueBit demo.
  * Starts the QueueBit server and an HTTP server in the same process.
- * Use the qpanel.html dashboard to publish messages to the queue and see them received by the HTTP server.
+ * Use the qpanel.html dashboard (run with live server in vscode) to publish messages to the queue
+ * and see them received by the HTTP server.
  * Run this example with /examples/start_node_inprocess.cmd
  * No need to run a separate QueueBit server.
+ * Pros: Simple setup, good for testing and demos. Lower costs since only one process is running.
+ * Cons: If the process crashes, both the queue server and HTTP server go down.
  */
 const http = require('http');
-const { QueueBitServer } = require('../src/server');
-const { QueueBitClient } = require('../src/client-node');
+const { QueueBitServer } = require('../../src/server');
+const { QueueBitClient } = require('../../src/client-node');
 
 const webserverPORT = 3000;
 const queuebitPORT = 3333;

package/examples/inprocess/start.cmd

@@ -0,0 +1 @@
+node inprocessserver.js

package/examples/{loadbalancer.js → loadbalancer/loadbalancer.js}

@@ -3,15 +3,15 @@
  * Messages are distributed round-robin across workers in the same load balancer.
  * Only ONE worker receives each message (unlike regular subscribe where ALL receive).
  * 
+ * Flow: Server Receives Message | Server sends to next worker in line for that load balancer id 
+ * Each client is given a loadbalancer id (e.g. 'workers'). 
+ * The server keeps track of which client is next in line for each loadbalancer id. 
  * Run this example with: node examples/queuegroup.js
  */
-const { QueueBitServer } = require('../src/server');
-const { QueueBitClient } = require('../src/client-node');
 
-const PORT = 3333;
+const { QueueBitClient } = require('../../src/client-node');
 
-// Start QueueBit server in-process
-new QueueBitServer({ port: PORT });
+const PORT = 3333;
 
 async function sleep(ms) { return new Promise(r => setTimeout(r, ms)); }
 
@@ -45,7 +45,7 @@ async function main() {
 
   for (let i = 1; i <= 6; i++) {
     await publisher.publish({ job: `task-${i}`, payload: `data-${i}` }, { subject: 'jobs' });
-    await sleep(100);
+    await sleep(1000);
   }
 
   await sleep(500);

package/examples/loadbalancer/server.js

@@ -0,0 +1,10 @@
+// simple server wrapper
+// you can start the server with node src/server-runner.js or create your own wrapper like this:
+const { QueueBitServer } = require('../../src/server');
+const PORT = 3333;
+new QueueBitServer({ port: PORT, 
+    monitorInterval: 1000, 
+    monitorCallback: (data) => {
+    console.log(data);
+} });
+console.log(`QueueBit server running on port ${PORT}`);

package/examples/loadbalancer/start.cmd

@@ -0,0 +1,5 @@
+echo start in command prompt (not bash) to open new terminals for each process
+start node server.js
+start node loadbalancer.js
+start node loadbalancer.js
+start node loadbalancer.js

package/examples/logger/logger.js

@@ -0,0 +1,19 @@
+/**
+ * Server to server queue.
+ * This adds queue functionality to a simple http server (the queue server is running elsewhere)
+ * Use the qpanel.html dashboard to publish messages to the queue and see them received by the HTTP server.
+ * run the server with /start_server.cmd and then run this example with /examples/start_node_client.cmd
+ */
+
+const { QueueBitClient } = require('../../src/client-node');
+
+
+const queuebitPORT = 3333;
+
+// Initialize a queuebit message queue. It will connect to the server running on port 3333
+const messageQueue = new QueueBitClient(`http://localhost:${queuebitPORT}`);
+
+messageQueue.subscribe((msg) => {
+  console.log('Received message from queue:', msg);
+}, { subject: 'default' });
+

package/examples/logger/start.cmd

@@ -0,0 +1,3 @@
+echo Ensure QueueBit server is running on port 3333 before starting this client.
+echo logs all messages to the default queue
+node ./logger.js

package/examples/qpanel.html

@@ -115,7 +115,7 @@
             <input type="text" id="subject" placeholder="Subject" class="small">
             <br>
             <button onclick="publishMessage()">Publish</button>
-            <button onclick="publishEphemeral()">Ephemeral</button>
+            <button onclick="publishEphemeral()">Ephemeral (deliver and delete)</button>
         </div>
     </div>
 

package/examples/standalone/server.js

@@ -0,0 +1,11 @@
+// simple server wrapper
+// you can start the server with node src/server-runner.js or create your own wrapper like this:
+// specify monitorInterval to enable server monitoring (logs memory usage and event loop lag every interval ms)
+const { QueueBitServer } = require('../../src/server');
+const PORT = 3333;
+new QueueBitServer({ port: PORT, 
+    monitorInterval: 1000, 
+    monitorCallback: (data) => {
+    console.log(data);
+} });
+console.log(`QueueBit server running on port ${PORT}`);

package/examples/standalone/start.cmd

@@ -0,0 +1 @@
+node server.js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usermetrics/queuebit",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "publishConfig": {
     "access": "public"
   },

package/src/server.js

@@ -7,6 +7,8 @@ class QueueBitServer {
     const port = options.port || 3000;
     this.maxQueueSize = options.maxQueueSize || 10000;
     this.version = packageJson.version;
+    this.monitorInterval = options.monitorInterval || null;
+    this.monitorCallback = options.monitorCallback || null;
     
     this.messages = new Map();
     this.subscribers = new Map();
@@ -33,6 +35,9 @@ class QueueBitServer {
     this.setupHandlers();
     this.startExpiryCheck();
     this.startDeliveryProcessor();
+    if (this.monitorInterval) {
+      this.startMonitor(this.monitorInterval);
+    }
     
     console.log(`QueueBit server v${this.version} listening on port ${port}`);
   }
@@ -296,6 +301,44 @@ class QueueBitServer {
     }, 1000); // Check every second
   }
 
+  startMonitor(interval = 5000) {
+    setInterval(() => {
+      const stats = {
+        timestamp: new Date().toISOString(),
+        deliveryQueuePending: this.deliveryQueue.length,
+        subjects: {},
+        totalMessages: 0,
+        totalSubscribers: 0,
+        totalLBWorkers: 0,
+        loadBalancers: {}
+      };
+
+      for (const [subject, queue] of this.messages.entries()) {
+        stats.subjects[subject] = stats.subjects[subject] || {};
+        stats.subjects[subject].messages = queue.length;
+        stats.totalMessages += queue.length;
+      }
+
+      for (const [subject, subs] of this.subscribers.entries()) {
+        stats.subjects[subject] = stats.subjects[subject] || {};
+        stats.subjects[subject].subscribers = subs.size;
+        stats.totalSubscribers += subs.size;
+      }
+
+      for (const [subject, lbs] of this.loadBalancers.entries()) {
+        for (const [lbName, lb] of lbs.entries()) {
+          const key = `${subject} | ${lbName}`;
+          stats.loadBalancers[key] = lb.sockets.length;
+          stats.totalLBWorkers += lb.sockets.length;          
+        }
+      }
+
+      if (this.monitorCallback) {
+        this.monitorCallback(stats);
+      }
+    }, interval);
+  }
+
   close() {
     this.io.close();
   }

package/examples/start_load_balancer.cmd

@@ -1 +0,0 @@
-node ./loadbalancer.js

package/examples/start_node_client.cmd

@@ -1 +0,0 @@
-node ./server2server.js

package/examples/start_node_inprocess.cmd

@@ -1 +0,0 @@
-call node inprocessserver.js