queen-mq 0.1.0 → 0.1.2

package/examples/test-complete-client.js

@@ -0,0 +1,260 @@
+#!/usr/bin/env node
+
+/**
+ * Complete test of the minimalist Queen client
+ * Shows all features including namespace/task and message properties
+ */
+
+import { Queen } from '../src/client/client.js';
+
+async function main() {
+  console.log('🧪 Testing Complete Minimalist Queen Client Features\n');
+  
+  const client = new Queen({
+    baseUrls: ['http://localhost:6632'],
+    timeout: 30000
+  });
+  
+  try {
+    // ============================================
+    // 1. Queue Configuration with Namespace/Task
+    // ============================================
+    console.log('1️⃣ Configuring queues with namespace and task...');
+    
+    // Configure queue with namespace and task
+    await client.queue('orders-processing', {
+      leaseTime: 300,
+      retryLimit: 3,
+      priority: 10
+    }, {
+      namespace: 'ecommerce',
+      task: 'process'
+    });
+    
+    await client.queue('inventory-updates', {
+      leaseTime: 300,
+      priority: 5
+    }, {
+      namespace: 'ecommerce',
+      task: 'update'
+    });
+    
+    await client.queue('notifications', {
+      priority: 8
+    }, {
+      namespace: 'ecommerce',
+      task: 'notify'
+    });
+    
+    console.log('✅ Queues configured with namespace/task metadata\n');
+    
+    // ============================================
+    // 2. Push with Message Properties
+    // ============================================
+    console.log('2️⃣ Pushing messages with properties...');
+    
+    // Method 1: Properties in options
+    await client.push('orders-processing', {
+      orderId: 123,
+      amount: 99.99
+    }, {
+      transactionId: 'txn-123'
+    });
+    
+    // Method 2: Properties in the message object
+    await client.push('orders-processing', {
+      orderId: 124,
+      amount: 199.99,
+      transactionId: 'txn-124'  // Will be extracted
+    });
+    
+    // Method 3: Batch with mixed properties
+    await client.push('inventory-updates', [
+      {
+        sku: 'PROD-001',
+        quantity: 5,
+        transactionId: 'inv-001'
+      },
+      {
+        sku: 'PROD-002',
+        quantity: 10,
+        transactionId: 'inv-002'
+      }
+    ]);
+    
+    // Method 4: Using special properties format
+    await client.push('notifications', {
+      _payload: { userId: 789, message: 'Order shipped' },
+      _transactionId: 'notif-001'
+    });
+    
+    console.log('✅ Messages pushed with various property patterns\n');
+    
+    // ============================================
+    // 3. Take by Queue/Partition
+    // ============================================
+    console.log('3️⃣ Taking messages by queue/partition...');
+    
+    // Take from specific queue
+    let count = 0;
+    for await (const msg of client.take('orders-processing', { limit: 2 })) {
+      count++;
+      console.log(`  📩 Order ${count}:`, msg.data);
+      console.log(`     Transaction ID: ${msg.transactionId}`);
+      await client.ack(msg);
+    }
+    console.log('✅ Processed orders\n');
+    
+    // ============================================
+    // 4. Take by Namespace/Task
+    // ============================================
+    console.log('4️⃣ Taking messages by namespace/task...');
+    
+    // Take all messages from ecommerce namespace
+    count = 0;
+    for await (const msg of client.take('namespace:ecommerce', { limit: 2 })) {
+      count++;
+      console.log(`  📦 Namespace message ${count} from ${msg.queue}:`, msg.data);
+      await client.ack(msg);
+    }
+    
+    // Take only 'update' tasks
+    for await (const msg of client.take('task:update', { limit: 2 })) {
+      console.log(`  🔄 Update task from ${msg.queue}:`, msg.data);
+      await client.ack(msg);
+    }
+    
+    // Combine namespace and task
+    for await (const msg of client.take('namespace:ecommerce/task:notify', { limit: 1 })) {
+      console.log(`  🔔 Notification:`, msg.data);
+      await client.ack(msg);
+    }
+    
+    console.log('✅ Processed messages by namespace/task\n');
+    
+    // ============================================
+    // 5. Consumer Groups with Subscription Modes
+    // ============================================
+    console.log('5️⃣ Testing consumer groups with subscription modes...');
+    
+    // Configure events queue first
+    await client.queue('events', {
+      leaseTime: 300,
+      retryLimit: 3
+    });
+    
+    // Push test events
+    await client.push('events', [
+      { event: 'user.signup', userId: 1 },
+      { event: 'user.login', userId: 2 },
+      { event: 'user.purchase', userId: 3 }
+    ]);
+    
+    // Consumer group starting from all messages
+    for await (const event of client.take('events@analytics', { 
+      limit: 1,
+      subscriptionMode: 'all'
+    })) {
+      console.log('  📊 Analytics (all):', event.data);
+      await client.ack(event, true, { group: 'analytics' });
+    }
+    
+    // Consumer group starting from new messages only
+    for await (const event of client.take('events@realtime', { 
+      limit: 1,
+      subscriptionMode: 'new'
+    })) {
+      console.log('  ⚡ Realtime (new only):', event.data);
+      await client.ack(event, true, { group: 'realtime' });
+    }
+    
+    console.log('✅ Consumer groups tested\n');
+    
+    // ============================================
+    // 6. Advanced Patterns
+    // ============================================
+    console.log('6️⃣ Testing advanced patterns...');
+    
+    // Configure tasks queue
+    await client.queue('tasks', {
+      leaseTime: 300,
+      priority: 8
+    });
+    
+    // Pattern 1: Partitioned messages with properties
+    await client.push('tasks/urgent', {
+      taskId: 'TASK-001',
+      priority: 'critical'
+    }, {
+      transactionId: 'task-txn-001'
+    });
+    
+    // Pattern 2: Consumer group on specific partition
+    for await (const task of client.take('tasks/urgent@workers', { limit: 1 })) {
+      console.log('  🚨 Urgent task for worker group:', task.data);
+      await client.ack(task, true, { group: 'workers' });
+    }
+    
+    // Configure logs queue
+    await client.queue('logs', {
+      leaseTime: 300,
+      retentionSeconds: 86400  // Keep for 1 day
+    });
+    
+    // Pattern 3: Batch push with partition
+    await client.push('logs/audit', [
+      { action: 'login', user: 'alice', timestamp: Date.now() },
+      { action: 'update', user: 'bob', timestamp: Date.now() },
+      { action: 'delete', user: 'charlie', timestamp: Date.now() }
+    ]);
+    
+    console.log('✅ Advanced patterns tested\n');
+    
+    // ============================================
+    // 7. Error Handling
+    // ============================================
+    console.log('7️⃣ Testing error handling...');
+    
+    // Configure error-test queue
+    await client.queue('error-test', {
+      leaseTime: 60,
+      retryLimit: 2
+    });
+    
+    // Push a message that will fail processing
+    await client.push('error-test', { 
+      willFail: true,
+      reason: 'Testing failure path'
+    });
+    
+    for await (const msg of client.take('error-test', { limit: 1 })) {
+      try {
+        // Simulate processing error
+        throw new Error('Simulated processing error');
+      } catch (error) {
+        console.log('  ❌ Failed to process:', msg.data);
+        // Acknowledge with failure and error context
+        await client.ack(msg, false, { 
+          error: error.message,
+          retryable: true 
+        });
+      }
+    }
+    
+    console.log('✅ Error handling tested\n');
+    
+    console.log('🎉 All features tested successfully!');
+    
+  } catch (error) {
+    console.error('❌ Test failed:', error.message);
+    process.exit(1);
+  } finally {
+    await client.close();
+  }
+}
+
+// Run tests
+main().catch(error => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});

package/examples/test-dashboard-api.js

@@ -0,0 +1,200 @@
+/**
+ * Test script for the new Dashboard Status API endpoints
+ * 
+ * This script demonstrates all 5 new endpoints:
+ * 1. GET /api/v1/status - Dashboard overview
+ * 2. GET /api/v1/status/queues - List queues with stats
+ * 3. GET /api/v1/status/queues/:queue - Queue detail
+ * 4. GET /api/v1/status/queues/:queue/messages - Queue messages
+ * 5. GET /api/v1/status/analytics - Advanced analytics
+ */
+
+import { createQueenClient } from '../src/client/queenClient.js';
+
+const BASE_URL = process.env.QUEEN_URL || 'http://localhost:3000';
+
+// Create client
+const client = createQueenClient({ baseUrl: BASE_URL });
+
+// Helper to make GET requests
+async function get(path) {
+  const response = await fetch(`${BASE_URL}${path}`, {
+    method: 'GET',
+    headers: {
+      'Content-Type': 'application/json'
+    }
+  });
+  
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`HTTP ${response.status}: ${error}`);
+  }
+  
+  return await response.json();
+}
+
+// Helper to format JSON output
+function printJson(label, data) {
+  console.log(`\n${'='.repeat(80)}`);
+  console.log(`📊 ${label}`);
+  console.log('='.repeat(80));
+  console.log(JSON.stringify(data, null, 2));
+}
+
+async function runTests() {
+  console.log('🚀 Testing Queen Dashboard Status API\n');
+  
+  try {
+    // First, let's create some test data
+    console.log('📝 Setting up test data...');
+    
+    // Configure a test queue
+    await client.configure({
+      queue: 'dashboard-test-queue',
+      namespace: 'test-namespace',
+      task: 'test-task',
+      partitions: 3
+    });
+    
+    // Push some test messages
+    const messages = [];
+    for (let i = 0; i < 20; i++) {
+      messages.push({
+        queue: 'dashboard-test-queue',
+        partition: `partition-${i % 3}`,
+        payload: {
+          messageNumber: i,
+          timestamp: new Date().toISOString(),
+          data: `Test message ${i}`
+        }
+      });
+    }
+    
+    await client.pushBatch(messages);
+    console.log('✅ Created test queue with 20 messages\n');
+    
+    // Wait a bit for messages to be processed
+    await new Promise(resolve => setTimeout(resolve, 1000));
+    
+    // Test 1: Dashboard Status
+    console.log('🧪 Test 1: Dashboard Status (GET /api/v1/status)');
+    const status = await get('/api/v1/status');
+    printJson('Dashboard Status', {
+      timeRange: status.timeRange,
+      queuesCount: status.queues.length,
+      messages: status.messages,
+      leases: status.leases,
+      throughputSamples: status.throughput.length,
+      dlqTotal: status.deadLetterQueue.totalMessages
+    });
+    
+    // Test 2: Queues List
+    console.log('\n🧪 Test 2: List Queues (GET /api/v1/status/queues)');
+    const queues = await get('/api/v1/status/queues?limit=10');
+    printJson('Queues List', {
+      total: queues.pagination.total,
+      queues: queues.queues.map(q => ({
+        name: q.name,
+        namespace: q.namespace,
+        partitions: q.partitions,
+        pending: q.messages.pending,
+        completed: q.messages.completed
+      }))
+    });
+    
+    // Test 3: Queue Detail
+    console.log('\n🧪 Test 3: Queue Detail (GET /api/v1/status/queues/:queue)');
+    const queueDetail = await get('/api/v1/status/queues/dashboard-test-queue');
+    printJson('Queue Detail', {
+      queue: queueDetail.queue,
+      totals: queueDetail.totals,
+      partitionCount: queueDetail.partitions.length,
+      partitions: queueDetail.partitions.map(p => ({
+        name: p.name,
+        messages: p.messages,
+        cursor: p.cursor
+      }))
+    });
+    
+    // Test 4: Queue Messages
+    console.log('\n🧪 Test 4: Queue Messages (GET /api/v1/status/queues/:queue/messages)');
+    const messages_result = await get('/api/v1/status/queues/dashboard-test-queue/messages?limit=5');
+    printJson('Queue Messages', {
+      total: messages_result.pagination.total,
+      showing: messages_result.messages.length,
+      messages: messages_result.messages.map(m => ({
+        transactionId: m.transactionId,
+        partition: m.partition,
+        status: m.status,
+        createdAt: m.createdAt
+      }))
+    });
+    
+    // Test 5: Filter by status
+    console.log('\n🧪 Test 5: Filter Messages by Status (GET /api/v1/status/queues/:queue/messages?status=pending)');
+    const pendingMessages = await get('/api/v1/status/queues/dashboard-test-queue/messages?status=pending&limit=5');
+    printJson('Pending Messages', {
+      total: pendingMessages.pagination.total,
+      messages: pendingMessages.messages.map(m => ({
+        transactionId: m.transactionId,
+        status: m.status,
+        age: m.age
+      }))
+    });
+    
+    // Test 6: Analytics (last hour with minute interval)
+    console.log('\n🧪 Test 6: Analytics (GET /api/v1/status/analytics?interval=minute)');
+    const analytics = await get('/api/v1/status/analytics?interval=minute');
+    printJson('Analytics Overview', {
+      timeRange: analytics.timeRange,
+      throughput: {
+        totals: analytics.throughput.totals,
+        recentSamples: analytics.throughput.timeSeries.slice(0, 3)
+      },
+      latency: analytics.latency.overall,
+      errorRates: analytics.errorRates.overall,
+      currentDepth: analytics.queueDepths.current,
+      topQueues: analytics.topQueues.slice(0, 3),
+      dlqTotal: analytics.deadLetterQueue.total
+    });
+    
+    // Test 7: Filter by namespace
+    console.log('\n🧪 Test 7: Dashboard Status filtered by namespace (GET /api/v1/status?namespace=test-namespace)');
+    const statusFiltered = await get('/api/v1/status?namespace=test-namespace');
+    printJson('Filtered Status', {
+      queuesCount: statusFiltered.queues.length,
+      queues: statusFiltered.queues.map(q => q.name),
+      messages: statusFiltered.messages
+    });
+    
+    // Test 8: Analytics with time range
+    console.log('\n🧪 Test 8: Analytics with custom time range (last 30 minutes)');
+    const thirtyMinutesAgo = new Date(Date.now() - 30 * 60 * 1000).toISOString();
+    const now = new Date().toISOString();
+    const analyticsTimeRange = await get(`/api/v1/status/analytics?from=${thirtyMinutesAgo}&to=${now}&interval=minute`);
+    printJson('Analytics (Last 30 min)', {
+      timeRange: analyticsTimeRange.timeRange,
+      throughputSamples: analyticsTimeRange.throughput.timeSeries.length,
+      totals: analyticsTimeRange.throughput.totals
+    });
+    
+    console.log('\n' + '='.repeat(80));
+    console.log('✅ All tests completed successfully!');
+    console.log('='.repeat(80));
+    
+  } catch (error) {
+    console.error('\n❌ Test failed:', error.message);
+    console.error(error.stack);
+    process.exit(1);
+  }
+}
+
+// Run tests
+runTests().then(() => {
+  console.log('\n✨ Dashboard API test complete!');
+  process.exit(0);
+}).catch(error => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});
+

package/examples/test-traceid.js

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+
+/**
+ * Test client-provided traceId functionality
+ */
+
+import { Queen } from '../src/client/client.js';
+import crypto from 'crypto';
+
+// Helper to generate a valid UUID v4
+function generateUUID() {
+  return crypto.randomUUID();
+}
+
+async function main() {
+  console.log('🧪 Testing Client-Provided TraceId\n');
+  
+  const client = new Queen({
+    baseUrls: ['http://localhost:6632'],
+    timeout: 30000
+  });
+  
+  try {
+    // Configure test queue
+    await client.queue('trace-test', {
+      leaseTime: 300,
+      retryLimit: 3
+    });
+    
+    // Test 1: Push with valid UUID traceId
+    console.log('1️⃣ Testing valid UUID traceId...');
+    const validTraceId = generateUUID();
+    console.log(`   Generated UUID: ${validTraceId}`);
+    
+    await client.push('trace-test', {
+      message: 'Test with valid traceId'
+    }, {
+      transactionId: 'txn-001',
+      traceId: validTraceId
+    });
+    console.log('✅ Message pushed with valid traceId\n');
+    
+    // Test 2: Push with invalid traceId (should be ignored)
+    console.log('2️⃣ Testing invalid traceId (should be ignored)...');
+    const invalidTraceId = 'not-a-valid-uuid';
+    console.log(`   Invalid traceId: ${invalidTraceId}`);
+    
+    await client.push('trace-test', {
+      message: 'Test with invalid traceId'
+    }, {
+      transactionId: 'txn-002',
+      traceId: invalidTraceId  // Will be ignored, server will generate one
+    });
+    console.log('✅ Message pushed (invalid traceId ignored)\n');
+    
+    // Test 3: Push without traceId (server generates)
+    console.log('3️⃣ Testing without traceId (server generates)...');
+    await client.push('trace-test', {
+      message: 'Test without traceId'
+    }, {
+      transactionId: 'txn-003'
+    });
+    console.log('✅ Message pushed (server generated traceId)\n');
+    
+    // Test 4: Using special properties format
+    console.log('4️⃣ Testing special properties format...');
+    const anotherValidTraceId = generateUUID();
+    
+    await client.push('trace-test', {
+      _payload: { message: 'Special format test' },
+      _transactionId: 'txn-004',
+      _traceId: anotherValidTraceId
+    });
+    console.log('✅ Message pushed with special format\n');
+    
+    // Test 5: Batch with mixed traceIds
+    console.log('5️⃣ Testing batch with mixed traceIds...');
+    const batchTraceId1 = generateUUID();
+    const batchTraceId2 = generateUUID();
+    
+    await client.push('trace-test', [
+      {
+        message: 'Batch message 1',
+        transactionId: 'batch-001',
+        traceId: batchTraceId1  // Valid UUID
+      },
+      {
+        message: 'Batch message 2',
+        transactionId: 'batch-002',
+        traceId: 'invalid-trace'  // Invalid, will be ignored
+      },
+      {
+        message: 'Batch message 3',
+        transactionId: 'batch-003'
+        // No traceId, server will generate
+      }
+    ]);
+    console.log('✅ Batch pushed with mixed traceId scenarios\n');
+    
+    // Retrieve and display messages
+    console.log('📥 Retrieving messages to verify traceIds...\n');
+    let count = 0;
+    for await (const msg of client.take('trace-test', { limit: 7 })) {
+      count++;
+      console.log(`Message ${count}:`);
+      console.log(`  Transaction ID: ${msg.transactionId}`);
+      console.log(`  Trace ID: ${msg.traceId}`);
+      console.log(`  Data: ${JSON.stringify(msg.data)}`);
+      
+      // Check if our valid traceIds were preserved
+      if (msg.transactionId === 'txn-001') {
+        if (msg.traceId === validTraceId) {
+          console.log('  ✅ Client-provided traceId was preserved!');
+        } else {
+          console.log('  ❌ Client-provided traceId was not preserved');
+        }
+      }
+      
+      if (msg.transactionId === 'txn-002') {
+        if (msg.traceId !== invalidTraceId) {
+          console.log('  ✅ Invalid traceId was correctly replaced');
+        }
+      }
+      
+      await client.ack(msg);
+      console.log('');
+    }
+    
+    console.log('🎉 TraceId test completed successfully!');
+    console.log('\nSummary:');
+    console.log('- Valid UUID traceIds are accepted and preserved');
+    console.log('- Invalid traceIds are ignored (server generates new ones)');
+    console.log('- Missing traceIds are auto-generated by server');
+    
+  } catch (error) {
+    console.error('❌ Test failed:', error.message);
+    process.exit(1);
+  } finally {
+    await client.close();
+  }
+}
+
+// Run test
+main().catch(error => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "queen-mq",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "description": "High-performance message queue backed by PostgreSQL",
   "main": "src/client/index.js",
-
   "scripts": {
     "start": "node src/server.js",
+    "start:cluster": "node src/cluster-server.js",
     "test:produce": "node test.js produce",
     "test:consume": "node test.js consume",
     "test": "node src/test/test.js",
@@ -23,6 +23,8 @@
     "init": "node init-db.js"
   },
   "dependencies": {
+    "axios": "^1.12.2",
+    "chart.js": "^4.5.1",
     "pg": "^8.13.3",
     "uuid": "^13.0.0",
     "uWebSockets.js": "github:uNetworking/uWebSockets.js#v20.52.0",
@@ -31,6 +33,17 @@
   "engines": {
     "node": ">=22.0.0"
   },
-  "author": "",
-  "license": "ISC"
+  "author": "Smartness",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/smartpricing/queen"
+  },
+  "keywords": [
+    "message-queue",
+    "queue",
+    "broker",
+    "message-queue-system",
+    "fifo"
+  ]
 }

package/server.log

@@ -0,0 +1 @@
+zsh: command not found: node