queen-mq 0.2.22 → 0.3.0

package/client-js/client-v2/http/LoadBalancer.js

@@ -0,0 +1,50 @@
+/**
+ * Load balancer for distributing requests across multiple servers
+ */
+
+export class LoadBalancer {
+  #urls
+  #strategy
+  #currentIndex = 0
+  #sessionMap = new Map()
+  #sessionId
+
+  constructor(urls, strategy = 'round-robin') {
+    this.#urls = urls.map(url => url.replace(/\/$/, '')) // Remove trailing slashes
+    this.#strategy = strategy
+    this.#sessionId = `session_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`
+  }
+
+  getNextUrl(sessionKey = null) {
+    const key = sessionKey || this.#sessionId
+
+    if (this.#strategy === 'session') {
+      // Session affinity: stick to the same server per session
+      if (!this.#sessionMap.has(key)) {
+        const assignedIndex = this.#currentIndex
+        this.#sessionMap.set(key, assignedIndex)
+        this.#currentIndex = (this.#currentIndex + 1) % this.#urls.length
+      }
+      return this.#urls[this.#sessionMap.get(key)]
+    }
+
+    // Round robin: cycle through URLs
+    const url = this.#urls[this.#currentIndex]
+    this.#currentIndex = (this.#currentIndex + 1) % this.#urls.length
+    return url
+  }
+
+  getAllUrls() {
+    return [...this.#urls]
+  }
+
+  getStrategy() {
+    return this.#strategy
+  }
+
+  reset() {
+    this.#currentIndex = 0
+    this.#sessionMap.clear()
+  }
+}
+

package/client-js/client-v2/index.js

@@ -0,0 +1,7 @@
+/**
+ * Queen Message Queue Client - Entry Point
+ */
+
+export { Queen } from './Queen.js'
+export { CLIENT_DEFAULTS, QUEUE_DEFAULTS, CONSUME_DEFAULTS, POP_DEFAULTS, BUFFER_DEFAULTS } from './utils/defaults.js'
+

package/client-js/client-v2/utils/defaults.js

@@ -0,0 +1,54 @@
+/**
+ * Default configuration values for Queen Client
+ * Following the convention:
+ * - Properties with "Millis" suffix → milliseconds
+ * - Properties with "Seconds" suffix → seconds  
+ * - Properties without suffix (time-related) → seconds
+ */
+
+export const CLIENT_DEFAULTS = {
+  timeoutMillis: 30000,                // 30 seconds
+  retryAttempts: 3,                    // 3 retry attempts
+  retryDelayMillis: 1000,              // 1 second initial delay (exponential backoff)
+  loadBalancingStrategy: 'round-robin', // 'round-robin' or 'session'
+  enableFailover: true                 // Auto-failover to other servers
+}
+
+export const QUEUE_DEFAULTS = {
+  leaseTime: 300,                      // 5 minutes (seconds)
+  retryLimit: 3,                       // Max 3 retries before DLQ
+  priority: 0,                         // Default priority
+  delayedProcessing: 0,                // No delay (seconds)
+  windowBuffer: 0,                     // No window buffering (seconds)
+  maxSize: 0,                         // No limit on messages per queue
+  retentionSeconds: 0,                 // No retention (keep forever)
+  completedRetentionSeconds: 0,        // No retention for completed messages
+  encryptionEnabled: false             // No encryption by default
+}
+
+export const CONSUME_DEFAULTS = {
+  concurrency: 1,                      // Single worker
+  batch: 1,                            // One message at a time
+  autoAck: true,                       // Client-side auto-ack (NOT sent to server)
+  wait: true,                          // Long polling enabled
+  timeoutMillis: 30000,                // 30 seconds long poll timeout
+  limit: null,                         // No limit (run forever)
+  idleMillis: null,                    // No idle timeout
+  renewLease: false,                   // No auto-renewal
+  renewLeaseIntervalMillis: null,      // Auto-renewal interval when enabled
+  subscriptionMode: null,              // No subscription mode (standard queue mode)
+  subscriptionFrom: null               // No subscription start point
+}
+
+export const POP_DEFAULTS = {
+  batch: 1,                            // One message
+  wait: false,                         // No long polling (immediate return)
+  timeoutMillis: 30000,                // 30 seconds if wait=true
+  autoAck: false                       // Server-side auto-ack (false = manual ack required)
+}
+
+export const BUFFER_DEFAULTS = {
+  messageCount: 100,                   // Flush after 100 messages
+  timeMillis: 1000                     // Or flush after 1 second
+}
+

package/client-js/client-v2/utils/logger.js

@@ -0,0 +1,54 @@
+/**
+ * Logger utility for Queen Client v2
+ * Controlled by QUEEN_CLIENT_LOG environment variable
+ */
+
+const LOG_ENABLED = process.env.QUEEN_CLIENT_LOG === 'true'
+
+/**
+ * Get formatted timestamp
+ */
+function getTimestamp() {
+  return new Date().toISOString()
+}
+
+/**
+ * Format log message with timestamp and operation
+ */
+function formatLog(operation, details, level = 'INFO') {
+  const timestamp = getTimestamp()
+  const detailsStr = typeof details === 'object' ? JSON.stringify(details) : details
+  return `[${timestamp}] [${level}] [${operation}] ${detailsStr}`
+}
+
+/**
+ * Log an operation
+ */
+export function log(operation, details) {
+  if (!LOG_ENABLED) return
+  console.log(formatLog(operation, details))
+}
+
+/**
+ * Log a warning
+ */
+export function warn(operation, details) {
+  if (!LOG_ENABLED) return
+  console.warn(formatLog(operation, details, 'WARN'))
+}
+
+/**
+ * Log an error
+ */
+export function error(operation, details) {
+  if (!LOG_ENABLED) return
+  console.error(formatLog(operation, details, 'ERROR'))
+}
+
+/**
+ * Check if logging is enabled
+ */
+export function isEnabled() {
+  return LOG_ENABLED
+}
+

package/client-js/client-v2/utils/validation.js

@@ -0,0 +1,31 @@
+/**
+ * Validation utilities
+ */
+
+const UUID_V4_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+
+export function isValidUUID(str) {
+  return typeof str === 'string' && UUID_V4_REGEX.test(str)
+}
+
+export function validateQueueName(name) {
+  if (typeof name !== 'string' || name.trim().length === 0) {
+    throw new Error('Queue name must be a non-empty string')
+  }
+  return name.trim()
+}
+
+export function validateUrl(url) {
+  if (typeof url !== 'string' || !url.startsWith('http')) {
+    throw new Error(`Invalid URL: ${url}`)
+  }
+  return url
+}
+
+export function validateUrls(urls) {
+  if (!Array.isArray(urls) || urls.length === 0) {
+    throw new Error('URLs must be a non-empty array')
+  }
+  return urls.map(validateUrl)
+}
+

package/client-js/test-v2/AI_TEST_SUMMARY.md

@@ -0,0 +1,226 @@
+# AI-Generated Test Coverage Summary
+
+This document describes the additional test files created to improve test coverage for the Queen Message Queue client v2.
+
+## New Test Files Created
+
+### 1. `ai_error_handling.js` - Error Handling & Edge Cases
+
+Tests various error conditions and edge cases to ensure the system handles failures gracefully.
+
+**Tests:**
+- `testInvalidQueueName` - Empty queue name validation
+- `testInvalidConfiguration` - Invalid config values (negative lease times, etc.)
+- `testInvalidMessageFormat` - Messages with incorrect structure
+- `testPushEmptyArray` - Pushing empty message arrays
+- `testAckWithoutPartitionId` - Acknowledgment without required partitionId
+- `testPopFromNonExistentQueue` - Handling non-existent queues
+- `testMultiplePushesWithSameTransactionId` - Duplicate detection across multiple pushes
+- `testAckExpiredLease` - Attempting to ack after lease expiration
+- `testBatchAckMixedResults` - Batch acknowledgment with some expired leases
+- `testVeryLargePayload` - Testing system limits with very large messages
+
+**Purpose:** Ensure robust error handling and proper validation of inputs.
+
+---
+
+### 2. `ai_lease_renewal.js` - Lease Extension Management
+
+Tests manual lease renewal functionality to keep messages locked during long-running operations.
+
+**Tests:**
+- `testManualLeaseRenewal` - Basic lease renewal with `client.renew()`
+- `testBatchLeaseRenewal` - Renewing multiple message leases at once
+- `testRenewalWithLeaseId` - Renewing using just the leaseId string
+- `testRenewalOfExpiredLease` - Attempting to renew an already-expired lease
+- `testMultipleRenewals` - Renewing the same message multiple times
+
+**Purpose:** Validate that lease renewal prevents messages from being re-delivered during long processing.
+
+---
+
+### 3. `ai_resources.js` - Resource & Status APIs
+
+Tests the administrative and monitoring APIs for querying system state.
+
+**Tests:**
+- `testListQueues` - List all queues in the system
+- `testGetQueueDetails` - Get details for a specific queue
+- `testGetNamespaces` - List all namespaces
+- `testGetTasks` - List all tasks
+- `testGetMessages` - Query messages with filters
+- `testSystemOverview` - Get system-wide statistics
+- `testHealthCheck` - Health check endpoint
+- `testDeleteQueue` - Delete a queue and verify removal
+
+**Purpose:** Ensure monitoring and administrative APIs work correctly.
+
+---
+
+### 4. `ai_buffering.js` - Client-Side Buffering Management
+
+Tests client-side message buffering features for high-throughput scenarios.
+
+**Tests:**
+- `testBufferStatistics` - Getting buffer statistics via `getBufferStats()`
+- `testManualBufferFlush` - Manual flush with `flushAllBuffers()`
+- `testBufferTimeThreshold` - Time-based buffer flushing
+- `testBufferCountThreshold` - Count-based buffer flushing
+- `testMultipleBuffers` - Multiple queues with independent buffers
+- `testBufferWithPartition` - Buffering with specific partitions
+
+**Purpose:** Validate client-side buffering behavior for batch optimization.
+
+---
+
+### 5. `ai_priority.js` - Priority Queue Testing
+
+Tests message priority handling to ensure high-priority messages are processed first.
+
+**Tests:**
+- `testBasicPriority` - Queues with different priority levels
+- `testPriorityWithNamespace` - Priority ordering within a namespace
+- `testPriorityWithTask` - Priority ordering within a task
+- `testDynamicPriorityChange` - Reconfiguring queue priority
+
+**Purpose:** Ensure priority-based message processing works correctly.
+
+---
+
+### 6. `ai_ttl_retention.js` - TTL and Retention Policies
+
+Tests message time-to-live and retention features.
+
+**Tests:**
+- `testMessageTTL` - Messages expiring based on TTL configuration
+- `testRetentionEnabled` - Retention of pending messages
+- `testCompletedRetention` - Retention of completed messages
+- `testNoRetention` - Immediate deletion without retention
+- `testMaxWaitTimeDLQ` - Messages moving to DLQ based on max wait time
+
+**Purpose:** Validate message lifecycle and retention policies.
+
+---
+
+### 7. `ai_mixed_scenarios.js` - Complex Integration Tests
+
+Tests complex scenarios combining multiple features.
+
+**Tests:**
+- `testMultipleQueuesSimultaneous` - Multiple queues with different configurations
+- `testCrossQueueWorkflow` - 3-stage processing pipeline across queues
+- `testPartitionWithConsumerGroupAndRetries` - Complex partition + group + retry scenario
+- `testBufferedPushWithTransactionConsume` - Buffering combined with transactional consumption
+- `testNamespaceWithMultipleQueues` - Multiple queues in same namespace
+- `testEncryptedWithPartitionAndGroup` - Encryption + partition + consumer group
+- `testHighConcurrencyMixedOperations` - High concurrency with mixed operations
+
+**Purpose:** Validate that multiple features work correctly when combined.
+
+---
+
+## Test Coverage Summary
+
+### Before AI Tests
+- ✅ Queue creation/deletion/configuration
+- ✅ Basic push/pop operations
+- ✅ Consumer operations
+- ✅ Transactions
+- ✅ DLQ functionality
+- ✅ Load testing
+
+### After AI Tests (New Coverage)
+- ✅ **Error handling and edge cases**
+- ✅ **Lease renewal API**
+- ✅ **Resource/Status APIs**
+- ✅ **Client-side buffering management**
+- ✅ **Priority queue behavior**
+- ✅ **TTL and retention policies**
+- ✅ **Complex multi-feature scenarios**
+
+## Running the Tests
+
+### Run Only AI-Generated Tests (45 tests)
+```bash
+cd /Users/alice/Work/queen/client-js/test-v2
+node run.js ai
+```
+
+### Run Only Human-Written Tests (49 tests)
+```bash
+node run.js human
+```
+
+### Run All Tests (94 tests)
+```bash
+node run.js
+# or
+node run.js all
+```
+
+### Run Specific Test
+```bash
+# AI test examples
+node run.js testManualLeaseRenewal
+node run.js testInvalidQueueName
+node run.js testListQueues
+
+# Human test examples
+node run.js pushMessage
+node run.js testConsumer
+node run.js transactionBasicPushAck
+```
+
+### List All Available Tests
+```bash
+# Show help with categorized test list
+node run.js help
+```
+
+## Total Test Count
+
+| Category | Original Tests | AI-Generated Tests | Total |
+|----------|---------------|-------------------|-------|
+| Queue Operations | 3 | 0 | 3 |
+| Push Operations | 13 | 0 | 13 |
+| Pop Operations | 5 | 0 | 5 |
+| Consumer Operations | 12 | 0 | 12 |
+| Load Tests | 3 | 0 | 3 |
+| DLQ Tests | 1 | 0 | 1 |
+| Transaction Tests | 11 | 0 | 11 |
+| Complete Workflow | 1 | 0 | 1 |
+| **Error Handling** | **0** | **10** | **10** |
+| **Lease Renewal** | **0** | **5** | **5** |
+| **Resources/Status** | **0** | **8** | **8** |
+| **Buffering** | **0** | **6** | **6** |
+| **Priority** | **0** | **4** | **4** |
+| **TTL/Retention** | **0** | **5** | **5** |
+| **Mixed Scenarios** | **0** | **7** | **7** |
+| **TOTAL** | **49** | **45** | **94** |
+
+## Notable Test Features
+
+1. **Comprehensive Error Coverage**: Tests handle various failure modes including network errors, invalid inputs, and expired leases.
+
+2. **Real-World Scenarios**: Mixed scenario tests simulate actual production use cases like multi-stage pipelines and cross-queue workflows.
+
+3. **Administrative Testing**: Resource API tests enable validation of monitoring and management features.
+
+4. **Performance Features**: Buffering and priority tests ensure high-throughput and prioritization work correctly.
+
+5. **Data Lifecycle**: TTL and retention tests validate complete message lifecycle management.
+
+## Test Dependencies
+
+All tests require:
+- Queen server running on `http://localhost:6632`
+- PostgreSQL database accessible
+- Node.js with ES modules support
+
+## Notes
+
+- Tests prefixed with `ai_*` are AI-generated
+- All tests are non-destructive and use isolated test queues
+- Tests clean up after themselves where possible
+- Some tests intentionally trigger errors to validate error handling
+

package/client-js/test-v2/GETTING_STARTED.md

@@ -0,0 +1,154 @@
+# Getting Started with AI-Generated Tests
+
+## Quick Start
+
+The AI has identified and created tests for **7 major gaps** in your test coverage:
+
+### 1. **Error Handling** (`ai_error_handling.js`) - 10 tests
+Critical edge cases like invalid inputs, expired leases, and system limits.
+
+### 2. **Lease Renewal** (`ai_lease_renewal.js`) - 5 tests  
+Manual lease extension API for long-running message processing.
+
+### 3. **Resources/Status** (`ai_resources.js`) - 8 tests
+Administrative APIs for monitoring queues, namespaces, tasks, and system health.
+
+### 4. **Client Buffering** (`ai_buffering.js`) - 6 tests
+Client-side message buffering for high-throughput scenarios.
+
+### 5. **Priority Queues** (`ai_priority.js`) - 4 tests
+Message priority handling across queues, namespaces, and tasks.
+
+### 6. **TTL & Retention** (`ai_ttl_retention.js`) - 5 tests
+Message expiration, retention policies, and DLQ based on wait time.
+
+### 7. **Mixed Scenarios** (`ai_mixed_scenarios.js`) - 7 tests
+Complex real-world scenarios combining multiple features.
+
+## Running the New Tests
+
+### Run ONLY AI-generated tests:
+```bash
+cd client-js/test-v2
+node run.js ai
+```
+
+### Run ONLY human-written tests:
+```bash
+node run.js human
+```
+
+### Run all tests (both AI and human):
+```bash
+node run.js
+# or
+node run.js all
+```
+
+### Run a specific test:
+```bash
+node run.js testManualLeaseRenewal
+node run.js testInvalidQueueName
+node run.js testListQueues
+```
+
+### List all available tests:
+```bash
+# Run with invalid argument to see help
+node run.js help
+```
+
+## What Was Missing Before?
+
+| Area | Status Before | Status Now |
+|------|--------------|------------|
+| Error Handling | ❌ No coverage | ✅ 10 tests |
+| Lease Renewal API | ❌ Only auto-renewal | ✅ Manual renewal covered |
+| Resource APIs | ❌ Not tested | ✅ All endpoints covered |
+| Buffer Management | ❌ Basic buffering only | ✅ Full coverage |
+| Priority Queues | ❌ Config only | ✅ Behavior validated |
+| TTL/Retention | ❌ Not tested | ✅ Complete lifecycle |
+| Complex Scenarios | ⚠️ Partial | ✅ Real-world workflows |
+
+## Key Test Highlights
+
+### Most Important Tests
+
+1. **`testManualLeaseRenewal`** - Essential for long-running tasks
+2. **`testAckExpiredLease`** - Prevents data loss from expired leases
+3. **`testCrossQueueWorkflow`** - Validates transactional pipelines
+4. **`testBufferStatistics`** - Monitors client-side batching
+5. **`testPriorityWithNamespace`** - Ensures priority ordering works
+
+### Production-Critical Tests
+
+- `testAckWithoutPartitionId` - Prevents acknowledging wrong messages
+- `testBatchAckMixedResults` - Handles partial batch failures
+- `testHighConcurrencyMixedOperations` - Validates concurrency handling
+- `testEncryptedWithPartitionAndGroup` - Complex security scenario
+
+## File Structure
+
+```
+test-v2/
+├── queue.js                    # Original: Queue CRUD
+├── push.js                     # Original: Push operations  
+├── pop.js                      # Original: Pop operations
+├── consume.js                  # Original: Consumer patterns
+├── load.js                     # Original: Load testing
+├── dlq.js                      # Original: Dead letter queue
+├── complete.js                 # Original: Workflows
+├── transaction.js              # Original: Transactions
+├── ai_error_handling.js        # NEW: Error & edge cases
+├── ai_lease_renewal.js         # NEW: Lease management
+├── ai_resources.js             # NEW: Admin APIs
+├── ai_buffering.js             # NEW: Buffer management
+├── ai_priority.js              # NEW: Priority behavior
+├── ai_ttl_retention.js         # NEW: Message lifecycle
+├── ai_mixed_scenarios.js       # NEW: Complex scenarios
+├── run.js                      # Test runner (updated)
+├── AI_TEST_SUMMARY.md          # Detailed documentation
+└── GETTING_STARTED.md          # This file
+```
+
+## Before Running Tests
+
+Make sure:
+1. ✅ Queen server is running on `http://localhost:6632`
+2. ✅ PostgreSQL database is accessible
+3. ✅ Environment variables are set (if needed)
+4. ✅ No production data in test database
+
+## Test Philosophy
+
+The AI-generated tests follow these principles:
+
+1. **Isolated** - Each test uses unique queue names
+2. **Self-contained** - Tests don't depend on each other
+3. **Realistic** - Tests mirror production scenarios
+4. **Defensive** - Tests validate error conditions
+5. **Complete** - Tests cover happy path and edge cases
+
+## Next Steps
+
+1. Review the tests in each file
+2. Run the full test suite: `node run.js`
+3. Check for any failures specific to your environment
+4. Adjust configuration if needed (ports, timeouts, etc.)
+5. Integrate into your CI/CD pipeline
+
+## Need Help?
+
+- **See all tests**: `node run.js` (no arguments)
+- **Run specific test**: `node run.js <testName>`
+- **Read detailed docs**: See `AI_TEST_SUMMARY.md`
+- **Check original tests**: Files without `ai_` prefix
+
+## Test Count Summary
+
+- **Original tests**: 49
+- **AI-generated tests**: 45  
+- **Total coverage**: 94 tests
+
+You've nearly **doubled your test coverage** with these additions! 🎉
+