Documentation
¶
Overview ¶
Package driver provides cache driver construction and related helpers for go-service.
It contains the NewDriver constructor used by DI wiring to build a cache backend implementation from github.com/alexfalkowski/go-service/v2/cache/config.Config.
Disabled / nil behavior ¶
When caching is disabled (i.e. the cache config is nil), NewDriver returns a nil Driver and a nil error.
Supported kinds ¶
The driver kind is selected by github.com/alexfalkowski/go-service/v2/cache/config.Config.Kind. Supported values are implementation-dependent, but this package currently includes built-in constructors for common backends (for example Redis and an in-memory ttlcache driver).
The built-in Redis backend resolves its URL from a go-service "source string", constructs a github.com/redis/go-redis/v9 client, and instruments that client via github.com/alexfalkowski/go-service/v2/cache/telemetry before exposing it through a context-aware driver. Redis configuration is strict by design: the github.com/alexfalkowski/go-service/v2/cache/config.Config.Options map must contain a "url" string. The standard config fixtures provide that shape; callers that build config manually should validate it before calling NewDriver.
The built-in "ttlcache" driver uses a bounded in-process cache and expires entries when they are read or before new values are saved.
If the configured kind is unknown, NewDriver returns ErrNotFound.
Errors ¶
This package provides ErrExpired, ErrMissing, and helper functions to classify backend-specific miss conditions in a backend-agnostic way.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrExpired = errors.New("cache: expired")
ErrExpired is returned when a cache entry exists but is expired.
Drivers may wrap this error; use IsExpiredError to classify this condition.
var ErrInvalidURL = errors.New("cache: invalid driver url")
ErrInvalidURL is returned when a cache backend URL cannot be parsed.
var ErrMissing = errors.New("cache: missing")
ErrMissing is returned when a cache entry does not exist.
Drivers may wrap this error; use IsMissingError to classify this condition.
var ErrNotFound = errors.New("cache: driver not found")
ErrNotFound is returned when the configured cache driver kind is unknown.
Functions ¶
func IsExpiredError ¶ added in v2.243.0
IsExpiredError reports whether err represents an expired cache entry.
This helper exists so higher-level code can treat expired entries as cache misses regardless of the underlying backend implementation.
func IsMissingError ¶ added in v2.303.6
IsMissingError reports whether err represents a missing cache entry.
This helper normalizes the miss semantics of the backends currently supported by this package, including Redis nil replies (redis.Nil).
Types ¶
type Driver ¶
type Driver interface {
// Delete removes the cached key.
Delete(ctx context.Context, key string) error
// Fetch retrieves the cached value for key.
Fetch(ctx context.Context, key string) (string, error)
// Flush removes all cached keys managed by the driver.
Flush(ctx context.Context) error
// Save stores value under key for the provided lifetime.
Save(ctx context.Context, key, value string, lifetime time.Duration) error
}
Driver is the minimal cache backend interface used by the cache facade.
Implementations must honor the provided context for blocking operations.
func NewDriver ¶ added in v2.73.0
func NewDriver(params DriverParams) (Driver, error)
NewDriver constructs a cache Driver for the configured backend.
Disabled behavior ¶
If cfg is nil (caching disabled), NewDriver returns (nil, nil). Callers are expected to tolerate a nil Driver.
Configuration expectations ¶
NewDriver dispatches on config.Config.Kind. Some backends expect specific keys to be present in config.Config.Options. For example, the "redis" backend expects:
- options["url"] to be a string "source string" (e.g. "env:REDIS_URL" or "file:/path/to/url" or a literal URL)
The URL is read via os.FS.ReadSource, parsed using redis.ParseURL, and then the client is instrumented for tracing and metrics via github.com/alexfalkowski/go-service/v2/cache/telemetry when those telemetry providers are enabled.
The Redis client is closed from the supplied lifecycle's di.Hook.OnStop hook.
Instrumentation errors are treated as fatal configuration/runtime errors and are converted into panics via github.com/alexfalkowski/go-service/v2/runtime.Must, matching the existing repository convention for mandatory telemetry wiring in internal constructors.
Backends ¶
Supported kinds include:
- "redis": Redis backend using github.com/redis/go-redis/v9
- "ttlcache": in-memory backend using github.com/jellydator/ttlcache/v3
The built-in "ttlcache" backend stores values in process memory and expires entries lazily on access.
If config.Config.Kind is unknown, NewDriver returns ErrNotFound.
Source Files