Documentation
¶
Overview ¶
Package cache is chok's cache battery: byte values under string keys, in a memory layer in the process, a Redis layer shared by the replicas, or both, with a circuit breaker in front of Redis, under one Config.
c := cache.MustNew(cfg.Cache)
app.Use(c)
data, err := c.GetOrLoad(ctx, "post:"+id, 10*time.Minute, func(ctx context.Context) ([]byte, error) {
p, err := posts.Get(ctx, id)
if err != nil {
return nil, err
}
return json.Marshal(p)
})
Reads go to the memory layer first and to Redis on a miss, a Redis hit filling the memory layer; writes and deletes go to both. GetOrLoad makes concurrent misses of one key share a single load. Redis returns the layer's client for what a key-value cache does not do.
Each replica has its own memory layer: a Delete clears this replica's memory and Redis, the other replicas' memory keeps the value until its TTL ends. Keep memory.ttl short for values that change, or use Redis alone.
The breaker turns a Redis outage into cache misses: once open it skips Redis entirely, so a request costs a database read rather than a timeout, and Health stays nil. Without the breaker Health pings Redis, and the App waits for it at start.
Importing the package sends go-redis's own log lines (a dial that failed, a connection dropped), process-wide, to slog.Default at warn instead of to stderr; identity/rbac, the other chok package on go-redis, does the same.
Example ¶
GetOrLoad in front of a slow source: the first call loads and stores, the next is a hit; Delete invalidates. A Config from chok.Load names its layers in the cache section; this one is built in code.
package main
import (
"context"
"fmt"
"time"
"github.com/zynthara/chok/cache"
)
func main() {
var cfg cache.Config
cfg.Memory.Enabled = true
c := cache.MustNew(cfg)
defer func() { _ = c.Close(context.Background()) }()
ctx := context.Background()
loads := 0
load := func(context.Context) ([]byte, error) {
loads++
return []byte(`{"title":"Hello chok"}`), nil
}
for range 2 {
v, err := c.GetOrLoad(ctx, "post:pst_1", time.Minute, load)
fmt.Println(string(v), err)
}
fmt.Println("loads:", loads)
_ = c.Delete(ctx, "post:pst_1")
_, hit, _ := c.Get(ctx, "post:pst_1")
fmt.Println("hit after delete:", hit)
}
Output: {"title":"Hello chok"} <nil> {"title":"Hello chok"} <nil> loads: 1 hit after delete: false
Index ¶
- type Cache
- func (c *Cache) Close(context.Context) error
- func (c *Cache) Delete(ctx context.Context, key string) error
- func (c *Cache) Get(ctx context.Context, key string) ([]byte, bool, error)
- func (c *Cache) GetOrLoad(ctx context.Context, key string, ttl time.Duration, ...) ([]byte, error)
- func (c *Cache) Health(ctx context.Context) error
- func (c *Cache) Name() string
- func (c *Cache) Redis() *redis.Client
- func (c *Cache) Set(ctx context.Context, key string, val []byte, ttl time.Duration) error
- type Config
- type Option
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Cache ¶
type Cache struct {
// contains filtered or unexported fields
}
Cache is the cache battery: the layers Config enables, memory first, behind one key-value interface. Register it with app.Use: it reports Redis's health and closes the Redis client.
func New ¶ added in v0.2.0
New builds the layers cfg enables. A Config with neither the memory nor the redis layer on is an error: a Cache that caches nothing is a mistake, not a mode. The Redis client connects on first use; New does not reach the server, Health does.
func (*Cache) Close ¶
Close stops the memory layer's maintenance and closes the Redis client. It is idempotent.
func (*Cache) Get ¶
Get returns the value under key from the first layer that has it, and copies a value Redis had into the memory layer. A miss is (nil, false, nil). A layer that fails counts as a miss; the error is returned only when every layer failed, or when ctx has ended. The value is the caller's to keep and change.
func (*Cache) GetOrLoad ¶ added in v0.2.0
func (c *Cache) GetOrLoad(ctx context.Context, key string, ttl time.Duration, load func(ctx context.Context) ([]byte, error)) ([]byte, error)
GetOrLoad returns the value under key, or calls load on a miss and stores what it returns for ttl (0: each layer's TTL). Concurrent callers missing the same key share one call of load, made with the context of the first; a caller whose own context ends stops waiting. A value that cannot be stored is still returned, and the failure logged; load's error is returned as it is and nothing is stored.
func (*Cache) Health ¶ added in v0.2.0
Health pings Redis while the redis layer runs without the breaker: then a Redis that is down fails every call. With the breaker, or with the memory layer only, the Cache is healthy: a down Redis is the degraded mode the breaker exists for, and its opening is logged.
type Config ¶ added in v0.2.0
type Config struct {
Memory struct {
// Enabled keeps entries in this process. Each replica has its own:
// a Delete reaches this replica's memory and Redis, not the other
// replicas' memory, so keep TTL short for data that changes.
Enabled bool `yaml:"enabled"`
// Capacity is the most entries kept; the least likely to be used
// again go first.
Capacity int `yaml:"capacity" default:"10000"`
// TTL is how long an entry lives when Set is given no TTL.
TTL time.Duration `yaml:"ttl" default:"5m"`
} `yaml:"memory"`
Redis struct {
// Enabled keeps entries in Redis, shared by every replica.
Enabled bool `yaml:"enabled"`
Addr string `yaml:"addr" default:"127.0.0.1:6379"`
Username string `yaml:"username"` // a Redis 6 ACL user; empty is the default user
Password string `yaml:"password" secret:"true"`
DB int `yaml:"db"`
// TLS encrypts the connection, verifying the server against the
// system roots, or against CACert when it is set (CACert alone
// turns TLS on), as managed Redis services require.
TLS bool `yaml:"tls"`
CACert string `yaml:"ca_cert"`
// The timeouts are short on purpose: a cache that answers late
// is worse than a miss.
DialTimeout time.Duration `yaml:"dial_timeout" default:"1s"`
ReadTimeout time.Duration `yaml:"read_timeout" default:"500ms"`
WriteTimeout time.Duration `yaml:"write_timeout" default:"500ms"`
PoolSize int `yaml:"pool_size" default:"10"`
// TTL is how long an entry lives when Set is given no TTL.
TTL time.Duration `yaml:"ttl" default:"10m"`
} `yaml:"redis"`
Breaker struct {
// Enabled puts a circuit breaker in front of Redis: after
// Threshold failures in a row Redis is left alone for
// ResetTimeout, its reads are misses and its writes are skipped;
// then one probe at a time goes through, and HalfOpenSuccesses
// successes in a row close the breaker again. A Redis that is
// down then costs a miss instead of a timeout per call, and the
// Cache reports healthy: the application serves from its
// database meanwhile.
Enabled bool `yaml:"enabled"`
Threshold int `yaml:"threshold" default:"5"`
ResetTimeout time.Duration `yaml:"reset_timeout" default:"30s"`
HalfOpenSuccesses int `yaml:"half_open_successes" default:"3"`
// ProbeTimeout bounds a probe on its own, so a caller's nearly
// spent deadline cannot fail it; it is at most ResetTimeout.
ProbeTimeout time.Duration `yaml:"probe_timeout" default:"2s"`
} `yaml:"breaker"`
}
Config is the cache section of an application's configuration: a memory layer in the process, a Redis layer shared by the replicas, or both (memory first), and a circuit breaker in front of Redis.
cache:
memory:
enabled: true
capacity: 10000
ttl: 5m
redis:
enabled: true
addr: redis.internal:6380
tls: true
ttl: 10m
breaker:
enabled: true
The password is a secret: set it through the environment ({APP}_CACHE_REDIS_PASSWORD) rather than in the file. New gives the zero fields of a Config built in code the defaults below; the switches have none.