queen-mq 0.6.4 → 0.12.0

package/client-v2/http/HttpClient.js

@@ -11,6 +11,7 @@ export class HttpClient {
   #retryAttempts
   #retryDelayMillis
   #enableFailover
+  #bearerToken
 
   constructor(options = {}) {
     const {
@@ -19,7 +20,8 @@ export class HttpClient {
       timeoutMillis = 30000,
       retryAttempts = 3,
       retryDelayMillis = 1000,
-      enableFailover = true
+      enableFailover = true,
+      bearerToken = null
     } = options
 
     this.#baseUrl = baseUrl
@@ -28,13 +30,15 @@ export class HttpClient {
     this.#retryAttempts = retryAttempts
     this.#retryDelayMillis = retryDelayMillis
     this.#enableFailover = enableFailover
+    this.#bearerToken = bearerToken
     
     logger.log('HttpClient.constructor', { 
       hasLoadBalancer: !!loadBalancer, 
       baseUrl: baseUrl || 'load-balanced', 
       timeoutMillis, 
       retryAttempts,
-      enableFailover 
+      enableFailover,
+      hasAuth: !!bearerToken
     })
   }
 
@@ -46,10 +50,15 @@ export class HttpClient {
     const timeoutId = setTimeout(() => controller.abort(), effectiveTimeout)
 
     try {
+      const headers = { 'Content-Type': 'application/json' }
+      if (this.#bearerToken) {
+        headers['Authorization'] = `Bearer ${this.#bearerToken}`
+      }
+
       const options = {
         method,
         signal: controller.signal,
-        headers: { 'Content-Type': 'application/json' }
+        headers
       }
 
       if (body) {
@@ -145,7 +154,7 @@ export class HttpClient {
     throw lastError
   }
 
-  async #requestWithFailover(method, path, body = null, requestTimeoutMillis = null) {
+  async #requestWithFailover(method, path, body = null, requestTimeoutMillis = null, affinityKey = null) {
     if (!this.#loadBalancer || !this.#enableFailover) {
       return this.#requestWithRetry(method, path, body, requestTimeoutMillis)
     }
@@ -154,10 +163,11 @@ export class HttpClient {
     const attemptedUrls = new Set()
     let lastError = null
 
-    logger.log('HttpClient.failover', { method, path, totalServers: urls.length })
+    logger.log('HttpClient.failover', { method, path, totalServers: urls.length, affinityKey })
 
     for (let i = 0; i < urls.length; i++) {
-      const url = this.#loadBalancer.getNextUrl()
+      // Pass affinity key to load balancer for consistent routing
+      const url = this.#loadBalancer.getNextUrl(affinityKey)
 
       if (attemptedUrls.has(url)) {
         continue
@@ -166,9 +176,20 @@ export class HttpClient {
       attemptedUrls.add(url)
 
       try {
-        return await this.#executeRequest(url + path, method, body, requestTimeoutMillis)
+        const result = await this.#executeRequest(url + path, method, body, requestTimeoutMillis)
+        
+        // Mark backend as healthy on success
+        this.#loadBalancer.markHealthy(url)
+        
+        return result
       } catch (error) {
         lastError = error
+        
+        // Mark backend as unhealthy on failure (5xx or network errors)
+        if (!error.status || error.status >= 500) {
+          this.#loadBalancer.markUnhealthy(url)
+        }
+        
         logger.warn('HttpClient.failover', { url, method, path, error: error.message })
         console.warn(`Request failed for ${url}: ${method} ${path} - ${error.message}`)
 
@@ -192,20 +213,20 @@ export class HttpClient {
     return this.#baseUrl
   }
 
-  async get(path, requestTimeoutMillis = null) {
-    return this.#requestWithFailover('GET', path, null, requestTimeoutMillis)
+  async get(path, requestTimeoutMillis = null, affinityKey = null) {
+    return this.#requestWithFailover('GET', path, null, requestTimeoutMillis, affinityKey)
   }
 
-  async post(path, body = null, requestTimeoutMillis = null) {
-    return this.#requestWithFailover('POST', path, body, requestTimeoutMillis)
+  async post(path, body = null, requestTimeoutMillis = null, affinityKey = null) {
+    return this.#requestWithFailover('POST', path, body, requestTimeoutMillis, affinityKey)
   }
 
-  async put(path, body = null, requestTimeoutMillis = null) {
-    return this.#requestWithFailover('PUT', path, body, requestTimeoutMillis)
+  async put(path, body = null, requestTimeoutMillis = null, affinityKey = null) {
+    return this.#requestWithFailover('PUT', path, body, requestTimeoutMillis, affinityKey)
   }
 
-  async delete(path, requestTimeoutMillis = null) {
-    return this.#requestWithFailover('DELETE', path, null, requestTimeoutMillis)
+  async delete(path, requestTimeoutMillis = null, affinityKey = null) {
+    return this.#requestWithFailover('DELETE', path, null, requestTimeoutMillis, affinityKey)
   }
 
   getLoadBalancer() {

package/client-v2/http/LoadBalancer.js

@@ -1,5 +1,6 @@
 /**
  * Load balancer for distributing requests across multiple servers
+ * Supports round-robin, session, and affinity-based routing with virtual nodes
  */
 
 export class LoadBalancer {
@@ -8,32 +9,245 @@ export class LoadBalancer {
   #currentIndex = 0
   #sessionMap = new Map()
   #sessionId
+  #healthStatus
+  #virtualNodes = null
+  #affinityHashRing
+  #healthRetryAfterMillis
 
-  constructor(urls, strategy = 'round-robin') {
+  constructor(urls, strategy = 'round-robin', options = {}) {
     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)}`
+    
+    // Virtual node replicas for affinity strategy (default: 150)
+    this.#affinityHashRing = options.affinityHashRing || 150
+    
+    // Health retry interval (default: 30 seconds)
+    this.#healthRetryAfterMillis = options.healthRetryAfterMillis || 30000
+    
+    // Initialize health status with last failure time
+    this.#healthStatus = new Map(this.#urls.map(url => [url, { 
+      healthy: true, 
+      failures: 0,
+      lastFailure: null
+    }]))
+    
+    // Build virtual node ring for affinity strategy
+    if (strategy === 'affinity') {
+      this.#buildVirtualNodeRing()
+    }
+  }
+
+  /**
+   * Build virtual node ring for consistent hashing
+   * Each real server gets multiple virtual positions in the hash space
+   */
+  #buildVirtualNodeRing() {
+    this.#virtualNodes = []
+    
+    for (const url of this.#urls) {
+      for (let i = 0; i < this.#affinityHashRing; i++) {
+        // Create virtual node identifier
+        const vnodeKey = `${url}#vnode${i}`
+        const hash = this.#hashString(vnodeKey)
+        
+        this.#virtualNodes.push({
+          hash,
+          realServer: url
+        })
+      }
+    }
+    
+    // Sort by hash value to create the ring
+    this.#virtualNodes.sort((a, b) => a.hash - b.hash)
+  }
+
+  /**
+   * Rebuild virtual node ring with specified URLs
+   * @param {Array<string>} urls - URLs to include in the ring (if not provided, uses all healthy URLs)
+   */
+  #rebuildVirtualNodeRing(urls = null) {
+    const urlsToInclude = urls || this.#urls.filter(url => this.#healthStatus.get(url)?.healthy !== false)
+    
+    this.#virtualNodes = []
+    
+    for (const url of urlsToInclude) {
+      for (let i = 0; i < this.#affinityHashRing; i++) {
+        const vnodeKey = `${url}#vnode${i}`
+        const hash = this.#hashString(vnodeKey)
+        
+        this.#virtualNodes.push({
+          hash,
+          realServer: url
+        })
+      }
+    }
+    
+    this.#virtualNodes.sort((a, b) => a.hash - b.hash)
   }
 
   getNextUrl(sessionKey = null) {
     const key = sessionKey || this.#sessionId
+    
+    // Get healthy URLs + unhealthy URLs that are ready for retry
+    const now = Date.now()
+    let needRingRebuild = false
+    
+    const healthyUrls = this.#urls.filter(url => {
+      const status = this.#healthStatus.get(url)
+      if (status.healthy) return true
+      
+      // Allow retry of unhealthy backends after configured interval
+      if (status.lastFailure && (now - status.lastFailure) >= this.#healthRetryAfterMillis) {
+        needRingRebuild = true  // Need to rebuild ring to include this server's vnodes
+        return true
+      }
+      
+      return false
+    })
+    
+    // Rebuild vnode ring if we have servers eligible for retry
+    // Pass healthyUrls so it includes servers ready for retry
+    if (needRingRebuild && this.#virtualNodes) {
+      this.#rebuildVirtualNodeRing(healthyUrls)
+    }
+    
+    if (healthyUrls.length === 0) {
+      // All backends unhealthy, try any backend as fallback
+      return this.#urls[this.#currentIndex % this.#urls.length]
+    }
 
+    if (this.#strategy === 'affinity') {
+      // Virtual node consistent hashing
+      return this.#getAffinityUrl(key, healthyUrls)
+    }
+    
     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
+        this.#currentIndex = (this.#currentIndex + 1) % healthyUrls.length
       }
-      return this.#urls[this.#sessionMap.get(key)]
+      
+      const assignedUrl = this.#urls[this.#sessionMap.get(key)]
+      // If assigned URL is unhealthy, reassign
+      if (!healthyUrls.includes(assignedUrl)) {
+        const newIndex = this.#currentIndex % healthyUrls.length
+        this.#sessionMap.set(key, newIndex)
+        this.#currentIndex = (this.#currentIndex + 1) % healthyUrls.length
+        return healthyUrls[newIndex]
+      }
+      
+      return assignedUrl
     }
 
-    // Round robin: cycle through URLs
-    const url = this.#urls[this.#currentIndex]
-    this.#currentIndex = (this.#currentIndex + 1) % this.#urls.length
+    // Round robin: cycle through healthy URLs only
+    const url = healthyUrls[this.#currentIndex % healthyUrls.length]
+    this.#currentIndex = (this.#currentIndex + 1) % healthyUrls.length
     return url
   }
 
+  /**
+   * Affinity-based routing using consistent hashing with virtual nodes
+   * Same key always routes to same backend (unless unhealthy)
+   */
+  #getAffinityUrl(key, healthyUrls) {
+    if (!key || !this.#virtualNodes || this.#virtualNodes.length === 0) {
+      // No key or no vnodes, fall back to round-robin
+      return healthyUrls[this.#currentIndex++ % healthyUrls.length]
+    }
+    
+    // Hash the consumer group key
+    const keyHash = this.#hashString(key)
+    
+    // Binary search to find the first vnode >= keyHash (clockwise on ring)
+    let left = 0
+    let right = this.#virtualNodes.length - 1
+    let result = 0
+    
+    while (left <= right) {
+      const mid = Math.floor((left + right) / 2)
+      if (this.#virtualNodes[mid].hash >= keyHash) {
+        result = mid
+        right = mid - 1
+      } else {
+        left = mid + 1
+      }
+    }
+    
+    // Walk forward on the ring to find first healthy server
+    const startIdx = result
+    for (let i = 0; i < this.#virtualNodes.length; i++) {
+      const idx = (startIdx + i) % this.#virtualNodes.length
+      const vnode = this.#virtualNodes[idx]
+      
+      if (healthyUrls.includes(vnode.realServer)) {
+        return vnode.realServer
+      }
+    }
+    
+    // Fallback (should never happen if healthyUrls is not empty)
+    return healthyUrls[0]
+  }
+
+  /**
+   * FNV-1a hash function for consistent hashing
+   */
+  #hashString(str) {
+    let hash = 2166136261 // FNV offset basis
+    for (let i = 0; i < str.length; i++) {
+      hash ^= str.charCodeAt(i)
+      hash += (hash << 1) + (hash << 4) + (hash << 7) + (hash << 8) + (hash << 24)
+    }
+    return hash >>> 0 // Convert to unsigned 32-bit integer
+  }
+
+  /**
+   * Mark a backend as unhealthy after failure
+   */
+  markUnhealthy(url) {
+    const status = this.#healthStatus.get(url)
+    if (status) {
+      status.healthy = false
+      status.failures++
+      status.lastFailure = Date.now()
+      
+      const retryInSeconds = (this.#healthRetryAfterMillis / 1000).toFixed(0)
+      
+      // Rebuild vnode ring to exclude unhealthy server
+      if (this.#virtualNodes) {
+        this.#rebuildVirtualNodeRing()
+      }
+    }
+  }
+
+  /**
+   * Mark a backend as healthy after success
+   */
+  markHealthy(url) {
+    const status = this.#healthStatus.get(url)
+    if (!status) return
+    
+    const wasUnhealthy = status.healthy === false
+    
+    status.healthy = true
+    status.failures = 0
+    status.lastFailure = null
+    
+    // Rebuild vnode ring to include recovered server
+    if (this.#virtualNodes && wasUnhealthy) {
+      this.#rebuildVirtualNodeRing()
+    }
+  }
+
+  /**
+   * Get health status of all backends
+   */
+  getHealthStatus() {
+    return new Map(this.#healthStatus)
+  }
+
   getAllUrls() {
     return [...this.#urls]
   }
@@ -41,6 +255,13 @@ export class LoadBalancer {
   getStrategy() {
     return this.#strategy
   }
+  
+  /**
+   * Get number of virtual nodes in the ring
+   */
+  getVirtualNodeCount() {
+    return this.#virtualNodes ? this.#virtualNodes.length : 0
+  }
 
   reset() {
     this.#currentIndex = 0

package/client-v2/index.js

@@ -3,5 +3,6 @@
  */
 
 export { Queen } from './Queen.js'
+export { Admin } from './admin/Admin.js'
 export { CLIENT_DEFAULTS, QUEUE_DEFAULTS, CONSUME_DEFAULTS, POP_DEFAULTS, BUFFER_DEFAULTS } from './utils/defaults.js'
 

package/client-v2/utils/defaults.js

@@ -10,8 +10,11 @@ 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
+  loadBalancingStrategy: 'affinity',   // 'round-robin', 'session', or 'affinity'
+  affinityHashRing: 128,               // Number of virtual nodes per server for affinity strategy
+  enableFailover: true,                // Auto-failover to other servers
+  healthRetryAfterMillis: 5000,        // Retry unhealthy backends after 5 seconds
+  bearerToken: null                    // Bearer token for proxy authentication
 }
 
 export const QUEUE_DEFAULTS = {

package/client-v2/utils/logger.js

@@ -1,9 +1,20 @@
 /**
  * Logger utility for Queen Client v2
- * Controlled by QUEEN_CLIENT_LOG environment variable
+ * Controlled by QUEEN_CLIENT_LOG environment variable (Node.js)
+ * or window.QUEEN_CLIENT_LOG (Browser)
  */
 
-const LOG_ENABLED = process.env.QUEEN_CLIENT_LOG === 'true'
+const LOG_ENABLED = (() => {
+  // Node.js environment
+  if (typeof process !== 'undefined' && process.env) {
+    return process.env.QUEEN_CLIENT_LOG === 'true'
+  }
+  // Browser environment
+  if (typeof window !== 'undefined') {
+    return window.QUEEN_CLIENT_LOG === true
+  }
+  return false
+})()
 
 /**
  * Get formatted timestamp

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "queen-mq",
-  "version": "0.6.4",
+  "version": "0.12.0",
   "type": "module",
   "description": "High-performance C++ message queue backed by PostgreSQL",
   "main": "client-v2/index.js",
@@ -8,12 +8,13 @@
     "test": "node test-v2/run.js human"
   },
   "files": [
-    "client-v2/**/*", 
+    "client-v2/**/*",
     "test-v2/**/*",
     "README.md"
   ],
   "dependencies": {
     "axios": "^1.12.2",
+    "pg": "^8.16.3",
     "uuid": "^13.0.0"
   },
   "engines": {

package/test-v2/consume.js

@@ -51,60 +51,6 @@ export async function testConsumerTrace(client) {
     return { success: msgToReturn !== null, message: 'Consumer test completed successfully' }
 }
 
-export async function testConsumerNamespace(client) { 
-    const queue = await client.queue('test-queue-v2-namespace')
-    .namespace('test-namespace')
-    .create()
-    if (!queue.configured) {
-        return { success: false, message: 'Queue not created' }
-    }
-
-    await client
-    .queue('test-queue-v2-namespace')
-    .push([{ data: { message: 'Hello, world!' } }])
-
-    let msgToReturn = null
-
-    await client
-    .queue()
-    .namespace('test-namespace')
-    .batch(1)
-    .limit(1)
-    .each()
-    .consume(async msg => {
-        msgToReturn = msg
-    })
-
-    return { success: msgToReturn !== null, message: 'Consumer test completed successfully' }
-}
-
-export async function testConsumerTask(client) { 
-    const queue = await client.queue('test-queue-v2-task')
-    .task('test-task')
-    .create()
-    if (!queue.configured) {
-        return { success: false, message: 'Queue not created' }
-    }
-
-    await client
-    .queue('test-queue-v2-task')
-    .push([{ data: { message: 'Hello, world!' } }])
-
-    let msgToReturn = null
-
-    await client
-    .queue()
-    .task('test-task')
-    .batch(1)
-    .limit(1)
-    .each()
-    .consume(async msg => {
-        msgToReturn = msg
-    })
-
-    return { success: msgToReturn !== null, message: 'Consumer test completed successfully' }
-}
-
 export async function testConsumerWithPartition(client) { 
     const queue = await client.queue('test-queue-v2-consume-with-partition').create()
     if (!queue.configured) {
@@ -252,6 +198,7 @@ export async function testConsumerOrderingBatch(client) {
 
 
 export async function testConsumerBatchConsumeBatch(client) { 
+    await client.queue('test-queue-v2-consume-batch').delete()
     const queue = await client.queue('test-queue-v2-consume-batch').create()
     if (!queue.configured) {
         return { success: false, message: 'Queue not created' }
@@ -271,7 +218,7 @@ export async function testConsumerBatchConsumeBatch(client) {
     .queue('test-queue-v2-consume-batch')
     .batch(10)
     .wait(false)
-    .limit(1)
+    .limit(3)
     .consume(async msgs => {
         msgLength = msgs.length
     })
@@ -465,12 +412,13 @@ export async function manualAck(client) {
 
     await client
     .queue('test-queue-v2-manual-ack')
-    .concurrency(10)
+    .concurrency(1)
     .subscriptionMode('from_beginning')
     .batch(1000)
     .wait(false)
-    .limit(1)
+    .limit(10000)
     .consume(async msgs => {
+        console.log('Messages: ' + msgs.length)
         for (const msg of msgs) {
             if (lastId === null) {
                 lastId = msg.data.id
@@ -525,6 +473,7 @@ export async function retries(client) {
     .limit(300)  // Allow up to 300 messages (3 batches of 100)
     .consume(async msgs => {
         attemptCount++;
+        console.log('Attempt: ' + attemptCount)
         if (attemptCount < 3) {
             // Fail first 2 attempts, succeed on 3rd
             throw new Error('Test error - triggering retry')

package/test-v2/load.js

@@ -11,7 +11,7 @@ export async function testLoad(client) {
     let messages = [];
     for (let i = 0; i < messagesToPush; i++) {
         messages.push({ data: { id: i } })
-        if (messages.length >= 10000) {
+        if (messages.length >= 100) {
             await client.queue('test-queue-v2-load').push(messages)
             messages = [];
         }
@@ -24,11 +24,10 @@ export async function testLoad(client) {
     await client
     .queue('test-queue-v2-load')
     .concurrency(10)
-    .batch(10000)
+    .batch(100)
     .wait(false)
-    .limit(1)
+    .limit(10000)
     .consume(async msgs => {
-        console.log(`Messages: ${msgs.length}`)
         for (const msg of msgs) {
             if (lastId === null) {
                 lastId = msg.data.id
@@ -60,35 +59,37 @@ export async function testLoadPartition(client) {
 
     let messages = [];
     let k = 0
-    for (let i = 0; i < messagesToPush; i++) {
+    for (let k = 0; k < 10; k++) {
+    for (let i = 0; i < messagesToPush / 10; i++) {
         messages.push({ data: { id: i } })
-        if (messages.length >= 10000) {
+        if (messages.length >= 100) {
             await client
             .queue('test-queue-v2-load-partition')
             .partition(k.toString())
             .push(messages)
             messages = [];
-            k++;
         }
     }
-    await client.queue('test-queue-v2-load-partition').push(messages)    
+    }  
 
     let uniqueIds = new Set();
-    let lastId = null;
+    
     
     for (let i = 0; i < 10; i++) {
+        let lastId = null;
     await client
     .queue('test-queue-v2-load-partition')
     .partition(i.toString())
-    .batch(10000)
+    .batch(100)
     .wait(false)
-    .limit(1)
+    .limit(10000)
     .consume(async msgs => {
         for (const msg of msgs) {
             if (lastId === null) {
                 lastId = msg.data.id
             } else {
                 if (msg.data.id !== lastId + 1) {
+                    console.log(`Message ordering violation: ${msg.data.id} !== ${lastId + 1}`)
                     throw new Error('Message ordering violation')
                 }
                 lastId = msg.data.id
@@ -98,14 +99,15 @@ export async function testLoadPartition(client) {
     })
     }
 
+    console.log(uniqueIds.size, messagesToPush)
     const uniqueIdsCount = uniqueIds.size;
 
-    return { success: uniqueIdsCount === messagesToPush, message: 'Load test completed successfully' }
+    return { success: uniqueIdsCount === messagesToPush / 10, message: 'Load test completed successfully' }
 }
 
 export async function testLoadConsumerGroup(client) { 
     const queue = await client
-    .queue('test-queue-v2-load-consumer-group')
+    .queue('')
     .create()
     if (!queue.configured) {
         return { success: false, message: 'Queue not created' }
@@ -116,7 +118,7 @@ export async function testLoadConsumerGroup(client) {
     let messages = [];
     for (let i = 0; i < messagesToPush; i++) {
         messages.push({ data: { id: i } })
-        if (messages.length >= 10000) {
+        if (messages.length >= 100) {
             await client.queue('test-queue-v2-load-consumer-group').push(messages)
             messages = [];
         }
@@ -129,11 +131,11 @@ export async function testLoadConsumerGroup(client) {
     await client
     .queue('test-queue-v2-load-consumer-group')
     .group('test-consumer-group-a')
-    .subscriptionMode('from_beginning')
+    .subscriptionMode('all')
     .concurrency(10)
-    .batch(10000)
+    .batch(100)
     .wait(false)
-    .limit(1)
+    .limit(10000)
     .consume(async msgs => {
         for (const msg of msgs) {
             if (lastIdA === null) {
@@ -154,11 +156,11 @@ export async function testLoadConsumerGroup(client) {
     await client
     .queue('test-queue-v2-load-consumer-group')
     .group('test-consumer-group-b')
-    .subscriptionMode('from_beginning')
+    .subscriptionMode('all')
     .concurrency(10)
-    .batch(10000)
+    .batch(100)
     .wait(false)
-    .limit(1)
+    .limit(10000)
     .consume(async msgs => {
         for (const msg of msgs) {
             if (lastIdB === null) {