queen-mq 0.12.1 → 0.12.3

package/test-v2/AI_TEST_SUMMARY.md

@@ -1,226 +0,0 @@
-# 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/test-v2/GETTING_STARTED.md

@@ -1,181 +0,0 @@
-# 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
-
-## Testing with Different Server Configurations
-
-### Standard Configuration (Default)
-
-Run server with default settings:
-```bash
-./bin/queen-server
-node test-v2/run.js
-```
-
-**Expected:** Consumer groups without explicit `.subscriptionMode()` process all historical messages.
-
-### With DEFAULT_SUBSCRIPTION_MODE="new"
-
-Run server with "new" as default:
-```bash
-DEFAULT_SUBSCRIPTION_MODE="new" ./bin/queen-server
-node test-v2/run.js
-```
-
-**Expected:** 
-- Tests with explicit `.subscriptionMode('new')` work the same
-- Tests without explicit mode will skip historical messages
-- `subscriptionModeServerDefault` test detects and reports server default
-
-**All tests pass with both configurations!** The tests are designed to be agnostic to server defaults.
-
-## 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! 🎉
-

package/test-v2/MAINTENANCE_TEST.md

@@ -1,148 +0,0 @@
-# Maintenance Mode Test
-
-## Overview
-
-Comprehensive test for the maintenance mode feature with file buffer.
-
-## Test Scenario
-
-1. **Start consumer** - Begins consuming messages from queue
-2. **Start producer** - Produces 10 messages/second
-3. **Enable maintenance** - Triggers maintenance mode via API
-4. **Verify buffering** - Consumer stops receiving (messages go to file buffer)
-5. **Continue producing** - Producer keeps running for 10 seconds during maintenance
-6. **Disable maintenance** - Deactivates maintenance mode via API
-7. **Verify drain** - Consumer resumes receiving messages
-8. **Stop producer** - Halts message production
-9. **Wait for completion** - Waits 10 seconds for file buffer to drain
-10. **Verify counts** - Ensures all produced messages were received
-
-## Running the Test
-
-### Standalone
-
-```bash
-cd /Users/alice/Work/queen/client-js/test-v2
-node maintenance.js
-```
-
-### Via Test Runner
-
-```bash
-# Run just this test
-node run.js test_maintenance_mode
-
-# Run all human tests (includes this one)
-node run.js human
-
-# Run all tests
-node run.js
-```
-
-## Expected Output
-
-```
-🧪 Testing Maintenance Mode with File Buffer
-
-📋 Step 1: Configuring queue "test-maintenance-queue"...
-✅ Queue configured
-
-📥 Step 2: Starting consumer...
-✅ Consumer started
-
-📤 Step 3: Starting producer (10 msgs/sec)...
-✅ Producer started
-
-⏱️  Step 4: Waiting 3 seconds for normal message flow...
-  📨 Received 10 messages (total: 10)
-  📨 Received 10 messages (total: 20)
-  📨 Received 10 messages (total: 30)
-   Produced: 30, Received: 30
-
-🔧 Step 5: Enabling MAINTENANCE MODE...
-   Response: { maintenanceMode: true, bufferedMessages: 0, ... }
-✅ Maintenance mode enabled
-
-⏱️  Step 6: Waiting 2 seconds - consumer should stop receiving...
-   Messages received during maintenance: 0
-   Total: Produced=50, Received=30
-
-⏱️  Step 7: Producing during maintenance for 10 seconds...
-   (Messages should go to file buffer)
-
-   Maintenance period complete:
-   - Total produced: 150
-   - Total received: 30
-   - Buffered (should be ~100): 120
-
-📊 Step 8: Checking maintenance status...
-   Status: { maintenanceMode: true, bufferedMessages: 120, ... }
-
-✅ Step 9: Disabling MAINTENANCE MODE...
-   Response: { maintenanceMode: false, bufferedMessages: 120, ... }
-   (File buffer should start draining to database)
-
-⏱️  Step 10: Waiting for messages to resume...
-  📨 Received 10 messages (total: 40)
-   Messages received after resuming: 10
-✅ Messages are flowing again!
-
-🛑 Step 11: Stopping producer...
-   Final produced count: 150
-
-⏱️  Step 12: Waiting 10 seconds for file buffer to drain...
-   1s - Received: 50/150 (33.3%)
-  📨 Received 10 messages (total: 60)
-   2s - Received: 70/150 (46.7%)
-  📨 Received 10 messages (total: 80)
-   3s - Received: 90/150 (60.0%)
-  📨 Received 10 messages (total: 100)
-   4s - Received: 110/150 (73.3%)
-  📨 Received 10 messages (total: 120)
-   5s - Received: 130/150 (86.7%)
-  📨 Received 10 messages (total: 140)
-   6s - Received: 150/150 (100.0%)
-   ✅ All messages received!
-
-🛑 Step 13: Stopping consumer...
-✅ Consumer stopped
-
-📊 Final Verification:
-
-   Total Produced: 150
-   Total Received: 150
-   Difference: 0
-
-✅ SUCCESS: All messages accounted for!
-   Maintenance mode works correctly with file buffer.
-
-👋 Queen client closed
-
-✅ All tests passed!
-```
-
-## What It Tests
-
-✅ **Maintenance mode activation** - API responds correctly
-✅ **Message buffering** - Messages go to file buffer (consumer stops receiving)
-✅ **Continued production** - Can push messages during maintenance
-✅ **Maintenance mode deactivation** - API responds correctly
-✅ **Automatic drain** - File buffer drains to database
-✅ **Message ordering** - All messages received in order (FIFO)
-✅ **No message loss** - Produced count == Received count
-✅ **Multi-instance support** - Uses database for state (works across restarts)
-
-## Success Criteria
-
-- All produced messages are eventually received
-- Consumer stops receiving during maintenance
-- Consumer resumes receiving after maintenance is disabled
-- No duplicates or lost messages
-- Drain completes within 10 seconds
-
-## Notes
-
-- Uses `axios` for direct API calls (maintenance endpoints)
-- Uses Queen client for queue operations (push/pop/ack)
-- Test takes ~25 seconds total (3s warmup + 10s maintenance + 10s drain)
-