queen-mq 0.2.11 → 0.2.23

package/README.md

@@ -175,6 +175,37 @@ FILE_BUFFER_DIR=/custom/path ./bin/queen-server
 | **Auto-Ack** | Fire-and-forget events, notifications | Tasks requiring retry logic |
 | **Failover** | Everything (automatic) | N/A - always beneficial |
 
+## Architecture
+
+Queen uses a high-performance **acceptor/worker pattern** with uWebSockets, combining non-blocking I/O for HTTP/WebSocket with a dedicated thread pool for database operations.
+
+**View the interactive architecture diagram:** [architecture.svg](./assets/architecture.svg)
+
+**Key Components:**
+- **UWS Acceptor**: Single thread listening on port 6632, round-robin distributes to workers
+- **UWS Workers**: N event loop threads (default: 10) handling HTTP routes and WebSocket
+- **Response Timers**: Per-worker timers (25ms tick) drain response queue back to clients
+- **DB ThreadPool**: Separate pool for blocking PostgreSQL operations
+- **Poll Workers**: 2 reserved threads for long-polling with adaptive backoff (100ms→2000ms)
+- **Poll Intention Registry**: Thread-safe store for long-poll requests
+- **Database Pool**: 150 shared PostgreSQL connections (libpq) with mutex/condition variable
+- **Response Queue**: Thread-safe queue decoupling DB results from event loop responses
+
+**Request Flow:**
+1. Client → Acceptor → Worker (event loop)
+2. Worker registers response, submits job to DB ThreadPool
+3. DB thread executes query, pushes result to Response Queue
+4. Worker's response timer drains queue, sends HTTP response
+
+**Long-Polling Flow:**
+1. No immediate messages? Register intention in Registry
+2. Poll Workers wake every 50ms, group intentions by queue/partition/consumer
+3. Rate-limited DB queries (100ms initial, exponential backoff to 2s)
+4. Messages distributed to waiting clients via Response Queue
+5. Timeouts detected by Poll Workers, send 204 No Content
+
+This architecture provides high concurrency, efficient connection pooling, and minimal latency for both immediate and long-polling requests.
+
 ## Webapp
 
 A modern Vue 3 web interface for managing and monitoring Queen MQ.
@@ -244,10 +275,6 @@ You can use Queen directly from HTTP without the JS client.
 ### Server Startup Timing (Critical)
 **Issue:** Worker initialization timeout (30s → 3600s) now matches file buffer recovery timeout. This is a temporary fix.
 
-**Problem:** During startup, if the file buffer has many events to recover (e.g., after a long PostgreSQL outage), Worker 0 performs blocking recovery that can take up to 1 hour. The acceptor waits for all workers to initialize before starting to accept connections.
-
-**Current Fix:** Worker initialization timeout increased to 3600s to prevent premature timeout.
-
 **Better Solution Needed:**
 - Make recovery non-blocking while preserving FIFO ordering guarantees
 - Implement progressive readiness with memory-buffered queue during recovery
@@ -255,10 +282,10 @@ You can use Queen directly from HTTP without the JS client.
 - See: `server/src/services/file_buffer.cpp:212` (MAX_STARTUP_RECOVERY_SECONDS)
 - See: `server/src/acceptor_server.cpp:1876` (worker initialization timeout)
 
+
 ### Other TODO Items
 - retention jobs
 - reconsume
-- fix frontend
-- pg async
-- pg reconnect
-- memory leak?
+- new client
+- auth
+- streaming engine

package/client-js/benchmark/consumer.js

@@ -5,7 +5,7 @@ const QUEUE_NAME = 'benchmark-queue-001';
 const NUMBER_OF_CONSUMERS = 10;
 const STARTING_PARTITION = parseInt(process.argv[2]) || 0;
 const BATCH_SIZE = 10000;
-const CONSUME_MODE = 'partition';
+const CONSUME_MODE = null//'partition';
 
 // Global metrics tracking
 const metrics = {
@@ -50,7 +50,7 @@ async function consumer(consumerId, partition) {
   try {
     for await (const messages of q.takeBatch(target, { //`namespace:benchmark`, 
       wait: true,
-      timeout: 15000,
+      timeout: 30000,
       batch: BATCH_SIZE,
       idleTimeout: 5000
     })) {

package/client-js/benchmark/producer.js

@@ -3,7 +3,7 @@ import fs from 'fs';
 
 const TOTAL_MESSAGES = 1000000;
 const PARTITIONS = 10; 
-const MAX_BATCH_SIZE = 10000;  // Reduced from 10000
+const MAX_BATCH_SIZE = 100;  // Reduced from 10000
 const PUSH_PARALLEL = 10;      // Reduced from 10 to avoid lock contention
 const QUEUE_NAME = 'benchmark-queue-001';
 

package/client-js/client/client.js

@@ -542,14 +542,16 @@ export class Queen {
       if (hasIndividualStatus) {
         // Option B: Each message has its own status
         acknowledgments = message.map(msg => {
-          // Extract transaction ID and lease ID
+          // Extract transaction ID, partition ID, and lease ID
           let transactionId;
+          let partitionId = null;
           let leaseId = null;
           
           if (typeof msg === 'string') {
             transactionId = msg;
           } else if (typeof msg === 'object' && msg !== null) {
             transactionId = msg.transactionId || msg.id;
+            partitionId = msg.partitionId || null;
             leaseId = msg.leaseId || null;
             if (!transactionId) {
               throw new Error('Message object must have transactionId or id property');
@@ -573,6 +575,11 @@ export class Queen {
             error: msg._error || context.error || null
           };
           
+          // Include partition ID if available
+          if (partitionId) {
+            ack.partitionId = partitionId;
+          }
+          
           // Include lease ID if available
           if (leaseId) {
             ack.leaseId = leaseId;
@@ -587,14 +594,16 @@ export class Queen {
           : status;
         
         acknowledgments = message.map(msg => {
-          // Extract transaction ID and lease ID
+          // Extract transaction ID, partition ID, and lease ID
           let transactionId;
+          let partitionId = null;
           let leaseId = null;
           
           if (typeof msg === 'string') {
             transactionId = msg;
           } else if (typeof msg === 'object' && msg !== null) {
             transactionId = msg.transactionId || msg.id;
+            partitionId = msg.partitionId || null;
             leaseId = msg.leaseId || null;
             if (!transactionId) {
               throw new Error('Message object must have transactionId or id property');
@@ -609,6 +618,11 @@ export class Queen {
             error: context.error || null
           };
           
+          // Include partition ID if available
+          if (partitionId) {
+            ack.partitionId = partitionId;
+          }
+          
           // Include lease ID if available
           if (leaseId) {
             ack.leaseId = leaseId;
@@ -636,14 +650,16 @@ export class Queen {
     }
     
     // Handle single message acknowledgment
-    // Extract transaction ID and lease ID
+    // Extract transaction ID, partition ID, and lease ID
     let transactionId;
+    let partitionId = null;
     let leaseId = null;
     
     if (typeof message === 'string') {
       transactionId = message;
     } else if (typeof message === 'object' && message !== null) {
       transactionId = message.transactionId || message.id;
+      partitionId = message.partitionId || null;  // Extract partition ID for partition-scoped ACK
       leaseId = message.leaseId || null;  // Extract lease ID if present
       if (!transactionId) {
         throw new Error('Message object must have transactionId or id property');
@@ -668,6 +684,11 @@ export class Queen {
       consumerGroup: context.group || null
     };
     
+    // Include partition ID if available for partition-scoped operations
+    if (partitionId) {
+      body.partitionId = partitionId;
+    }
+    
     // Include lease ID if available for lease validation
     if (leaseId) {
       body.leaseId = leaseId;
@@ -1244,7 +1265,11 @@ class PipelineBuilder {
           await tx.commit();
         } else {
           // Default: just ACK the messages
-          await this.#client.ack(messages, true);
+          // Extract consumer group from queue address if present (format: queue@group)
+          const atIndex = this.#queue.lastIndexOf('@');
+          const consumerGroup = atIndex > 0 ? this.#queue.substring(atIndex + 1) : null;
+          const context = consumerGroup ? { group: consumerGroup } : {};
+          await this.#client.ack(messages, true, context);
         }
         
         return {

package/client-js/test/README.md

@@ -40,7 +40,7 @@ The test suite is organized into focused, modular files:
 - Subscription modes (all vs new messages)
 - Consumer group isolation
 
-#### 5. Edge Cases (`edge-case-tests.js`)
+#### 5. Edge Cases (`edge-case-tests.js` & `partition-transaction-tests.js`)
 - Empty and null payloads
 - Very large payloads
 - Concurrent push/take operations
@@ -48,6 +48,11 @@ The test suite is organized into focused, modular files:
 - Lease expiration and redelivery
 - SQL injection prevention
 - XSS prevention
+- **Partition-scoped transaction_id handling** (`partition-transaction-tests.js`):
+  - Duplicate transaction IDs across partitions with correct ACK targeting
+  - Batch ACK with duplicate transaction IDs
+  - DLQ operations with duplicate transaction IDs
+  - Analytics API with duplicate transaction IDs
 
 #### 6. Advanced Patterns (`advanced-pattern-tests.js`)
 - Multi-stage pipeline workflow
@@ -138,20 +143,36 @@ for await (const msg of client.take('myqueue/partition@group', { limit: 10 })) {
 cd /Users/alice/Work/queen
 
 # Run all tests
-nvm use 22 && node src/test/test-new.js
+nvm use 22 && node client-js/test/test-new.js
 
 # Run specific test category
-node src/test/test-new.js core        # Core features only
-node src/test/test-new.js partition   # Partition locking tests only
-node src/test/test-new.js enterprise  # Enterprise features only
-node src/test/test-new.js bus         # Bus mode tests only
-node src/test/test-new.js edge        # Edge cases only
-node src/test/test-new.js advanced    # Advanced patterns only
+node client-js/test/test-new.js core        # Core features only
+node client-js/test/test-new.js partition   # Partition locking tests only
+node client-js/test/test-new.js enterprise  # Enterprise features only
+node client-js/test/test-new.js bus         # Bus mode tests only
+node client-js/test/test-new.js edge        # Edge cases (includes partition-scoped txn_id tests)
+node client-js/test/test-new.js advanced    # Advanced patterns only
 
 # Show help
-node src/test/test-new.js help
+node client-js/test/test-new.js help
 ```
 
+### Testing Partition-Scoped Transaction ID Fix
+
+The `edge` test category includes critical tests for partition-scoped transaction_id handling:
+
+```bash
+# Run all edge case tests (includes partition transaction_id tests)
+node client-js/test/test-new.js edge
+```
+
+These tests verify that:
+- ✅ The same `transaction_id` can exist in multiple partitions
+- ✅ ACK operations correctly target messages using BOTH `partition_id` AND `transaction_id`
+- ✅ Batch ACK operations scope correctly by partition
+- ✅ DLQ operations only affect the intended partition
+- ✅ Analytics API (`GET /api/v1/messages/:partitionId/:transactionId`) returns the correct message
+
 ### Available Test Categories
 
 - **`core`** - Core features (queue creation, push, take, ack, delayed processing, FIFO)

package/client-js/test/partition-transaction-tests.js

@@ -0,0 +1,482 @@
+/**
+ * Partition-Scoped Transaction ID Tests
+ * 
+ * Tests that transaction_id uniqueness is properly scoped to partitions.
+ * With the constraint UNIQUE(partition_id, transaction_id), the same transaction_id
+ * can exist in multiple partitions. This tests that ACK operations correctly
+ * identify and operate on the right message by using BOTH partition_id AND transaction_id.
+ */
+
+import { startTest, passTest, failTest, sleep, dbPool, getMessageCount, log, TEST_CONFIG } from './utils.js';
+
+/**
+ * Test: Duplicate transaction IDs across partitions with correct ACK targeting
+ * 
+ * This is the critical test that verifies the fix for partition-scoped transaction_ids.
+ * Without the fix, ACKing a message in one partition could accidentally ACK
+ * a message with the same transaction_id in a different partition.
+ */
+export async function testDuplicateTransactionIdsAcrossPartitions(client) {
+  startTest('Duplicate Transaction IDs Across Partitions - ACK Targeting', 'edge');
+  
+  try {
+    const queue = 'test-duplicate-txn-ids';
+    const partition1 = 'partition-A';
+    const partition2 = 'partition-B';
+    const sharedTxnId = 'shared-txn-12345';
+    
+    // Configure queue
+    await client.queue(queue, { leaseTime: 30 });
+    
+    // CRITICAL: Push messages with the SAME transaction_id to DIFFERENT partitions
+    log(`Pushing message with txn=${sharedTxnId} to ${partition1}`, 'test');
+    await client.push(`${queue}/${partition1}`, 
+      { data: 'Message in Partition A', partition: partition1 },
+      { transactionId: sharedTxnId }
+    );
+    
+    log(`Pushing message with txn=${sharedTxnId} to ${partition2}`, 'test');
+    await client.push(`${queue}/${partition2}`, 
+      { data: 'Message in Partition B', partition: partition2 },
+      { transactionId: sharedTxnId }
+    );
+    
+    await sleep(100);
+    
+    // Verify both messages exist in database
+    const msgCountA = await getMessageCount(queue, partition1);
+    const msgCountB = await getMessageCount(queue, partition2);
+    
+    if (msgCountA !== 1) {
+      throw new Error(`Expected 1 message in ${partition1}, found ${msgCountA}`);
+    }
+    if (msgCountB !== 1) {
+      throw new Error(`Expected 1 message in ${partition2}, found ${msgCountB}`);
+    }
+    
+    log('✓ Both messages with same transaction_id exist in different partitions', 'success');
+    
+    // Take message from partition A
+    log(`Taking message from ${partition1}`, 'test');
+    let messageA = null;
+    for await (const msg of client.take(`${queue}/${partition1}`, { limit: 1 })) {
+      messageA = msg;
+      break;
+    }
+    
+    if (!messageA) {
+      throw new Error('Failed to take message from partition A');
+    }
+    
+    if (messageA.transactionId !== sharedTxnId) {
+      throw new Error(`Expected transaction_id ${sharedTxnId}, got ${messageA.transactionId}`);
+    }
+    
+    if (messageA.data.partition !== partition1) {
+      throw new Error(`Expected partition ${partition1}, got ${messageA.data.partition}`);
+    }
+    
+    log(`✓ Received correct message from ${partition1}: ${JSON.stringify(messageA.data)}`, 'success');
+    
+    // ACK the message from partition A
+    log(`ACKing message in ${partition1} with txn=${sharedTxnId}`, 'test');
+    await client.ack(messageA, true);
+    
+    await sleep(200);
+    
+    // CRITICAL CHECK: Verify message in partition A is acknowledged
+    const result = await dbPool.query(`
+      SELECT 
+        m.id,
+        m.transaction_id,
+        p.name as partition_name,
+        pc.last_consumed_id,
+        CASE
+          WHEN m.id <= pc.last_consumed_id AND DATE_TRUNC('milliseconds', m.created_at) <= DATE_TRUNC('milliseconds', pc.last_consumed_created_at)
+          THEN 'completed'
+          ELSE 'pending'
+        END as status
+      FROM queen.messages m
+      JOIN queen.partitions p ON p.id = m.partition_id
+      JOIN queen.queues q ON q.id = p.queue_id
+      LEFT JOIN queen.partition_consumers pc ON pc.partition_id = p.id AND pc.consumer_group = '__QUEUE_MODE__'
+      WHERE q.name = $1 AND m.transaction_id = $2
+      ORDER BY p.name
+    `, [queue, sharedTxnId]);
+    
+    if (result.rows.length !== 2) {
+      throw new Error(`Expected 2 messages in database, found ${result.rows.length}`);
+    }
+    
+    const msgA = result.rows.find(r => r.partition_name === partition1);
+    const msgB = result.rows.find(r => r.partition_name === partition2);
+    
+    if (!msgA || !msgB) {
+      throw new Error('Could not find both messages in query result');
+    }
+    
+    log(`Message A (${partition1}): status=${msgA.status}`, 'test');
+    log(`Message B (${partition2}): status=${msgB.status}`, 'test');
+    
+    // CRITICAL ASSERTION: Message in partition A should be completed
+    if (msgA.status !== 'completed') {
+      throw new Error(`Message in ${partition1} should be completed, but status is: ${msgA.status}`);
+    }
+    
+    // CRITICAL ASSERTION: Message in partition B should still be pending
+    if (msgB.status !== 'pending') {
+      throw new Error(`Message in ${partition2} should still be pending, but status is: ${msgB.status}`);
+    }
+    
+    log(`✓ ACK correctly targeted only ${partition1}, ${partition2} remains pending`, 'success');
+    
+    // Now take and ACK message from partition B
+    log(`Taking message from ${partition2}`, 'test');
+    let messageB = null;
+    for await (const msg of client.take(`${queue}/${partition2}`, { limit: 1 })) {
+      messageB = msg;
+      break;
+    }
+    
+    if (!messageB) {
+      throw new Error('Failed to take message from partition B');
+    }
+    
+    if (messageB.transactionId !== sharedTxnId) {
+      throw new Error(`Expected transaction_id ${sharedTxnId}, got ${messageB.transactionId}`);
+    }
+    
+    if (messageB.data.partition !== partition2) {
+      throw new Error(`Expected partition ${partition2}, got ${messageB.data.partition}`);
+    }
+    
+    log(`✓ Received correct message from ${partition2}: ${JSON.stringify(messageB.data)}`, 'success');
+    
+    // ACK the message from partition B
+    log(`ACKing message in ${partition2} with txn=${sharedTxnId}`, 'test');
+    await client.ack(messageB, true);
+    
+    await sleep(200);
+    
+    // Verify both messages are now completed
+    const finalResult = await dbPool.query(`
+      SELECT 
+        p.name as partition_name,
+        CASE
+          WHEN m.id <= pc.last_consumed_id AND DATE_TRUNC('milliseconds', m.created_at) <= DATE_TRUNC('milliseconds', pc.last_consumed_created_at)
+          THEN 'completed'
+          ELSE 'pending'
+        END as status
+      FROM queen.messages m
+      JOIN queen.partitions p ON p.id = m.partition_id
+      JOIN queen.queues q ON q.id = p.queue_id
+      LEFT JOIN queen.partition_consumers pc ON pc.partition_id = p.id AND pc.consumer_group = '__QUEUE_MODE__'
+      WHERE q.name = $1 AND m.transaction_id = $2
+      ORDER BY p.name
+    `, [queue, sharedTxnId]);
+    
+    const finalMsgA = finalResult.rows.find(r => r.partition_name === partition1);
+    const finalMsgB = finalResult.rows.find(r => r.partition_name === partition2);
+    
+    if (finalMsgA.status !== 'completed' || finalMsgB.status !== 'completed') {
+      throw new Error('Both messages should be completed after individual ACKs');
+    }
+    
+    log('✓ Both messages correctly ACKed independently', 'success');
+    
+    passTest('Partition-scoped transaction_id ACK targeting works correctly');
+  } catch (error) {
+    failTest(error);
+  }
+}
+
+/**
+ * Test: Batch ACK with duplicate transaction IDs across partitions
+ * 
+ * Tests that batch acknowledgment correctly scopes to partition_id
+ */
+export async function testBatchAckWithDuplicateTransactionIds(client) {
+  startTest('Batch ACK with Duplicate Transaction IDs', 'edge');
+  
+  try {
+    const queue = 'test-batch-ack-duplicate';
+    const partition1 = 'partition-X';
+    const partition2 = 'partition-Y';
+    
+    await client.queue(queue, { leaseTime: 30 });
+    
+    // Push 3 messages to partition1 with specific transaction IDs
+    const txnIds = ['batch-1', 'batch-2', 'batch-3'];
+    
+    for (const txnId of txnIds) {
+      await client.push(`${queue}/${partition1}`, 
+        { data: `P1-${txnId}` },
+        { transactionId: txnId }
+      );
+      
+      // Push same transaction_id to partition2
+      await client.push(`${queue}/${partition2}`, 
+        { data: `P2-${txnId}` },
+        { transactionId: txnId }
+      );
+    }
+    
+    await sleep(500); // Give more time for messages to be ready
+    
+    // Take all messages from partition1 (batch size 10 to get all 3)
+    const messagesP1 = [];
+    for await (const msg of client.take(`${queue}/${partition1}`, { batch: 10, limit: 10 })) {
+      messagesP1.push(msg);
+      if (messagesP1.length >= 3) break;
+    }
+    
+    if (messagesP1.length !== 3) {
+      log(`DEBUG: Only got ${messagesP1.length} messages. Transaction IDs: ${messagesP1.map(m => m.transactionId).join(', ')}`, 'warning');
+      
+      // Check database to see what's there
+      const dbCheck = await dbPool.query(`
+        SELECT m.transaction_id, p.name as partition_name, m.created_at
+        FROM queen.messages m
+        JOIN queen.partitions p ON p.id = m.partition_id
+        JOIN queen.queues q ON q.id = p.queue_id
+        WHERE q.name = $1
+        ORDER BY p.name, m.created_at
+      `, [queue]);
+      
+      log(`DEBUG: Database has ${dbCheck.rows.length} messages: ${JSON.stringify(dbCheck.rows)}`, 'warning');
+      throw new Error(`Expected 3 messages from partition1, got ${messagesP1.length}`);
+    }
+    
+    log(`Received ${messagesP1.length} messages from ${partition1}`, 'test');
+    
+    // Batch ACK all messages from partition1
+    for (const msg of messagesP1) {
+      await client.ack(msg, true);
+    }
+    
+    await sleep(200);
+    
+    // Verify partition1 messages are completed but partition2 messages are still pending
+    for (const txnId of txnIds) {
+      const result = await dbPool.query(`
+        SELECT 
+          p.name as partition_name,
+          CASE
+            WHEN m.id <= pc.last_consumed_id AND DATE_TRUNC('milliseconds', m.created_at) <= DATE_TRUNC('milliseconds', pc.last_consumed_created_at)
+            THEN 'completed'
+            ELSE 'pending'
+          END as status
+        FROM queen.messages m
+        JOIN queen.partitions p ON p.id = m.partition_id
+        JOIN queen.queues q ON q.id = p.queue_id
+        LEFT JOIN queen.partition_consumers pc ON pc.partition_id = p.id AND pc.consumer_group = '__QUEUE_MODE__'
+        WHERE q.name = $1 AND m.transaction_id = $2
+        ORDER BY p.name
+      `, [queue, txnId]);
+      
+      const p1Status = result.rows.find(r => r.partition_name === partition1)?.status;
+      const p2Status = result.rows.find(r => r.partition_name === partition2)?.status;
+      
+      if (p1Status !== 'completed') {
+        throw new Error(`${partition1} message with txn=${txnId} should be completed, got ${p1Status}`);
+      }
+      
+      if (p2Status !== 'pending') {
+        throw new Error(`${partition2} message with txn=${txnId} should be pending, got ${p2Status}`);
+      }
+    }
+    
+    log(`✓ Batch ACK in ${partition1} did not affect ${partition2}`, 'success');
+    
+    passTest('Batch ACK correctly scopes by partition_id');
+  } catch (error) {
+    failTest(error);
+  }
+}
+
+/**
+ * Test: DLQ with duplicate transaction IDs
+ * 
+ * Tests that moving messages to DLQ correctly scopes by partition_id
+ */
+export async function testDLQWithDuplicateTransactionIds(client) {
+  startTest('DLQ with Duplicate Transaction IDs', 'edge');
+  
+  try {
+    const queue = 'test-dlq-duplicate';
+    const partition1 = 'partition-DLQ-A';
+    const partition2 = 'partition-DLQ-B';
+    const txnId = 'dlq-shared-txn';
+    
+    await client.queue(queue, { retryLimit: 0 }); // Immediate DLQ
+    
+    // Push same transaction_id to both partitions
+    await client.push(`${queue}/${partition1}`, { data: 'P1-data' }, { transactionId: txnId });
+    await client.push(`${queue}/${partition2}`, { data: 'P2-data' }, { transactionId: txnId });
+    
+    await sleep(100);
+    
+    // Take from partition1 and fail it
+    let msgP1 = null;
+    for await (const msg of client.take(`${queue}/${partition1}`, { limit: 1 })) {
+      msgP1 = msg;
+      break;
+    }
+    
+    if (!msgP1) {
+      throw new Error('Failed to take message from partition1');
+    }
+    
+    // ACK as failed - should go to DLQ
+    await client.ack(msgP1, false, { error: 'Test error for P1' });
+    
+    await sleep(200);
+    
+    // Check DLQ - only partition1 message should be there
+    const dlqResult = await dbPool.query(`
+      SELECT 
+        p.name as partition_name,
+        dlq.error_message
+      FROM queen.dead_letter_queue dlq
+      JOIN queen.messages m ON dlq.message_id = m.id
+      JOIN queen.partitions p ON p.id = m.partition_id
+      JOIN queen.queues q ON q.id = p.queue_id
+      WHERE q.name = $1 AND m.transaction_id = $2
+    `, [queue, txnId]);
+    
+    if (dlqResult.rows.length !== 1) {
+      throw new Error(`Expected 1 message in DLQ, found ${dlqResult.rows.length}`);
+    }
+    
+    if (dlqResult.rows[0].partition_name !== partition1) {
+      throw new Error(`Expected DLQ message from ${partition1}, got ${dlqResult.rows[0].partition_name}`);
+    }
+    
+    if (!dlqResult.rows[0].error_message.includes('Test error for P1')) {
+      throw new Error(`Unexpected error message: ${dlqResult.rows[0].error_message}`);
+    }
+    
+    log(`✓ DLQ correctly scoped to ${partition1}`, 'success');
+    
+    // Verify partition2 message is still pending
+    let msgP2 = null;
+    for await (const msg of client.take(`${queue}/${partition2}`, { limit: 1 })) {
+      msgP2 = msg;
+      break;
+    }
+    
+    if (!msgP2) {
+      throw new Error('Message in partition2 should still be available');
+    }
+    
+    if (msgP2.transactionId !== txnId) {
+      throw new Error(`Expected transaction_id ${txnId} in P2, got ${msgP2.transactionId}`);
+    }
+    
+    log(`✓ ${partition2} message with same txn_id is still available`, 'success');
+    
+    passTest('DLQ correctly scopes by partition_id');
+  } catch (error) {
+    failTest(error);
+  }
+}
+
+/**
+ * Test: Analytics API with duplicate transaction IDs
+ * 
+ * Tests that the GET /api/v1/messages/:partitionId/:transactionId endpoint
+ * returns the correct message when the same transaction_id exists in multiple partitions
+ */
+export async function testAnalyticsAPIWithDuplicateTransactionIds(client) {
+  startTest('Analytics API with Duplicate Transaction IDs', 'edge');
+  
+  try {
+    const queue = 'test-analytics-duplicate';
+    const partition1 = 'analytics-P1';
+    const partition2 = 'analytics-P2';
+    const txnId = 'analytics-shared-txn';
+    
+    await client.queue(queue, {});
+    
+    // Push messages with same transaction_id to both partitions
+    await client.push(`${queue}/${partition1}`, 
+      { unique: 'data-from-P1', timestamp: Date.now() },
+      { transactionId: txnId }
+    );
+    
+    await client.push(`${queue}/${partition2}`, 
+      { unique: 'data-from-P2', timestamp: Date.now() + 1000 },
+      { transactionId: txnId }
+    );
+    
+    await sleep(100);
+    
+    // Get partition IDs from database
+    const partitionResult = await dbPool.query(`
+      SELECT p.id, p.name
+      FROM queen.partitions p
+      JOIN queen.queues q ON q.id = p.queue_id
+      WHERE q.name = $1
+      ORDER BY p.name
+    `, [queue]);
+    
+    const p1Id = partitionResult.rows.find(r => r.name === partition1)?.id;
+    const p2Id = partitionResult.rows.find(r => r.name === partition2)?.id;
+    
+    if (!p1Id || !p2Id) {
+      throw new Error('Failed to get partition IDs');
+    }
+    
+    log(`Partition IDs: ${partition1}=${p1Id}, ${partition2}=${p2Id}`, 'test');
+    
+    // Fetch message using Analytics API (via HTTP)
+    const baseUrl = TEST_CONFIG.baseUrls[0];
+    
+    // Fetch from partition1
+    const response1 = await fetch(`${baseUrl}/api/v1/messages/${p1Id}/${txnId}`);
+    if (!response1.ok) {
+      throw new Error(`Failed to fetch message from partition1: ${response1.statusText}`);
+    }
+    const data1 = await response1.json();
+    
+    if (data1.transactionId !== txnId) {
+      throw new Error(`Expected transactionId ${txnId}, got ${data1.transactionId}`);
+    }
+    
+    if (data1.partition !== partition1) {
+      throw new Error(`Expected partition ${partition1}, got ${data1.partition}`);
+    }
+    
+    if (data1.payload.unique !== 'data-from-P1') {
+      throw new Error(`Expected data from P1, got: ${JSON.stringify(data1.payload)}`);
+    }
+    
+    log(`✓ Analytics API correctly returned message from ${partition1}`, 'success');
+    
+    // Fetch from partition2
+    const response2 = await fetch(`${baseUrl}/api/v1/messages/${p2Id}/${txnId}`);
+    if (!response2.ok) {
+      throw new Error(`Failed to fetch message from partition2: ${response2.statusText}`);
+    }
+    const data2 = await response2.json();
+    
+    if (data2.transactionId !== txnId) {
+      throw new Error(`Expected transactionId ${txnId}, got ${data2.transactionId}`);
+    }
+    
+    if (data2.partition !== partition2) {
+      throw new Error(`Expected partition ${partition2}, got ${data2.partition}`);
+    }
+    
+    if (data2.payload.unique !== 'data-from-P2') {
+      throw new Error(`Expected data from P2, got: ${JSON.stringify(data2.payload)}`);
+    }
+    
+    log(`✓ Analytics API correctly returned message from ${partition2}`, 'success');
+    
+    passTest('Analytics API correctly distinguishes messages by partition_id');
+  } catch (error) {
+    failTest(error);
+  }
+}
+

package/client-js/test/test-new.js

@@ -80,6 +80,13 @@ import {
   testXSSPrevention
 } from './edge-case-tests.js';
 
+import {
+  testDuplicateTransactionIdsAcrossPartitions,
+  testBatchAckWithDuplicateTransactionIds,
+  testDLQWithDuplicateTransactionIds,
+  testAnalyticsAPIWithDuplicateTransactionIds
+} from './partition-transaction-tests.js';
+
 import {
   testMultiStagePipeline,
   testFanOutFanIn,
@@ -274,6 +281,12 @@ async function runTests() {
       await runTest(() => testLeaseExpiration(client));
       await runTest(() => testSQLInjectionPrevention(client));
       await runTest(() => testXSSPrevention(client));
+      
+      // Partition-scoped transaction_id tests
+      await runTest(() => testDuplicateTransactionIdsAcrossPartitions(client));
+      await runTest(() => testBatchAckWithDuplicateTransactionIds(client));
+      await runTest(() => testDLQWithDuplicateTransactionIds(client));
+      await runTest(() => testAnalyticsAPIWithDuplicateTransactionIds(client));
     }
     
     // ============================================

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "queen-mq",
-  "version": "0.2.11",
+  "version": "0.2.23",
   "type": "module",
   "description": "High-performance C++ message queue backed by PostgreSQL",
   "main": "client-js/client/index.js",