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. To use mTLS, set ClientCert and ClientKey to a PEM-encoded client certificate/key pair; the master and sentinel connections can use different pairs.
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 the CA certificate or client certificate and key cannot be parsed, or when only one of ClientCert and ClientKey is set.
The returned *tls.Config sets MinVersion to TLS 1.2 and uses the system root CAs unless CACert is supplied. When ClientCert and ClientKey are set, it presents them to the server for mutual TLS.
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
// ClientCert and ClientKey are a PEM-encoded client certificate/key pair
// presented to the server for mutual TLS. Both fields must be set together.
ClientCert []byte
ClientKey []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