Documentation
¶
Overview ¶
Package valkey is the gas.CacheProvider backend for a Valkey or other Redis-compatible server, built on the valkey-go client. Its Service also implements gas.Service, gas.HealthReporter, and gas.ReadyReporter, and Client exposes the underlying valkey.Client for commands the gas.CacheProvider interface does not cover.
Wiring ¶
New returns a DI constructor that takes a gas.ConfigProvider and a gas.Logger and returns *Service; register it under gas.CacheProvider. The constructor does not return an error, so it is not yet on the shape in CONVENTIONS.md (KI-004 in KNOWN_ISSUES.md). WithConfig supplies the configuration directly and skips binding it from the ConfigProvider.
Configuration ¶
Without WithConfig, the service binds a Config from the ConfigProvider over DefaultConfig when it starts. The cache settings are Addr (default "localhost:6379"), Password (empty for no authentication), DB (default 0), DialTimeout (default five seconds, also the bound on the connection ping), WriteTimeout (default three seconds), ConnRetries (default 0), and ConnRetryInterval (default two seconds). Validate requires a non-empty Addr and a DB of 0 or more.
Lifecycle ¶
Starting the service creates a client and pings the server. If that fails and ConnRetries is positive, it retries up to ConnRetries times, sleeping ConnRetryInterval before the first retry and doubling the wait each time (an interval of 0 or less uses two seconds); starting fails once the retries run out. The ping runs under the start context, and when that context ends during a wait the retries stop and starting fails with an error wrapping both the context's error and the last connection error. Stopping the service closes the client and makes every operation return cache.ErrClosed, as does every operation before the service has started. An operation that is running when the service stops, or when a restart replaces the client, also returns cache.ErrClosed. The client is held in an atomic pointer, so operations can run while the service restarts.
Behavior ¶
Get returns cache.ErrKeyNotFound for a missing key. Set with a positive TTL sets a millisecond expiry on the server; a TTL of 0 or less stores the key without one. Errors from the server are wrapped with the service name and the key. CheckHealth fails only before the service has started or once it has stopped, since the client reconnects on its own; CheckReady pings the server with the caller's context. Client returns nil before the service first connects, and the closed client after it stops.
SPDX-License-Identifier: MIT
Index ¶
- func New(opts ...Option) func(gas.ConfigProvider, gas.Logger) (*Service, error)
- type Config
- type Option
- type Service
- func (s *Service) CheckHealth(_ context.Context) error
- func (s *Service) CheckReady(ctx context.Context) error
- func (s *Service) Client() valkey.Client
- func (s *Service) Close(context.Context) error
- func (s *Service) Delete(ctx context.Context, key string) error
- func (s *Service) Exists(ctx context.Context, key string) (bool, error)
- func (s *Service) Get(ctx context.Context, key string) ([]byte, error)
- func (s *Service) Init(ctx context.Context) error
- func (s *Service) Name() string
- func (s *Service) Set(ctx context.Context, key string, value []byte, ttl time.Duration) error
- type Settings
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Config ¶
type Config struct {
gas.WithGasEnv
Cache Settings
}
Config holds Valkey cache settings.
func DefaultConfig ¶
func DefaultConfig() *Config
DefaultConfig returns a Config with sensible defaults.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service is a Valkey-backed cache implementing gas.Service and gas.CacheProvider.
func (*Service) CheckHealth ¶
CheckHealth reports liveness. The valkey-go client reconnects internally, so a transient network failure is not a liveness failure; only a service that was never started or has been closed is, and it reports cache.ErrClosed.
func (*Service) CheckReady ¶
CheckReady reports readiness by pinging the Valkey server with the caller's context. It returns cache.ErrClosed if the service was never started or is closed before the ping completes.
func (*Service) Client ¶
Client returns the underlying valkey.Client for advanced operations. It returns nil before Init first connects; after Close it returns the closed client.
func (*Service) Delete ¶
Delete removes a key from the cache. It returns cache.ErrClosed if the service was never started or is closed before the command completes.
func (*Service) Exists ¶
Exists checks whether a key exists in the cache. It returns cache.ErrClosed if the service was never started or is closed before the command completes.
func (*Service) Get ¶
Get returns the value for the given key, or cache.ErrKeyNotFound if the key does not exist. It returns cache.ErrClosed if the service was never started or is closed before the command completes.
func (*Service) Init ¶
Init binds the configuration, creates the Valkey client, and verifies connectivity. A config bound from the ConfigProvider is validated by Bind against its validate tags; one passed with WithConfig is used as given. The ping and the retry backoff use ctx, so a canceled or expired ctx stops the retries.
type Settings ¶
type Settings struct {
// Addr is the Valkey server address in host:port format. Required.
Addr string `validate:"required"`
// Password is the authentication password. Empty means no auth.
//nolint:gosec // intentional
Password string
// DB is the database number to use (0-15). Must not be negative.
DB int `validate:"min=0"`
// DialTimeout is the timeout for establishing new connections.
DialTimeout time.Duration
// WriteTimeout is applied to net.Conn.SetDeadline and controls
// the maximum duration for write operations and periodic PINGs.
WriteTimeout time.Duration
// ConnRetries is the number of times to retry connecting on failure.
// 0 means no retries (fail immediately).
ConnRetries int
// ConnRetryInterval is the base interval between connection retry
// attempts. The interval doubles after each failed attempt.
ConnRetryInterval time.Duration
}
Settings represents the configuration for the Valkey cache.
Source Files