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 sync 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 "sync" driver uses an in-process github.com/alexfalkowski/go-sync.Map and lazily expires entries when they are read.
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 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 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
- "sync": in-memory backend using github.com/alexfalkowski/go-sync Map
The built-in "sync" backend stores values in process memory and expires entries lazily on access.
If config.Config.Kind is unknown, NewDriver returns ErrNotFound.
Source Files