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.
TTL resolution ¶
TTL handling depends on the selected driver. The built-in in-memory "sync" driver stores values in process memory and expires entries lazily when they are read.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var Module = di.Module( di.Constructor(driver.NewDriver), 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)
- 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 all cached keys from the underlying driver.
For persistent backends such as Redis this can be a destructive operation for the selected database. 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 *config.Config
Encoder *encoding.Map
Pool *sync.BufferPool
Compressor *compress.Map
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. |
|
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. |