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 github.com/alexfalkowski/go-service/v2/cache/driver/errors.ErrNotFound.
Flush behavior ¶
Driver.Flush is intentionally backend-specific. The built-in ttlcache backend clears its in-process entries. The built-in Redis backend calls Redis FLUSHDB, which clears the entire selected Redis database, including keys not created by go-service cache key namespacing.
Errors ¶
Package github.com/alexfalkowski/go-service/v2/cache/driver/errors provides shared sentinel errors and helper functions to classify backend-specific miss conditions in a backend-agnostic way.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Driver ¶
type Driver interface {
// Delete removes the cached key.
Delete(ctx context.Context, key string) error
// Get retrieves the cached value for key.
Get(ctx context.Context, key string) (string, error)
// GetOrSave atomically returns the value stored for key, or stores value
// when the key is absent.
//
// The returned bool reports whether an existing value was found: when true,
// the returned string is the value already stored and value was not written;
// when false, value was stored and the returned string is empty.
GetOrSave(ctx context.Context, key, value string, lifetime time.Duration) (string, bool, error)
// Flush removes cached data according to backend-specific semantics.
//
// Implementations may clear more than go-service cache namespace keys. For
// example, the built-in Redis driver clears the entire selected Redis
// database.
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 github.com/redis/go-redis/v9.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 github.com/alexfalkowski/go-service/v2/cache/driver/errors.ErrNotFound.
type DriverParams ¶ added in v2.389.0
type DriverParams struct {
di.In
// Lifecycle registers backend shutdown hooks.
Lifecycle di.Lifecycle
// FS resolves backend source-string options.
FS *os.FS
// Config selects and configures the cache backend.
Config *config.Config
// Logger routes backend logs through the go-service logger when configured.
Logger *logger.Logger
}
DriverParams defines dependencies for constructing a Driver.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package errors defines shared sentinel errors and classifiers for cache drivers.
|
Package errors defines shared sentinel errors and classifiers for cache drivers. |
|
internal
|
|
|
redis
Package redis provides the internal Redis cache driver.
|
Package redis provides the internal Redis cache driver. |
|
ttlcache
Package ttlcache provides the internal ttlcache-backed cache driver.
|
Package ttlcache provides the internal ttlcache-backed cache driver. |