Documentation
¶
Overview ¶
Package cache defines a small, driver-agnostic Cache interface and the supporting hook / error contract.
Implementations live in subpackages:
- cache/memory — in-process LRU-like map with TTL. Zero deps, ideal for tests, single-binary deployments, and the local tier of a two-level cache.
- cache/redis — Redis client. Zero external deps (rolls its own minimal RESP2 over net.Conn with a bounded connection pool); production-grade enough for typical web-tier caching workloads.
The interface is deliberately narrow — Get / Set / Delete / Exists / TTL / Ping / Close — so any new backend (Memcached, BadgerDB, DynamoDB, etc.) is a few hundred lines.
Every implementation accepts a drops.Hook for the same per-operation observability used elsewhere in the project; pair with drops.LoggerHook for instant request logging.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrNotFound is returned by Get / TTL when the key is absent. ErrNotFound = errors.New("cache: key not found") // ErrClosed is returned by every method on a closed Cache. ErrClosed = errors.New("cache: closed") // ErrInvalidKey is returned when a key fails per-backend // validation (empty, too long, illegal bytes, etc.). ErrInvalidKey = errors.New("cache: invalid key") )
Sentinel errors. errors.Is works against the wrapped instances each backend may produce.
Functions ¶
This section is empty.
Types ¶
type Cache ¶
type Cache interface {
// Get returns the value for key. ErrNotFound is returned (and is
// the ONLY way to distinguish "missing" from "empty value") when
// no entry exists.
Get(ctx context.Context, key string) ([]byte, error)
// Set stores value under key. ttl=0 means "no expiry" (the entry
// lives until evicted or deleted).
Set(ctx context.Context, key string, value []byte, ttl time.Duration) error
// Delete removes the listed keys and returns the number actually
// removed (entries that did not exist count as 0).
Delete(ctx context.Context, keys ...string) (int, error)
// Exists reports whether the key has a live entry.
Exists(ctx context.Context, key string) (bool, error)
// TTL returns the remaining lifetime. The reserved values are:
// -1 — key exists but has no expiry
// 0 — key does not exist (also returns ErrNotFound)
TTL(ctx context.Context, key string) (time.Duration, error)
// Ping verifies the backend is reachable. Suitable as a readiness
// probe shape.
Ping(ctx context.Context) error
// Close releases the underlying resources (connections, file
// handles, goroutines). Idempotent.
Close() error
}
Cache is the minimal contract every backend satisfies. Payloads are []byte so the interface stays codec-agnostic; callers serialise with whatever they like (encoding/json, msgpack, protobuf, raw bytes).
Implementations are safe for concurrent use by multiple goroutines.
type Item ¶
Item is a key/value pair with an optional per-item TTL; useful for helpers that take heterogeneous batches.
type MultiCache ¶
type MultiCache interface {
Cache
// GetMulti returns the entries that were found, keyed by their
// cache key. Missing keys are simply absent from the result map.
GetMulti(ctx context.Context, keys ...string) (map[string][]byte, error)
// SetMulti stores the supplied items in a single round-trip. All
// entries get the same TTL.
SetMulti(ctx context.Context, items map[string][]byte, ttl time.Duration) error
}
MultiCache extends Cache with bulk operations. Backends that can't implement them more efficiently than a loop over Get/Set should NOT satisfy this interface — callers that depend on the batch shape will then fall back to the loop and the round-trip cost is at least visible at the call site.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package memory provides an in-process cache.Cache implementation.
|
Package memory provides an in-process cache.Cache implementation. |
|
Package redis provides a cache.Cache implementation backed by a Redis server.
|
Package redis provides a cache.Cache implementation backed by a Redis server. |