queen-mq 0.1.0 → 0.1.1

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-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,6 +1,6 @@
 {
   "name": "queen-mq",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "description": "High-performance message queue backed by PostgreSQL",
   "main": "src/client/index.js",
@@ -31,6 +31,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/src/client/client.js

@@ -55,6 +55,14 @@ export class Queen {
     this.#connected = true;
   }
   
+  /**
+   * Validate if a string is a valid UUID v4
+   */
+  #isValidUUID(str) {
+    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+    return uuidRegex.test(str);
+  }
+  
   /**
    * Parse address string into components
    * Examples:
@@ -62,9 +70,37 @@ export class Queen {
    * - "myqueue/urgent" -> { queue: "myqueue", partition: "urgent" }
    * - "myqueue@workers" -> { queue: "myqueue", consumerGroup: "workers" }
    * - "myqueue/urgent@workers" -> { queue: "myqueue", partition: "urgent", consumerGroup: "workers" }
+   * - "namespace:billing" -> { namespace: "billing" }
+   * - "task:process" -> { task: "process" }
+   * - "namespace:billing/task:process" -> { namespace: "billing", task: "process" }
    */
   #parseAddress(address) {
-    // Match: queue[/partition][@group]
+    // Check for namespace/task pattern
+    if (address.includes('namespace:') || address.includes('task:')) {
+      const parts = {};
+      
+      // Extract consumer group if present (after @)
+      let workingAddress = address;
+      const atIndex = address.lastIndexOf('@');
+      if (atIndex > 0) {
+        parts.consumerGroup = address.substring(atIndex + 1);
+        workingAddress = address.substring(0, atIndex);
+      }
+      
+      const segments = workingAddress.split('/');
+      
+      for (const segment of segments) {
+        if (segment.startsWith('namespace:')) {
+          parts.namespace = segment.substring(10);
+        } else if (segment.startsWith('task:')) {
+          parts.task = segment.substring(5);
+        }
+      }
+      
+      return parts;
+    }
+    
+    // Standard queue[/partition][@group] pattern
     const match = address.match(/^([^/@]+)(?:\/([^@]+))?(?:@(.+))?$/);
     if (!match) {
       throw new Error(`Invalid address format: ${address}`);
@@ -81,13 +117,18 @@ export class Queen {
    * Configure a queue with options
    * @param {string} name - Queue name
    * @param {Object} options - Queue configuration options
+   * @param {Object} metadata - Optional metadata { namespace, task }
    */
-  async queue(name, options = {}) {
+  async queue(name, options = {}, metadata = {}) {
     await this.#ensureConnected();
     
+    const { namespace, task } = metadata;
+    
     const result = await withRetry(
       () => this.#http.post('/api/v1/configure', { 
         queue: name,
+        namespace: namespace || null,
+        task: task || null,
         options 
       }),
       this.#config.retryAttempts,
@@ -105,8 +146,9 @@ export class Queen {
    * Push messages to a queue
    * @param {string} address - Queue address (e.g., "myqueue" or "myqueue/partition")
    * @param {Object|Array} payload - Single message or array of messages
+   * @param {Object} options - Optional message properties { transactionId, traceId }
    */
-  async push(address, payload) {
+  async push(address, payload, options = {}) {
     await this.#ensureConnected();
     
     const { queue, partition } = this.#parseAddress(address);
@@ -115,12 +157,44 @@ export class Queen {
     const items = Array.isArray(payload) ? payload : [payload];
     
     // Format items for the API
-    const formattedItems = items.map(item => ({
-      queue,
-      partition,
-      payload: item,
-      transactionId: item.transactionId // Optional, for idempotency
-    }));
+    const formattedItems = items.map(item => {
+      // If item is an object with special properties, extract them
+      const isMessageObject = typeof item === 'object' && item !== null &&
+        (item._payload || item._transactionId || item._traceId);
+      
+      if (isMessageObject) {
+        const result = {
+          queue,
+          partition,
+          payload: item._payload || item,
+          transactionId: item._transactionId || item.transactionId
+        };
+        
+        // Include traceId if provided and valid UUID
+        const traceId = item._traceId || item.traceId;
+        if (traceId && this.#isValidUUID(traceId)) {
+          result.traceId = traceId;
+        }
+        
+        return result;
+      }
+      
+      // Otherwise use the item as payload and apply options
+      const result = {
+        queue,
+        partition,
+        payload: item,
+        transactionId: options.transactionId || (item && typeof item === 'object' ? item.transactionId : undefined)
+      };
+      
+      // Include traceId if provided and valid UUID
+      const traceId = options.traceId || (item && typeof item === 'object' ? item.traceId : undefined);
+      if (traceId && this.#isValidUUID(traceId)) {
+        result.traceId = traceId;
+      }
+      
+      return result;
+    });
     
     const result = await withRetry(
       () => this.#http.post('/api/v1/push', { 
@@ -146,7 +220,7 @@ export class Queen {
   async *take(address, options = {}) {
     await this.#ensureConnected();
     
-    const { queue, partition, consumerGroup } = this.#parseAddress(address);
+    const { queue, partition, consumerGroup, namespace, task } = this.#parseAddress(address);
     const { 
       limit = null,
       batch = 1, 
@@ -178,10 +252,19 @@ export class Queen {
       if (subscriptionFrom) params.append('subscriptionFrom', subscriptionFrom);
       
       // Determine the endpoint based on parameters
-      if (partition && partition !== 'Default') {
-        path = `/api/v1/pop/queue/${queue}/partition/${partition}`;
+      if (queue) {
+        if (partition && partition !== 'Default') {
+          path = `/api/v1/pop/queue/${queue}/partition/${partition}`;
+        } else {
+          path = `/api/v1/pop/queue/${queue}`;
+        }
+      } else if (namespace || task) {
+        // Pop by namespace/task
+        path = '/api/v1/pop';
+        if (namespace) params.append('namespace', namespace);
+        if (task) params.append('task', task);
       } else {
-        path = `/api/v1/pop/queue/${queue}`;
+        throw new Error('Must specify either queue, namespace, or task');
       }
       
       try {
@@ -210,11 +293,13 @@ export class Queen {
         // Reset empty counter on successful fetch
         consecutiveEmptyResponses = 0;
         
-        // Yield each message
+        // Yield each message (filter out any null/undefined values)
         for (const message of result.messages) {
-          yield message;
-          count++;
-          if (limit && count >= limit) return;
+          if (message) { // Skip null/undefined messages
+            yield message;
+            count++;
+            if (limit && count >= limit) return;
+          }
         }
         
       } catch (error) {
@@ -244,9 +329,17 @@ export class Queen {
     await this.#ensureConnected();
     
     // Extract transaction ID
-    const transactionId = typeof message === 'object' ? 
-      (message.transactionId || message.id) : 
-      message;
+    let transactionId;
+    if (typeof message === 'string') {
+      transactionId = message;
+    } else if (typeof message === 'object' && message !== null) {
+      transactionId = message.transactionId || message.id;
+      if (!transactionId) {
+        throw new Error('Message object must have transactionId or id property');
+      }
+    } else {
+      throw new Error('Message must be a string (transaction ID) or object with transactionId');
+    }
     
     // Determine status string
     let statusStr;