update doc and config

Author: ndyakov

hitless/README.md

@@ -19,6 +19,23 @@ The hitless upgrade system integrates with go-redis through pool hooks:
 - `FAILING_OVER` - Apply relaxed timeouts during failover
 - `FAILED_OVER` - Clear relaxed timeouts after failover
 
+### Worker Management
+The hitless upgrade system uses **on-demand workers** for processing connection handoffs:
+
+- **No minimum workers**: Workers are created only when needed
+- **Automatic scaling**: Workers scale up to `MaxWorkers` under load
+- **Automatic cleanup**: Idle workers are automatically terminated
+- **Efficient resource usage**: No resources consumed when idle
+- **Burst handling**: Can quickly scale to handle traffic spikes
+- **Smart defaults**: Auto-calculated as `min(10, PoolSize/3)` to prevent over-allocation
+- **Performance guarantee**: Explicit values enforced to minimum of 10 workers
+
+#### MaxWorkers Configuration Logic
+- **When not set (0)**: `min(10, PoolSize/3)` - scales with pool size but caps at 10
+- **When explicitly set**: `max(10, set_value)` - ensures minimum 10 workers for performance
+
+This design ensures optimal resource utilization while maintaining responsiveness during Redis topology changes.
+
 ## Configuration Examples
 
 ### Basic Setup
@@ -47,13 +64,14 @@ opt := &redis.Options{
     HitlessUpgrades: &redis.HitlessUpgradeConfig{
         Enabled: true,
         Config: &hitless.Config{
-            MaxRetries:           3,
-            RetryDelay:          time.Second,
-            HandoffTimeout:      30 * time.Second,
-            RelaxedTimeout:      10 * time.Second,
-            PostHandoffDuration: 5 * time.Second,
-            LogLevel:            1,
-            MaxWorkers:          10,
+            MaxHandoffRetries:           3,
+            HandoffRetryDelay:          time.Second,
+            HandoffTimeout:             30 * time.Second,
+            RelaxedTimeout:             10 * time.Second,
+            PostHandoffRelaxedDuration: 5 * time.Second,
+            LogLevel:                   1,
+            MaxWorkers:                 15, // On-demand workers (default: min(10, PoolSize/3), enforced min: 10)
+            HandoffQueueSize:           50, // Queue size for handoff requests
         },
     },
 }
@@ -62,6 +80,52 @@ client := redis.NewClient(opt)
 defer client.Close()
 ```
 
+### Configuration Examples
+
+#### MaxWorkers Auto-Calculation
+```go
+// Small pool - conservative worker allocation
+opt := &redis.Options{
+    PoolSize: 6,  // MaxWorkers will be min(10, 6/3) = 2
+    HitlessUpgrades: &redis.HitlessUpgradeConfig{Enabled: true},
+}
+
+// Medium pool - proportional worker allocation
+opt := &redis.Options{
+    PoolSize: 30, // MaxWorkers will be min(10, 30/3) = 10
+    HitlessUpgrades: &redis.HitlessUpgradeConfig{Enabled: true},
+}
+
+// Large pool - capped worker allocation
+opt := &redis.Options{
+    PoolSize: 120, // MaxWorkers will be min(10, 120/3) = 10 (capped)
+    HitlessUpgrades: &redis.HitlessUpgradeConfig{Enabled: true},
+}
+```
+
+#### Explicit MaxWorkers Configuration
+```go
+// Small explicit value - enforced minimum
+opt := &redis.Options{
+    HitlessUpgrades: &redis.HitlessUpgradeConfig{
+        Enabled: true,
+        Config: &hitless.Config{
+            MaxWorkers: 5, // Will be enforced to 10 for performance
+        },
+    },
+}
+
+// Large explicit value - respected as-is
+opt := &redis.Options{
+    HitlessUpgrades: &redis.HitlessUpgradeConfig{
+        Enabled: true,
+        Config: &hitless.Config{
+            MaxWorkers: 20, // Will be kept as 20
+        },
+    },
+}
+```
+
 ### Cluster Client
 ```go
 cluster := redis.NewClusterClient(&redis.ClusterOptions{

hitless/config.go

@@ -86,24 +86,19 @@ type Config struct {
 	// Default: 15 seconds (matches server-side eviction timeout)
 	HandoffTimeout time.Duration
 
-	// MinWorkers is the minimum number of worker goroutines for processing handoff requests.
-	// The processor starts with this number of workers and scales down to this level when idle.
-	// If zero, defaults to max(1, PoolSize/50) to be proportional to connection pool size.
-	//
-	// Default: max(1, PoolSize/50)
-	MinWorkers int
-
 	// MaxWorkers is the maximum number of worker goroutines for processing handoff requests.
-	// The processor will scale up to this number when under load.
-	// If zero, defaults to max(MinWorkers*4, PoolSize/10) to handle bursts effectively.
+	// Workers are created on-demand and automatically cleaned up when idle.
+	// If zero, defaults to min(10, PoolSize/3) to handle bursts effectively.
+	// If explicitly set, enforces minimum of 10 workers.
 	//
-	// Default: max(MinWorkers*4, PoolSize/10)
+	// Default: min(10, PoolSize/3), Minimum when set: 10
 	MaxWorkers int
 
 	// 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.
 	//
-	// Default: 10x max workers, but never more than pool size, min 2
+	// Default: 10x max workers, capped by pool size, min 2
 	HandoffQueueSize int
 
 	// PostHandoffRelaxedDuration is how long to keep relaxed timeouts on the new connection
@@ -198,7 +193,6 @@ func DefaultConfig() *Config {
 		EndpointType:               EndpointTypeAuto,       // Auto-detect based on connection
 		RelaxedTimeout:             30 * time.Second,
 		HandoffTimeout:             15 * time.Second,
-		MinWorkers:                 0, // Auto-calculated based on pool size
 		MaxWorkers:                 0, // Auto-calculated based on pool size
 		HandoffQueueSize:           0, // Auto-calculated based on max workers
 		PostHandoffRelaxedDuration: 0, // Auto-calculated based on relaxed timeout
@@ -239,12 +233,9 @@ func (c *Config) Validate() error {
 	}
 	// Validate worker configuration
 	// Allow 0 for auto-calculation, but negative values are invalid
-	if c.MinWorkers < 0 {
+	if c.MaxWorkers < 0 {
 		return ErrInvalidHandoffWorkers
 	}
-	if c.MinWorkers > 0 && c.MaxWorkers > 0 && c.MaxWorkers < c.MinWorkers {
-		return ErrInvalidWorkerRange
-	}
 	// HandoffQueueSize validation - allow 0 for auto-calculation
 	if c.HandoffQueueSize < 0 {
 		return ErrInvalidHandoffQueueSize
@@ -369,7 +360,6 @@ func (c *Config) ApplyDefaultsWithPoolSize(poolSize int) *Config {
 	}
 
 	// Copy worker configuration
-	result.MinWorkers = c.MinWorkers
 	result.MaxWorkers = c.MaxWorkers
 
 	// Apply worker defaults based on pool size
@@ -383,6 +373,10 @@ func (c *Config) ApplyDefaultsWithPoolSize(poolSize int) *Config {
 	} else {
 		result.HandoffQueueSize = c.HandoffQueueSize
 	}
+
+	// Always cap queue size by pool size - no point having more queue slots than connections
+	result.HandoffQueueSize = util.Min(result.HandoffQueueSize, poolSize)
+
 	// Ensure minimum queue size of 2
 	if result.HandoffQueueSize < 2 {
 		result.HandoffQueueSize = 2
@@ -491,7 +485,6 @@ func (c *Config) Clone() *Config {
 		EndpointType:               c.EndpointType,
 		RelaxedTimeout:             c.RelaxedTimeout,
 		HandoffTimeout:             c.HandoffTimeout,
-		MinWorkers:                 c.MinWorkers,
 		MaxWorkers:                 c.MaxWorkers,
 		HandoffQueueSize:           c.HandoffQueueSize,
 		PostHandoffRelaxedDuration: c.PostHandoffRelaxedDuration,
@@ -521,19 +514,17 @@ func (c *Config) applyWorkerDefaults(poolSize int) {
 		poolSize = 10 * runtime.GOMAXPROCS(0)
 	}
 
-	// MinWorkers: max(1, poolSize/50) - conservative baseline
-	if c.MinWorkers == 0 {
-		c.MinWorkers = util.Max(1, poolSize/50)
-	}
-
-	// MaxWorkers: max(MinWorkers*4, poolSize/10) - handle bursts effectively
 	if c.MaxWorkers == 0 {
-		c.MaxWorkers = util.Max(c.MinWorkers*4, poolSize/10)
+		// When not set: min(10, poolSize/3) - don't exceed 10 workers for small pools
+		c.MaxWorkers = util.Min(10, poolSize/3)
+	} else {
+		// When explicitly set: max(10, set_value) - ensure at least 10 workers
+		c.MaxWorkers = util.Max(10, c.MaxWorkers)
 	}
 
-	// Ensure MaxWorkers >= MinWorkers
-	if c.MaxWorkers < c.MinWorkers {
-		c.MaxWorkers = c.MinWorkers
+	// Ensure minimum of 1 worker (fallback for very small pools)
+	if c.MaxWorkers < 1 {
+		c.MaxWorkers = 1
 	}
 }