update config

Author: ndyakov

.github/copilot-instructions.md

@@ -307,6 +307,19 @@ func (opt *Options) init() {
 }
 ```
 
+### Hitless Upgrade Scaling
+
+**MaxWorkers**: `min(10, max(1, PoolSize/3))`
+- Scales with pool size but caps at 10 workers
+- Minimum 1 worker for very small pools
+- Minimum 10 when explicitly set
+
+**HandoffQueueSize**: `max(8×MaxWorkers, max(50, PoolSize/2))` capped by `2×PoolSize`
+- Hybrid scaling: worker-based (8 per worker) and pool-based (PoolSize/2)
+- Takes the larger value for optimal burst handling
+- Minimum 50 when explicitly set
+- Memory-efficient cap at 2× pool size
+
 ### Push Notification Handling
 
 ```go

hitless/README.md

@@ -46,8 +46,17 @@ Config: &hitless.Config{
 - **On-demand**: Workers created when needed, cleaned up when idle
 
 ### Queue Sizing
-- **Auto-calculated**: `10 × MaxWorkers`, capped by pool size
-- **Always capped**: Queue size never exceeds pool size
+- **Auto-calculated**: `max(8 × MaxWorkers, max(50, PoolSize/2))` - hybrid scaling
+  - Worker-based: 8 handoffs per worker for burst processing
+  - Pool-based: Scales with pool size (minimum 50, up to PoolSize/2)
+  - Takes the larger of the two for optimal performance
+- **Explicit values**: `max(50, set_value)` - enforces minimum 50 when set
+- **Always capped**: Queue size never exceeds `2 × PoolSize` for memory efficiency
+
+**Examples:**
+- Pool 10: Queue 50 (max(8×3, max(50, 5)) = max(24, 50) = 50)
+- Pool 100: Queue 80 (max(8×10, max(50, 50)) = max(80, 50) = 80)
+- Pool 200: Queue 100 (max(8×10, max(50, 100)) = max(80, 100) = 100)
 
 ## Notification Hooks
 

hitless/config.go

@@ -97,9 +97,10 @@ type Config struct {
 
 	// HandoffQueueSize is the size of the buffered channel used to queue handoff requests.
 	// If the queue is full, new handoff requests will be rejected.
-	// Always capped by pool size since you can't handoff more connections than exist.
+	// Scales with both worker count and pool size for better burst handling.
 	//
-	// Default: 10x max workers, capped by pool size, min 2
+	// Default: max(8x workers, max(50, PoolSize/2)), capped by 2x pool size
+	// When set: min 50, capped by 2x pool size
 	HandoffQueueSize int
 
 	// PostHandoffRelaxedDuration is how long to keep relaxed timeouts on the new connection
@@ -230,32 +231,27 @@ func (c *Config) ApplyDefaultsWithPoolSize(poolSize int) *Config {
 		result.HandoffTimeout = c.HandoffTimeout
 	}
 
-	// Apply defaults for integer fields (zero means not set)
-	if c.HandoffQueueSize <= 0 {
-		result.HandoffQueueSize = defaults.HandoffQueueSize
-	} else {
-		result.HandoffQueueSize = c.HandoffQueueSize
-	}
-
 	// Copy worker configuration
 	result.MaxWorkers = c.MaxWorkers
 
 	// Apply worker defaults based on pool size
 	result.applyWorkerDefaults(poolSize)
 
-	// Apply queue size defaults based on max workers, capped by pool size
+	// Apply queue size defaults with hybrid scaling approach
 	if c.HandoffQueueSize <= 0 {
-		// Queue size: 10x max workers, but never more than pool size
-		workerBasedSize := result.MaxWorkers * 10
-		result.HandoffQueueSize = util.Min(workerBasedSize, poolSize)
+		// Default: max(8x workers, max(50, PoolSize/2)), capped by 2x pool size
+		workerBasedSize := result.MaxWorkers * 8
+		poolBasedSize := util.Max(50, poolSize/2)
+		result.HandoffQueueSize = util.Max(workerBasedSize, poolBasedSize)
 	} else {
-		result.HandoffQueueSize = c.HandoffQueueSize
+		// When explicitly set: enforce minimum of 50
+		result.HandoffQueueSize = util.Max(50, c.HandoffQueueSize)
 	}
 
-	// Always cap queue size by pool size - no point having more queue slots than connections
-	result.HandoffQueueSize = util.Min(result.HandoffQueueSize, poolSize)
+	// Always cap queue size by 2x pool size - balances burst capacity with memory efficiency
+	result.HandoffQueueSize = util.Min(result.HandoffQueueSize, poolSize*2)
 
-	// Ensure minimum queue size of 2
+	// Ensure minimum queue size of 2 (fallback for very small pools)
 	if result.HandoffQueueSize < 2 {
 		result.HandoffQueueSize = 2
 	}

hitless/config_test.go

@@ -116,13 +116,15 @@ func TestApplyDefaults(t *testing.T) {
 			t.Errorf("Expected MaxWorkers to be > 0 after applying defaults, got %d", result.MaxWorkers)
 		}
 
-		// HandoffQueueSize should be auto-calculated (10 * MaxWorkers, capped by pool size)
-		workerBasedSize := result.MaxWorkers * 10
+		// HandoffQueueSize should be auto-calculated with hybrid scaling
+		workerBasedSize := result.MaxWorkers * 8
 		poolSize := 100 // Default pool size used in ApplyDefaults
-		expectedQueueSize := util.Min(workerBasedSize, poolSize)
+		poolBasedSize := util.Max(50, poolSize/2)
+		expectedQueueSize := util.Max(workerBasedSize, poolBasedSize)
+		expectedQueueSize = util.Min(expectedQueueSize, poolSize*2) // Cap by 2x pool size
 		if result.HandoffQueueSize != expectedQueueSize {
-			t.Errorf("Expected HandoffQueueSize to be %d (util.Min(10*MaxWorkers=%d, poolSize=%d)), got %d",
-				expectedQueueSize, workerBasedSize, poolSize, result.HandoffQueueSize)
+			t.Errorf("Expected HandoffQueueSize to be %d (max(8*MaxWorkers=%d, max(50, poolSize/2=%d)) capped by 2*poolSize=%d), got %d",
+				expectedQueueSize, workerBasedSize, poolBasedSize, poolSize*2, result.HandoffQueueSize)
 		}
 	})
 
@@ -139,24 +141,50 @@ func TestApplyDefaults(t *testing.T) {
 			t.Errorf("Expected MaxWorkers to be 12 (explicitly set), got %d", result.MaxWorkers)
 		}
 
-		// Should apply default for unset fields (auto-calculated queue size, capped by pool size)
-		workerBasedSize := result.MaxWorkers * 10
+		// Should apply default for unset fields (auto-calculated queue size with hybrid scaling)
+		workerBasedSize := result.MaxWorkers * 8
 		poolSize := 100 // Default pool size used in ApplyDefaults
-		expectedQueueSize := util.Min(workerBasedSize, poolSize)
+		poolBasedSize := util.Max(50, poolSize/2)
+		expectedQueueSize := util.Max(workerBasedSize, poolBasedSize)
+		expectedQueueSize = util.Min(expectedQueueSize, poolSize*2) // Cap by 2x pool size
 		if result.HandoffQueueSize != expectedQueueSize {
-			t.Errorf("Expected HandoffQueueSize to be %d (util.Min(10*MaxWorkers=%d, poolSize=%d)), got %d",
-				expectedQueueSize, workerBasedSize, poolSize, result.HandoffQueueSize)
+			t.Errorf("Expected HandoffQueueSize to be %d (max(8*MaxWorkers=%d, max(50, poolSize/2=%d)) capped by 2*poolSize=%d), got %d",
+				expectedQueueSize, workerBasedSize, poolBasedSize, poolSize*2, result.HandoffQueueSize)
 		}
 
-		// Test explicit queue size capping by pool size
+		// Test explicit queue size capping by 2x pool size
 		configWithLargeQueue := &Config{
 			MaxWorkers:       5,
-			HandoffQueueSize: 1000, // Much larger than pool size
+			HandoffQueueSize: 1000, // Much larger than 2x pool size
 		}
 
 		resultCapped := configWithLargeQueue.ApplyDefaultsWithPoolSize(20) // Small pool size
-		if resultCapped.HandoffQueueSize != 20 {
-			t.Errorf("Expected HandoffQueueSize to be capped by pool size (20), got %d", resultCapped.HandoffQueueSize)
+		expectedCap := 20 * 2 // 2x pool size = 40
+		if resultCapped.HandoffQueueSize != expectedCap {
+			t.Errorf("Expected HandoffQueueSize to be capped by 2x pool size (%d), got %d", expectedCap, resultCapped.HandoffQueueSize)
+		}
+
+		// Test explicit queue size minimum enforcement
+		configWithSmallQueue := &Config{
+			MaxWorkers:       5,
+			HandoffQueueSize: 10, // Below minimum of 50
+		}
+
+		resultMinimum := configWithSmallQueue.ApplyDefaultsWithPoolSize(100) // Large pool size
+		if resultMinimum.HandoffQueueSize != 50 {
+			t.Errorf("Expected HandoffQueueSize to be enforced minimum (50), got %d", resultMinimum.HandoffQueueSize)
+		}
+
+		// Test that large explicit values are capped by 2x pool size
+		configWithVeryLargeQueue := &Config{
+			MaxWorkers:       5,
+			HandoffQueueSize: 500, // Much larger than 2x pool size
+		}
+
+		resultVeryLarge := configWithVeryLargeQueue.ApplyDefaultsWithPoolSize(100) // Pool size 100
+		expectedVeryLargeCap := 100 * 2 // 2x pool size = 200
+		if resultVeryLarge.HandoffQueueSize != expectedVeryLargeCap {
+			t.Errorf("Expected very large HandoffQueueSize to be capped by 2x pool size (%d), got %d", expectedVeryLargeCap, resultVeryLarge.HandoffQueueSize)
 		}
 
 		if result.RelaxedTimeout != 10*time.Second {
@@ -183,13 +211,15 @@ func TestApplyDefaults(t *testing.T) {
 			t.Errorf("Expected MaxWorkers to be > 0 (auto-calculated), got %d", result.MaxWorkers)
 		}
 
-		// HandoffQueueSize should be auto-calculated (10 * MaxWorkers, capped by pool size)
-		workerBasedSize := result.MaxWorkers * 10
+		// HandoffQueueSize should be auto-calculated with hybrid scaling
+		workerBasedSize := result.MaxWorkers * 8
 		poolSize := 100 // Default pool size used in ApplyDefaults
-		expectedQueueSize := util.Min(workerBasedSize, poolSize)
+		poolBasedSize := util.Max(50, poolSize/2)
+		expectedQueueSize := util.Max(workerBasedSize, poolBasedSize)
+		expectedQueueSize = util.Min(expectedQueueSize, poolSize*2) // Cap by 2x pool size
 		if result.HandoffQueueSize != expectedQueueSize {
-			t.Errorf("Expected HandoffQueueSize to be %d (util.Min(10*MaxWorkers=%d, poolSize=%d)), got %d",
-				expectedQueueSize, workerBasedSize, poolSize, result.HandoffQueueSize)
+			t.Errorf("Expected HandoffQueueSize to be %d (max(8*MaxWorkers=%d, max(50, poolSize/2=%d)) capped by 2*poolSize=%d), got %d",
+				expectedQueueSize, workerBasedSize, poolBasedSize, poolSize*2, result.HandoffQueueSize)
 		}
 
 		if result.RelaxedTimeout != 10*time.Second {
@@ -294,19 +324,21 @@ func TestIntegrationWithApplyDefaults(t *testing.T) {
 			t.Errorf("Expected LogLevel to be 2, got %d", expectedConfig.LogLevel)
 		}
 
-		// Should apply defaults for missing fields (auto-calculated queue size, capped by pool size)
-		workerBasedSize := expectedConfig.MaxWorkers * 10
+		// Should apply defaults for missing fields (auto-calculated queue size with hybrid scaling)
+		workerBasedSize := expectedConfig.MaxWorkers * 8
 		poolSize := 100 // Default pool size used in ApplyDefaults
-		expectedQueueSize := util.Min(workerBasedSize, poolSize)
+		poolBasedSize := util.Max(50, poolSize/2)
+		expectedQueueSize := util.Max(workerBasedSize, poolBasedSize)
+		expectedQueueSize = util.Min(expectedQueueSize, poolSize*2) // Cap by 2x pool size
 		if expectedConfig.HandoffQueueSize != expectedQueueSize {
-			t.Errorf("Expected HandoffQueueSize to be %d (util.Min(10*MaxWorkers=%d, poolSize=%d)), got %d",
-				expectedQueueSize, workerBasedSize, poolSize, expectedConfig.HandoffQueueSize)
+			t.Errorf("Expected HandoffQueueSize to be %d (max(8*MaxWorkers=%d, max(50, poolSize/2=%d)) capped by 2*poolSize=%d), got %d",
+				expectedQueueSize, workerBasedSize, poolBasedSize, poolSize*2, expectedConfig.HandoffQueueSize)
 		}
 
-		// Test that queue size is always capped by pool size
-		if expectedConfig.HandoffQueueSize > poolSize {
-			t.Errorf("HandoffQueueSize (%d) should never exceed pool size (%d)",
-				expectedConfig.HandoffQueueSize, poolSize)
+		// Test that queue size is always capped by 2x pool size
+		if expectedConfig.HandoffQueueSize > poolSize*2 {
+			t.Errorf("HandoffQueueSize (%d) should never exceed 2x pool size (%d)",
+				expectedConfig.HandoffQueueSize, poolSize*2)
 		}
 
 		if expectedConfig.RelaxedTimeout != 10*time.Second {

hitless/pool_hook.go

@@ -273,7 +273,7 @@ func (ph *PoolHook) processHandoffRequest(request HandoffRequest) {
 				afterTime = handoffTimeout / 2
 			}
 
-			internal.Logger.Printf(context.Background(), "Handoff failed for connection WILL RETRY After %v: %v", afterTime, err)
+			internal.Logger.Printf(context.Background(), "Handoff failed for conn[%d] WILL RETRY After %v: %v", request.ConnID, afterTime, err)
 			time.AfterFunc(afterTime, func() {
 				if err := ph.queueHandoff(request.Conn); err != nil {
 					internal.Logger.Printf(context.Background(), "can't queue handoff for retry: %v", err)

internal/pool/pool.go

@@ -289,7 +289,7 @@ func (p *ConnPool) newConn(ctx context.Context, pooled bool) (*Conn, error) {
 	if pooled {
 		// If pool is full remove the cn on next Put.
 		currentPoolSize := p.poolSize.Load()
-		if currentPoolSize >= int32(p.cfg.PoolSize) {
+		if currentPoolSize >= p.cfg.PoolSize {
 			cn.pooled = false
 		} else {
 			p.poolSize.Add(1)

osscluster.go

@@ -20,6 +20,7 @@ import (
 	"github.com/redis/go-redis/v9/internal/pool"
 	"github.com/redis/go-redis/v9/internal/proto"
 	"github.com/redis/go-redis/v9/internal/rand"
+	"github.com/redis/go-redis/v9/push"
 )
 
 const (
@@ -126,6 +127,10 @@ type ClusterOptions struct {
 	// UnstableResp3 enables Unstable mode for Redis Search module with RESP3.
 	UnstableResp3 bool
 
+	// PushNotificationProcessor is the processor for handling push notifications.
+	// If nil, a default processor will be created for RESP3 connections.
+	PushNotificationProcessor push.NotificationProcessor
+
 	// FailingTimeoutSeconds is the timeout in seconds for marking a cluster node as failing.
 	// When a node is marked as failing, it will be avoided for this duration.
 	// Default is 15 seconds.
@@ -376,9 +381,10 @@ func (opt *ClusterOptions) clientOptions() *Options {
 		// much use for ClusterSlots config).  This means we cannot execute the
 		// READONLY command against that node -- setting readOnly to false in such
 		// situations in the options below will prevent that from happening.
-		readOnly:             opt.ReadOnly && opt.ClusterSlots == nil,
-		UnstableResp3:        opt.UnstableResp3,
-		HitlessUpgradeConfig: hitlessConfig,
+		readOnly:                  opt.ReadOnly && opt.ClusterSlots == nil,
+		UnstableResp3:             opt.UnstableResp3,
+		HitlessUpgradeConfig:      hitlessConfig,
+		PushNotificationProcessor: opt.PushNotificationProcessor,
 	}
 }