Documentation
¶
Overview ¶
Package redis provides a shared Redis client connection layer used by toolhive components and stacklok-llm-gateway services.
The package wraps github.com/redis/go-redis/v9 with a single Config type and NewClient factory that supports three connection modes:
- Standalone — a single endpoint (Addr).
- Cluster — Redis Cluster protocol against a single seed Addr.
- Sentinel — high-availability failover via SentinelConfig.
The returned client is a goredis.UniversalClient so callers can write mode-agnostic code.
Connection Modes ¶
Standalone:
cli, err := redis.NewClient(ctx, &redis.Config{
Addr: "redis.example.com:6379",
Password: "...",
DB: 0,
})
Cluster:
cli, err := redis.NewClient(ctx, &redis.Config{
Addr: "cluster.example.com:6379",
ClusterMode: true,
Username: "app",
Password: "...",
})
Sentinel:
cli, err := redis.NewClient(ctx, &redis.Config{
SentinelConfig: &redis.SentinelConfig{
MasterName: "mymaster",
SentinelAddrs: []string{"sentinel-0:26379", "sentinel-1:26379"},
},
Password: "...",
})
TLS ¶
TLS is opt-in per connection target. When TLS is set, master/cluster connections use it. SentinelTLS, when set, applies to sentinel daemon connections independently — useful when the master and sentinels present different certificate chains. Both fields accept either system CAs (CACert nil) or a custom CA bundle.
Defaults and Validation ¶
NewClient applies DefaultDialTimeout, DefaultReadTimeout, and DefaultWriteTimeout when the corresponding Config fields are zero, then validates connection-mode topology (Addr XOR SentinelConfig, ClusterMode requires Addr, Sentinel requires MasterName plus at least one address). It verifies the connection with a Ping before returning. Caller-specific validation (key-prefix requirements, ACL enforcement) remains the caller's responsibility.
Index ¶
Constants ¶
const ( DefaultDialTimeout = 5 * time.Second DefaultReadTimeout = 3 * time.Second DefaultWriteTimeout = 3 * time.Second )
Default timeouts applied by NewClient when the corresponding Config field is zero.
Variables ¶
This section is empty.
Functions ¶
func BuildTLSConfig ¶
BuildTLSConfig converts a TLSConfig into a *tls.Config suitable for dialing a Redis endpoint. Returns (nil, nil) when cfg is nil, signalling "no TLS". Returns an error when CACert is present but cannot be parsed.
The returned *tls.Config sets MinVersion to TLS 1.2 and uses the system root CAs unless CACert is supplied.
func NewClient ¶
NewClient constructs a Redis client according to cfg. The returned client is a goredis.UniversalClient so callers can remain mode-agnostic. NewClient applies timeout defaults, validates connection-mode topology, builds the appropriate underlying client (standalone, cluster, or sentinel), and verifies connectivity with a Ping before returning. On Ping failure the underlying client is closed and the error is returned.
cfg is copied internally before defaults are applied; the caller's Config is not mutated.
Types ¶
type Config ¶
type Config struct {
// Addr is the Redis server address (host:port) for standalone or cluster
// modes. Mutually exclusive with SentinelConfig.
Addr string
// ClusterMode enables the Redis Cluster protocol. Requires Addr. Cluster
// mode ignores DB because Redis Cluster only supports database 0.
ClusterMode bool
// SentinelConfig activates Sentinel failover mode. Mutually exclusive
// with Addr.
SentinelConfig *SentinelConfig
// Username is the optional ACL username (Redis 6.0+). When empty, auth
// falls back to legacy AUTH using only Password.
Username string
// Password is the AUTH/ACL password. May be empty when the server does
// not require authentication.
Password string //nolint:gosec // G101: field name, not a hardcoded credential
// DB is the Redis database index. Applies to standalone and sentinel
// modes; ignored in cluster mode.
DB int
// DialTimeout is the timeout for establishing a connection. When zero,
// DefaultDialTimeout is used.
DialTimeout time.Duration
// ReadTimeout is the timeout for socket reads. When zero,
// DefaultReadTimeout is used.
ReadTimeout time.Duration
// WriteTimeout is the timeout for socket writes. When zero,
// DefaultWriteTimeout is used.
WriteTimeout time.Duration
// TLS configures TLS for master/cluster connections. When nil, those
// connections are plaintext.
TLS *TLSConfig
// SentinelTLS configures TLS for sentinel daemon connections. Only
// applies when SentinelConfig is set. When nil, sentinel connections are
// plaintext (independent of TLS).
SentinelTLS *TLSConfig
}
Config configures a Redis client. Exactly one of Addr or SentinelConfig must be set. ClusterMode upgrades an Addr-based config to the Redis Cluster protocol.
type SentinelConfig ¶
type SentinelConfig struct {
// MasterName is the logical name of the monitored master, as configured
// on the sentinel daemons.
MasterName string
// SentinelAddrs is the list of sentinel daemon addresses (host:port).
SentinelAddrs []string
}
SentinelConfig describes a Redis Sentinel deployment used to discover the current master.
type TLSConfig ¶
type TLSConfig struct {
// InsecureSkipVerify disables certificate verification. Intended for
// self-signed development setups; never use in production.
InsecureSkipVerify bool
// CACert is the PEM-encoded CA bundle used to verify the server. When
// nil, system root CAs are used.
CACert []byte
}
TLSConfig describes how to verify a TLS-enabled Redis (or sentinel) endpoint. The mere presence of a TLSConfig enables TLS; the zero value means "verify against system CAs with hostname verification".
Source Files