Enabled -> Mode. Cleaner readme

Author: ndyakov

hitless/README.md

@@ -1,272 +1,86 @@
 # Hitless Upgrades
 
-This package provides hitless upgrade functionality for Redis clients, enabling seamless connection migration during Redis server upgrades, failovers, or cluster topology changes without dropping active connections.
+Seamless Redis connection handoffs during topology changes without interrupting operations.
 
-## How It Works
+## Quick Start
 
-The hitless upgrade system integrates with go-redis through pool hooks:
-
-1. **Push Notifications**: Redis sends RESP3 push notifications for topology changes
-2. **Connection Marking**: Affected connections are marked for handoff
-3. **Pool Integration**: Marked connections are queued for handoff when returned to pool
-4. **Async Migration**: Worker goroutines perform connection handoffs in background
-5. **Connection Replacement**: Old connections are replaced with new ones to target endpoints
-
-### Push Notification Types
-- `MOVING` - Connection handoff to new endpoint
-- `MIGRATING` - Apply relaxed timeouts during migration
-- `MIGRATED` - Clear relaxed timeouts after migration
-- `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
 ```go
-import "github.com/redis/go-redis/v9"
+import "github.com/redis/go-redis/v9/hitless"
 
 opt := &redis.Options{
     Addr:     "localhost:6379",
-    Protocol: 3, // RESP3 required for push notifications
+    Protocol: 3, // RESP3 required
     HitlessUpgrades: &redis.HitlessUpgradeConfig{
-        Enabled: true,
+        Mode: hitless.MaintNotificationsEnabled, // or MaintNotificationsAuto
     },
 }
-
 client := redis.NewClient(opt)
-defer client.Close()
 ```
 
-### Advanced Configuration
-```go
-import "github.com/redis/go-redis/v9/hitless"
+## Modes
 
-opt := &redis.Options{
-    Addr:     "localhost:6379",
-    Protocol: 3,
-    HitlessUpgrades: &redis.HitlessUpgradeConfig{
-        Enabled: true,
-        Config: &hitless.Config{
-            MaxHandoffRetries:           3,  // Retry failed handoffs up to 3 times
-            HandoffTimeout:             15 * time.Second, // Timeout for individual handoff operations
-            RelaxedTimeout:             10 * time.Second, // Extended timeout during migrations
-            PostHandoffRelaxedDuration: 20 * time.Second, // Keep relaxed timeout after handoff
-            LogLevel:                   1,  // Warning level logging
-            MaxWorkers:                 15, // On-demand workers (default: min(10, PoolSize/3), enforced min: 10)
-            HandoffQueueSize:           50, // Queue size for handoff requests
-        },
-    },
-}
+- **`MaintNotificationsDisabled`**: Hitless upgrades are completely disabled
+- **`MaintNotificationsEnabled`**: Hitless upgrades are forcefully enabled (fails if server doesn't support it)
+- **`MaintNotificationsAuto`**: Hitless upgrades are enabled if server supports it (default)
 
-client := redis.NewClient(opt)
-defer client.Close()
-```
+## Configuration
 
-### 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},
-}
+import "github.com/redis/go-redis/v9/hitless"
 
-// Large pool - capped worker allocation
-opt := &redis.Options{
-    PoolSize: 120, // MaxWorkers will be min(10, 120/3) = 10 (capped)
-    HitlessUpgrades: &redis.HitlessUpgradeConfig{Enabled: true},
+Config: &hitless.Config{
+    Mode:                       hitless.MaintNotificationsAuto, // Notification mode
+    MaxHandoffRetries:           3,  // Retry failed handoffs
+    HandoffTimeout:             15 * time.Second, // Handoff operation timeout
+    RelaxedTimeout:             10 * time.Second, // Extended timeout during migrations
+    PostHandoffRelaxedDuration: 20 * time.Second, // Keep relaxed timeout after handoff
+    LogLevel:                   1,  // 0=errors, 1=warnings, 2=info, 3=debug
+    MaxWorkers:                 15, // Concurrent handoff workers
+    HandoffQueueSize:           50, // Handoff request queue size
 }
 ```
 
-#### 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
-        },
-    },
-}
+### Worker Scaling
+- **Auto-calculated**: `min(10, PoolSize/3)` - scales with pool size, capped at 10
+- **Explicit values**: `max(10, set_value)` - enforces minimum 10 workers
+- **On-demand**: Workers created when needed, cleaned up when idle
 
-// Large explicit value - respected as-is
-opt := &redis.Options{
-    HitlessUpgrades: &redis.HitlessUpgradeConfig{
-        Enabled: true,
-        Config: &hitless.Config{
-            MaxWorkers: 20, // Will be kept as 20
-        },
-    },
-}
-```
+### Queue Sizing
+- **Auto-calculated**: `10 × MaxWorkers`, capped by pool size
+- **Always capped**: Queue size never exceeds pool size
+
+## Cluster Support
 
-### Cluster Client
 ```go
-cluster := redis.NewClusterClient(&redis.ClusterOptions{
-    Addrs:    []string{"localhost:7000", "localhost:7001", "localhost:7002"},
+opt := &redis.ClusterOptions{
+    Addrs:    []string{"localhost:7000", "localhost:7001"},
     Protocol: 3,
     HitlessUpgrades: &redis.HitlessUpgradeConfig{
-        Enabled: true,
+        Mode: hitless.MaintNotificationsEnabled,
     },
-})
-defer cluster.Close()
-```
-
-## Hook Examples
-
-### Custom Pool Hook
-```go
-package main
-
-import (
-    "context"
-    "log"
-
-    "github.com/redis/go-redis/v9/internal/pool"
-)
-
-// Custom hook that logs connection events
-type LoggingHook struct {
-    name string
-}
-
-func (lh *LoggingHook) OnGet(ctx context.Context, conn *pool.Conn, isNewConn bool) error {
-    log.Printf("Hook %s: Getting connection %d (new: %v)", lh.name, conn.GetID(), isNewConn)
-    return nil
-}
-
-func (lh *LoggingHook) OnPut(ctx context.Context, conn *pool.Conn) (shouldPool bool, shouldRemove bool, err error) {
-    log.Printf("Hook %s: Putting connection %d back to pool", lh.name, conn.GetID())
-    return true, false, nil // Pool the connection, don't remove it
-}
-
-func main() {
-    // Create pool with custom hook
-    opt := &pool.Options{
-        Dialer: func(ctx context.Context) (net.Conn, error) {
-            return net.Dial("tcp", "localhost:6379")
-        },
-        PoolSize: 10,
-    }
-
-    connPool := pool.NewConnPool(opt)
-    defer connPool.Close()
-
-    // Add custom hook
-    loggingHook := &LoggingHook{name: "MyLogger"}
-    connPool.AddPoolHook(loggingHook)
-
-    // Use the pool - hooks will be called automatically
-    ctx := context.Background()
-    conn, err := connPool.Get(ctx)
-    if err != nil {
-        log.Fatal(err)
-    }
-
-    // Do something with connection...
-
-    connPool.Put(ctx, conn)
 }
+client := redis.NewClusterClient(opt)
 ```
 
-### Multiple Hooks
-```go
-package main
-
-import (
-    "context"
-    "log"
-    "time"
-
-    "github.com/redis/go-redis/v9/internal/pool"
-)
-
-// Metrics hook
-type MetricsHook struct {
-    getCount int64
-    putCount int64
-}
-
-func (mh *MetricsHook) OnGet(ctx context.Context, conn *pool.Conn, isNewConn bool) error {
-    mh.getCount++
-    return nil
-}
-
-func (mh *MetricsHook) OnPut(ctx context.Context, conn *pool.Conn) (shouldPool bool, shouldRemove bool, err error) {
-    mh.putCount++
-    return true, false, nil
-}
+## Metrics Hook Example
 
-// Validation hook
-type ValidationHook struct{}
-
-func (vh *ValidationHook) OnGet(ctx context.Context, conn *pool.Conn, isNewConn bool) error {
-    if !conn.IsUsable() {
-        return errors.New("connection not usable")
-    }
-    return nil
-}
+A metrics collection hook is available in `example_hooks.go` that demonstrates how to monitor hitless upgrade operations:
 
-func (vh *ValidationHook) OnPut(ctx context.Context, conn *pool.Conn) (shouldPool bool, shouldRemove bool, err error) {
-    // Check if connection has errors
-    if conn.HasBufferedData() {
-        return false, true, nil // Don't pool, remove connection
-    }
-    return true, false, nil
-}
-
-func main() {
-    opt := &pool.Options{
-        Dialer: func(ctx context.Context) (net.Conn, error) {
-            return net.Dial("tcp", "localhost:6379")
-        },
-        PoolSize: 10,
-    }
-
-    connPool := pool.NewConnPool(opt)
-    defer connPool.Close()
-
-    // Add multiple hooks - they execute in order
-    metricsHook := &MetricsHook{}
-    validationHook := &ValidationHook{}
+```go
+import "github.com/redis/go-redis/v9/hitless"
 
-    connPool.AddPoolHook(metricsHook)
-    connPool.AddPoolHook(validationHook)
+metricsHook := hitless.NewMetricsHook()
+// Use with your monitoring system
+```
 
-    // Hooks will be called in the order they were added
-    ctx := context.Background()
-    conn, err := connPool.Get(ctx) // Both OnGet methods called
-    if err != nil {
-        log.Fatal(err)
-    }
+The metrics hook tracks:
+- Handoff success/failure rates
+- Handoff duration
+- Queue depth
+- Worker utilization
+- Connection lifecycle events
 
-    connPool.Put(ctx, conn) // Both OnPut methods called
+## Requirements
 
-    log.Printf("Metrics: Get=%d, Put=%d", metricsHook.getCount, metricsHook.putCount)
-}
-```
+- **RESP3 Protocol**: Required for push notifications
+- **Redis 7.0+**: For maintenance notification support

hitless/config.go

@@ -64,10 +64,10 @@ func (e EndpointType) String() string {
 
 // Config provides configuration options for hitless upgrades.
 type Config struct {
-	// Enabled controls how client maintenance notifications are handled.
+	// Mode controls how client maintenance notifications are handled.
 	// Valid values: MaintNotificationsDisabled, MaintNotificationsEnabled, MaintNotificationsAuto
 	// Default: MaintNotificationsAuto
-	Enabled MaintNotificationsMode
+	Mode MaintNotificationsMode
 
 	// EndpointType specifies the type of endpoint to request in MOVING notifications.
 	// Valid values: EndpointTypeAuto, EndpointTypeInternalIP, EndpointTypeInternalFQDN,
@@ -123,13 +123,13 @@ type Config struct {
 }
 
 func (c *Config) IsEnabled() bool {
-	return c != nil && c.Enabled != MaintNotificationsDisabled
+	return c != nil && c.Mode != MaintNotificationsDisabled
 }
 
 // DefaultConfig returns a Config with sensible defaults.
 func DefaultConfig() *Config {
 	return &Config{
-		Enabled:                    MaintNotificationsAuto, // Enable by default for Redis Cloud
+		Mode:                       MaintNotificationsAuto, // Enable by default for Redis Cloud
 		EndpointType:               EndpointTypeAuto,       // Auto-detect based on connection
 		RelaxedTimeout:             10 * time.Second,
 		HandoffTimeout:             15 * time.Second,
@@ -168,8 +168,8 @@ func (c *Config) Validate() error {
 		return ErrInvalidLogLevel
 	}
 
-	// Validate Enabled (maintenance notifications mode)
-	if !c.Enabled.IsValid() {
+	// Validate Mode (maintenance notifications mode)
+	if !c.Mode.IsValid() {
 		return ErrInvalidMaintNotifications
 	}
 
@@ -206,10 +206,10 @@ func (c *Config) ApplyDefaultsWithPoolSize(poolSize int) *Config {
 	result := &Config{}
 
 	// Apply defaults for enum fields (empty/zero means not set)
-	if c.Enabled == "" {
-		result.Enabled = defaults.Enabled
+	if c.Mode == "" {
+		result.Mode = defaults.Mode
 	} else {
-		result.Enabled = c.Enabled
+		result.Mode = c.Mode
 	}
 
 	if c.EndpointType == "" {
@@ -296,7 +296,7 @@ func (c *Config) Clone() *Config {
 	}
 
 	return &Config{
-		Enabled:                    c.Enabled,
+		Mode:                       c.Mode,
 		EndpointType:               c.EndpointType,
 		RelaxedTimeout:             c.RelaxedTimeout,
 		HandoffTimeout:             c.HandoffTimeout,