Size computation for allocation may overflow (#99)

* Size computation for allocation may overflow

Performing calculations involving the size of potentially large strings or slices can result in an overflow (for signed integer types) or a wraparound (for unsigned types). An overflow causes the result of the calculation to become negative, while a wraparound results in a small (positive) number.

vendor/github.com/redis/go-redis/v9/internal/auth/streaming/conn_reauth_credentials_listener.go

@@ -0,0 +1,100 @@
+package streaming
+
+import (
+	"github.com/redis/go-redis/v9/auth"
+	"github.com/redis/go-redis/v9/internal/pool"
+)
+
+// ConnReAuthCredentialsListener is a credentials listener for a specific connection
+// that triggers re-authentication when credentials change.
+//
+// This listener implements the auth.CredentialsListener interface and is subscribed
+// to a StreamingCredentialsProvider. When new credentials are received via OnNext,
+// it marks the connection for re-authentication through the manager.
+//
+// The re-authentication is always performed asynchronously to avoid blocking the
+// credentials provider and to prevent potential deadlocks with the pool semaphore.
+// The actual re-auth happens when the connection is returned to the pool in an idle state.
+//
+// Lifecycle:
+//   - Created during connection initialization via Manager.Listener()
+//   - Subscribed to the StreamingCredentialsProvider
+//   - Receives credential updates via OnNext()
+//   - Cleaned up when connection is removed from pool via Manager.RemoveListener()
+type ConnReAuthCredentialsListener struct {
+	// reAuth is the function to re-authenticate the connection with new credentials
+	reAuth func(conn *pool.Conn, credentials auth.Credentials) error
+
+	// onErr is the function to call when re-authentication or acquisition fails
+	onErr func(conn *pool.Conn, err error)
+
+	// conn is the connection this listener is associated with
+	conn *pool.Conn
+
+	// manager is the streaming credentials manager for coordinating re-auth
+	manager *Manager
+}
+
+// OnNext is called when new credentials are received from the StreamingCredentialsProvider.
+//
+// This method marks the connection for asynchronous re-authentication. The actual
+// re-authentication happens in the background when the connection is returned to the
+// pool and is in an idle state.
+//
+// Asynchronous re-auth is used to:
+//   - Avoid blocking the credentials provider's notification goroutine
+//   - Prevent deadlocks with the pool's semaphore (especially with small pool sizes)
+//   - Ensure re-auth happens when the connection is safe to use (not processing commands)
+//
+// The reAuthFn callback receives:
+//   - nil if the connection was successfully acquired for re-auth
+//   - error if acquisition timed out or failed
+//
+// Thread-safe: Called by the credentials provider's notification goroutine.
+func (c *ConnReAuthCredentialsListener) OnNext(credentials auth.Credentials) {
+	if c.conn == nil || c.conn.IsClosed() || c.manager == nil || c.reAuth == nil {
+		return
+	}
+
+	// Always use async reauth to avoid complex pool semaphore issues
+	// The synchronous path can cause deadlocks in the pool's semaphore mechanism
+	// when called from the Subscribe goroutine, especially with small pool sizes.
+	// The connection pool hook will re-authenticate the connection when it is
+	// returned to the pool in a clean, idle state.
+	c.manager.MarkForReAuth(c.conn, func(err error) {
+		// err is from connection acquisition (timeout, etc.)
+		if err != nil {
+			// Log the error
+			c.OnError(err)
+			return
+		}
+		// err is from reauth command execution
+		err = c.reAuth(c.conn, credentials)
+		if err != nil {
+			// Log the error
+			c.OnError(err)
+			return
+		}
+	})
+}
+
+// OnError is called when an error occurs during credential streaming or re-authentication.
+//
+// This method can be called from:
+//   - The StreamingCredentialsProvider when there's an error in the credentials stream
+//   - The re-auth process when connection acquisition times out
+//   - The re-auth process when the AUTH command fails
+//
+// The error is delegated to the onErr callback provided during listener creation.
+//
+// Thread-safe: Can be called from multiple goroutines (provider, re-auth worker).
+func (c *ConnReAuthCredentialsListener) OnError(err error) {
+	if c.onErr == nil {
+		return
+	}
+
+	c.onErr(c.conn, err)
+}
+
+// Ensure ConnReAuthCredentialsListener implements the CredentialsListener interface.
+var _ auth.CredentialsListener = (*ConnReAuthCredentialsListener)(nil)

vendor/github.com/redis/go-redis/v9/internal/auth/streaming/cred_listeners.go

@@ -0,0 +1,77 @@
+package streaming
+
+import (
+	"sync"
+
+	"github.com/redis/go-redis/v9/auth"
+)
+
+// CredentialsListeners is a thread-safe collection of credentials listeners
+// indexed by connection ID.
+//
+// This collection is used by the Manager to maintain a registry of listeners
+// for each connection in the pool. Listeners are reused when connections are
+// reinitialized (e.g., after a handoff) to avoid creating duplicate subscriptions
+// to the StreamingCredentialsProvider.
+//
+// The collection supports concurrent access from multiple goroutines during
+// connection initialization, credential updates, and connection removal.
+type CredentialsListeners struct {
+	// listeners maps connection ID to credentials listener
+	listeners map[uint64]auth.CredentialsListener
+
+	// lock protects concurrent access to the listeners map
+	lock sync.RWMutex
+}
+
+// NewCredentialsListeners creates a new thread-safe credentials listeners collection.
+func NewCredentialsListeners() *CredentialsListeners {
+	return &CredentialsListeners{
+		listeners: make(map[uint64]auth.CredentialsListener),
+	}
+}
+
+// Add adds or updates a credentials listener for a connection.
+//
+// If a listener already exists for the connection ID, it is replaced.
+// This is safe because the old listener should have been unsubscribed
+// before the connection was reinitialized.
+//
+// Thread-safe: Can be called concurrently from multiple goroutines.
+func (c *CredentialsListeners) Add(connID uint64, listener auth.CredentialsListener) {
+	c.lock.Lock()
+	defer c.lock.Unlock()
+	if c.listeners == nil {
+		c.listeners = make(map[uint64]auth.CredentialsListener)
+	}
+	c.listeners[connID] = listener
+}
+
+// Get retrieves the credentials listener for a connection.
+//
+// Returns:
+//   - listener: The credentials listener for the connection, or nil if not found
+//   - ok: true if a listener exists for the connection ID, false otherwise
+//
+// Thread-safe: Can be called concurrently from multiple goroutines.
+func (c *CredentialsListeners) Get(connID uint64) (auth.CredentialsListener, bool) {
+	c.lock.RLock()
+	defer c.lock.RUnlock()
+	if len(c.listeners) == 0 {
+		return nil, false
+	}
+	listener, ok := c.listeners[connID]
+	return listener, ok
+}
+
+// Remove removes the credentials listener for a connection.
+//
+// This is called when a connection is removed from the pool to prevent
+// memory leaks. If no listener exists for the connection ID, this is a no-op.
+//
+// Thread-safe: Can be called concurrently from multiple goroutines.
+func (c *CredentialsListeners) Remove(connID uint64) {
+	c.lock.Lock()
+	defer c.lock.Unlock()
+	delete(c.listeners, connID)
+}

vendor/github.com/redis/go-redis/v9/internal/auth/streaming/manager.go

@@ -0,0 +1,137 @@
+package streaming
+
+import (
+	"errors"
+	"time"
+
+	"github.com/redis/go-redis/v9/auth"
+	"github.com/redis/go-redis/v9/internal/pool"
+)
+
+// Manager coordinates streaming credentials and re-authentication for a connection pool.
+//
+// The manager is responsible for:
+//   - Creating and managing per-connection credentials listeners
+//   - Providing the pool hook for re-authentication
+//   - Coordinating between credentials updates and pool operations
+//
+// When credentials change via a StreamingCredentialsProvider:
+//  1. The credentials listener (ConnReAuthCredentialsListener) receives the update
+//  2. It calls MarkForReAuth on the manager
+//  3. The manager delegates to the pool hook
+//  4. The pool hook schedules background re-authentication
+//
+// The manager maintains a registry of credentials listeners indexed by connection ID,
+// allowing listener reuse when connections are reinitialized (e.g., after handoff).
+type Manager struct {
+	// credentialsListeners maps connection ID to credentials listener
+	credentialsListeners *CredentialsListeners
+
+	// pool is the connection pool being managed
+	pool pool.Pooler
+
+	// poolHookRef is the re-authentication pool hook
+	poolHookRef *ReAuthPoolHook
+}
+
+// NewManager creates a new streaming credentials manager.
+//
+// Parameters:
+//   - pl: The connection pool to manage
+//   - reAuthTimeout: Maximum time to wait for acquiring a connection for re-authentication
+//
+// The manager creates a ReAuthPoolHook sized to match the pool size, ensuring that
+// re-auth operations don't exhaust the connection pool.
+func NewManager(pl pool.Pooler, reAuthTimeout time.Duration) *Manager {
+	m := &Manager{
+		pool:                 pl,
+		poolHookRef:          NewReAuthPoolHook(pl.Size(), reAuthTimeout),
+		credentialsListeners: NewCredentialsListeners(),
+	}
+	m.poolHookRef.manager = m
+	return m
+}
+
+// PoolHook returns the pool hook for re-authentication.
+//
+// This hook should be registered with the connection pool to enable
+// automatic re-authentication when credentials change.
+func (m *Manager) PoolHook() pool.PoolHook {
+	return m.poolHookRef
+}
+
+// Listener returns or creates a credentials listener for a connection.
+//
+// This method is called during connection initialization to set up the
+// credentials listener. If a listener already exists for the connection ID
+// (e.g., after a handoff), it is reused.
+//
+// Parameters:
+//   - poolCn: The connection to create/get a listener for
+//   - reAuth: Function to re-authenticate the connection with new credentials
+//   - onErr: Function to call when re-authentication fails
+//
+// Returns:
+//   - auth.CredentialsListener: The listener to subscribe to the credentials provider
+//   - error: Non-nil if poolCn is nil
+//
+// Note: The reAuth and onErr callbacks are captured once when the listener is
+// created and reused for the connection's lifetime. They should not change.
+//
+// Thread-safe: Can be called concurrently during connection initialization.
+func (m *Manager) Listener(
+	poolCn *pool.Conn,
+	reAuth func(*pool.Conn, auth.Credentials) error,
+	onErr func(*pool.Conn, error),
+) (auth.CredentialsListener, error) {
+	if poolCn == nil {
+		return nil, errors.New("poolCn cannot be nil")
+	}
+	connID := poolCn.GetID()
+	// if we reconnect the underlying network connection, the streaming credentials listener will continue to work
+	// so we can get the old listener from the cache and use it.
+	// subscribing the same (an already subscribed) listener for a StreamingCredentialsProvider SHOULD be a no-op
+	listener, ok := m.credentialsListeners.Get(connID)
+	if !ok || listener == nil {
+		// Create new listener for this connection
+		// Note: Callbacks (reAuth, onErr) are captured once and reused for the connection's lifetime
+		newCredListener := &ConnReAuthCredentialsListener{
+			conn:    poolCn,
+			reAuth:  reAuth,
+			onErr:   onErr,
+			manager: m,
+		}
+
+		m.credentialsListeners.Add(connID, newCredListener)
+		listener = newCredListener
+	}
+	return listener, nil
+}
+
+// MarkForReAuth marks a connection for re-authentication.
+//
+// This method is called by the credentials listener when new credentials are
+// received. It delegates to the pool hook to schedule background re-authentication.
+//
+// Parameters:
+//   - poolCn: The connection to re-authenticate
+//   - reAuthFn: Function to call for re-authentication, receives error if acquisition fails
+//
+// Thread-safe: Called by credentials listeners when credentials change.
+func (m *Manager) MarkForReAuth(poolCn *pool.Conn, reAuthFn func(error)) {
+	connID := poolCn.GetID()
+	m.poolHookRef.MarkForReAuth(connID, reAuthFn)
+}
+
+// RemoveListener removes the credentials listener for a connection.
+//
+// This method is called by the pool hook's OnRemove to clean up listeners
+// when connections are removed from the pool.
+//
+// Parameters:
+//   - connID: The connection ID whose listener should be removed
+//
+// Thread-safe: Called during connection removal.
+func (m *Manager) RemoveListener(connID uint64) {
+	m.credentialsListeners.Remove(connID)
+}

vendor/github.com/redis/go-redis/v9/internal/auth/streaming/pool_hook.go

@@ -0,0 +1,241 @@
+package streaming
+
+import (
+	"context"
+	"sync"
+	"time"
+
+	"github.com/redis/go-redis/v9/internal"
+	"github.com/redis/go-redis/v9/internal/pool"
+)
+
+// ReAuthPoolHook is a pool hook that manages background re-authentication of connections
+// when credentials change via a streaming credentials provider.
+//
+// The hook uses a semaphore-based worker pool to limit concurrent re-authentication
+// operations and prevent pool exhaustion. When credentials change, connections are
+// marked for re-authentication and processed asynchronously in the background.
+//
+// The re-authentication process:
+//  1. OnPut: When a connection is returned to the pool, check if it needs re-auth
+//  2. If yes, schedule it for background processing (move from shouldReAuth to scheduledReAuth)
+//  3. A worker goroutine acquires the connection (waits until it's not in use)
+//  4. Executes the re-auth function while holding the connection
+//  5. Releases the connection back to the pool
+//
+// The hook ensures that:
+//   - Only one re-auth operation runs per connection at a time
+//   - Connections are not used for commands during re-authentication
+//   - Re-auth operations timeout if they can't acquire the connection
+//   - Resources are properly cleaned up on connection removal
+type ReAuthPoolHook struct {
+	// shouldReAuth maps connection ID to re-auth function
+	// Connections in this map need re-authentication but haven't been scheduled yet
+	shouldReAuth     map[uint64]func(error)
+	shouldReAuthLock sync.RWMutex
+
+	// workers is a semaphore limiting concurrent re-auth operations
+	// Initialized with poolSize tokens to prevent pool exhaustion
+	// Uses FastSemaphore for better performance with eventual fairness
+	workers *internal.FastSemaphore
+
+	// reAuthTimeout is the maximum time to wait for acquiring a connection for re-auth
+	reAuthTimeout time.Duration
+
+	// scheduledReAuth maps connection ID to scheduled status
+	// Connections in this map have a background worker attempting re-authentication
+	scheduledReAuth map[uint64]bool
+	scheduledLock   sync.RWMutex
+
+	// manager is a back-reference for cleanup operations
+	manager *Manager
+}
+
+// NewReAuthPoolHook creates a new re-authentication pool hook.
+//
+// Parameters:
+//   - poolSize: Maximum number of concurrent re-auth operations (typically matches pool size)
+//   - reAuthTimeout: Maximum time to wait for acquiring a connection for re-authentication
+//
+// The poolSize parameter is used to initialize the worker semaphore, ensuring that
+// re-auth operations don't exhaust the connection pool.
+func NewReAuthPoolHook(poolSize int, reAuthTimeout time.Duration) *ReAuthPoolHook {
+	return &ReAuthPoolHook{
+		shouldReAuth:    make(map[uint64]func(error)),
+		scheduledReAuth: make(map[uint64]bool),
+		workers:         internal.NewFastSemaphore(int32(poolSize)),
+		reAuthTimeout:   reAuthTimeout,
+	}
+}
+
+// MarkForReAuth marks a connection for re-authentication.
+//
+// This method is called when credentials change and a connection needs to be
+// re-authenticated. The actual re-authentication happens asynchronously when
+// the connection is returned to the pool (in OnPut).
+//
+// Parameters:
+//   - connID: The connection ID to mark for re-authentication
+//   - reAuthFn: Function to call for re-authentication, receives error if acquisition fails
+//
+// Thread-safe: Can be called concurrently from multiple goroutines.
+func (r *ReAuthPoolHook) MarkForReAuth(connID uint64, reAuthFn func(error)) {
+	r.shouldReAuthLock.Lock()
+	defer r.shouldReAuthLock.Unlock()
+	r.shouldReAuth[connID] = reAuthFn
+}
+
+// OnGet is called when a connection is retrieved from the pool.
+//
+// This hook checks if the connection needs re-authentication or has a scheduled
+// re-auth operation. If so, it rejects the connection (returns accept=false),
+// causing the pool to try another connection.
+//
+// Returns:
+//   - accept: false if connection needs re-auth, true otherwise
+//   - err: always nil (errors are not used in this hook)
+//
+// Thread-safe: Called concurrently by multiple goroutines getting connections.
+func (r *ReAuthPoolHook) OnGet(_ context.Context, conn *pool.Conn, _ bool) (accept bool, err error) {
+	connID := conn.GetID()
+	r.shouldReAuthLock.RLock()
+	_, shouldReAuth := r.shouldReAuth[connID]
+	r.shouldReAuthLock.RUnlock()
+	// This connection was marked for reauth while in the pool,
+	// reject the connection
+	if shouldReAuth {
+		// simply reject the connection, it will be re-authenticated in OnPut
+		return false, nil
+	}
+	r.scheduledLock.RLock()
+	_, hasScheduled := r.scheduledReAuth[connID]
+	r.scheduledLock.RUnlock()
+	// has scheduled reauth, reject the connection
+	if hasScheduled {
+		// simply reject the connection, it currently has a reauth scheduled
+		// and the worker is waiting for slot to execute the reauth
+		return false, nil
+	}
+	return true, nil
+}
+
+// OnPut is called when a connection is returned to the pool.
+//
+// This hook checks if the connection needs re-authentication. If so, it schedules
+// a background goroutine to perform the re-auth asynchronously. The goroutine:
+//  1. Waits for a worker slot (semaphore)
+//  2. Acquires the connection (waits until not in use)
+//  3. Executes the re-auth function
+//  4. Releases the connection and worker slot
+//
+// The connection is always pooled (not removed) since re-auth happens in background.
+//
+// Returns:
+//   - shouldPool: always true (connection stays in pool during background re-auth)
+//   - shouldRemove: always false
+//   - err: always nil
+//
+// Thread-safe: Called concurrently by multiple goroutines returning connections.
+func (r *ReAuthPoolHook) OnPut(_ context.Context, conn *pool.Conn) (bool, bool, error) {
+	if conn == nil {
+		// noop
+		return true, false, nil
+	}
+	connID := conn.GetID()
+	// Check if reauth is needed and get the function with proper locking
+	r.shouldReAuthLock.RLock()
+	reAuthFn, ok := r.shouldReAuth[connID]
+	r.shouldReAuthLock.RUnlock()
+
+	if ok {
+		// Acquire both locks to atomically move from shouldReAuth to scheduledReAuth
+		// This prevents race conditions where OnGet might miss the transition
+		r.shouldReAuthLock.Lock()
+		r.scheduledLock.Lock()
+		r.scheduledReAuth[connID] = true
+		delete(r.shouldReAuth, connID)
+		r.scheduledLock.Unlock()
+		r.shouldReAuthLock.Unlock()
+		go func() {
+			r.workers.AcquireBlocking()
+			// safety first
+			if conn == nil || (conn != nil && conn.IsClosed()) {
+				r.workers.Release()
+				return
+			}
+			defer func() {
+				if rec := recover(); rec != nil {
+					// once again - safety first
+					internal.Logger.Printf(context.Background(), "panic in reauth worker: %v", rec)
+				}
+				r.scheduledLock.Lock()
+				delete(r.scheduledReAuth, connID)
+				r.scheduledLock.Unlock()
+				r.workers.Release()
+			}()
+
+			// Create timeout context for connection acquisition
+			// This prevents indefinite waiting if the connection is stuck
+			ctx, cancel := context.WithTimeout(context.Background(), r.reAuthTimeout)
+			defer cancel()
+
+			// Try to acquire the connection for re-authentication
+			// We need to ensure the connection is IDLE (not IN_USE) before transitioning to UNUSABLE
+			// This prevents re-authentication from interfering with active commands
+			// Use AwaitAndTransition to wait for the connection to become IDLE
+			stateMachine := conn.GetStateMachine()
+			if stateMachine == nil {
+				// No state machine - should not happen, but handle gracefully
+				reAuthFn(pool.ErrConnUnusableTimeout)
+				return
+			}
+
+			// Use predefined slice to avoid allocation
+			_, err := stateMachine.AwaitAndTransition(ctx, pool.ValidFromIdle(), pool.StateUnusable)
+			if err != nil {
+				// Timeout or other error occurred, cannot acquire connection
+				reAuthFn(err)
+				return
+			}
+
+			// safety first
+			if !conn.IsClosed() {
+				// Successfully acquired the connection, perform reauth
+				reAuthFn(nil)
+			}
+
+			// Release the connection: transition from UNUSABLE back to IDLE
+			stateMachine.Transition(pool.StateIdle)
+		}()
+	}
+
+	// the reauth will happen in background, as far as the pool is concerned:
+	// pool the connection, don't remove it, no error
+	return true, false, nil
+}
+
+// OnRemove is called when a connection is removed from the pool.
+//
+// This hook cleans up all state associated with the connection:
+//   - Removes from shouldReAuth map (pending re-auth)
+//   - Removes from scheduledReAuth map (active re-auth)
+//   - Removes credentials listener from manager
+//
+// This prevents memory leaks and ensures that removed connections don't have
+// lingering re-auth operations or listeners.
+//
+// Thread-safe: Called when connections are removed due to errors, timeouts, or pool closure.
+func (r *ReAuthPoolHook) OnRemove(_ context.Context, conn *pool.Conn, _ error) {
+	connID := conn.GetID()
+	r.shouldReAuthLock.Lock()
+	r.scheduledLock.Lock()
+	delete(r.scheduledReAuth, connID)
+	delete(r.shouldReAuth, connID)
+	r.scheduledLock.Unlock()
+	r.shouldReAuthLock.Unlock()
+	if r.manager != nil {
+		r.manager.RemoveListener(connID)
+	}
+}
+
+var _ pool.PoolHook = (*ReAuthPoolHook)(nil)

vendor/github.com/redis/go-redis/v9/internal/interfaces/interfaces.go

@@ -0,0 +1,54 @@
+// Package interfaces provides shared interfaces used by both the main redis package
+// and the maintnotifications upgrade package to avoid circular dependencies.
+package interfaces
+
+import (
+	"context"
+	"net"
+	"time"
+)
+
+// NotificationProcessor is (most probably) a push.NotificationProcessor
+// forward declaration to avoid circular imports
+type NotificationProcessor interface {
+	RegisterHandler(pushNotificationName string, handler interface{}, protected bool) error
+	UnregisterHandler(pushNotificationName string) error
+	GetHandler(pushNotificationName string) interface{}
+}
+
+// ClientInterface defines the interface that clients must implement for maintnotifications upgrades.
+type ClientInterface interface {
+	// GetOptions returns the client options.
+	GetOptions() OptionsInterface
+
+	// GetPushProcessor returns the client's push notification processor.
+	GetPushProcessor() NotificationProcessor
+}
+
+// OptionsInterface defines the interface for client options.
+// Uses an adapter pattern to avoid circular dependencies.
+type OptionsInterface interface {
+	// GetReadTimeout returns the read timeout.
+	GetReadTimeout() time.Duration
+
+	// GetWriteTimeout returns the write timeout.
+	GetWriteTimeout() time.Duration
+
+	// GetNetwork returns the network type.
+	GetNetwork() string
+
+	// GetAddr returns the connection address.
+	GetAddr() string
+
+	// IsTLSEnabled returns true if TLS is enabled.
+	IsTLSEnabled() bool
+
+	// GetProtocol returns the protocol version.
+	GetProtocol() int
+
+	// GetPoolSize returns the connection pool size.
+	GetPoolSize() int
+
+	// NewDialer returns a new dialer function for the connection.
+	NewDialer() func(context.Context) (net.Conn, error)
+}

vendor/github.com/redis/go-redis/v9/internal/log.go

@@ -7,20 +7,73 @@ import (
 	"os"
 )
 
+// TODO (ned): Revisit logging
+// Add more standardized approach with log levels and configurability
+
 type Logging interface {
 	Printf(ctx context.Context, format string, v ...interface{})
 }
 
-type logger struct {
+type DefaultLogger struct {
 	log *log.Logger
 }
 
-func (l *logger) Printf(ctx context.Context, format string, v ...interface{}) {
+func (l *DefaultLogger) Printf(ctx context.Context, format string, v ...interface{}) {
 	_ = l.log.Output(2, fmt.Sprintf(format, v...))
 }
 
+func NewDefaultLogger() Logging {
+	return &DefaultLogger{
+		log: log.New(os.Stderr, "redis: ", log.LstdFlags|log.Lshortfile),
+	}
+}
+
 // Logger calls Output to print to the stderr.
 // Arguments are handled in the manner of fmt.Print.
-var Logger Logging = &logger{
-	log: log.New(os.Stderr, "redis: ", log.LstdFlags|log.Lshortfile),
+var Logger Logging = NewDefaultLogger()
+
+var LogLevel LogLevelT = LogLevelError
+
+// LogLevelT represents the logging level
+type LogLevelT int
+
+// Log level constants for the entire go-redis library
+const (
+	LogLevelError LogLevelT = iota // 0 - errors only
+	LogLevelWarn                   // 1 - warnings and errors
+	LogLevelInfo                   // 2 - info, warnings, and errors
+	LogLevelDebug                  // 3 - debug, info, warnings, and errors
+)
+
+// String returns the string representation of the log level
+func (l LogLevelT) String() string {
+	switch l {
+	case LogLevelError:
+		return "ERROR"
+	case LogLevelWarn:
+		return "WARN"
+	case LogLevelInfo:
+		return "INFO"
+	case LogLevelDebug:
+		return "DEBUG"
+	default:
+		return "UNKNOWN"
+	}
+}
+
+// IsValid returns true if the log level is valid
+func (l LogLevelT) IsValid() bool {
+	return l >= LogLevelError && l <= LogLevelDebug
+}
+
+func (l LogLevelT) WarnOrAbove() bool {
+	return l >= LogLevelWarn
+}
+
+func (l LogLevelT) InfoOrAbove() bool {
+	return l >= LogLevelInfo
+}
+
+func (l LogLevelT) DebugOrAbove() bool {
+	return l >= LogLevelDebug
 }

vendor/github.com/redis/go-redis/v9/internal/maintnotifications/logs/log_messages.go

@@ -0,0 +1,625 @@
+package logs
+
+import (
+	"encoding/json"
+	"fmt"
+	"regexp"
+
+	"github.com/redis/go-redis/v9/internal"
+)
+
+// appendJSONIfDebug appends JSON data to a message only if the global log level is Debug
+func appendJSONIfDebug(message string, data map[string]interface{}) string {
+	if internal.LogLevel.DebugOrAbove() {
+		jsonData, _ := json.Marshal(data)
+		return fmt.Sprintf("%s %s", message, string(jsonData))
+	}
+	return message
+}
+
+const (
+	// ========================================
+	// CIRCUIT_BREAKER.GO - Circuit breaker management
+	// ========================================
+	CircuitBreakerTransitioningToHalfOpenMessage = "circuit breaker transitioning to half-open"
+	CircuitBreakerOpenedMessage                  = "circuit breaker opened"
+	CircuitBreakerReopenedMessage                = "circuit breaker reopened"
+	CircuitBreakerClosedMessage                  = "circuit breaker closed"
+	CircuitBreakerCleanupMessage                 = "circuit breaker cleanup"
+	CircuitBreakerOpenMessage                    = "circuit breaker is open, failing fast"
+
+	// ========================================
+	// CONFIG.GO - Configuration and debug
+	// ========================================
+	DebugLoggingEnabledMessage = "debug logging enabled"
+	ConfigDebugMessage         = "config debug"
+
+	// ========================================
+	// ERRORS.GO - Error message constants
+	// ========================================
+	InvalidRelaxedTimeoutErrorMessage                 = "relaxed timeout must be greater than 0"
+	InvalidHandoffTimeoutErrorMessage                 = "handoff timeout must be greater than 0"
+	InvalidHandoffWorkersErrorMessage                 = "MaxWorkers must be greater than or equal to 0"
+	InvalidHandoffQueueSizeErrorMessage               = "handoff queue size must be greater than 0"
+	InvalidPostHandoffRelaxedDurationErrorMessage     = "post-handoff relaxed duration must be greater than or equal to 0"
+	InvalidEndpointTypeErrorMessage                   = "invalid endpoint type"
+	InvalidMaintNotificationsErrorMessage             = "invalid maintenance notifications setting (must be 'disabled', 'enabled', or 'auto')"
+	InvalidHandoffRetriesErrorMessage                 = "MaxHandoffRetries must be between 1 and 10"
+	InvalidClientErrorMessage                         = "invalid client type"
+	InvalidNotificationErrorMessage                   = "invalid notification format"
+	MaxHandoffRetriesReachedErrorMessage              = "max handoff retries reached"
+	HandoffQueueFullErrorMessage                      = "handoff queue is full, cannot queue new handoff requests - consider increasing HandoffQueueSize or MaxWorkers in configuration"
+	InvalidCircuitBreakerFailureThresholdErrorMessage = "circuit breaker failure threshold must be >= 1"
+	InvalidCircuitBreakerResetTimeoutErrorMessage     = "circuit breaker reset timeout must be >= 0"
+	InvalidCircuitBreakerMaxRequestsErrorMessage      = "circuit breaker max requests must be >= 1"
+	ConnectionMarkedForHandoffErrorMessage            = "connection marked for handoff"
+	ConnectionInvalidHandoffStateErrorMessage         = "connection is in invalid state for handoff"
+	ShutdownErrorMessage                              = "shutdown"
+	CircuitBreakerOpenErrorMessage                    = "circuit breaker is open, failing fast"
+
+	// ========================================
+	// EXAMPLE_HOOKS.GO - Example metrics hooks
+	// ========================================
+	MetricsHookProcessingNotificationMessage = "metrics hook processing"
+	MetricsHookRecordedErrorMessage          = "metrics hook recorded error"
+
+	// ========================================
+	// HANDOFF_WORKER.GO - Connection handoff processing
+	// ========================================
+	HandoffStartedMessage                            = "handoff started"
+	HandoffFailedMessage                             = "handoff failed"
+	ConnectionNotMarkedForHandoffMessage             = "is not marked for handoff and has no retries"
+	ConnectionNotMarkedForHandoffErrorMessage        = "is not marked for handoff"
+	HandoffRetryAttemptMessage                       = "Performing handoff"
+	CannotQueueHandoffForRetryMessage                = "can't queue handoff for retry"
+	HandoffQueueFullMessage                          = "handoff queue is full"
+	FailedToDialNewEndpointMessage                   = "failed to dial new endpoint"
+	ApplyingRelaxedTimeoutDueToPostHandoffMessage    = "applying relaxed timeout due to post-handoff"
+	HandoffSuccessMessage                            = "handoff succeeded"
+	RemovingConnectionFromPoolMessage                = "removing connection from pool"
+	NoPoolProvidedMessageCannotRemoveMessage         = "no pool provided, cannot remove connection, closing it"
+	WorkerExitingDueToShutdownMessage                = "worker exiting due to shutdown"
+	WorkerExitingDueToShutdownWhileProcessingMessage = "worker exiting due to shutdown while processing request"
+	WorkerPanicRecoveredMessage                      = "worker panic recovered"
+	WorkerExitingDueToInactivityTimeoutMessage       = "worker exiting due to inactivity timeout"
+	ReachedMaxHandoffRetriesMessage                  = "reached max handoff retries"
+
+	// ========================================
+	// MANAGER.GO - Moving operation tracking and handler registration
+	// ========================================
+	DuplicateMovingOperationMessage  = "duplicate MOVING operation ignored"
+	TrackingMovingOperationMessage   = "tracking MOVING operation"
+	UntrackingMovingOperationMessage = "untracking MOVING operation"
+	OperationNotTrackedMessage       = "operation not tracked"
+	FailedToRegisterHandlerMessage   = "failed to register handler"
+
+	// ========================================
+	// HOOKS.GO - Notification processing hooks
+	// ========================================
+	ProcessingNotificationMessage          = "processing notification started"
+	ProcessingNotificationFailedMessage    = "proccessing notification failed"
+	ProcessingNotificationSucceededMessage = "processing notification succeeded"
+
+	// ========================================
+	// POOL_HOOK.GO - Pool connection management
+	// ========================================
+	FailedToQueueHandoffMessage = "failed to queue handoff"
+	MarkedForHandoffMessage     = "connection marked for handoff"
+
+	// ========================================
+	// PUSH_NOTIFICATION_HANDLER.GO - Push notification validation and processing
+	// ========================================
+	InvalidNotificationFormatMessage              = "invalid notification format"
+	InvalidNotificationTypeFormatMessage          = "invalid notification type format"
+	InvalidSeqIDInMovingNotificationMessage       = "invalid seqID in MOVING notification"
+	InvalidTimeSInMovingNotificationMessage       = "invalid timeS in MOVING notification"
+	InvalidNewEndpointInMovingNotificationMessage = "invalid newEndpoint in MOVING notification"
+	NoConnectionInHandlerContextMessage           = "no connection in handler context"
+	InvalidConnectionTypeInHandlerContextMessage  = "invalid connection type in handler context"
+	SchedulingHandoffToCurrentEndpointMessage     = "scheduling handoff to current endpoint"
+	RelaxedTimeoutDueToNotificationMessage        = "applying relaxed timeout due to notification"
+	UnrelaxedTimeoutMessage                       = "clearing relaxed timeout"
+	ManagerNotInitializedMessage                  = "manager not initialized"
+	FailedToMarkForHandoffMessage                 = "failed to mark connection for handoff"
+
+	// ========================================
+	// used in pool/conn
+	// ========================================
+	UnrelaxedTimeoutAfterDeadlineMessage = "clearing relaxed timeout after deadline"
+)
+
+func HandoffStarted(connID uint64, newEndpoint string) string {
+	message := fmt.Sprintf("conn[%d] %s to %s", connID, HandoffStartedMessage, newEndpoint)
+	return appendJSONIfDebug(message, map[string]interface{}{
+		"connID":   connID,
+		"endpoint": newEndpoint,
+	})
+}
+
+func HandoffFailed(connID uint64, newEndpoint string, attempt int, maxAttempts int, err error) string {
+	message := fmt.Sprintf("conn[%d] %s to %s (attempt %d/%d): %v", connID, HandoffFailedMessage, newEndpoint, attempt, maxAttempts, err)
+	return appendJSONIfDebug(message, map[string]interface{}{
+		"connID":      connID,
+		"endpoint":    newEndpoint,
+		"attempt":     attempt,
+		"maxAttempts": maxAttempts,
+		"error":       err.Error(),
+	})
+}
+
+func HandoffSucceeded(connID uint64, newEndpoint string) string {
+	message := fmt.Sprintf("conn[%d] %s to %s", connID, HandoffSuccessMessage, newEndpoint)
+	return appendJSONIfDebug(message, map[string]interface{}{
+		"connID":   connID,
+		"endpoint": newEndpoint,
+	})
+}
+
+// Timeout-related log functions
+func RelaxedTimeoutDueToNotification(connID uint64, notificationType string, timeout interface{}) string {
+	message := fmt.Sprintf("conn[%d] %s %s (%v)", connID, RelaxedTimeoutDueToNotificationMessage, notificationType, timeout)
+	return appendJSONIfDebug(message, map[string]interface{}{
+		"connID":           connID,
+		"notificationType": notificationType,
+		"timeout":          fmt.Sprintf("%v", timeout),
+	})
+}
+
+func UnrelaxedTimeout(connID uint64) string {
+	message := fmt.Sprintf("conn[%d] %s", connID, UnrelaxedTimeoutMessage)
+	return appendJSONIfDebug(message, map[string]interface{}{
+		"connID": connID,
+	})
+}
+
+func UnrelaxedTimeoutAfterDeadline(connID uint64) string {
+	message := fmt.Sprintf("conn[%d] %s", connID, UnrelaxedTimeoutAfterDeadlineMessage)
+	return appendJSONIfDebug(message, map[string]interface{}{
+		"connID": connID,
+	})
+}
+
+// Handoff queue and marking functions
+func HandoffQueueFull(queueLen, queueCap int) string {
+	message := fmt.Sprintf("%s (%d/%d), cannot queue new handoff requests - consider increasing HandoffQueueSize or MaxWorkers in configuration", HandoffQueueFullMessage, queueLen, queueCap)
+	return appendJSONIfDebug(message, map[string]interface{}{
+		"queueLen": queueLen,
+		"queueCap": queueCap,
+	})
+}
+
+func FailedToQueueHandoff(connID uint64, err error) string {
+	message := fmt.Sprintf("conn[%d] %s: %v", connID, FailedToQueueHandoffMessage, err)
+	return appendJSONIfDebug(message, map[string]interface{}{
+		"connID": connID,
+		"error":  err.Error(),
+	})
+}
+
+func FailedToMarkForHandoff(connID uint64, err error) string {
+	message := fmt.Sprintf("conn[%d] %s: %v", connID, FailedToMarkForHandoffMessage, err)
+	return appendJSONIfDebug(message, map[string]interface{}{
+		"connID": connID,
+		"error":  err.Error(),
+	})
+}
+
+func FailedToDialNewEndpoint(connID uint64, endpoint string, err error) string {
+	message := fmt.Sprintf("conn[%d] %s %s: %v", connID, FailedToDialNewEndpointMessage, endpoint, err)
+	return appendJSONIfDebug(message, map[string]interface{}{
+		"connID":   connID,
+		"endpoint": endpoint,
+		"error":    err.Error(),
+	})
+}
+
+func ReachedMaxHandoffRetries(connID uint64, endpoint string, maxRetries int) string {
+	message := fmt.Sprintf("conn[%d] %s to %s (max retries: %d)", connID, ReachedMaxHandoffRetriesMessage, endpoint, maxRetries)
+	return appendJSONIfDebug(message, map[string]interface{}{
+		"connID":     connID,
+		"endpoint":   endpoint,
+		"maxRetries": maxRetries,
+	})
+}
+
+// Notification processing functions
+func ProcessingNotification(connID uint64, seqID int64, notificationType string, notification interface{}) string {
+	message := fmt.Sprintf("conn[%d] seqID[%d] %s %s: %v", connID, seqID, ProcessingNotificationMessage, notificationType, notification)
+	return appendJSONIfDebug(message, map[string]interface{}{
+		"connID":           connID,
+		"seqID":            seqID,
+		"notificationType": notificationType,
+		"notification":     fmt.Sprintf("%v", notification),
+	})
+}
+
+func ProcessingNotificationFailed(connID uint64, notificationType string, err error, notification interface{}) string {
+	message := fmt.Sprintf("conn[%d] %s %s: %v - %v", connID, ProcessingNotificationFailedMessage, notificationType, err, notification)
+	return appendJSONIfDebug(message, map[string]interface{}{
+		"connID":           connID,
+		"notificationType": notificationType,
+		"error":            err.Error(),
+		"notification":     fmt.Sprintf("%v", notification),
+	})
+}
+
+func ProcessingNotificationSucceeded(connID uint64, notificationType string) string {
+	message := fmt.Sprintf("conn[%d] %s %s", connID, ProcessingNotificationSucceededMessage, notificationType)
+	return appendJSONIfDebug(message, map[string]interface{}{
+		"connID":           connID,
+		"notificationType": notificationType,
+	})
+}
+
+// Moving operation tracking functions
+func DuplicateMovingOperation(connID uint64, endpoint string, seqID int64) string {
+	message := fmt.Sprintf("conn[%d] %s for %s seqID[%d]", connID, DuplicateMovingOperationMessage, endpoint, seqID)
+	return appendJSONIfDebug(message, map[string]interface{}{
+		"connID":   connID,
+		"endpoint": endpoint,
+		"seqID":    seqID,
+	})
+}
+
+func TrackingMovingOperation(connID uint64, endpoint string, seqID int64) string {
+	message := fmt.Sprintf("conn[%d] %s for %s seqID[%d]", connID, TrackingMovingOperationMessage, endpoint, seqID)
+	return appendJSONIfDebug(message, map[string]interface{}{
+		"connID":   connID,
+		"endpoint": endpoint,
+		"seqID":    seqID,
+	})
+}
+
+func UntrackingMovingOperation(connID uint64, seqID int64) string {
+	message := fmt.Sprintf("conn[%d] %s seqID[%d]", connID, UntrackingMovingOperationMessage, seqID)
+	return appendJSONIfDebug(message, map[string]interface{}{
+		"connID": connID,
+		"seqID":  seqID,
+	})
+}
+
+func OperationNotTracked(connID uint64, seqID int64) string {
+	message := fmt.Sprintf("conn[%d] %s seqID[%d]", connID, OperationNotTrackedMessage, seqID)
+	return appendJSONIfDebug(message, map[string]interface{}{
+		"connID": connID,
+		"seqID":  seqID,
+	})
+}
+
+// Connection pool functions
+func RemovingConnectionFromPool(connID uint64, reason error) string {
+	message := fmt.Sprintf("conn[%d] %s due to: %v", connID, RemovingConnectionFromPoolMessage, reason)
+	return appendJSONIfDebug(message, map[string]interface{}{
+		"connID": connID,
+		"reason": reason.Error(),
+	})
+}
+
+func NoPoolProvidedCannotRemove(connID uint64, reason error) string {
+	message := fmt.Sprintf("conn[%d] %s due to: %v", connID, NoPoolProvidedMessageCannotRemoveMessage, reason)
+	return appendJSONIfDebug(message, map[string]interface{}{
+		"connID": connID,
+		"reason": reason.Error(),
+	})
+}
+
+// Circuit breaker functions
+func CircuitBreakerOpen(connID uint64, endpoint string) string {
+	message := fmt.Sprintf("conn[%d] %s for %s", connID, CircuitBreakerOpenMessage, endpoint)
+	return appendJSONIfDebug(message, map[string]interface{}{
+		"connID":   connID,
+		"endpoint": endpoint,
+	})
+}
+
+// Additional handoff functions for specific cases
+func ConnectionNotMarkedForHandoff(connID uint64) string {
+	message := fmt.Sprintf("conn[%d] %s", connID, ConnectionNotMarkedForHandoffMessage)
+	return appendJSONIfDebug(message, map[string]interface{}{
+		"connID": connID,
+	})
+}
+
+func ConnectionNotMarkedForHandoffError(connID uint64) string {
+	return fmt.Sprintf("conn[%d] %s", connID, ConnectionNotMarkedForHandoffErrorMessage)
+}
+
+func HandoffRetryAttempt(connID uint64, retries int, newEndpoint string, oldEndpoint string) string {
+	message := fmt.Sprintf("conn[%d] Retry %d: %s to %s(was %s)", connID, retries, HandoffRetryAttemptMessage, newEndpoint, oldEndpoint)
+	return appendJSONIfDebug(message, map[string]interface{}{
+		"connID":      connID,
+		"retries":     retries,
+		"newEndpoint": newEndpoint,
+		"oldEndpoint": oldEndpoint,
+	})
+}
+
+func CannotQueueHandoffForRetry(err error) string {
+	message := fmt.Sprintf("%s: %v", CannotQueueHandoffForRetryMessage, err)
+	return appendJSONIfDebug(message, map[string]interface{}{
+		"error": err.Error(),
+	})
+}
+
+// Validation and error functions
+func InvalidNotificationFormat(notification interface{}) string {
+	message := fmt.Sprintf("%s: %v", InvalidNotificationFormatMessage, notification)
+	return appendJSONIfDebug(message, map[string]interface{}{
+		"notification": fmt.Sprintf("%v", notification),
+	})
+}
+
+func InvalidNotificationTypeFormat(notificationType interface{}) string {
+	message := fmt.Sprintf("%s: %v", InvalidNotificationTypeFormatMessage, notificationType)
+	return appendJSONIfDebug(message, map[string]interface{}{
+		"notificationType": fmt.Sprintf("%v", notificationType),
+	})
+}
+
+// InvalidNotification creates a log message for invalid notifications of any type
+func InvalidNotification(notificationType string, notification interface{}) string {
+	message := fmt.Sprintf("invalid %s notification: %v", notificationType, notification)
+	return appendJSONIfDebug(message, map[string]interface{}{
+		"notificationType": notificationType,
+		"notification":     fmt.Sprintf("%v", notification),
+	})
+}
+
+func InvalidSeqIDInMovingNotification(seqID interface{}) string {
+	message := fmt.Sprintf("%s: %v", InvalidSeqIDInMovingNotificationMessage, seqID)
+	return appendJSONIfDebug(message, map[string]interface{}{
+		"seqID": fmt.Sprintf("%v", seqID),
+	})
+}
+
+func InvalidTimeSInMovingNotification(timeS interface{}) string {
+	message := fmt.Sprintf("%s: %v", InvalidTimeSInMovingNotificationMessage, timeS)
+	return appendJSONIfDebug(message, map[string]interface{}{
+		"timeS": fmt.Sprintf("%v", timeS),
+	})
+}
+
+func InvalidNewEndpointInMovingNotification(newEndpoint interface{}) string {
+	message := fmt.Sprintf("%s: %v", InvalidNewEndpointInMovingNotificationMessage, newEndpoint)
+	return appendJSONIfDebug(message, map[string]interface{}{
+		"newEndpoint": fmt.Sprintf("%v", newEndpoint),
+	})
+}
+
+func NoConnectionInHandlerContext(notificationType string) string {
+	message := fmt.Sprintf("%s for %s notification", NoConnectionInHandlerContextMessage, notificationType)
+	return appendJSONIfDebug(message, map[string]interface{}{
+		"notificationType": notificationType,
+	})
+}
+
+func InvalidConnectionTypeInHandlerContext(notificationType string, conn interface{}, handlerCtx interface{}) string {
+	message := fmt.Sprintf("%s for %s notification - %T %#v", InvalidConnectionTypeInHandlerContextMessage, notificationType, conn, handlerCtx)
+	return appendJSONIfDebug(message, map[string]interface{}{
+		"notificationType": notificationType,
+		"connType":         fmt.Sprintf("%T", conn),
+	})
+}
+
+func SchedulingHandoffToCurrentEndpoint(connID uint64, seconds float64) string {
+	message := fmt.Sprintf("conn[%d] %s in %v seconds", connID, SchedulingHandoffToCurrentEndpointMessage, seconds)
+	return appendJSONIfDebug(message, map[string]interface{}{
+		"connID":  connID,
+		"seconds": seconds,
+	})
+}
+
+func ManagerNotInitialized() string {
+	return appendJSONIfDebug(ManagerNotInitializedMessage, map[string]interface{}{})
+}
+
+func FailedToRegisterHandler(notificationType string, err error) string {
+	message := fmt.Sprintf("%s for %s: %v", FailedToRegisterHandlerMessage, notificationType, err)
+	return appendJSONIfDebug(message, map[string]interface{}{
+		"notificationType": notificationType,
+		"error":            err.Error(),
+	})
+}
+
+func ShutdownError() string {
+	return appendJSONIfDebug(ShutdownErrorMessage, map[string]interface{}{})
+}
+
+// Configuration validation error functions
+func InvalidRelaxedTimeoutError() string {
+	return appendJSONIfDebug(InvalidRelaxedTimeoutErrorMessage, map[string]interface{}{})
+}
+
+func InvalidHandoffTimeoutError() string {
+	return appendJSONIfDebug(InvalidHandoffTimeoutErrorMessage, map[string]interface{}{})
+}
+
+func InvalidHandoffWorkersError() string {
+	return appendJSONIfDebug(InvalidHandoffWorkersErrorMessage, map[string]interface{}{})
+}
+
+func InvalidHandoffQueueSizeError() string {
+	return appendJSONIfDebug(InvalidHandoffQueueSizeErrorMessage, map[string]interface{}{})
+}
+
+func InvalidPostHandoffRelaxedDurationError() string {
+	return appendJSONIfDebug(InvalidPostHandoffRelaxedDurationErrorMessage, map[string]interface{}{})
+}
+
+func InvalidEndpointTypeError() string {
+	return appendJSONIfDebug(InvalidEndpointTypeErrorMessage, map[string]interface{}{})
+}
+
+func InvalidMaintNotificationsError() string {
+	return appendJSONIfDebug(InvalidMaintNotificationsErrorMessage, map[string]interface{}{})
+}
+
+func InvalidHandoffRetriesError() string {
+	return appendJSONIfDebug(InvalidHandoffRetriesErrorMessage, map[string]interface{}{})
+}
+
+func InvalidClientError() string {
+	return appendJSONIfDebug(InvalidClientErrorMessage, map[string]interface{}{})
+}
+
+func InvalidNotificationError() string {
+	return appendJSONIfDebug(InvalidNotificationErrorMessage, map[string]interface{}{})
+}
+
+func MaxHandoffRetriesReachedError() string {
+	return appendJSONIfDebug(MaxHandoffRetriesReachedErrorMessage, map[string]interface{}{})
+}
+
+func HandoffQueueFullError() string {
+	return appendJSONIfDebug(HandoffQueueFullErrorMessage, map[string]interface{}{})
+}
+
+func InvalidCircuitBreakerFailureThresholdError() string {
+	return appendJSONIfDebug(InvalidCircuitBreakerFailureThresholdErrorMessage, map[string]interface{}{})
+}
+
+func InvalidCircuitBreakerResetTimeoutError() string {
+	return appendJSONIfDebug(InvalidCircuitBreakerResetTimeoutErrorMessage, map[string]interface{}{})
+}
+
+func InvalidCircuitBreakerMaxRequestsError() string {
+	return appendJSONIfDebug(InvalidCircuitBreakerMaxRequestsErrorMessage, map[string]interface{}{})
+}
+
+// Configuration and debug functions
+func DebugLoggingEnabled() string {
+	return appendJSONIfDebug(DebugLoggingEnabledMessage, map[string]interface{}{})
+}
+
+func ConfigDebug(config interface{}) string {
+	message := fmt.Sprintf("%s: %+v", ConfigDebugMessage, config)
+	return appendJSONIfDebug(message, map[string]interface{}{
+		"config": fmt.Sprintf("%+v", config),
+	})
+}
+
+// Handoff worker functions
+func WorkerExitingDueToShutdown() string {
+	return appendJSONIfDebug(WorkerExitingDueToShutdownMessage, map[string]interface{}{})
+}
+
+func WorkerExitingDueToShutdownWhileProcessing() string {
+	return appendJSONIfDebug(WorkerExitingDueToShutdownWhileProcessingMessage, map[string]interface{}{})
+}
+
+func WorkerPanicRecovered(panicValue interface{}) string {
+	message := fmt.Sprintf("%s: %v", WorkerPanicRecoveredMessage, panicValue)
+	return appendJSONIfDebug(message, map[string]interface{}{
+		"panic": fmt.Sprintf("%v", panicValue),
+	})
+}
+
+func WorkerExitingDueToInactivityTimeout(timeout interface{}) string {
+	message := fmt.Sprintf("%s (%v)", WorkerExitingDueToInactivityTimeoutMessage, timeout)
+	return appendJSONIfDebug(message, map[string]interface{}{
+		"timeout": fmt.Sprintf("%v", timeout),
+	})
+}
+
+func ApplyingRelaxedTimeoutDueToPostHandoff(connID uint64, timeout interface{}, until string) string {
+	message := fmt.Sprintf("conn[%d] %s (%v) until %s", connID, ApplyingRelaxedTimeoutDueToPostHandoffMessage, timeout, until)
+	return appendJSONIfDebug(message, map[string]interface{}{
+		"connID":  connID,
+		"timeout": fmt.Sprintf("%v", timeout),
+		"until":   until,
+	})
+}
+
+// Example hooks functions
+func MetricsHookProcessingNotification(notificationType string, connID uint64) string {
+	message := fmt.Sprintf("%s %s notification on conn[%d]", MetricsHookProcessingNotificationMessage, notificationType, connID)
+	return appendJSONIfDebug(message, map[string]interface{}{
+		"notificationType": notificationType,
+		"connID":           connID,
+	})
+}
+
+func MetricsHookRecordedError(notificationType string, connID uint64, err error) string {
+	message := fmt.Sprintf("%s for %s notification on conn[%d]: %v", MetricsHookRecordedErrorMessage, notificationType, connID, err)
+	return appendJSONIfDebug(message, map[string]interface{}{
+		"notificationType": notificationType,
+		"connID":           connID,
+		"error":            err.Error(),
+	})
+}
+
+// Pool hook functions
+func MarkedForHandoff(connID uint64) string {
+	message := fmt.Sprintf("conn[%d] %s", connID, MarkedForHandoffMessage)
+	return appendJSONIfDebug(message, map[string]interface{}{
+		"connID": connID,
+	})
+}
+
+// Circuit breaker additional functions
+func CircuitBreakerTransitioningToHalfOpen(endpoint string) string {
+	message := fmt.Sprintf("%s for %s", CircuitBreakerTransitioningToHalfOpenMessage, endpoint)
+	return appendJSONIfDebug(message, map[string]interface{}{
+		"endpoint": endpoint,
+	})
+}
+
+func CircuitBreakerOpened(endpoint string, failures int64) string {
+	message := fmt.Sprintf("%s for endpoint %s after %d failures", CircuitBreakerOpenedMessage, endpoint, failures)
+	return appendJSONIfDebug(message, map[string]interface{}{
+		"endpoint": endpoint,
+		"failures": failures,
+	})
+}
+
+func CircuitBreakerReopened(endpoint string) string {
+	message := fmt.Sprintf("%s for endpoint %s due to failure in half-open state", CircuitBreakerReopenedMessage, endpoint)
+	return appendJSONIfDebug(message, map[string]interface{}{
+		"endpoint": endpoint,
+	})
+}
+
+func CircuitBreakerClosed(endpoint string, successes int64) string {
+	message := fmt.Sprintf("%s for endpoint %s after %d successful requests", CircuitBreakerClosedMessage, endpoint, successes)
+	return appendJSONIfDebug(message, map[string]interface{}{
+		"endpoint":  endpoint,
+		"successes": successes,
+	})
+}
+
+func CircuitBreakerCleanup(removed int, total int) string {
+	message := fmt.Sprintf("%s removed %d/%d entries", CircuitBreakerCleanupMessage, removed, total)
+	return appendJSONIfDebug(message, map[string]interface{}{
+		"removed": removed,
+		"total":   total,
+	})
+}
+
+// ExtractDataFromLogMessage extracts structured data from maintnotifications log messages
+// Returns a map containing the parsed key-value pairs from the structured data section
+// Example: "conn[123] handoff started to localhost:6379 {"connID":123,"endpoint":"localhost:6379"}"
+// Returns: map[string]interface{}{"connID": 123, "endpoint": "localhost:6379"}
+func ExtractDataFromLogMessage(logMessage string) map[string]interface{} {
+	result := make(map[string]interface{})
+
+	// Find the JSON data section at the end of the message
+	re := regexp.MustCompile(`(\{.*\})$`)
+	matches := re.FindStringSubmatch(logMessage)
+	if len(matches) < 2 {
+		return result
+	}
+
+	jsonStr := matches[1]
+	if jsonStr == "" {
+		return result
+	}
+
+	// Parse the JSON directly
+	var jsonResult map[string]interface{}
+	if err := json.Unmarshal([]byte(jsonStr), &jsonResult); err == nil {
+		return jsonResult
+	}
+
+	// If JSON parsing fails, return empty map
+	return result
+}

vendor/github.com/redis/go-redis/v9/internal/pool/conn.go

@@ -1,28 +1,124 @@
+// Package pool implements the pool management
 package pool
 
 import (
 	"bufio"
 	"context"
+	"errors"
+	"fmt"
 	"net"
+	"sync"
 	"sync/atomic"
 	"time"
 
+	"github.com/redis/go-redis/v9/internal"
+	"github.com/redis/go-redis/v9/internal/maintnotifications/logs"
 	"github.com/redis/go-redis/v9/internal/proto"
 )
 
 var noDeadline = time.Time{}
 
+// Preallocated errors for hot paths to avoid allocations
+var (
+	errAlreadyMarkedForHandoff  = errors.New("connection is already marked for handoff")
+	errNotMarkedForHandoff      = errors.New("connection was not marked for handoff")
+	errHandoffStateChanged      = errors.New("handoff state changed during marking")
+	errConnectionNotAvailable   = errors.New("redis: connection not available")
+	errConnNotAvailableForWrite = errors.New("redis: connection not available for write operation")
+)
+
+// getCachedTimeNs returns the current time in nanoseconds.
+// This function previously used a global cache updated by a background goroutine,
+// but that caused unnecessary CPU usage when the client was idle (ticker waking up
+// the scheduler every 50ms). We now use time.Now() directly, which is fast enough
+// on modern systems (vDSO on Linux) and only adds ~1-2% overhead in extreme
+// high-concurrency benchmarks while eliminating idle CPU usage.
+func getCachedTimeNs() int64 {
+	return time.Now().UnixNano()
+}
+
+// GetCachedTimeNs returns the current time in nanoseconds.
+// Exported for use by other packages that need fast time access.
+func GetCachedTimeNs() int64 {
+	return getCachedTimeNs()
+}
+
+// Global atomic counter for connection IDs
+var connIDCounter uint64
+
+// HandoffState represents the atomic state for connection handoffs
+// This struct is stored atomically to prevent race conditions between
+// checking handoff status and reading handoff parameters
+type HandoffState struct {
+	ShouldHandoff bool   // Whether connection should be handed off
+	Endpoint      string // New endpoint for handoff
+	SeqID         int64  // Sequence ID from MOVING notification
+}
+
+// atomicNetConn is a wrapper to ensure consistent typing in atomic.Value
+type atomicNetConn struct {
+	conn net.Conn
+}
+
+// generateConnID generates a fast unique identifier for a connection with zero allocations
+func generateConnID() uint64 {
+	return atomic.AddUint64(&connIDCounter, 1)
+}
+
 type Conn struct {
-	usedAt  int64 // atomic
-	netConn net.Conn
+	// Connection identifier for unique tracking
+	id uint64
+
+	usedAt    atomic.Int64
+	lastPutAt atomic.Int64
+
+	// Lock-free netConn access using atomic.Value
+	// Contains *atomicNetConn wrapper, accessed atomically for better performance
+	netConnAtomic atomic.Value // stores *atomicNetConn
 
 	rd *proto.Reader
 	bw *bufio.Writer
 	wr *proto.Writer
 
-	Inited    bool
+	// Lightweight mutex to protect reader operations during handoff
+	// Only used for the brief period during SetNetConn and HasBufferedData/PeekReplyTypeSafe
+	readerMu sync.RWMutex
+
+	// State machine for connection state management
+	// Replaces: usable, Inited, used
+	// Provides thread-safe state transitions with FIFO waiting queue
+	// States: CREATED → INITIALIZING → IDLE ⇄ IN_USE
+	//                                    ↓
+	//                                UNUSABLE (handoff/reauth)
+	//                                    ↓
+	//                                IDLE/CLOSED
+	stateMachine *ConnStateMachine
+
+	// Handoff metadata - managed separately from state machine
+	// These are atomic for lock-free access during handoff operations
+	handoffStateAtomic   atomic.Value  // stores *HandoffState
+	handoffRetriesAtomic atomic.Uint32 // retry counter
+
 	pooled    bool
+	pubsub    bool
+	closed    atomic.Bool
 	createdAt time.Time
+	expiresAt time.Time
+
+	// maintenanceNotifications upgrade support: relaxed timeouts during migrations/failovers
+
+	// Using atomic operations for lock-free access to avoid mutex contention
+	relaxedReadTimeoutNs  atomic.Int64 // time.Duration as nanoseconds
+	relaxedWriteTimeoutNs atomic.Int64 // time.Duration as nanoseconds
+	relaxedDeadlineNs     atomic.Int64 // time.Time as nanoseconds since epoch
+
+	// Counter to track multiple relaxed timeout setters if we have nested calls
+	// will be decremented when ClearRelaxedTimeout is called or deadline is reached
+	// if counter reaches 0, we clear the relaxed timeouts
+	relaxedCounter atomic.Int32
+
+	// Connection initialization function for reconnections
+	initConnFunc func(context.Context, *Conn) error
 
 	onClose func() error
 }
@@ -32,9 +128,11 @@ func NewConn(netConn net.Conn) *Conn {
 }
 
 func NewConnWithBufferSize(netConn net.Conn, readBufSize, writeBufSize int) *Conn {
+	now := time.Now()
 	cn := &Conn{
-		netConn:   netConn,
-		createdAt: time.Now(),
+		createdAt:    now,
+		id:           generateConnID(), // Generate unique ID for this connection
+		stateMachine: NewConnStateMachine(),
 	}
 
 	// Use specified buffer sizes, or fall back to 32KiB defaults if 0
@@ -50,37 +148,656 @@ func NewConnWithBufferSize(netConn net.Conn, readBufSize, writeBufSize int) *Con
 		cn.bw = bufio.NewWriterSize(netConn, proto.DefaultBufferSize)
 	}
 
+	// Store netConn atomically for lock-free access using wrapper
+	cn.netConnAtomic.Store(&atomicNetConn{conn: netConn})
+
 	cn.wr = proto.NewWriter(cn.bw)
-	cn.SetUsedAt(time.Now())
+	cn.SetUsedAt(now)
+	// Initialize handoff state atomically
+	initialHandoffState := &HandoffState{
+		ShouldHandoff: false,
+		Endpoint:      "",
+		SeqID:         0,
+	}
+	cn.handoffStateAtomic.Store(initialHandoffState)
 	return cn
 }
 
 func (cn *Conn) UsedAt() time.Time {
-	unix := atomic.LoadInt64(&cn.usedAt)
-	return time.Unix(unix, 0)
+	return time.Unix(0, cn.usedAt.Load())
+}
+func (cn *Conn) SetUsedAt(tm time.Time) {
+	cn.usedAt.Store(tm.UnixNano())
 }
 
-func (cn *Conn) SetUsedAt(tm time.Time) {
-	atomic.StoreInt64(&cn.usedAt, tm.Unix())
+func (cn *Conn) UsedAtNs() int64 {
+	return cn.usedAt.Load()
+}
+func (cn *Conn) SetUsedAtNs(ns int64) {
+	cn.usedAt.Store(ns)
+}
+
+func (cn *Conn) LastPutAtNs() int64 {
+	return cn.lastPutAt.Load()
+}
+func (cn *Conn) SetLastPutAtNs(ns int64) {
+	cn.lastPutAt.Store(ns)
+}
+
+// Backward-compatible wrapper methods for state machine
+// These maintain the existing API while using the new state machine internally
+
+// CompareAndSwapUsable atomically compares and swaps the usable flag (lock-free).
+//
+// This is used by background operations (handoff, re-auth) to acquire exclusive
+// access to a connection. The operation sets usable to false, preventing the pool
+// from returning the connection to clients.
+//
+// Returns true if the swap was successful (old value matched), false otherwise.
+//
+// Implementation note: This is a compatibility wrapper around the state machine.
+// It checks if the current state is "usable" (IDLE or IN_USE) and transitions accordingly.
+// Deprecated: Use GetStateMachine().TryTransition() directly for better state management.
+func (cn *Conn) CompareAndSwapUsable(old, new bool) bool {
+	currentState := cn.stateMachine.GetState()
+
+	// Check if current state matches the "old" usable value
+	currentUsable := (currentState == StateIdle || currentState == StateInUse)
+	if currentUsable != old {
+		return false
+	}
+
+	// If we're trying to set to the same value, succeed immediately
+	if old == new {
+		return true
+	}
+
+	// Transition based on new value
+	if new {
+		// Trying to make usable - transition from UNUSABLE to IDLE
+		// This should only work from UNUSABLE or INITIALIZING states
+		// Use predefined slice to avoid allocation
+		_, err := cn.stateMachine.TryTransition(
+			validFromInitializingOrUnusable,
+			StateIdle,
+		)
+		return err == nil
+	}
+	// Trying to make unusable - transition from IDLE to UNUSABLE
+	// This is typically for acquiring the connection for background operations
+	// Use predefined slice to avoid allocation
+	_, err := cn.stateMachine.TryTransition(
+		validFromIdle,
+		StateUnusable,
+	)
+	return err == nil
+}
+
+// IsUsable returns true if the connection is safe to use for new commands (lock-free).
+//
+// A connection is "usable" when it's in a stable state and can be returned to clients.
+// It becomes unusable during:
+//   - Handoff operations (network connection replacement)
+//   - Re-authentication (credential updates)
+//   - Other background operations that need exclusive access
+//
+// Note: CREATED state is considered usable because new connections need to pass OnGet() hook
+// before initialization. The initialization happens after OnGet() in the client code.
+func (cn *Conn) IsUsable() bool {
+	state := cn.stateMachine.GetState()
+	// CREATED, IDLE, and IN_USE states are considered usable
+	// CREATED: new connection, not yet initialized (will be initialized by client)
+	// IDLE: initialized and ready to be acquired
+	// IN_USE: usable but currently acquired by someone
+	return state == StateCreated || state == StateIdle || state == StateInUse
+}
+
+// SetUsable sets the usable flag for the connection (lock-free).
+//
+// Deprecated: Use GetStateMachine().Transition() directly for better state management.
+// This method is kept for backwards compatibility.
+//
+// This should be called to mark a connection as usable after initialization or
+// to release it after a background operation completes.
+//
+// Prefer CompareAndSwapUsable() when acquiring exclusive access to avoid race conditions.
+// Deprecated: Use GetStateMachine().Transition() directly for better state management.
+func (cn *Conn) SetUsable(usable bool) {
+	if usable {
+		// Transition to IDLE state (ready to be acquired)
+		cn.stateMachine.Transition(StateIdle)
+	} else {
+		// Transition to UNUSABLE state (for background operations)
+		cn.stateMachine.Transition(StateUnusable)
+	}
+}
+
+// IsInited returns true if the connection has been initialized.
+// This is a backward-compatible wrapper around the state machine.
+func (cn *Conn) IsInited() bool {
+	state := cn.stateMachine.GetState()
+	// Connection is initialized if it's in IDLE or any post-initialization state
+	return state != StateCreated && state != StateInitializing && state != StateClosed
+}
+
+// Used - State machine based implementation
+
+// CompareAndSwapUsed atomically compares and swaps the used flag (lock-free).
+// This method is kept for backwards compatibility.
+//
+// This is the preferred method for acquiring a connection from the pool, as it
+// ensures that only one goroutine marks the connection as used.
+//
+// Implementation: Uses state machine transitions IDLE ⇄ IN_USE
+//
+// Returns true if the swap was successful (old value matched), false otherwise.
+// Deprecated: Use GetStateMachine().TryTransition() directly for better state management.
+func (cn *Conn) CompareAndSwapUsed(old, new bool) bool {
+	if old == new {
+		// No change needed
+		currentState := cn.stateMachine.GetState()
+		currentUsed := (currentState == StateInUse)
+		return currentUsed == old
+	}
+
+	if !old && new {
+		// Acquiring: IDLE → IN_USE
+		// Use predefined slice to avoid allocation
+		_, err := cn.stateMachine.TryTransition(validFromCreatedOrIdle, StateInUse)
+		return err == nil
+	} else {
+		// Releasing: IN_USE → IDLE
+		// Use predefined slice to avoid allocation
+		_, err := cn.stateMachine.TryTransition(validFromInUse, StateIdle)
+		return err == nil
+	}
+}
+
+// IsUsed returns true if the connection is currently in use (lock-free).
+//
+// Deprecated: Use GetStateMachine().GetState() == StateInUse directly for better clarity.
+// This method is kept for backwards compatibility.
+//
+// A connection is "used" when it has been retrieved from the pool and is
+// actively processing a command. Background operations (like re-auth) should
+// wait until the connection is not used before executing commands.
+func (cn *Conn) IsUsed() bool {
+	return cn.stateMachine.GetState() == StateInUse
+}
+
+// SetUsed sets the used flag for the connection (lock-free).
+//
+// This should be called when returning a connection to the pool (set to false)
+// or when a single-connection pool retrieves its connection (set to true).
+//
+// Prefer CompareAndSwapUsed() when acquiring from a multi-connection pool to
+// avoid race conditions.
+// Deprecated: Use GetStateMachine().Transition() directly for better state management.
+func (cn *Conn) SetUsed(val bool) {
+	if val {
+		cn.stateMachine.Transition(StateInUse)
+	} else {
+		cn.stateMachine.Transition(StateIdle)
+	}
+}
+
+// getNetConn returns the current network connection using atomic load (lock-free).
+// This is the fast path for accessing netConn without mutex overhead.
+func (cn *Conn) getNetConn() net.Conn {
+	if v := cn.netConnAtomic.Load(); v != nil {
+		if wrapper, ok := v.(*atomicNetConn); ok {
+			return wrapper.conn
+		}
+	}
+	return nil
+}
+
+// setNetConn stores the network connection atomically (lock-free).
+// This is used for the fast path of connection replacement.
+func (cn *Conn) setNetConn(netConn net.Conn) {
+	cn.netConnAtomic.Store(&atomicNetConn{conn: netConn})
+}
+
+// Handoff state management - atomic access to handoff metadata
+
+// ShouldHandoff returns true if connection needs handoff (lock-free).
+func (cn *Conn) ShouldHandoff() bool {
+	if v := cn.handoffStateAtomic.Load(); v != nil {
+		return v.(*HandoffState).ShouldHandoff
+	}
+	return false
+}
+
+// GetHandoffEndpoint returns the new endpoint for handoff (lock-free).
+func (cn *Conn) GetHandoffEndpoint() string {
+	if v := cn.handoffStateAtomic.Load(); v != nil {
+		return v.(*HandoffState).Endpoint
+	}
+	return ""
+}
+
+// GetMovingSeqID returns the sequence ID from the MOVING notification (lock-free).
+func (cn *Conn) GetMovingSeqID() int64 {
+	if v := cn.handoffStateAtomic.Load(); v != nil {
+		return v.(*HandoffState).SeqID
+	}
+	return 0
+}
+
+// GetHandoffInfo returns all handoff information atomically (lock-free).
+// This method prevents race conditions by returning all handoff state in a single atomic operation.
+// Returns (shouldHandoff, endpoint, seqID).
+func (cn *Conn) GetHandoffInfo() (bool, string, int64) {
+	if v := cn.handoffStateAtomic.Load(); v != nil {
+		state := v.(*HandoffState)
+		return state.ShouldHandoff, state.Endpoint, state.SeqID
+	}
+	return false, "", 0
+}
+
+// HandoffRetries returns the current handoff retry count (lock-free).
+func (cn *Conn) HandoffRetries() int {
+	return int(cn.handoffRetriesAtomic.Load())
+}
+
+// IncrementAndGetHandoffRetries atomically increments and returns handoff retries (lock-free).
+func (cn *Conn) IncrementAndGetHandoffRetries(n int) int {
+	return int(cn.handoffRetriesAtomic.Add(uint32(n)))
+}
+
+// IsPooled returns true if the connection is managed by a pool and will be pooled on Put.
+func (cn *Conn) IsPooled() bool {
+	return cn.pooled
+}
+
+// IsPubSub returns true if the connection is used for PubSub.
+func (cn *Conn) IsPubSub() bool {
+	return cn.pubsub
+}
+
+// SetRelaxedTimeout sets relaxed timeouts for this connection during maintenanceNotifications upgrades.
+// These timeouts will be used for all subsequent commands until the deadline expires.
+// Uses atomic operations for lock-free access.
+func (cn *Conn) SetRelaxedTimeout(readTimeout, writeTimeout time.Duration) {
+	cn.relaxedCounter.Add(1)
+	cn.relaxedReadTimeoutNs.Store(int64(readTimeout))
+	cn.relaxedWriteTimeoutNs.Store(int64(writeTimeout))
+}
+
+// SetRelaxedTimeoutWithDeadline sets relaxed timeouts with an expiration deadline.
+// After the deadline, timeouts automatically revert to normal values.
+// Uses atomic operations for lock-free access.
+func (cn *Conn) SetRelaxedTimeoutWithDeadline(readTimeout, writeTimeout time.Duration, deadline time.Time) {
+	cn.SetRelaxedTimeout(readTimeout, writeTimeout)
+	cn.relaxedDeadlineNs.Store(deadline.UnixNano())
+}
+
+// ClearRelaxedTimeout removes relaxed timeouts, returning to normal timeout behavior.
+// Uses atomic operations for lock-free access.
+func (cn *Conn) ClearRelaxedTimeout() {
+	// Atomically decrement counter and check if we should clear
+	newCount := cn.relaxedCounter.Add(-1)
+	deadlineNs := cn.relaxedDeadlineNs.Load()
+	if newCount <= 0 && (deadlineNs == 0 || time.Now().UnixNano() >= deadlineNs) {
+		// Use atomic load to get current value for CAS to avoid stale value race
+		current := cn.relaxedCounter.Load()
+		if current <= 0 && cn.relaxedCounter.CompareAndSwap(current, 0) {
+			cn.clearRelaxedTimeout()
+		}
+	}
+}
+
+func (cn *Conn) clearRelaxedTimeout() {
+	cn.relaxedReadTimeoutNs.Store(0)
+	cn.relaxedWriteTimeoutNs.Store(0)
+	cn.relaxedDeadlineNs.Store(0)
+	cn.relaxedCounter.Store(0)
+}
+
+// HasRelaxedTimeout returns true if relaxed timeouts are currently active on this connection.
+// This checks both the timeout values and the deadline (if set).
+// Uses atomic operations for lock-free access.
+func (cn *Conn) HasRelaxedTimeout() bool {
+	// Fast path: no relaxed timeouts are set
+	if cn.relaxedCounter.Load() <= 0 {
+		return false
+	}
+
+	readTimeoutNs := cn.relaxedReadTimeoutNs.Load()
+	writeTimeoutNs := cn.relaxedWriteTimeoutNs.Load()
+
+	// If no relaxed timeouts are set, return false
+	if readTimeoutNs <= 0 && writeTimeoutNs <= 0 {
+		return false
+	}
+
+	deadlineNs := cn.relaxedDeadlineNs.Load()
+	// If no deadline is set, relaxed timeouts are active
+	if deadlineNs == 0 {
+		return true
+	}
+
+	// If deadline is set, check if it's still in the future
+	return time.Now().UnixNano() < deadlineNs
+}
+
+// getEffectiveReadTimeout returns the timeout to use for read operations.
+// If relaxed timeout is set and not expired, it takes precedence over the provided timeout.
+// This method automatically clears expired relaxed timeouts using atomic operations.
+func (cn *Conn) getEffectiveReadTimeout(normalTimeout time.Duration) time.Duration {
+	readTimeoutNs := cn.relaxedReadTimeoutNs.Load()
+
+	// Fast path: no relaxed timeout set
+	if readTimeoutNs <= 0 {
+		return normalTimeout
+	}
+
+	deadlineNs := cn.relaxedDeadlineNs.Load()
+	// If no deadline is set, use relaxed timeout
+	if deadlineNs == 0 {
+		return time.Duration(readTimeoutNs)
+	}
+
+	// Use cached time to avoid expensive syscall (max 50ms staleness is acceptable for timeout checks)
+	nowNs := getCachedTimeNs()
+	// Check if deadline has passed
+	if nowNs < deadlineNs {
+		// Deadline is in the future, use relaxed timeout
+		return time.Duration(readTimeoutNs)
+	} else {
+		// Deadline has passed, clear relaxed timeouts atomically and use normal timeout
+		newCount := cn.relaxedCounter.Add(-1)
+		if newCount <= 0 {
+			internal.Logger.Printf(context.Background(), logs.UnrelaxedTimeoutAfterDeadline(cn.GetID()))
+			cn.clearRelaxedTimeout()
+		}
+		return normalTimeout
+	}
+}
+
+// getEffectiveWriteTimeout returns the timeout to use for write operations.
+// If relaxed timeout is set and not expired, it takes precedence over the provided timeout.
+// This method automatically clears expired relaxed timeouts using atomic operations.
+func (cn *Conn) getEffectiveWriteTimeout(normalTimeout time.Duration) time.Duration {
+	writeTimeoutNs := cn.relaxedWriteTimeoutNs.Load()
+
+	// Fast path: no relaxed timeout set
+	if writeTimeoutNs <= 0 {
+		return normalTimeout
+	}
+
+	deadlineNs := cn.relaxedDeadlineNs.Load()
+	// If no deadline is set, use relaxed timeout
+	if deadlineNs == 0 {
+		return time.Duration(writeTimeoutNs)
+	}
+
+	// Use cached time to avoid expensive syscall (max 50ms staleness is acceptable for timeout checks)
+	nowNs := getCachedTimeNs()
+	// Check if deadline has passed
+	if nowNs < deadlineNs {
+		// Deadline is in the future, use relaxed timeout
+		return time.Duration(writeTimeoutNs)
+	} else {
+		// Deadline has passed, clear relaxed timeouts atomically and use normal timeout
+		newCount := cn.relaxedCounter.Add(-1)
+		if newCount <= 0 {
+			internal.Logger.Printf(context.Background(), logs.UnrelaxedTimeoutAfterDeadline(cn.GetID()))
+			cn.clearRelaxedTimeout()
+		}
+		return normalTimeout
+	}
 }
 
 func (cn *Conn) SetOnClose(fn func() error) {
 	cn.onClose = fn
 }
 
+// SetInitConnFunc sets the connection initialization function to be called on reconnections.
+func (cn *Conn) SetInitConnFunc(fn func(context.Context, *Conn) error) {
+	cn.initConnFunc = fn
+}
+
+// ExecuteInitConn runs the stored connection initialization function if available.
+func (cn *Conn) ExecuteInitConn(ctx context.Context) error {
+	if cn.initConnFunc != nil {
+		return cn.initConnFunc(ctx, cn)
+	}
+	return fmt.Errorf("redis: no initConnFunc set for conn[%d]", cn.GetID())
+}
+
 func (cn *Conn) SetNetConn(netConn net.Conn) {
-	cn.netConn = netConn
+	// Store the new connection atomically first (lock-free)
+	cn.setNetConn(netConn)
+	// Protect reader reset operations to avoid data races
+	// Use write lock since we're modifying the reader state
+	cn.readerMu.Lock()
 	cn.rd.Reset(netConn)
+	cn.readerMu.Unlock()
+
 	cn.bw.Reset(netConn)
 }
 
+// GetNetConn safely returns the current network connection using atomic load (lock-free).
+// This method is used by the pool for health checks and provides better performance.
+func (cn *Conn) GetNetConn() net.Conn {
+	return cn.getNetConn()
+}
+
+// SetNetConnAndInitConn replaces the underlying connection and executes the initialization.
+// This method ensures only one initialization can happen at a time by using atomic state transitions.
+// If another goroutine is currently initializing, this will wait for it to complete.
+func (cn *Conn) SetNetConnAndInitConn(ctx context.Context, netConn net.Conn) error {
+	// Wait for and transition to INITIALIZING state - this prevents concurrent initializations
+	// Valid from states: CREATED (first init), IDLE (reconnect), UNUSABLE (handoff/reauth)
+	// If another goroutine is initializing, we'll wait for it to finish
+	// if the context has a deadline, use that, otherwise use the connection read (relaxed) timeout
+	// which should be set during handoff. If it is not set, use a 5 second default
+	deadline, ok := ctx.Deadline()
+	if !ok {
+		deadline = time.Now().Add(cn.getEffectiveReadTimeout(5 * time.Second))
+	}
+	waitCtx, cancel := context.WithDeadline(ctx, deadline)
+	defer cancel()
+	// Use predefined slice to avoid allocation
+	finalState, err := cn.stateMachine.AwaitAndTransition(
+		waitCtx,
+		validFromCreatedIdleOrUnusable,
+		StateInitializing,
+	)
+	if err != nil {
+		return fmt.Errorf("cannot initialize connection from state %s: %w", finalState, err)
+	}
+
+	// Replace the underlying connection
+	cn.SetNetConn(netConn)
+
+	// Execute initialization
+	// NOTE: ExecuteInitConn (via baseClient.initConn) will transition to IDLE on success
+	// or CLOSED on failure. We don't need to do it here.
+	// NOTE: Initconn returns conn in IDLE state
+	initErr := cn.ExecuteInitConn(ctx)
+	if initErr != nil {
+		// ExecuteInitConn already transitioned to CLOSED, just return the error
+		return initErr
+	}
+
+	// ExecuteInitConn already transitioned to IDLE
+	return nil
+}
+
+// MarkForHandoff marks the connection for handoff due to MOVING notification.
+// Returns an error if the connection is already marked for handoff.
+// Note: This only sets metadata - the connection state is not changed until OnPut.
+// This allows the current user to finish using the connection before handoff.
+func (cn *Conn) MarkForHandoff(newEndpoint string, seqID int64) error {
+	// Check if already marked for handoff
+	if cn.ShouldHandoff() {
+		return errAlreadyMarkedForHandoff
+	}
+
+	// Set handoff metadata atomically
+	cn.handoffStateAtomic.Store(&HandoffState{
+		ShouldHandoff: true,
+		Endpoint:      newEndpoint,
+		SeqID:         seqID,
+	})
+	return nil
+}
+
+// MarkQueuedForHandoff marks the connection as queued for handoff processing.
+// This makes the connection unusable until handoff completes.
+// This is called from OnPut hook, where the connection is typically in IN_USE state.
+// The pool will preserve the UNUSABLE state and not overwrite it with IDLE.
+func (cn *Conn) MarkQueuedForHandoff() error {
+	// Get current handoff state
+	currentState := cn.handoffStateAtomic.Load()
+	if currentState == nil {
+		return errNotMarkedForHandoff
+	}
+
+	state := currentState.(*HandoffState)
+	if !state.ShouldHandoff {
+		return errNotMarkedForHandoff
+	}
+
+	// Create new state with ShouldHandoff=false but preserve endpoint and seqID
+	// This prevents the connection from being queued multiple times while still
+	// allowing the worker to access the handoff metadata
+	newState := &HandoffState{
+		ShouldHandoff: false,
+		Endpoint:      state.Endpoint, // Preserve endpoint for handoff processing
+		SeqID:         state.SeqID,    // Preserve seqID for handoff processing
+	}
+
+	// Atomic compare-and-swap to update state
+	if !cn.handoffStateAtomic.CompareAndSwap(currentState, newState) {
+		// State changed between load and CAS - retry or return error
+		return errHandoffStateChanged
+	}
+
+	// Transition to UNUSABLE from IN_USE (normal flow), IDLE (edge cases), or CREATED (tests/uninitialized)
+	// The connection is typically in IN_USE state when OnPut is called (normal Put flow)
+	// But in some edge cases or tests, it might be in IDLE or CREATED state
+	// The pool will detect this state change and preserve it (not overwrite with IDLE)
+	// Use predefined slice to avoid allocation
+	finalState, err := cn.stateMachine.TryTransition(validFromCreatedInUseOrIdle, StateUnusable)
+	if err != nil {
+		// Check if already in UNUSABLE state (race condition or retry)
+		// ShouldHandoff should be false now, but check just in case
+		if finalState == StateUnusable && !cn.ShouldHandoff() {
+			// Already unusable - this is fine, keep the new handoff state
+			return nil
+		}
+		// Restore the original state if transition fails for other reasons
+		cn.handoffStateAtomic.Store(currentState)
+		return fmt.Errorf("failed to mark connection as unusable: %w", err)
+	}
+	return nil
+}
+
+// GetID returns the unique identifier for this connection.
+func (cn *Conn) GetID() uint64 {
+	return cn.id
+}
+
+// GetStateMachine returns the connection's state machine for advanced state management.
+// This is primarily used by internal packages like maintnotifications for handoff processing.
+func (cn *Conn) GetStateMachine() *ConnStateMachine {
+	return cn.stateMachine
+}
+
+// TryAcquire attempts to acquire the connection for use.
+// This is an optimized inline method for the hot path (Get operation).
+//
+// It tries to transition from IDLE -> IN_USE or CREATED -> CREATED.
+// Returns true if the connection was successfully acquired, false otherwise.
+// The CREATED->CREATED is done so we can keep the state correct for later
+// initialization of the connection in initConn.
+//
+// Performance: This is faster than calling GetStateMachine() + TryTransitionFast()
+//
+// NOTE: We directly access cn.stateMachine.state here instead of using the state machine's
+// methods. This breaks encapsulation but is necessary for performance.
+// The IDLE->IN_USE and CREATED->CREATED transitions don't need
+// waiter notification, and benchmarks show 1-3% improvement. If the state machine ever
+// needs to notify waiters on these transitions, update this to use TryTransitionFast().
+func (cn *Conn) TryAcquire() bool {
+	// The || operator short-circuits, so only 1 CAS in the common case
+	return cn.stateMachine.state.CompareAndSwap(uint32(StateIdle), uint32(StateInUse)) ||
+		cn.stateMachine.state.CompareAndSwap(uint32(StateCreated), uint32(StateCreated))
+}
+
+// Release releases the connection back to the pool.
+// This is an optimized inline method for the hot path (Put operation).
+//
+// It tries to transition from IN_USE -> IDLE.
+// Returns true if the connection was successfully released, false otherwise.
+//
+// Performance: This is faster than calling GetStateMachine() + TryTransitionFast().
+//
+// NOTE: We directly access cn.stateMachine.state here instead of using the state machine's
+// methods. This breaks encapsulation but is necessary for performance.
+// If the state machine ever needs to notify waiters
+// on this transition, update this to use TryTransitionFast().
+func (cn *Conn) Release() bool {
+	// Inline the hot path - single CAS operation
+	return cn.stateMachine.state.CompareAndSwap(uint32(StateInUse), uint32(StateIdle))
+}
+
+// ClearHandoffState clears the handoff state after successful handoff.
+// Makes the connection usable again.
+func (cn *Conn) ClearHandoffState() {
+	// Clear handoff metadata
+	cn.handoffStateAtomic.Store(&HandoffState{
+		ShouldHandoff: false,
+		Endpoint:      "",
+		SeqID:         0,
+	})
+
+	// Reset retry counter
+	cn.handoffRetriesAtomic.Store(0)
+
+	// Mark connection as usable again
+	// Use state machine directly instead of deprecated SetUsable
+	// probably done by initConn
+	cn.stateMachine.Transition(StateIdle)
+}
+
+// HasBufferedData safely checks if the connection has buffered data.
+// This method is used to avoid data races when checking for push notifications.
+func (cn *Conn) HasBufferedData() bool {
+	// Use read lock for concurrent access to reader state
+	cn.readerMu.RLock()
+	defer cn.readerMu.RUnlock()
+	return cn.rd.Buffered() > 0
+}
+
+// PeekReplyTypeSafe safely peeks at the reply type.
+// This method is used to avoid data races when checking for push notifications.
+func (cn *Conn) PeekReplyTypeSafe() (byte, error) {
+	// Use read lock for concurrent access to reader state
+	cn.readerMu.RLock()
+	defer cn.readerMu.RUnlock()
+
+	if cn.rd.Buffered() <= 0 {
+		return 0, fmt.Errorf("redis: can't peek reply type, no data available")
+	}
+	return cn.rd.PeekReplyType()
+}
+
 func (cn *Conn) Write(b []byte) (int, error) {
-	return cn.netConn.Write(b)
+	// Lock-free netConn access for better performance
+	if netConn := cn.getNetConn(); netConn != nil {
+		return netConn.Write(b)
+	}
+	return 0, net.ErrClosed
 }
 
 func (cn *Conn) RemoteAddr() net.Addr {
-	if cn.netConn != nil {
-		return cn.netConn.RemoteAddr()
+	// Lock-free netConn access for better performance
+	if netConn := cn.getNetConn(); netConn != nil {
+		return netConn.RemoteAddr()
 	}
 	return nil
 }
@@ -89,7 +806,16 @@ func (cn *Conn) WithReader(
 	ctx context.Context, timeout time.Duration, fn func(rd *proto.Reader) error,
 ) error {
 	if timeout >= 0 {
-		if err := cn.netConn.SetReadDeadline(cn.deadline(ctx, timeout)); err != nil {
+		// Use relaxed timeout if set, otherwise use provided timeout
+		effectiveTimeout := cn.getEffectiveReadTimeout(timeout)
+
+		// Get the connection directly from atomic storage
+		netConn := cn.getNetConn()
+		if netConn == nil {
+			return errConnectionNotAvailable
+		}
+
+		if err := netConn.SetReadDeadline(cn.deadline(ctx, effectiveTimeout)); err != nil {
 			return err
 		}
 	}
@@ -100,13 +826,25 @@ func (cn *Conn) WithWriter(
 	ctx context.Context, timeout time.Duration, fn func(wr *proto.Writer) error,
 ) error {
 	if timeout >= 0 {
-		if err := cn.netConn.SetWriteDeadline(cn.deadline(ctx, timeout)); err != nil {
-			return err
+		// Use relaxed timeout if set, otherwise use provided timeout
+		effectiveTimeout := cn.getEffectiveWriteTimeout(timeout)
+
+		// Set write deadline on the connection
+		if netConn := cn.getNetConn(); netConn != nil {
+			if err := netConn.SetWriteDeadline(cn.deadline(ctx, effectiveTimeout)); err != nil {
+				return err
+			}
+		} else {
+			// Connection is not available - return preallocated error
+			return errConnNotAvailableForWrite
 		}
 	}
 
+	// Reset the buffered writer if needed, should not happen
 	if cn.bw.Buffered() > 0 {
-		cn.bw.Reset(cn.netConn)
+		if netConn := cn.getNetConn(); netConn != nil {
+			cn.bw.Reset(netConn)
+		}
 	}
 
 	if err := fn(cn.wr); err != nil {
@@ -116,17 +854,47 @@ func (cn *Conn) WithWriter(
 	return cn.bw.Flush()
 }
 
+func (cn *Conn) IsClosed() bool {
+	return cn.closed.Load() || cn.stateMachine.GetState() == StateClosed
+}
+
 func (cn *Conn) Close() error {
+	cn.closed.Store(true)
+
+	// Transition to CLOSED state
+	cn.stateMachine.Transition(StateClosed)
+
 	if cn.onClose != nil {
 		// ignore error
 		_ = cn.onClose()
 	}
-	return cn.netConn.Close()
+
+	// Lock-free netConn access for better performance
+	if netConn := cn.getNetConn(); netConn != nil {
+		return netConn.Close()
+	}
+	return nil
 }
 
+// MaybeHasData tries to peek at the next byte in the socket without consuming it
+// This is used to check if there are push notifications available
+// Important: This will work on Linux, but not on Windows
+func (cn *Conn) MaybeHasData() bool {
+	// Lock-free netConn access for better performance
+	if netConn := cn.getNetConn(); netConn != nil {
+		return maybeHasData(netConn)
+	}
+	return false
+}
+
+// deadline computes the effective deadline time based on context and timeout.
+// It updates the usedAt timestamp to now.
+// Uses cached time to avoid expensive syscall (max 50ms staleness is acceptable for deadline calculation).
 func (cn *Conn) deadline(ctx context.Context, timeout time.Duration) time.Time {
-	tm := time.Now()
-	cn.SetUsedAt(tm)
+	// Use cached time for deadline calculation (called 2x per command: read + write)
+	nowNs := getCachedTimeNs()
+	cn.SetUsedAtNs(nowNs)
+	tm := time.Unix(0, nowNs)
 
 	if timeout > 0 {
 		tm = tm.Add(timeout)

vendor/github.com/redis/go-redis/v9/internal/pool/conn_check.go

@@ -12,6 +12,9 @@ import (
 
 var errUnexpectedRead = errors.New("unexpected read from socket")
 
+// connCheck checks if the connection is still alive and if there is data in the socket
+// it will try to peek at the next byte without consuming it since we may want to work with it
+// later on (e.g. push notifications)
 func connCheck(conn net.Conn) error {
 	// Reset previous timeout.
 	_ = conn.SetDeadline(time.Time{})
@@ -29,7 +32,9 @@ func connCheck(conn net.Conn) error {
 
 	if err := rawConn.Read(func(fd uintptr) bool {
 		var buf [1]byte
-		n, err := syscall.Read(int(fd), buf[:])
+		// Use MSG_PEEK to peek at data without consuming it
+		n, _, err := syscall.Recvfrom(int(fd), buf[:], syscall.MSG_PEEK|syscall.MSG_DONTWAIT)
+
 		switch {
 		case n == 0 && err == nil:
 			sysErr = io.EOF
@@ -47,3 +52,8 @@ func connCheck(conn net.Conn) error {
 
 	return sysErr
 }
+
+// maybeHasData checks if there is data in the socket without consuming it
+func maybeHasData(conn net.Conn) bool {
+	return connCheck(conn) == errUnexpectedRead
+}

vendor/github.com/redis/go-redis/v9/internal/pool/conn_check_dummy.go

@@ -2,8 +2,19 @@
 
 package pool
 
-import "net"
+import (
+	"errors"
+	"net"
+)
 
-func connCheck(conn net.Conn) error {
+// errUnexpectedRead is placeholder error variable for non-unix build constraints
+var errUnexpectedRead = errors.New("unexpected read from socket")
+
+func connCheck(_ net.Conn) error {
 	return nil
 }
+
+// since we can't check for data on the socket, we just assume there is some
+func maybeHasData(_ net.Conn) bool {
+	return true
+}

vendor/github.com/redis/go-redis/v9/internal/pool/conn_state.go

@@ -0,0 +1,343 @@
+package pool
+
+import (
+	"container/list"
+	"context"
+	"errors"
+	"fmt"
+	"sync"
+	"sync/atomic"
+)
+
+// ConnState represents the connection state in the state machine.
+// States are designed to be lightweight and fast to check.
+//
+// State Transitions:
+//
+//	CREATED → INITIALIZING → IDLE ⇄ IN_USE
+//	                           ↓
+//	                       UNUSABLE (handoff/reauth)
+//	                           ↓
+//	                        IDLE/CLOSED
+type ConnState uint32
+
+const (
+	// StateCreated - Connection just created, not yet initialized
+	StateCreated ConnState = iota
+
+	// StateInitializing - Connection initialization in progress
+	StateInitializing
+
+	// StateIdle - Connection initialized and idle in pool, ready to be acquired
+	StateIdle
+
+	// StateInUse - Connection actively processing a command (retrieved from pool)
+	StateInUse
+
+	// StateUnusable - Connection temporarily unusable due to background operation
+	// (handoff, reauth, etc.). Cannot be acquired from pool.
+	StateUnusable
+
+	// StateClosed - Connection closed
+	StateClosed
+)
+
+// Predefined state slices to avoid allocations in hot paths
+var (
+	validFromInUse              = []ConnState{StateInUse}
+	validFromCreatedOrIdle      = []ConnState{StateCreated, StateIdle}
+	validFromCreatedInUseOrIdle = []ConnState{StateCreated, StateInUse, StateIdle}
+	// For AwaitAndTransition calls
+	validFromCreatedIdleOrUnusable = []ConnState{StateCreated, StateIdle, StateUnusable}
+	validFromIdle                  = []ConnState{StateIdle}
+	// For CompareAndSwapUsable
+	validFromInitializingOrUnusable = []ConnState{StateInitializing, StateUnusable}
+)
+
+// Accessor functions for predefined slices to avoid allocations in external packages
+// These return the same slice instance, so they're zero-allocation
+
+// ValidFromIdle returns a predefined slice containing only StateIdle.
+// Use this to avoid allocations when calling AwaitAndTransition or TryTransition.
+func ValidFromIdle() []ConnState {
+	return validFromIdle
+}
+
+// ValidFromCreatedIdleOrUnusable returns a predefined slice for initialization transitions.
+// Use this to avoid allocations when calling AwaitAndTransition or TryTransition.
+func ValidFromCreatedIdleOrUnusable() []ConnState {
+	return validFromCreatedIdleOrUnusable
+}
+
+// String returns a human-readable string representation of the state.
+func (s ConnState) String() string {
+	switch s {
+	case StateCreated:
+		return "CREATED"
+	case StateInitializing:
+		return "INITIALIZING"
+	case StateIdle:
+		return "IDLE"
+	case StateInUse:
+		return "IN_USE"
+	case StateUnusable:
+		return "UNUSABLE"
+	case StateClosed:
+		return "CLOSED"
+	default:
+		return fmt.Sprintf("UNKNOWN(%d)", s)
+	}
+}
+
+var (
+	// ErrInvalidStateTransition is returned when a state transition is not allowed
+	ErrInvalidStateTransition = errors.New("invalid state transition")
+
+	// ErrStateMachineClosed is returned when operating on a closed state machine
+	ErrStateMachineClosed = errors.New("state machine is closed")
+
+	// ErrTimeout is returned when a state transition times out
+	ErrTimeout = errors.New("state transition timeout")
+)
+
+// waiter represents a goroutine waiting for a state transition.
+// Designed for minimal allocations and fast processing.
+type waiter struct {
+	validStates map[ConnState]struct{} // States we're waiting for
+	targetState ConnState              // State to transition to
+	done        chan error             // Signaled when transition completes or times out
+}
+
+// ConnStateMachine manages connection state transitions with FIFO waiting queue.
+// Optimized for:
+// - Lock-free reads (hot path)
+// - Minimal allocations
+// - Fast state transitions
+// - FIFO fairness for waiters
+// Note: Handoff metadata (endpoint, seqID, retries) is managed separately in the Conn struct.
+type ConnStateMachine struct {
+	// Current state - atomic for lock-free reads
+	state atomic.Uint32
+
+	// FIFO queue for waiters - only locked during waiter add/remove/notify
+	mu          sync.Mutex
+	waiters     *list.List   // List of *waiter
+	waiterCount atomic.Int32 // Fast lock-free check for waiters (avoids mutex in hot path)
+}
+
+// NewConnStateMachine creates a new connection state machine.
+// Initial state is StateCreated.
+func NewConnStateMachine() *ConnStateMachine {
+	sm := &ConnStateMachine{
+		waiters: list.New(),
+	}
+	sm.state.Store(uint32(StateCreated))
+	return sm
+}
+
+// GetState returns the current state (lock-free read).
+// This is the hot path - optimized for zero allocations and minimal overhead.
+// Note: Zero allocations applies to state reads; converting the returned state to a string
+// (via String()) may allocate if the state is unknown.
+func (sm *ConnStateMachine) GetState() ConnState {
+	return ConnState(sm.state.Load())
+}
+
+// TryTransitionFast is an optimized version for the hot path (Get/Put operations).
+// It only handles simple state transitions without waiter notification.
+// This is safe because:
+// 1. Get/Put don't need to wait for state changes
+// 2. Background operations (handoff/reauth) use UNUSABLE state, which this won't match
+// 3. If a background operation is in progress (state is UNUSABLE), this fails fast
+//
+// Returns true if transition succeeded, false otherwise.
+// Use this for performance-critical paths where you don't need error details.
+//
+// Performance: Single CAS operation - as fast as the old atomic bool!
+// For multiple from states, use: sm.TryTransitionFast(State1, Target) || sm.TryTransitionFast(State2, Target)
+// The || operator short-circuits, so only 1 CAS is executed in the common case.
+func (sm *ConnStateMachine) TryTransitionFast(fromState, targetState ConnState) bool {
+	return sm.state.CompareAndSwap(uint32(fromState), uint32(targetState))
+}
+
+// TryTransition attempts an immediate state transition without waiting.
+// Returns the current state after the transition attempt and an error if the transition failed.
+// The returned state is the CURRENT state (after the attempt), not the previous state.
+// This is faster than AwaitAndTransition when you don't need to wait.
+// Uses compare-and-swap to atomically transition, preventing concurrent transitions.
+// This method does NOT wait - it fails immediately if the transition cannot be performed.
+//
+// Performance: Zero allocations on success path (hot path).
+func (sm *ConnStateMachine) TryTransition(validFromStates []ConnState, targetState ConnState) (ConnState, error) {
+	// Try each valid from state with CAS
+	// This ensures only ONE goroutine can successfully transition at a time
+	for _, fromState := range validFromStates {
+		// Try to atomically swap from fromState to targetState
+		// If successful, we won the race and can proceed
+		if sm.state.CompareAndSwap(uint32(fromState), uint32(targetState)) {
+			// Success! We transitioned atomically
+			// Hot path optimization: only check for waiters if transition succeeded
+			// This avoids atomic load on every Get/Put when no waiters exist
+			if sm.waiterCount.Load() > 0 {
+				sm.notifyWaiters()
+			}
+			return targetState, nil
+		}
+	}
+
+	// All CAS attempts failed - state is not valid for this transition
+	// Return the current state so caller can decide what to do
+	// Note: This error path allocates, but it's the exceptional case
+	currentState := sm.GetState()
+	return currentState, fmt.Errorf("%w: cannot transition from %s to %s (valid from: %v)",
+		ErrInvalidStateTransition, currentState, targetState, validFromStates)
+}
+
+// Transition unconditionally transitions to the target state.
+// Use with caution - prefer AwaitAndTransition or TryTransition for safety.
+// This is useful for error paths or when you know the transition is valid.
+func (sm *ConnStateMachine) Transition(targetState ConnState) {
+	sm.state.Store(uint32(targetState))
+	sm.notifyWaiters()
+}
+
+// AwaitAndTransition waits for the connection to reach one of the valid states,
+// then atomically transitions to the target state.
+// Returns the current state after the transition attempt and an error if the operation failed.
+// The returned state is the CURRENT state (after the attempt), not the previous state.
+// Returns error if timeout expires or context is cancelled.
+//
+// This method implements FIFO fairness - the first caller to wait gets priority
+// when the state becomes available.
+//
+// Performance notes:
+// - If already in a valid state, this is very fast (no allocation, no waiting)
+// - If waiting is required, allocates one waiter struct and one channel
+func (sm *ConnStateMachine) AwaitAndTransition(
+	ctx context.Context,
+	validFromStates []ConnState,
+	targetState ConnState,
+) (ConnState, error) {
+	// Fast path: try immediate transition with CAS to prevent race conditions
+	// BUT: only if there are no waiters in the queue (to maintain FIFO ordering)
+	if sm.waiterCount.Load() == 0 {
+		for _, fromState := range validFromStates {
+			// Check if we're already in target state
+			if fromState == targetState && sm.GetState() == targetState {
+				return targetState, nil
+			}
+
+			// Try to atomically swap from fromState to targetState
+			if sm.state.CompareAndSwap(uint32(fromState), uint32(targetState)) {
+				// Success! We transitioned atomically
+				sm.notifyWaiters()
+				return targetState, nil
+			}
+		}
+	}
+
+	// Fast path failed - check if we should wait or fail
+	currentState := sm.GetState()
+
+	// Check if closed
+	if currentState == StateClosed {
+		return currentState, ErrStateMachineClosed
+	}
+
+	// Slow path: need to wait for state change
+	// Create waiter with valid states map for fast lookup
+	validStatesMap := make(map[ConnState]struct{}, len(validFromStates))
+	for _, s := range validFromStates {
+		validStatesMap[s] = struct{}{}
+	}
+
+	w := &waiter{
+		validStates: validStatesMap,
+		targetState: targetState,
+		done:        make(chan error, 1), // Buffered to avoid goroutine leak
+	}
+
+	// Add to FIFO queue
+	sm.mu.Lock()
+	elem := sm.waiters.PushBack(w)
+	sm.waiterCount.Add(1)
+	sm.mu.Unlock()
+
+	// Wait for state change or timeout
+	select {
+	case <-ctx.Done():
+		// Timeout or cancellation - remove from queue
+		sm.mu.Lock()
+		sm.waiters.Remove(elem)
+		sm.waiterCount.Add(-1)
+		sm.mu.Unlock()
+		return sm.GetState(), ctx.Err()
+	case err := <-w.done:
+		// Transition completed (or failed)
+		// Note: waiterCount is decremented either in notifyWaiters (when the waiter is notified and removed)
+		// or here (on timeout/cancellation).
+		return sm.GetState(), err
+	}
+}
+
+// notifyWaiters checks if any waiters can proceed and notifies them in FIFO order.
+// This is called after every state transition.
+func (sm *ConnStateMachine) notifyWaiters() {
+	// Fast path: check atomic counter without acquiring lock
+	// This eliminates mutex overhead in the common case (no waiters)
+	if sm.waiterCount.Load() == 0 {
+		return
+	}
+
+	sm.mu.Lock()
+	defer sm.mu.Unlock()
+
+	// Double-check after acquiring lock (waiters might have been processed)
+	if sm.waiters.Len() == 0 {
+		return
+	}
+
+	// Process waiters in FIFO order until no more can be processed
+	// We loop instead of recursing to avoid stack overflow and mutex issues
+	for {
+		processed := false
+
+		// Find the first waiter that can proceed
+		for elem := sm.waiters.Front(); elem != nil; elem = elem.Next() {
+			w := elem.Value.(*waiter)
+
+			// Read current state inside the loop to get the latest value
+			currentState := sm.GetState()
+
+			// Check if current state is valid for this waiter
+			if _, valid := w.validStates[currentState]; valid {
+				// Remove from queue first
+				sm.waiters.Remove(elem)
+				sm.waiterCount.Add(-1)
+
+				// Use CAS to ensure state hasn't changed since we checked
+				// This prevents race condition where another thread changes state
+				// between our check and our transition
+				if sm.state.CompareAndSwap(uint32(currentState), uint32(w.targetState)) {
+					// Successfully transitioned - notify waiter
+					w.done <- nil
+					processed = true
+					break
+				} else {
+					// State changed - re-add waiter to front of queue to maintain FIFO ordering
+					// This waiter was first in line and should retain priority
+					sm.waiters.PushFront(w)
+					sm.waiterCount.Add(1)
+					// Continue to next iteration to re-read state
+					processed = true
+					break
+				}
+			}
+		}
+
+		// If we didn't process any waiter, we're done
+		if !processed {
+			break
+		}
+	}
+}

vendor/github.com/redis/go-redis/v9/internal/pool/hooks.go

@@ -0,0 +1,165 @@
+package pool
+
+import (
+	"context"
+	"sync"
+)
+
+// PoolHook defines the interface for connection lifecycle hooks.
+type PoolHook interface {
+	// OnGet is called when a connection is retrieved from the pool.
+	// It can modify the connection or return an error to prevent its use.
+	// The accept flag can be used to prevent the connection from being used.
+	// On Accept = false the connection is rejected and returned to the pool.
+	// The error can be used to prevent the connection from being used and returned to the pool.
+	// On Errors, the connection is removed from the pool.
+	// It has isNewConn flag to indicate if this is a new connection (rather than idle from the pool)
+	// The flag can be used for gathering metrics on pool hit/miss ratio.
+	OnGet(ctx context.Context, conn *Conn, isNewConn bool) (accept bool, err error)
+
+	// OnPut is called when a connection is returned to the pool.
+	// It returns whether the connection should be pooled and whether it should be removed.
+	OnPut(ctx context.Context, conn *Conn) (shouldPool bool, shouldRemove bool, err error)
+
+	// OnRemove is called when a connection is removed from the pool.
+	// This happens when:
+	// - Connection fails health check
+	// - Connection exceeds max lifetime
+	// - Pool is being closed
+	// - Connection encounters an error
+	// Implementations should clean up any per-connection state.
+	// The reason parameter indicates why the connection was removed.
+	OnRemove(ctx context.Context, conn *Conn, reason error)
+}
+
+// PoolHookManager manages multiple pool hooks.
+type PoolHookManager struct {
+	hooks   []PoolHook
+	hooksMu sync.RWMutex
+}
+
+// NewPoolHookManager creates a new pool hook manager.
+func NewPoolHookManager() *PoolHookManager {
+	return &PoolHookManager{
+		hooks: make([]PoolHook, 0),
+	}
+}
+
+// AddHook adds a pool hook to the manager.
+// Hooks are called in the order they were added.
+func (phm *PoolHookManager) AddHook(hook PoolHook) {
+	phm.hooksMu.Lock()
+	defer phm.hooksMu.Unlock()
+	phm.hooks = append(phm.hooks, hook)
+}
+
+// RemoveHook removes a pool hook from the manager.
+func (phm *PoolHookManager) RemoveHook(hook PoolHook) {
+	phm.hooksMu.Lock()
+	defer phm.hooksMu.Unlock()
+
+	for i, h := range phm.hooks {
+		if h == hook {
+			// Remove hook by swapping with last element and truncating
+			phm.hooks[i] = phm.hooks[len(phm.hooks)-1]
+			phm.hooks = phm.hooks[:len(phm.hooks)-1]
+			break
+		}
+	}
+}
+
+// ProcessOnGet calls all OnGet hooks in order.
+// If any hook returns an error, processing stops and the error is returned.
+func (phm *PoolHookManager) ProcessOnGet(ctx context.Context, conn *Conn, isNewConn bool) (acceptConn bool, err error) {
+	// Copy slice reference while holding lock (fast)
+	phm.hooksMu.RLock()
+	hooks := phm.hooks
+	phm.hooksMu.RUnlock()
+
+	// Call hooks without holding lock (slow operations)
+	for _, hook := range hooks {
+		acceptConn, err := hook.OnGet(ctx, conn, isNewConn)
+		if err != nil {
+			return false, err
+		}
+
+		if !acceptConn {
+			return false, nil
+		}
+	}
+	return true, nil
+}
+
+// ProcessOnPut calls all OnPut hooks in order.
+// The first hook that returns shouldRemove=true or shouldPool=false will stop processing.
+func (phm *PoolHookManager) ProcessOnPut(ctx context.Context, conn *Conn) (shouldPool bool, shouldRemove bool, err error) {
+	// Copy slice reference while holding lock (fast)
+	phm.hooksMu.RLock()
+	hooks := phm.hooks
+	phm.hooksMu.RUnlock()
+
+	shouldPool = true // Default to pooling the connection
+
+	// Call hooks without holding lock (slow operations)
+	for _, hook := range hooks {
+		hookShouldPool, hookShouldRemove, hookErr := hook.OnPut(ctx, conn)
+
+		if hookErr != nil {
+			return false, true, hookErr
+		}
+
+		// If any hook says to remove or not pool, respect that decision
+		if hookShouldRemove {
+			return false, true, nil
+		}
+
+		if !hookShouldPool {
+			shouldPool = false
+		}
+	}
+
+	return shouldPool, false, nil
+}
+
+// ProcessOnRemove calls all OnRemove hooks in order.
+func (phm *PoolHookManager) ProcessOnRemove(ctx context.Context, conn *Conn, reason error) {
+	// Copy slice reference while holding lock (fast)
+	phm.hooksMu.RLock()
+	hooks := phm.hooks
+	phm.hooksMu.RUnlock()
+
+	// Call hooks without holding lock (slow operations)
+	for _, hook := range hooks {
+		hook.OnRemove(ctx, conn, reason)
+	}
+}
+
+// GetHookCount returns the number of registered hooks (for testing).
+func (phm *PoolHookManager) GetHookCount() int {
+	phm.hooksMu.RLock()
+	defer phm.hooksMu.RUnlock()
+	return len(phm.hooks)
+}
+
+// GetHooks returns a copy of all registered hooks.
+func (phm *PoolHookManager) GetHooks() []PoolHook {
+	phm.hooksMu.RLock()
+	defer phm.hooksMu.RUnlock()
+
+	hooks := make([]PoolHook, len(phm.hooks))
+	copy(hooks, phm.hooks)
+	return hooks
+}
+
+// Clone creates a copy of the hook manager with the same hooks.
+// This is used for lock-free atomic updates of the hook manager.
+func (phm *PoolHookManager) Clone() *PoolHookManager {
+	phm.hooksMu.RLock()
+	defer phm.hooksMu.RUnlock()
+
+	newManager := &PoolHookManager{
+		hooks: make([]PoolHook, len(phm.hooks)),
+	}
+	copy(newManager.hooks, phm.hooks)
+	return newManager
+}

vendor/github.com/redis/go-redis/v9/internal/pool/pool_single.go

@@ -1,7 +1,13 @@
 package pool
 
-import "context"
+import (
+	"context"
+	"time"
+)
 
+// SingleConnPool is a pool that always returns the same connection.
+// Note: This pool is not thread-safe.
+// It is intended to be used by clients that need a single connection.
 type SingleConnPool struct {
 	pool      Pooler
 	cn        *Conn
@@ -10,6 +16,12 @@ type SingleConnPool struct {
 
 var _ Pooler = (*SingleConnPool)(nil)
 
+// NewSingleConnPool creates a new single connection pool.
+// The pool will always return the same connection.
+// The pool will not:
+// - Close the connection
+// - Reconnect the connection
+// - Track the connection in any way
 func NewSingleConnPool(pool Pooler, cn *Conn) *SingleConnPool {
 	return &SingleConnPool{
 		pool: pool,
@@ -25,20 +37,47 @@ func (p *SingleConnPool) CloseConn(cn *Conn) error {
 	return p.pool.CloseConn(cn)
 }
 
-func (p *SingleConnPool) Get(ctx context.Context) (*Conn, error) {
+func (p *SingleConnPool) Get(_ context.Context) (*Conn, error) {
 	if p.stickyErr != nil {
 		return nil, p.stickyErr
 	}
+	if p.cn == nil {
+		return nil, ErrClosed
+	}
+
+	// NOTE: SingleConnPool is NOT thread-safe by design and is used in special scenarios:
+	// - During initialization (connection is in INITIALIZING state)
+	// - During re-authentication (connection is in UNUSABLE state)
+	// - For transactions (connection might be in various states)
+	// We use SetUsed() which forces the transition, rather than TryTransition() which
+	// would fail if the connection is not in IDLE/CREATED state.
+	p.cn.SetUsed(true)
+	p.cn.SetUsedAt(time.Now())
 	return p.cn, nil
 }
 
-func (p *SingleConnPool) Put(ctx context.Context, cn *Conn) {}
+func (p *SingleConnPool) Put(_ context.Context, cn *Conn) {
+	if p.cn == nil {
+		return
+	}
+	if p.cn != cn {
+		return
+	}
+	p.cn.SetUsed(false)
+}
 
-func (p *SingleConnPool) Remove(ctx context.Context, cn *Conn, reason error) {
+func (p *SingleConnPool) Remove(_ context.Context, cn *Conn, reason error) {
+	cn.SetUsed(false)
 	p.cn = nil
 	p.stickyErr = reason
 }
 
+// RemoveWithoutTurn has the same behavior as Remove for SingleConnPool
+// since SingleConnPool doesn't use a turn-based queue system.
+func (p *SingleConnPool) RemoveWithoutTurn(ctx context.Context, cn *Conn, reason error) {
+	p.Remove(ctx, cn, reason)
+}
+
 func (p *SingleConnPool) Close() error {
 	p.cn = nil
 	p.stickyErr = ErrClosed
@@ -53,6 +92,13 @@ func (p *SingleConnPool) IdleLen() int {
 	return 0
 }
 
+// Size returns the maximum pool size, which is always 1 for SingleConnPool.
+func (p *SingleConnPool) Size() int { return 1 }
+
 func (p *SingleConnPool) Stats() *Stats {
 	return &Stats{}
 }
+
+func (p *SingleConnPool) AddPoolHook(_ PoolHook) {}
+
+func (p *SingleConnPool) RemovePoolHook(_ PoolHook) {}

vendor/github.com/redis/go-redis/v9/internal/pool/pool_sticky.go

@@ -123,6 +123,12 @@ func (p *StickyConnPool) Remove(ctx context.Context, cn *Conn, reason error) {
 	p.ch <- cn
 }
 
+// RemoveWithoutTurn has the same behavior as Remove for StickyConnPool
+// since StickyConnPool doesn't use a turn-based queue system.
+func (p *StickyConnPool) RemoveWithoutTurn(ctx context.Context, cn *Conn, reason error) {
+	p.Remove(ctx, cn, reason)
+}
+
 func (p *StickyConnPool) Close() error {
 	if shared := atomic.AddInt32(&p.shared, -1); shared > 0 {
 		return nil
@@ -196,6 +202,13 @@ func (p *StickyConnPool) IdleLen() int {
 	return len(p.ch)
 }
 
+// Size returns the maximum pool size, which is always 1 for StickyConnPool.
+func (p *StickyConnPool) Size() int { return 1 }
+
 func (p *StickyConnPool) Stats() *Stats {
 	return &Stats{}
 }
+
+func (p *StickyConnPool) AddPoolHook(hook PoolHook) {}
+
+func (p *StickyConnPool) RemovePoolHook(hook PoolHook) {}

vendor/github.com/redis/go-redis/v9/internal/pool/pubsub.go

@@ -0,0 +1,80 @@
+package pool
+
+import (
+	"context"
+	"net"
+	"sync"
+	"sync/atomic"
+)
+
+type PubSubStats struct {
+	Created   uint32
+	Untracked uint32
+	Active    uint32
+}
+
+// PubSubPool manages a pool of PubSub connections.
+type PubSubPool struct {
+	opt       *Options
+	netDialer func(ctx context.Context, network, addr string) (net.Conn, error)
+
+	// Map to track active PubSub connections
+	activeConns sync.Map // map[uint64]*Conn (connID -> conn)
+	closed      atomic.Bool
+	stats       PubSubStats
+}
+
+// NewPubSubPool implements a pool for PubSub connections.
+// It intentionally does not implement the Pooler interface
+func NewPubSubPool(opt *Options, netDialer func(ctx context.Context, network, addr string) (net.Conn, error)) *PubSubPool {
+	return &PubSubPool{
+		opt:       opt,
+		netDialer: netDialer,
+	}
+}
+
+func (p *PubSubPool) NewConn(ctx context.Context, network string, addr string, channels []string) (*Conn, error) {
+	if p.closed.Load() {
+		return nil, ErrClosed
+	}
+
+	netConn, err := p.netDialer(ctx, network, addr)
+	if err != nil {
+		return nil, err
+	}
+	cn := NewConnWithBufferSize(netConn, p.opt.ReadBufferSize, p.opt.WriteBufferSize)
+	cn.pubsub = true
+	atomic.AddUint32(&p.stats.Created, 1)
+	return cn, nil
+
+}
+
+func (p *PubSubPool) TrackConn(cn *Conn) {
+	atomic.AddUint32(&p.stats.Active, 1)
+	p.activeConns.Store(cn.GetID(), cn)
+}
+
+func (p *PubSubPool) UntrackConn(cn *Conn) {
+	atomic.AddUint32(&p.stats.Active, ^uint32(0))
+	atomic.AddUint32(&p.stats.Untracked, 1)
+	p.activeConns.Delete(cn.GetID())
+}
+
+func (p *PubSubPool) Close() error {
+	p.closed.Store(true)
+	p.activeConns.Range(func(key, value interface{}) bool {
+		cn := value.(*Conn)
+		_ = cn.Close()
+		return true
+	})
+	return nil
+}
+
+func (p *PubSubPool) Stats() *PubSubStats {
+	// load stats atomically
+	return &PubSubStats{
+		Created:   atomic.LoadUint32(&p.stats.Created),
+		Untracked: atomic.LoadUint32(&p.stats.Untracked),
+		Active:    atomic.LoadUint32(&p.stats.Active),
+	}
+}

vendor/github.com/redis/go-redis/v9/internal/pool/want_conn.go

@@ -0,0 +1,93 @@
+package pool
+
+import (
+	"context"
+	"sync"
+)
+
+type wantConn struct {
+	mu        sync.Mutex      // protects ctx, done and sending of the result
+	ctx       context.Context // context for dial, cleared after delivered or canceled
+	cancelCtx context.CancelFunc
+	done      bool                // true after delivered or canceled
+	result    chan wantConnResult // channel to deliver connection or error
+}
+
+// getCtxForDial returns context for dial or nil if connection was delivered or canceled.
+func (w *wantConn) getCtxForDial() context.Context {
+	w.mu.Lock()
+	defer w.mu.Unlock()
+
+	return w.ctx
+}
+
+func (w *wantConn) tryDeliver(cn *Conn, err error) bool {
+	w.mu.Lock()
+	defer w.mu.Unlock()
+	if w.done {
+		return false
+	}
+
+	w.done = true
+	w.ctx = nil
+
+	w.result <- wantConnResult{cn: cn, err: err}
+	close(w.result)
+
+	return true
+}
+
+func (w *wantConn) cancel() *Conn {
+	w.mu.Lock()
+	var cn *Conn
+	if w.done {
+		select {
+		case result := <-w.result:
+			cn = result.cn
+		default:
+		}
+	} else {
+		close(w.result)
+	}
+
+	w.done = true
+	w.ctx = nil
+	w.mu.Unlock()
+
+	return cn
+}
+
+type wantConnResult struct {
+	cn  *Conn
+	err error
+}
+
+type wantConnQueue struct {
+	mu    sync.RWMutex
+	items []*wantConn
+}
+
+func newWantConnQueue() *wantConnQueue {
+	return &wantConnQueue{
+		items: make([]*wantConn, 0),
+	}
+}
+
+func (q *wantConnQueue) enqueue(w *wantConn) {
+	q.mu.Lock()
+	defer q.mu.Unlock()
+	q.items = append(q.items, w)
+}
+
+func (q *wantConnQueue) dequeue() (*wantConn, bool) {
+	q.mu.Lock()
+	defer q.mu.Unlock()
+
+	if len(q.items) == 0 {
+		return nil, false
+	}
+
+	item := q.items[0]
+	q.items = q.items[1:]
+	return item, true
+}

vendor/github.com/redis/go-redis/v9/internal/proto/reader.go

@@ -50,7 +50,8 @@ func (e RedisError) Error() string { return string(e) }
 func (RedisError) RedisError() {}
 
 func ParseErrorReply(line []byte) error {
-	return RedisError(line[1:])
+	msg := string(line[1:])
+	return parseTypedRedisError(msg)
 }
 
 //------------------------------------------------------------------------------
@@ -99,6 +100,92 @@ func (r *Reader) PeekReplyType() (byte, error) {
 	return b[0], nil
 }
 
+func (r *Reader) PeekPushNotificationName() (string, error) {
+	// "prime" the buffer by peeking at the next byte
+	c, err := r.Peek(1)
+	if err != nil {
+		return "", err
+	}
+	if c[0] != RespPush {
+		return "", fmt.Errorf("redis: can't peek push notification name, next reply is not a push notification")
+	}
+
+	// peek 36 bytes at most, should be enough to read the push notification name
+	toPeek := 36
+	buffered := r.Buffered()
+	if buffered == 0 {
+		return "", fmt.Errorf("redis: can't peek push notification name, no data available")
+	}
+	if buffered < toPeek {
+		toPeek = buffered
+	}
+	buf, err := r.rd.Peek(toPeek)
+	if err != nil {
+		return "", err
+	}
+	if buf[0] != RespPush {
+		return "", fmt.Errorf("redis: can't parse push notification: %q", buf)
+	}
+
+	if len(buf) < 3 {
+		return "", fmt.Errorf("redis: can't parse push notification: %q", buf)
+	}
+
+	// remove push notification type
+	buf = buf[1:]
+	// remove first line - e.g. >2\r\n
+	for i := 0; i < len(buf)-1; i++ {
+		if buf[i] == '\r' && buf[i+1] == '\n' {
+			buf = buf[i+2:]
+			break
+		} else {
+			if buf[i] < '0' || buf[i] > '9' {
+				return "", fmt.Errorf("redis: can't parse push notification: %q", buf)
+			}
+		}
+	}
+	if len(buf) < 2 {
+		return "", fmt.Errorf("redis: can't parse push notification: %q", buf)
+	}
+	// next line should be $<length><string>\r\n or +<length><string>\r\n
+	// should have the type of the push notification name and it's length
+	if buf[0] != RespString && buf[0] != RespStatus {
+		return "", fmt.Errorf("redis: can't parse push notification name: %q", buf)
+	}
+	typeOfName := buf[0]
+	// remove the type of the push notification name
+	buf = buf[1:]
+	if typeOfName == RespString {
+		// remove the length of the string
+		if len(buf) < 2 {
+			return "", fmt.Errorf("redis: can't parse push notification name: %q", buf)
+		}
+		for i := 0; i < len(buf)-1; i++ {
+			if buf[i] == '\r' && buf[i+1] == '\n' {
+				buf = buf[i+2:]
+				break
+			} else {
+				if buf[i] < '0' || buf[i] > '9' {
+					return "", fmt.Errorf("redis: can't parse push notification name: %q", buf)
+				}
+			}
+		}
+	}
+
+	if len(buf) < 2 {
+		return "", fmt.Errorf("redis: can't parse push notification name: %q", buf)
+	}
+	// keep only the notification name
+	for i := 0; i < len(buf)-1; i++ {
+		if buf[i] == '\r' && buf[i+1] == '\n' {
+			buf = buf[:i]
+			break
+		}
+	}
+
+	return util.BytesToString(buf), nil
+}
+
 // ReadLine Return a valid reply, it will check the protocol or redis error,
 // and discard the attribute type.
 func (r *Reader) ReadLine() ([]byte, error) {
@@ -115,7 +202,7 @@ func (r *Reader) ReadLine() ([]byte, error) {
 		var blobErr string
 		blobErr, err = r.readStringReply(line)
 		if err == nil {
-			err = RedisError(blobErr)
+			err = parseTypedRedisError(blobErr)
 		}
 		return nil, err
 	case RespAttr:

vendor/github.com/redis/go-redis/v9/internal/proto/redis_errors.go

@@ -0,0 +1,488 @@
+package proto
+
+import (
+	"errors"
+	"strings"
+)
+
+// Typed Redis errors for better error handling with wrapping support.
+// These errors maintain backward compatibility by keeping the same error messages.
+
+// LoadingError is returned when Redis is loading the dataset in memory.
+type LoadingError struct {
+	msg string
+}
+
+func (e *LoadingError) Error() string {
+	return e.msg
+}
+
+func (e *LoadingError) RedisError() {}
+
+// NewLoadingError creates a new LoadingError with the given message.
+func NewLoadingError(msg string) *LoadingError {
+	return &LoadingError{msg: msg}
+}
+
+// ReadOnlyError is returned when trying to write to a read-only replica.
+type ReadOnlyError struct {
+	msg string
+}
+
+func (e *ReadOnlyError) Error() string {
+	return e.msg
+}
+
+func (e *ReadOnlyError) RedisError() {}
+
+// NewReadOnlyError creates a new ReadOnlyError with the given message.
+func NewReadOnlyError(msg string) *ReadOnlyError {
+	return &ReadOnlyError{msg: msg}
+}
+
+// MovedError is returned when a key has been moved to a different node in a cluster.
+type MovedError struct {
+	msg  string
+	addr string
+}
+
+func (e *MovedError) Error() string {
+	return e.msg
+}
+
+func (e *MovedError) RedisError() {}
+
+// Addr returns the address of the node where the key has been moved.
+func (e *MovedError) Addr() string {
+	return e.addr
+}
+
+// NewMovedError creates a new MovedError with the given message and address.
+func NewMovedError(msg string, addr string) *MovedError {
+	return &MovedError{msg: msg, addr: addr}
+}
+
+// AskError is returned when a key is being migrated and the client should ask another node.
+type AskError struct {
+	msg  string
+	addr string
+}
+
+func (e *AskError) Error() string {
+	return e.msg
+}
+
+func (e *AskError) RedisError() {}
+
+// Addr returns the address of the node to ask.
+func (e *AskError) Addr() string {
+	return e.addr
+}
+
+// NewAskError creates a new AskError with the given message and address.
+func NewAskError(msg string, addr string) *AskError {
+	return &AskError{msg: msg, addr: addr}
+}
+
+// ClusterDownError is returned when the cluster is down.
+type ClusterDownError struct {
+	msg string
+}
+
+func (e *ClusterDownError) Error() string {
+	return e.msg
+}
+
+func (e *ClusterDownError) RedisError() {}
+
+// NewClusterDownError creates a new ClusterDownError with the given message.
+func NewClusterDownError(msg string) *ClusterDownError {
+	return &ClusterDownError{msg: msg}
+}
+
+// TryAgainError is returned when a command cannot be processed and should be retried.
+type TryAgainError struct {
+	msg string
+}
+
+func (e *TryAgainError) Error() string {
+	return e.msg
+}
+
+func (e *TryAgainError) RedisError() {}
+
+// NewTryAgainError creates a new TryAgainError with the given message.
+func NewTryAgainError(msg string) *TryAgainError {
+	return &TryAgainError{msg: msg}
+}
+
+// MasterDownError is returned when the master is down.
+type MasterDownError struct {
+	msg string
+}
+
+func (e *MasterDownError) Error() string {
+	return e.msg
+}
+
+func (e *MasterDownError) RedisError() {}
+
+// NewMasterDownError creates a new MasterDownError with the given message.
+func NewMasterDownError(msg string) *MasterDownError {
+	return &MasterDownError{msg: msg}
+}
+
+// MaxClientsError is returned when the maximum number of clients has been reached.
+type MaxClientsError struct {
+	msg string
+}
+
+func (e *MaxClientsError) Error() string {
+	return e.msg
+}
+
+func (e *MaxClientsError) RedisError() {}
+
+// NewMaxClientsError creates a new MaxClientsError with the given message.
+func NewMaxClientsError(msg string) *MaxClientsError {
+	return &MaxClientsError{msg: msg}
+}
+
+// AuthError is returned when authentication fails.
+type AuthError struct {
+	msg string
+}
+
+func (e *AuthError) Error() string {
+	return e.msg
+}
+
+func (e *AuthError) RedisError() {}
+
+// NewAuthError creates a new AuthError with the given message.
+func NewAuthError(msg string) *AuthError {
+	return &AuthError{msg: msg}
+}
+
+// PermissionError is returned when a user lacks required permissions.
+type PermissionError struct {
+	msg string
+}
+
+func (e *PermissionError) Error() string {
+	return e.msg
+}
+
+func (e *PermissionError) RedisError() {}
+
+// NewPermissionError creates a new PermissionError with the given message.
+func NewPermissionError(msg string) *PermissionError {
+	return &PermissionError{msg: msg}
+}
+
+// ExecAbortError is returned when a transaction is aborted.
+type ExecAbortError struct {
+	msg string
+}
+
+func (e *ExecAbortError) Error() string {
+	return e.msg
+}
+
+func (e *ExecAbortError) RedisError() {}
+
+// NewExecAbortError creates a new ExecAbortError with the given message.
+func NewExecAbortError(msg string) *ExecAbortError {
+	return &ExecAbortError{msg: msg}
+}
+
+// OOMError is returned when Redis is out of memory.
+type OOMError struct {
+	msg string
+}
+
+func (e *OOMError) Error() string {
+	return e.msg
+}
+
+func (e *OOMError) RedisError() {}
+
+// NewOOMError creates a new OOMError with the given message.
+func NewOOMError(msg string) *OOMError {
+	return &OOMError{msg: msg}
+}
+
+// parseTypedRedisError parses a Redis error message and returns a typed error if applicable.
+// This function maintains backward compatibility by keeping the same error messages.
+func parseTypedRedisError(msg string) error {
+	// Check for specific error patterns and return typed errors
+	switch {
+	case strings.HasPrefix(msg, "LOADING "):
+		return NewLoadingError(msg)
+	case strings.HasPrefix(msg, "READONLY "):
+		return NewReadOnlyError(msg)
+	case strings.HasPrefix(msg, "MOVED "):
+		// Extract address from "MOVED <slot> <addr>"
+		addr := extractAddr(msg)
+		return NewMovedError(msg, addr)
+	case strings.HasPrefix(msg, "ASK "):
+		// Extract address from "ASK <slot> <addr>"
+		addr := extractAddr(msg)
+		return NewAskError(msg, addr)
+	case strings.HasPrefix(msg, "CLUSTERDOWN "):
+		return NewClusterDownError(msg)
+	case strings.HasPrefix(msg, "TRYAGAIN "):
+		return NewTryAgainError(msg)
+	case strings.HasPrefix(msg, "MASTERDOWN "):
+		return NewMasterDownError(msg)
+	case msg == "ERR max number of clients reached":
+		return NewMaxClientsError(msg)
+	case strings.HasPrefix(msg, "NOAUTH "), strings.HasPrefix(msg, "WRONGPASS "), strings.Contains(msg, "unauthenticated"):
+		return NewAuthError(msg)
+	case strings.HasPrefix(msg, "NOPERM "):
+		return NewPermissionError(msg)
+	case strings.HasPrefix(msg, "EXECABORT "):
+		return NewExecAbortError(msg)
+	case strings.HasPrefix(msg, "OOM "):
+		return NewOOMError(msg)
+	default:
+		// Return generic RedisError for unknown error types
+		return RedisError(msg)
+	}
+}
+
+// extractAddr extracts the address from MOVED/ASK error messages.
+// Format: "MOVED <slot> <addr>" or "ASK <slot> <addr>"
+func extractAddr(msg string) string {
+	ind := strings.LastIndex(msg, " ")
+	if ind == -1 {
+		return ""
+	}
+	return msg[ind+1:]
+}
+
+// IsLoadingError checks if an error is a LoadingError, even if wrapped.
+func IsLoadingError(err error) bool {
+	if err == nil {
+		return false
+	}
+	var loadingErr *LoadingError
+	if errors.As(err, &loadingErr) {
+		return true
+	}
+	// Check if wrapped error is a RedisError with LOADING prefix
+	var redisErr RedisError
+	if errors.As(err, &redisErr) && strings.HasPrefix(redisErr.Error(), "LOADING ") {
+		return true
+	}
+	// Fallback to string checking for backward compatibility
+	return strings.HasPrefix(err.Error(), "LOADING ")
+}
+
+// IsReadOnlyError checks if an error is a ReadOnlyError, even if wrapped.
+func IsReadOnlyError(err error) bool {
+	if err == nil {
+		return false
+	}
+	var readOnlyErr *ReadOnlyError
+	if errors.As(err, &readOnlyErr) {
+		return true
+	}
+	// Check if wrapped error is a RedisError with READONLY prefix
+	var redisErr RedisError
+	if errors.As(err, &redisErr) && strings.HasPrefix(redisErr.Error(), "READONLY ") {
+		return true
+	}
+	// Fallback to string checking for backward compatibility
+	return strings.HasPrefix(err.Error(), "READONLY ")
+}
+
+// IsMovedError checks if an error is a MovedError, even if wrapped.
+// Returns the error and a boolean indicating if it's a MovedError.
+func IsMovedError(err error) (*MovedError, bool) {
+	if err == nil {
+		return nil, false
+	}
+	var movedErr *MovedError
+	if errors.As(err, &movedErr) {
+		return movedErr, true
+	}
+	// Fallback to string checking for backward compatibility
+	s := err.Error()
+	if strings.HasPrefix(s, "MOVED ") {
+		// Parse: MOVED 3999 127.0.0.1:6381
+		parts := strings.Split(s, " ")
+		if len(parts) == 3 {
+			return &MovedError{msg: s, addr: parts[2]}, true
+		}
+	}
+	return nil, false
+}
+
+// IsAskError checks if an error is an AskError, even if wrapped.
+// Returns the error and a boolean indicating if it's an AskError.
+func IsAskError(err error) (*AskError, bool) {
+	if err == nil {
+		return nil, false
+	}
+	var askErr *AskError
+	if errors.As(err, &askErr) {
+		return askErr, true
+	}
+	// Fallback to string checking for backward compatibility
+	s := err.Error()
+	if strings.HasPrefix(s, "ASK ") {
+		// Parse: ASK 3999 127.0.0.1:6381
+		parts := strings.Split(s, " ")
+		if len(parts) == 3 {
+			return &AskError{msg: s, addr: parts[2]}, true
+		}
+	}
+	return nil, false
+}
+
+// IsClusterDownError checks if an error is a ClusterDownError, even if wrapped.
+func IsClusterDownError(err error) bool {
+	if err == nil {
+		return false
+	}
+	var clusterDownErr *ClusterDownError
+	if errors.As(err, &clusterDownErr) {
+		return true
+	}
+	// Check if wrapped error is a RedisError with CLUSTERDOWN prefix
+	var redisErr RedisError
+	if errors.As(err, &redisErr) && strings.HasPrefix(redisErr.Error(), "CLUSTERDOWN ") {
+		return true
+	}
+	// Fallback to string checking for backward compatibility
+	return strings.HasPrefix(err.Error(), "CLUSTERDOWN ")
+}
+
+// IsTryAgainError checks if an error is a TryAgainError, even if wrapped.
+func IsTryAgainError(err error) bool {
+	if err == nil {
+		return false
+	}
+	var tryAgainErr *TryAgainError
+	if errors.As(err, &tryAgainErr) {
+		return true
+	}
+	// Check if wrapped error is a RedisError with TRYAGAIN prefix
+	var redisErr RedisError
+	if errors.As(err, &redisErr) && strings.HasPrefix(redisErr.Error(), "TRYAGAIN ") {
+		return true
+	}
+	// Fallback to string checking for backward compatibility
+	return strings.HasPrefix(err.Error(), "TRYAGAIN ")
+}
+
+// IsMasterDownError checks if an error is a MasterDownError, even if wrapped.
+func IsMasterDownError(err error) bool {
+	if err == nil {
+		return false
+	}
+	var masterDownErr *MasterDownError
+	if errors.As(err, &masterDownErr) {
+		return true
+	}
+	// Check if wrapped error is a RedisError with MASTERDOWN prefix
+	var redisErr RedisError
+	if errors.As(err, &redisErr) && strings.HasPrefix(redisErr.Error(), "MASTERDOWN ") {
+		return true
+	}
+	// Fallback to string checking for backward compatibility
+	return strings.HasPrefix(err.Error(), "MASTERDOWN ")
+}
+
+// IsMaxClientsError checks if an error is a MaxClientsError, even if wrapped.
+func IsMaxClientsError(err error) bool {
+	if err == nil {
+		return false
+	}
+	var maxClientsErr *MaxClientsError
+	if errors.As(err, &maxClientsErr) {
+		return true
+	}
+	// Check if wrapped error is a RedisError with max clients prefix
+	var redisErr RedisError
+	if errors.As(err, &redisErr) && strings.HasPrefix(redisErr.Error(), "ERR max number of clients reached") {
+		return true
+	}
+	// Fallback to string checking for backward compatibility
+	return strings.HasPrefix(err.Error(), "ERR max number of clients reached")
+}
+
+// IsAuthError checks if an error is an AuthError, even if wrapped.
+func IsAuthError(err error) bool {
+	if err == nil {
+		return false
+	}
+	var authErr *AuthError
+	if errors.As(err, &authErr) {
+		return true
+	}
+	// Check if wrapped error is a RedisError with auth error prefix
+	var redisErr RedisError
+	if errors.As(err, &redisErr) {
+		s := redisErr.Error()
+		return strings.HasPrefix(s, "NOAUTH ") || strings.HasPrefix(s, "WRONGPASS ") || strings.Contains(s, "unauthenticated")
+	}
+	// Fallback to string checking for backward compatibility
+	s := err.Error()
+	return strings.HasPrefix(s, "NOAUTH ") || strings.HasPrefix(s, "WRONGPASS ") || strings.Contains(s, "unauthenticated")
+}
+
+// IsPermissionError checks if an error is a PermissionError, even if wrapped.
+func IsPermissionError(err error) bool {
+	if err == nil {
+		return false
+	}
+	var permErr *PermissionError
+	if errors.As(err, &permErr) {
+		return true
+	}
+	// Check if wrapped error is a RedisError with NOPERM prefix
+	var redisErr RedisError
+	if errors.As(err, &redisErr) && strings.HasPrefix(redisErr.Error(), "NOPERM ") {
+		return true
+	}
+	// Fallback to string checking for backward compatibility
+	return strings.HasPrefix(err.Error(), "NOPERM ")
+}
+
+// IsExecAbortError checks if an error is an ExecAbortError, even if wrapped.
+func IsExecAbortError(err error) bool {
+	if err == nil {
+		return false
+	}
+	var execAbortErr *ExecAbortError
+	if errors.As(err, &execAbortErr) {
+		return true
+	}
+	// Check if wrapped error is a RedisError with EXECABORT prefix
+	var redisErr RedisError
+	if errors.As(err, &redisErr) && strings.HasPrefix(redisErr.Error(), "EXECABORT ") {
+		return true
+	}
+	// Fallback to string checking for backward compatibility
+	return strings.HasPrefix(err.Error(), "EXECABORT ")
+}
+
+// IsOOMError checks if an error is an OOMError, even if wrapped.
+func IsOOMError(err error) bool {
+	if err == nil {
+		return false
+	}
+	var oomErr *OOMError
+	if errors.As(err, &oomErr) {
+		return true
+	}
+	// Check if wrapped error is a RedisError with OOM prefix
+	var redisErr RedisError
+	if errors.As(err, &redisErr) && strings.HasPrefix(redisErr.Error(), "OOM ") {
+		return true
+	}
+	// Fallback to string checking for backward compatibility
+	return strings.HasPrefix(err.Error(), "OOM ")
+}

vendor/github.com/redis/go-redis/v9/internal/redis.go

@@ -0,0 +1,3 @@
+package internal
+
+const RedisNull = "<nil>"

vendor/github.com/redis/go-redis/v9/internal/semaphore.go

@@ -0,0 +1,193 @@
+package internal
+
+import (
+	"context"
+	"sync"
+	"time"
+)
+
+var semTimers = sync.Pool{
+	New: func() interface{} {
+		t := time.NewTimer(time.Hour)
+		t.Stop()
+		return t
+	},
+}
+
+// FastSemaphore is a channel-based semaphore optimized for performance.
+// It uses a fast path that avoids timer allocation when tokens are available.
+// The channel is pre-filled with tokens: Acquire = receive, Release = send.
+// Closing the semaphore unblocks all waiting goroutines.
+//
+// Performance: ~30 ns/op with zero allocations on fast path.
+// Fairness: Eventual fairness (no starvation) but not strict FIFO.
+type FastSemaphore struct {
+	tokens chan struct{}
+	max    int32
+}
+
+// NewFastSemaphore creates a new fast semaphore with the given capacity.
+func NewFastSemaphore(capacity int32) *FastSemaphore {
+	ch := make(chan struct{}, capacity)
+	// Pre-fill with tokens
+	for i := int32(0); i < capacity; i++ {
+		ch <- struct{}{}
+	}
+	return &FastSemaphore{
+		tokens: ch,
+		max:    capacity,
+	}
+}
+
+// TryAcquire attempts to acquire a token without blocking.
+// Returns true if successful, false if no tokens available.
+func (s *FastSemaphore) TryAcquire() bool {
+	select {
+	case <-s.tokens:
+		return true
+	default:
+		return false
+	}
+}
+
+// Acquire acquires a token, blocking if necessary until one is available.
+// Returns an error if the context is cancelled or the timeout expires.
+// Uses a fast path to avoid timer allocation when tokens are immediately available.
+func (s *FastSemaphore) Acquire(ctx context.Context, timeout time.Duration, timeoutErr error) error {
+	// Check context first
+	select {
+	case <-ctx.Done():
+		return ctx.Err()
+	default:
+	}
+
+	// Try fast path first (no timer needed)
+	select {
+	case <-s.tokens:
+		return nil
+	default:
+	}
+
+	// Slow path: need to wait with timeout
+	timer := semTimers.Get().(*time.Timer)
+	defer semTimers.Put(timer)
+	timer.Reset(timeout)
+
+	select {
+	case <-s.tokens:
+		if !timer.Stop() {
+			<-timer.C
+		}
+		return nil
+	case <-ctx.Done():
+		if !timer.Stop() {
+			<-timer.C
+		}
+		return ctx.Err()
+	case <-timer.C:
+		return timeoutErr
+	}
+}
+
+// AcquireBlocking acquires a token, blocking indefinitely until one is available.
+func (s *FastSemaphore) AcquireBlocking() {
+	<-s.tokens
+}
+
+// Release releases a token back to the semaphore.
+func (s *FastSemaphore) Release() {
+	s.tokens <- struct{}{}
+}
+
+// Close closes the semaphore, unblocking all waiting goroutines.
+// After close, all Acquire calls will receive a closed channel signal.
+func (s *FastSemaphore) Close() {
+	close(s.tokens)
+}
+
+// Len returns the current number of acquired tokens.
+func (s *FastSemaphore) Len() int32 {
+	return s.max - int32(len(s.tokens))
+}
+
+// FIFOSemaphore is a channel-based semaphore with strict FIFO ordering.
+// Unlike FastSemaphore, this guarantees that threads are served in the exact order they call Acquire().
+// The channel is pre-filled with tokens: Acquire = receive, Release = send.
+// Closing the semaphore unblocks all waiting goroutines.
+//
+// Performance: ~115 ns/op with zero allocations (slower than FastSemaphore due to timer allocation).
+// Fairness: Strict FIFO ordering guaranteed by Go runtime.
+type FIFOSemaphore struct {
+	tokens chan struct{}
+	max    int32
+}
+
+// NewFIFOSemaphore creates a new FIFO semaphore with the given capacity.
+func NewFIFOSemaphore(capacity int32) *FIFOSemaphore {
+	ch := make(chan struct{}, capacity)
+	// Pre-fill with tokens
+	for i := int32(0); i < capacity; i++ {
+		ch <- struct{}{}
+	}
+	return &FIFOSemaphore{
+		tokens: ch,
+		max:    capacity,
+	}
+}
+
+// TryAcquire attempts to acquire a token without blocking.
+// Returns true if successful, false if no tokens available.
+func (s *FIFOSemaphore) TryAcquire() bool {
+	select {
+	case <-s.tokens:
+		return true
+	default:
+		return false
+	}
+}
+
+// Acquire acquires a token, blocking if necessary until one is available.
+// Returns an error if the context is cancelled or the timeout expires.
+// Always uses timer to guarantee FIFO ordering (no fast path).
+func (s *FIFOSemaphore) Acquire(ctx context.Context, timeout time.Duration, timeoutErr error) error {
+	// No fast path - always use timer to guarantee FIFO
+	timer := semTimers.Get().(*time.Timer)
+	defer semTimers.Put(timer)
+	timer.Reset(timeout)
+
+	select {
+	case <-s.tokens:
+		if !timer.Stop() {
+			<-timer.C
+		}
+		return nil
+	case <-ctx.Done():
+		if !timer.Stop() {
+			<-timer.C
+		}
+		return ctx.Err()
+	case <-timer.C:
+		return timeoutErr
+	}
+}
+
+// AcquireBlocking acquires a token, blocking indefinitely until one is available.
+func (s *FIFOSemaphore) AcquireBlocking() {
+	<-s.tokens
+}
+
+// Release releases a token back to the semaphore.
+func (s *FIFOSemaphore) Release() {
+	s.tokens <- struct{}{}
+}
+
+// Close closes the semaphore, unblocking all waiting goroutines.
+// After close, all Acquire calls will receive a closed channel signal.
+func (s *FIFOSemaphore) Close() {
+	close(s.tokens)
+}
+
+// Len returns the current number of acquired tokens.
+func (s *FIFOSemaphore) Len() int32 {
+	return s.max - int32(len(s.tokens))
+}

vendor/github.com/redis/go-redis/v9/internal/util/convert.go

@@ -28,3 +28,14 @@ func MustParseFloat(s string) float64 {
 	}
 	return f
 }
+
+// SafeIntToInt32 safely converts an int to int32, returning an error if overflow would occur.
+func SafeIntToInt32(value int, fieldName string) (int32, error) {
+	if value > math.MaxInt32 {
+		return 0, fmt.Errorf("redis: %s value %d exceeds maximum allowed value %d", fieldName, value, math.MaxInt32)
+	}
+	if value < math.MinInt32 {
+		return 0, fmt.Errorf("redis: %s value %d is below minimum allowed value %d", fieldName, value, math.MinInt32)
+	}
+	return int32(value), nil
+}

vendor/github.com/redis/go-redis/v9/internal/util/math.go

@@ -0,0 +1,17 @@
+package util
+
+// Max returns the maximum of two integers
+func Max(a, b int) int {
+	if a > b {
+		return a
+	}
+	return b
+}
+
+// Min returns the minimum of two integers
+func Min(a, b int) int {
+	if a < b {
+		return a
+	}
+	return b
+}