redis

type Auth ¶

type Auth struct {
	StaticPassword *StaticPasswordAuth
	GCPIAM         *GCPIAMAuth
}

Auth selects one Redis authentication strategy.

type Client ¶

type Client struct {
	// contains filtered or unexported fields
}

Client wraps a redis.UniversalClient with reconnection and IAM token refresh logic.

func New(ctx context.Context, cfg Config) (*Client, error)

func (c *Client) Close() error

func (c *Client) Connect(ctx context.Context) error

func (c *Client) GetClient(ctx context.Context) (redis.UniversalClient, error)

func (c *Client) IsConnected() (bool, error)

func (c *Client) LastRefreshError() error

func (c *Client) Status() (Status, error)

type ClusterTopology ¶

type ClusterTopology struct {
	Addresses []string
}

ClusterTopology configures Redis cluster access.

type Config ¶

type Config struct {
	Topology       Topology
	TLS            *TLSConfig
	Auth           Auth
	Options        ConnectionOptions
	Logger         log.Logger
	MetricsFactory *metrics.MetricsFactory
}

Config defines Redis client topology, auth, TLS, and connection settings.

type ConnectionOptions ¶

type ConnectionOptions struct {
	DB              int
	Protocol        int
	PoolSize        int
	MinIdleConns    int
	ReadTimeout     time.Duration
	WriteTimeout    time.Duration
	DialTimeout     time.Duration
	PoolTimeout     time.Duration
	MaxRetries      int
	MinRetryBackoff time.Duration
	MaxRetryBackoff time.Duration
}

ConnectionOptions configures protocol, timeouts, pools, and retries.

type GCPIAMAuth ¶

type GCPIAMAuth struct {
	CredentialsBase64       string
	ServiceAccount          string
	TokenLifetime           time.Duration
	RefreshEvery            time.Duration
	RefreshCheckInterval    time.Duration
	RefreshOperationTimeout time.Duration
}

GCPIAMAuth authenticates with short-lived GCP IAM access tokens.

func (a GCPIAMAuth) GoString() string

func (a GCPIAMAuth) String() string

type LockHandle ¶ added in v2.3.0

type LockHandle interface {
	// Unlock releases the distributed lock.
	Unlock(ctx context.Context) error
}

LockHandle represents an acquired distributed lock. It is obtained from TryLock and must be released via its Unlock method.

Example usage:

handle, acquired, err := locker.TryLock(ctx, "lock:resource:123")
if err != nil {
    return err
}
if !acquired {
    return nil // lock busy, skip
}
defer handle.Unlock(ctx)
// ... critical section ...

type LockManager ¶ added in v2.3.0

type LockManager interface {
	// WithLock executes a function while holding a distributed lock with default options.
	// The lock is automatically released when the function returns.
	WithLock(ctx context.Context, lockKey string, fn func(context.Context) error) error

	// WithLockOptions executes a function while holding a distributed lock with custom options.
	// Use this for fine-grained control over lock behavior.
	WithLockOptions(ctx context.Context, lockKey string, opts LockOptions, fn func(context.Context) error) error

	// TryLock attempts to acquire a lock without retrying.
	// Returns the handle and true if lock was acquired, nil and false otherwise.
	// Use LockHandle.Unlock to release the lock when done.
	TryLock(ctx context.Context, lockKey string) (LockHandle, bool, error)
}

LockManager provides an interface for distributed locking operations. This interface allows for easy mocking in tests without requiring a real Redis instance.

Example test implementation:

type MockLockManager struct{}

func (m *MockLockManager) WithLock(ctx context.Context, lockKey string, fn func(context.Context) error) error {
    // In tests, just execute the function without actual locking
    return fn(ctx)
}

func (m *MockLockManager) WithLockOptions(ctx context.Context, lockKey string, opts LockOptions, fn func(context.Context) error) error {
    return fn(ctx)
}

func (m *MockLockManager) TryLock(ctx context.Context, lockKey string) (LockHandle, bool, error) {
    return &mockHandle{}, true, nil
}

type LockOptions ¶

type LockOptions struct {
	// Expiry is how long the lock is held before auto-expiring (prevents deadlocks)
	// Default: 10 seconds
	Expiry time.Duration

	// Tries is the number of attempts to acquire the lock before giving up
	// Default: 3, Maximum: 1000
	Tries int

	// RetryDelay is the delay between retry attempts
	// Default: 500ms
	RetryDelay time.Duration

	// DriftFactor accounts for clock drift in distributed systems (RedLock algorithm)
	// Default: 0.01 (1%)
	DriftFactor float64
}

LockOptions configures lock behavior for advanced use cases. Use DefaultLockOptions() for sensible defaults.

func DefaultLockOptions() LockOptions

func RateLimiterLockOptions() LockOptions

type RedisLockManager ¶ added in v2.3.0

type RedisLockManager struct {
	// contains filtered or unexported fields
}

RedisLockManager provides distributed locking capabilities using Redis and the RedLock algorithm. This implementation ensures mutual exclusion across multiple service instances, preventing race conditions in critical sections such as: - Password update operations - Cache invalidation - Rate limiting checks - Any other operation requiring distributed coordination

The RedLock algorithm provides strong guarantees even in the presence of: - Network partitions - Process crashes - Clock drift

Example usage:

lock, err := redis.NewRedisLockManager(redisClient)
if err != nil {
    return err
}

err = lock.WithLock(ctx, "lock:user:123", func(ctx context.Context) error {
    // Critical section - only one instance will execute this at a time
    return updateUser(123)
})

func NewRedisLockManager(conn *Client) (*RedisLockManager, error)

lock, err := redis.NewRedisLockManager(redisClient)
if err != nil {
    return fmt.Errorf("failed to initialize lock: %w", err)
}

func (dl *RedisLockManager) TryLock(ctx context.Context, lockKey string) (LockHandle, bool, error)

handle, acquired, err := lock.TryLock(ctx, "lock:cache:refresh")
if err != nil {
    // Unexpected error (network, context cancellation, etc.) - should be propagated
    return fmt.Errorf("failed to attempt lock acquisition: %w", err)
}
if !acquired {
    logger.Info("Lock busy, skipping cache refresh")
    return nil
}
defer handle.Unlock(ctx)
// Perform cache refresh...

func (dl *RedisLockManager) Unlock(ctx context.Context, handle LockHandle) error

func (dl *RedisLockManager) WithLock(ctx context.Context, lockKey string, fn func(context.Context) error) error

err := lock.WithLock(ctx, "lock:user:password:123", func(ctx context.Context) error {
    return updatePassword(123, newPassword)
})

func (dl *RedisLockManager) WithLockOptions(ctx context.Context, lockKey string, opts LockOptions, fn func(context.Context) error) error

opts := redis.LockOptions{
    Expiry:     30 * time.Second, // Long-running operation
    Tries:      5,                 // More aggressive retries
    RetryDelay: 1 * time.Second,
}
err := lock.WithLockOptions(ctx, "lock:report:generation", opts, func(ctx context.Context) error {
    return generateReport()
})

type SentinelTopology ¶

type SentinelTopology struct {
	Addresses  []string
	MasterName string
}

SentinelTopology configures Redis Sentinel access.

type StandaloneTopology ¶

type StandaloneTopology struct {
	Address string
}

StandaloneTopology configures single-node Redis access.

type StaticPasswordAuth ¶

type StaticPasswordAuth struct {
	Password string
}

StaticPasswordAuth authenticates using a static password.

func (a StaticPasswordAuth) GoString() string

func (StaticPasswordAuth) String() string

type Status ¶

type Status struct {
	Connected          bool
	LastRefreshError   error
	LastRefreshAt      time.Time
	RefreshLoopRunning bool
}

Status reports client connectivity and IAM refresh loop health.

type TLSConfig ¶

type TLSConfig struct {
	CACertBase64          string
	MinVersion            uint16
	AllowLegacyMinVersion bool
}

TLSConfig configures TLS validation for Redis connections.

type Topology ¶

type Topology struct {
	Standalone *StandaloneTopology
	Sentinel   *SentinelTopology
	Cluster    *ClusterTopology
}

Topology selects exactly one Redis deployment mode.