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 `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 `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 go-redis client, and instruments that client via `cache/telemetry` before exposing it through a context-aware driver. Redis configuration is strict by design: `Config.Options["url"]` must exist and be a 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 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.
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 cfg.Kind. Some backends expect specific keys to be present in cfg.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 fs.ReadSource, parsed using redis/go-redis ParseURL, and then the client is instrumented for tracing and metrics via `cache/telemetry` when those telemetry providers are enabled.
The Redis client is closed from the supplied lifecycle's 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
- "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 cfg.Kind is unknown, NewDriver returns ErrNotFound.
Source Files