package lazycache ¶
import "golazy.dev/lazycache"Constants ¶
const LazyDevCacheEntryPath ¶
const LazyDevCacheEntryPath = "/cache/entry"const LazyDevCacheEventsPath ¶
const LazyDevCacheEventsPath = "/cache/events"const LazyDevCacheOffPath ¶
const LazyDevCacheOffPath = "/cache/off"const LazyDevCacheOnPath ¶
const LazyDevCacheOnPath = "/cache/on"const LazyDevCachePath ¶
const LazyDevCachePath = "/cache"Variables ¶
var ErrMiss ¶
ErrMiss reports that a key is not available from the cache.
var ErrMiss = errors.New("lazycache: miss")Functions ¶
func BuildVersionFromContext ¶
BuildVersionFromContext returns the cache-key build version for ctx.
func BuildVersionFromContext(ctx context.Context) stringfunc Get[T any] ¶
Get returns a cached value with a concrete type.
func Get[T any](cache *Cache, parts ...any) (T, error)func Key ¶
Key builds the canonical cache key for a list of parts.
func Key(parts ...any) (string, error)func PrometheusCollector ¶
PrometheusCollector returns a collector for cache statistics.
func PrometheusCollector(cache *Cache) func(io.Writer) errorfunc RegisterLazyDevHandlers ¶
RegisterLazyDevHandlers registers cache inspection and toggle endpoints.
func RegisterLazyDevHandlers(controlPlane *lazycontrolplane.ControlPlane, cache *Cache)func Set[T any] ¶
Set stores a typed value under the key built from parts.
func Set[T any](cache *Cache, value T, parts ...any) errorfunc WithBuildVersion ¶
WithBuildVersion returns a context carrying the application build version used by cache keys.
func WithBuildVersion(ctx context.Context, version string) context.Contextfunc WithCache ¶
WithCache returns a context carrying cache.
func WithCache(ctx context.Context, cache *Cache) context.Contextfunc WritePrometheus ¶
WritePrometheus writes cache statistics using the Prometheus text exposition format.
func WritePrometheus(w io.Writer, cache *Cache) errorTypes ¶
type Backend ¶
Backend is the storage boundary used by Cache.
type Backend interface {
Get(key string) (any, error)
Set(key string, value any) error
Stats() Stats
}type Cache ¶
Cache wraps a backend with GoLazy key building and on/off switching.
type Cache struct {
// contains filtered or unexported fields
}func FromContext ¶
FromContext returns the cache carried by ctx.
func FromContext(ctx context.Context) (*Cache, bool)func New ¶
New creates a cache around a backend.
func New(options Options) (*Cache, error)func (c *Cache) Enabled ¶
Enabled reports whether reads and writes are active.
func (c *Cache) Enabled() boolfunc (c *Cache) Entries ¶
Entries returns inspectable backend entries when the backend exposes them.
func (c *Cache) Entries() []EntryInfofunc (c *Cache) Entry ¶
Entry returns an inspectable backend entry when the backend exposes it.
func (c *Cache) Entry(key string) (EntryDetail, error)func (c *Cache) Get ¶
Get returns a cached value for the key built from parts.
func (c *Cache) Get(parts ...any) (any, error)func (c *Cache) Keys ¶
Keys returns the backend keys when the backend exposes them.
func (c *Cache) Keys() []stringfunc (c *Cache) Off ¶
Off disables reads and turns writes into no-ops.
func (c *Cache) Off()func (c *Cache) On ¶
On enables reads and writes.
func (c *Cache) On()func (c *Cache) Set ¶
Set stores value under the key built from parts.
func (c *Cache) Set(value any, parts ...any) errorfunc (c *Cache) Stats ¶
Stats returns the backend statistics.
func (c *Cache) Stats() Statsfunc (c *Cache) Subscribe ¶
Subscribe returns a channel of cache events and an unsubscribe function. Slow subscribers may miss events; the cache never blocks request handling for development observers.
func (c *Cache) Subscribe() (<-chan Event, func())type EntryDetail ¶
EntryDetail describes one cached value with a development-friendly body.
type EntryDetail struct {
EntryInfo
Content string `json:"content"`
ContentType string `json:"content_type"`
}type EntryInfo ¶
EntryInfo describes one cached value without exposing its body.
type EntryInfo struct {
Key string `json:"key"`
SizeBytes int64 `json:"size_bytes"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
LastAccessedAt time.Time `json:"last_accessed_at"`
Hits uint64 `json:"hits"`
Sets uint64 `json:"sets"`
}type EntryInspector ¶
EntryInspector is an optional backend capability used by development tooling.
type EntryInspector interface {
Entries() []EntryInfo
Entry(key string) (EntryDetail, error)
}type Event ¶
Event describes a cache operation observed by development tooling.
type Event struct {
Kind EventKind `json:"kind"`
Key string `json:"key,omitempty"`
Enabled bool `json:"enabled"`
Stats Stats `json:"stats"`
Entry *EntryInfo `json:"entry,omitempty"`
At time.Time `json:"at"`
}type EventKind ¶
EventKind names a cache event that development tooling can observe.
type EventKind stringtype KeyLister ¶
KeyLister is an optional backend capability used by development tooling.
type KeyLister interface {
Keys() []string
}type Options ¶
Options configures a Cache.
type Options struct {
Backend Backend
}type Stats ¶
Stats is the common cache statistics shape returned by every backend.
type Stats struct {
Entries int `json:"entries"`
MaxEntries int `json:"max_entries"`
SizeBytes int64 `json:"size_bytes"`
Hits uint64 `json:"hits"`
Misses uint64 `json:"misses"`
Sets uint64 `json:"sets"`
Evictions uint64 `json:"evictions"`
}Directories ¶
| Path | Synopsis |
|---|---|
| lazycache/inmemorycache | Package inmemorycache provides the default in-process lazycache backend. |
Package lazycache provides the cache contract used by GoLazy applications.
The package owns the portable parts of application caching: canonical cache keys, the enabled/disabled switch, typed Get and Set helpers, statistics, and optional development inspection. It intentionally does not import a concrete storage backend. A standalone program creates a Backend, passes it to New, and then stores values with Cache.Set or the typed Set helper.
Keys are built from one or more non-empty parts with Key. The resulting string is stable across callers, and time.Time parts are normalized to UTC so helpers in other packages can share the same key format.
Backend is the minimum storage boundary: Get, Set, and Stats. KeyLister and EntryInspector are optional capabilities. Cache uses them only when a backend exposes them, mainly so development tools can list keys or inspect entries without making every backend support that view.
lazyapp is the usual integration point for a GoLazy app. When an application does not configure another backend, lazyapp creates the default lazycache/inmemorycache backend, wraps it with this package, stores the cache on the application context with WithCache, and wires the view cache helpers that read it back with FromContext. The cache package stays backend-agnostic; the default backend choice belongs to lazyapp.
When built with the lazydev tag, RegisterLazyDevHandlers exposes cache state on the development control plane. lazyapp calls it as part of its control plane setup, so normal applications do not need to register those endpoints themselves.