Documentation
¶
Overview ¶
Package cache provides cache abstractions, configuration, and drivers for go-service.
The primary entrypoint is NewCache, which constructs a *Cache from configuration.
Disabled / nil behavior ¶
Caching is intentionally optional. When cache configuration is disabled/unset, constructors return nil and callers are expected to tolerate a nil cache instance.
In addition to the instance API on *Cache, this package exposes package-level generic helpers (Get and Persist). Those helpers are nil-safe after Register has been called (via DI wiring in Module), and they become no-ops / return zero values when caching is disabled. In the standard service composition this registration is performed for you by the module graph.
Value encoding ¶
Cache persists arbitrary values by encoding (and optionally compressing) them before passing them to the configured driver. The encoder/compressor used is selected by configuration with sensible defaults. The configured encoder and compressor are also included in the driver key namespace so format changes create cache misses instead of decoding values written by an incompatible format.
TTL resolution ¶
TTL handling depends on the selected driver. The built-in in-memory "ttlcache" driver stores a bounded number of values in process memory, expires entries when they are read, and removes expired entries before saving new values.
Flush behavior ¶
Cache.Flush delegates to the selected driver and can have backend-wide effects. The built-in Redis backend uses Redis FLUSHDB, so it clears the entire selected Redis database, including keys that were not created through this cache facade. Use a dedicated Redis database for go-service cache data before calling Flush against Redis.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var Module = di.Module( di.Constructor(driver.NewDriver), di.Constructor(NewPinger), di.Constructor(NewCache), di.Register(Register), )
Module wires the cache subsystem into go.uber.org/fx.
It provides, in order:
- a cache driver.Driver (see driver.NewDriver)
- an optional cache Pinger for backends that support connectivity checks
- a *Cache (see NewCache)
- package-level registration (see Register) so generic helpers (Get/Persist) can be used
Disabled behavior ¶
When caching is disabled via configuration, driver.NewDriver returns a nil driver.Driver and NewCache returns a nil *Cache. Register is still invoked with nil, which makes the package-level helpers behave as if caching is disabled (no-ops / zero values) rather than failing.
Functions ¶
func Get ¶
Get loads a cached value for key into a newly allocated value of type T and returns it.
Semantics:
- If caching is disabled (no cache registered), Get returns a zero-value *T and a nil error.
- If the cache driver reports a miss/expired entry, Get returns a zero-value *T and a nil error.
- If a non-miss error occurs (for example decode failure or driver error), Get returns the zero-value *T along with that error.
The returned pointer is always non-nil.
func Persist ¶
Persist stores value under key with the provided TTL.
If caching is disabled (no cache registered), Persist is a no-op and returns nil. Otherwise it delegates to the registered *Cache.
func Register ¶
func Register(c *Cache)
Register installs the package-level cache instance used by the generic helper functions.
This function is primarily intended to be called by dependency injection wiring (see Module). Once registered, package-level helpers like Get and Persist will delegate to the registered *Cache instance.
If c is nil, the helpers behave as if caching is disabled (they return zero values / act as no-ops).
Types ¶
type Cache ¶
type Cache struct {
// contains filtered or unexported fields
}
Cache provides a typed cache facade on top of a cache driver.
It serializes values using an encoder, optionally compresses the serialized bytes, base64-encodes the final bytes, and stores the resulting string via the configured driver.
Encoding selection is operation-dependent:
- Cache.Persist uses "plain" only for io.WriterTo values
- Cache.Get uses "plain" only for io.ReaderFrom destinations
- proto.Message uses "proto"
- otherwise the configured encoder is used, falling back to "json"
Compression is selected from configuration, falling back to "none" when unknown/unavailable.
func NewCache ¶
func NewCache(params CacheParams) *Cache
NewCache constructs a Cache from configuration.
If caching is disabled (i.e. CacheParams.Config is nil), NewCache returns nil. Callers are expected to tolerate a nil cache instance.
func (*Cache) Flush ¶ added in v2.389.0
Flush removes cached data according to the underlying driver's flush semantics.
For persistent backends such as Redis this can be a destructive operation: the built-in Redis driver uses FLUSHDB and clears the entire selected Redis database, including keys that were not created through this cache facade. It is intentionally not called during lifecycle shutdown.
func (*Cache) Get ¶
Get loads a cached value for key into value.
Cache misses are not treated as errors: if the entry is missing or expired, Get returns nil and leaves value unchanged.
The value parameter should be a pointer to the destination value (for example *MyStruct).
func (*Cache) Persist ¶
Persist stores value under key with the provided TTL.
The value is encoded, compressed, and base64-encoded before being saved via the driver. A TTL <= 0 is passed through to the driver; semantics are driver-specific (for example, it may mean "no expiration" or "immediate expiration").
TTL resolution is driver-specific.
type CacheParams ¶ added in v2.50.0
type CacheParams struct {
di.In
// Config configures cache encoding, compression, and limits.
Config *config.Config
// Encoder provides value encoders by name.
Encoder *encoding.Map
// Pool provides reusable buffers for cache encoding.
Pool *sync.BufferPool
// Compressor provides compression implementations by name.
Compressor *compress.Map
// Driver stores encoded cache values.
Driver driver.Driver
}
CacheParams defines dependencies for constructing a Cache.
It is intended for dependency injection (go.uber.org/fx/go.uber.org/dig). The constructor will typically be wired via Module.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package config provides cache configuration types for go-service.
|
Package config provides cache configuration types for go-service. |
|
Package driver provides cache driver construction and related helpers for go-service.
|
Package driver provides cache driver construction and related helpers for go-service. |
|
errors
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. |
|
internal/ttlcache
Package ttlcache provides the internal ttlcache-backed cache driver.
|
Package ttlcache provides the internal ttlcache-backed cache driver. |
|
Package telemetry exposes selected Redis OpenTelemetry helpers through the go-service cache import tree.
|
Package telemetry exposes selected Redis OpenTelemetry helpers through the go-service cache import tree. |