Documentation
¶
Overview ¶
Package cache is the official cache pack: string keys with TTL on Valkey (or Redis), Remember for the read-through pattern and Incr for counters every node shares (a rate limit, a quota). CACHE_URL=memory gives a bounded in-process cache for tests and single-node development; production uses the server so every node sees the same entries.
Index ¶
- Variables
- func Pack() lidza.Pack
- func Remember[T any](ctx context.Context, c *Cache, key string, ttl time.Duration, ...) (T, error)
- type Cache
- func (c *Cache) Delete(ctx context.Context, keys ...string) error
- func (c *Cache) Get(ctx context.Context, key string, out any) error
- func (c *Cache) Incr(ctx context.Context, key string, by int64, ttl time.Duration) (int64, error)
- func (c *Cache) Invalidate(ctx context.Context, prefix string) error
- func (c *Cache) Name() string
- func (c *Cache) Ready(ctx context.Context) error
- func (c *Cache) Set(ctx context.Context, key string, value any, ttl time.Duration) error
- func (c *Cache) Start(ctx context.Context, s *lidza.Services) error
- func (c *Cache) Stop(context.Context) error
- type Config
- type Counter
- type Memory
- func (m *Memory) Close() error
- func (m *Memory) Delete(_ context.Context, keys ...string) error
- func (m *Memory) DeletePrefix(_ context.Context, prefix string) error
- func (m *Memory) Get(_ context.Context, key string) ([]byte, error)
- func (m *Memory) Incr(_ context.Context, key string, by int64, ttl time.Duration) (int64, error)
- func (m *Memory) Len() int
- func (m *Memory) Ping(context.Context) error
- func (m *Memory) Set(_ context.Context, key string, value []byte, ttl time.Duration) error
- type Store
- type Valkey
- func (v *Valkey) Close() error
- func (v *Valkey) Delete(ctx context.Context, keys ...string) error
- func (v *Valkey) DeletePrefix(ctx context.Context, prefix string) error
- func (v *Valkey) Get(ctx context.Context, key string) ([]byte, error)
- func (v *Valkey) Incr(ctx context.Context, key string, by int64, ttl time.Duration) (int64, error)
- func (v *Valkey) Ping(ctx context.Context) error
- func (v *Valkey) Set(ctx context.Context, key string, value []byte, ttl time.Duration) error
Constants ¶
This section is empty.
Variables ¶
var ErrMiss = errors.New("cache miss")
ErrMiss is returned by Get when the key is absent or expired.
var ErrNotCounter = errors.New("cache: the store does not implement Counter")
ErrNotCounter is returned by Incr when the store cannot count.
Functions ¶
Types ¶
type Cache ¶
type Cache struct {
// contains filtered or unexported fields
}
Cache is the running pack.
func (*Cache) Incr ¶
Incr adds by (negative to subtract) to the counter under key and returns the new value, atomically across every node sharing the server. The increment that creates the key sets its ttl, so a counter per window resets on its own:
n, err := cache.From(ctx).Incr(ctx, "rate:"+clientIP+":"+minute, 1, time.Minute)
if n > 100 { ... refuse ... }
Later increments keep that expiry (a fixed window, not a sliding one). Get reads the counter into an int64. A key holding a non-integer value is an error.
func (*Cache) Invalidate ¶
Invalidate removes every key under prefix.
type Config ¶
type Config struct {
// URL is redis://host:port, valkey://..., or "memory".
URL string `env:"CACHE_URL" required:"true"`
// Prefix namespaces keys, so several apps can share a server.
Prefix string `env:"CACHE_PREFIX" default:"lidza:"`
// MemoryMax bounds the in-process backend's entries.
MemoryMax int `env:"CACHE_MEMORY_MAX" default:"10000"`
}
Config comes from the environment.
type Counter ¶
type Counter interface {
// Incr adds by to the integer under key atomically and returns the
// new value. A missing key starts at 0 and gets ttl (0: none); an
// existing key keeps its expiry.
Incr(ctx context.Context, key string, by int64, ttl time.Duration) (int64, error)
}
Counter is the backend contract of Incr, apart from Store so a backend written for an older version still satisfies Store. Memory and Valkey implement it.
type Memory ¶
type Memory struct {
// contains filtered or unexported fields
}
Memory is the bounded in-process backend.
type Store ¶
type Store interface {
Get(ctx context.Context, key string) ([]byte, error)
Set(ctx context.Context, key string, value []byte, ttl time.Duration) error
Delete(ctx context.Context, keys ...string) error
// DeletePrefix removes every key under prefix (an invalidation
// sweep); the server backend scans, so keep prefixes specific.
DeletePrefix(ctx context.Context, prefix string) error
Ping(ctx context.Context) error
Close() error
}
Store is the backend contract.
Source Files