queen-mq 0.6.4 → 0.7.4

package/README.md

@@ -614,7 +614,7 @@ const messages: Message<OrderData>[] = await queen.queue('orders').pop()
 - **[Complete V2 Guide](client-v2/README.md)** - Full tutorial with all features (94 test examples)
 - **[HTTP API Reference](https://github.com/smartpricing/queen/blob/master/server/API.md)** - Raw HTTP endpoints
 - **[Server Guide](https://github.com/smartpricing/queen/blob/master/server/README.md)** - Server setup and configuration
-- **[Architecture Guide](https://github.com/smartpricing/queen/blob/master/docs/ARCHITECTURE.md)** - Deep dive into internals
+- **[Architecture Guide](https://github.com/smartpricing/queen/blob/master/documentation/ARCHITECTURE.md)** - Deep dive into internals
 
 ---
 

package/client-v2/Queen.js

@@ -75,7 +75,7 @@ export class Queen {
   }
 
   #createHttpClient() {
-    const { urls, timeoutMillis, retryAttempts, retryDelayMillis, loadBalancingStrategy, enableFailover } = this.#config
+    const { urls, timeoutMillis, retryAttempts, retryDelayMillis, loadBalancingStrategy, affinityHashRing, healthRetryAfterMillis, enableFailover } = this.#config
 
     if (urls.length === 1) {
       // Single server
@@ -88,7 +88,10 @@ export class Queen {
     }
 
     // Multiple servers with load balancing
-    const loadBalancer = new LoadBalancer(urls, loadBalancingStrategy)
+    const loadBalancer = new LoadBalancer(urls, loadBalancingStrategy, {
+      affinityHashRing,
+      healthRetryAfterMillis
+    })
     return new HttpClient({
       loadBalancer,
       timeoutMillis,

package/client-v2/README.md

@@ -43,16 +43,67 @@ const queen = new Queen(['http://server1:6632', 'http://server2:6632'])
 
 // Or with full configuration
 const queen = new Queen({
-  urls: ['http://server1:6632', 'http://server2:6632'],
+  urls: ['http://server1:6632', 'http://server2:6632', 'http://server3:6632'],
   timeoutMillis: 30000,
   retryAttempts: 3,
-  loadBalancingStrategy: 'round-robin', // or 'session'
+  loadBalancingStrategy: 'affinity',  // 'affinity', 'round-robin', or 'session'
+  affinityHashRing: 150,               // Virtual nodes per server (for affinity mode)
   enableFailover: true
 })
 ```
 
 That's it! You're connected. Now let's do something fun. 🎉
 
+### Load Balancing Strategies
+
+When connecting to multiple Queen servers, you can choose how requests are distributed:
+
+#### Affinity Mode (Recommended for Production)
+
+Uses consistent hashing with virtual nodes to route consumer groups to the same backend server. This optimizes database queries by consolidating poll intentions.
+
+```javascript
+const queen = new Queen({
+  urls: ['http://server1:6632', 'http://server2:6632', 'http://server3:6632'],
+  loadBalancingStrategy: 'affinity',
+  affinityHashRing: 150  // Virtual nodes per server (default: 150)
+})
+```
+
+**Benefits:**
+- ✅ Same consumer group always routes to same server
+- ✅ Poll intentions consolidated → optimized DB queries
+- ✅ Graceful failover (only ~33% of keys move if server fails)
+- ✅ Works great with 3-server HA setup
+
+**How it works:**
+1. Each consumer group generates an affinity key: `queue:partition:consumerGroup`
+2. Key is hashed and mapped to a virtual node on the ring
+3. Virtual node maps to a real backend server
+4. Same key always routes to same server
+
+#### Round-Robin Mode
+
+Cycles through servers in order. Simple but doesn't optimize for poll intention consolidation.
+
+```javascript
+const queen = new Queen({
+  urls: ['http://server1:6632', 'http://server2:6632'],
+  loadBalancingStrategy: 'round-robin'
+})
+```
+
+#### Session Mode
+
+Sticky sessions - each client instance sticks to one server.
+
+```javascript
+const queen = new Queen({
+  urls: ['http://server1:6632', 'http://server2:6632'],
+  loadBalancingStrategy: 'session'
+})
+```
+
 ---
 
 ## Part 1: Hello Queue!

package/client-v2/builders/QueueBuilder.js

@@ -48,6 +48,26 @@ export class QueueBuilder {
     this.#queueName = queueName
   }
 
+  // ===========================
+  // Affinity Key Generation
+  // ===========================
+
+  /**
+   * Generate affinity key for consistent routing
+   * Matches server's PollIntention::grouping_key() format
+   * Format: queue:partition:consumerGroup or namespace:task:consumerGroup
+   */
+  #getAffinityKey() {
+    if (this.#queueName) {
+      // Queue-based routing: queue:partition:consumerGroup
+      return `${this.#queueName}:${this.#partition || '*'}:${this.#group || '__QUEUE_MODE__'}`
+    } else if (this.#namespace || this.#task) {
+      // Namespace/task-based routing: namespace:task:consumerGroup
+      return `${this.#namespace || '*'}:${this.#task || '*'}:${this.#group || '__QUEUE_MODE__'}`
+    }
+    return null
+  }
+
   // ===========================
   // Queue Configuration Methods
   // ===========================
@@ -270,7 +290,10 @@ export class QueueBuilder {
       if (this.#subscriptionMode) params.append('subscriptionMode', this.#subscriptionMode)
       if (this.#subscriptionFrom) params.append('subscriptionFrom', this.#subscriptionFrom)
 
-      const result = await this.#httpClient.get(`${path}?${params}`, this.#timeoutMillis + 5000)
+      // Generate affinity key for consistent routing to same backend
+      const affinityKey = this.#getAffinityKey()
+      
+      const result = await this.#httpClient.get(`${path}?${params}`, this.#timeoutMillis + 5000, affinityKey)
 
       if (!result || !result.messages) {
         logger.log('QueueBuilder.pop', { status: 'no-messages' })

package/client-v2/consumer/ConsumerManager.js

@@ -13,6 +13,22 @@ export class ConsumerManager {
     this.#queen = queen
   }
 
+  /**
+   * Generate affinity key for consistent routing
+   * Matches server's PollIntention::grouping_key() format
+   * Format: queue:partition:consumerGroup or namespace:task:consumerGroup
+   */
+  #getAffinityKey(queue, partition, namespace, task, group) {
+    if (queue) {
+      // Queue-based routing: queue:partition:consumerGroup
+      return `${queue}:${partition || '*'}:${group || '__QUEUE_MODE__'}`
+    } else if (namespace || task) {
+      // Namespace/task-based routing: namespace:task:consumerGroup
+      return `${namespace || '*'}:${task || '*'}:${group || '__QUEUE_MODE__'}`
+    }
+    return null
+  }
+
   async start(handler, options) {
     const {
       queue,
@@ -52,6 +68,9 @@ export class ConsumerManager {
     // Build the path and params for pop requests
     const path = this.#buildPath(queue, partition, namespace, task)
     const baseParams = this.#buildParams(batch, wait, timeoutMillis, group, subscriptionMode, subscriptionFrom, namespace, task, autoAck)
+    
+    // Generate affinity key for consistent routing to same backend
+    const affinityKey = this.#getAffinityKey(queue, partition, namespace, task, group)
 
     // Start workers
     const workers = []
@@ -67,7 +86,8 @@ export class ConsumerManager {
         renewLeaseIntervalMillis,
         each,
         signal,
-        group  // Pass consumer group to workers
+        group,  // Pass consumer group to workers
+        affinityKey  // Pass affinity key to workers
       }))
     }
 
@@ -91,7 +111,8 @@ export class ConsumerManager {
       renewLeaseIntervalMillis,
       each,
       signal,
-      group
+      group,
+      affinityKey
     } = options
 
     logger.log('ConsumerManager.worker', { workerId, status: 'started', limit, idleMillis })
@@ -122,9 +143,9 @@ export class ConsumerManager {
       }
 
       try {
-        // Pop messages
+        // Pop messages with affinity key for consistent routing
         const clientTimeout = wait ? timeoutMillis + 5000 : timeoutMillis
-        const result = await this.#httpClient.get(`${path}?${baseParams}`, clientTimeout)
+        const result = await this.#httpClient.get(`${path}?${baseParams}`, clientTimeout, affinityKey)
 
         // Handle empty response
         if (!result || !result.messages || result.messages.length === 0) {

package/client-v2/http/HttpClient.js

@@ -145,7 +145,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 +154,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 +167,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 +204,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/utils/defaults.js

@@ -10,8 +10,10 @@ 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
 }
 
 export const QUEUE_DEFAULTS = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "queen-mq",
-  "version": "0.6.4",
+  "version": "0.7.4",
   "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/maintenance.js

@@ -63,7 +63,7 @@ export async function test_maintenance_mode(client = null) {
     const consumePromise = (async () => {
       while (consumerActive) {
         try {
-          const messages = await queen.queue(QUEUE_NAME).batch(10).wait(true).limit(1).each().pop();
+          const messages = await queen.queue(QUEUE_NAME).batch(10).wait(false).limit(1).each().pop();
           
           if (messages && messages.length > 0) {
             receivedCount += messages.length;