cache

package
v0.2.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 3, 2026 License: MIT Imports: 15 Imported by: 0

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

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 MustNew added in v0.2.0

func MustNew(cfg Config, opts ...Option) *Cache

MustNew is New that panics on error.

func New added in v0.2.0

func New(cfg Config, opts ...Option) (*Cache, error)

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

func (c *Cache) Close(context.Context) error

Close stops the memory layer's maintenance and closes the Redis client. It is idempotent.

func (*Cache) Delete

func (c *Cache) Delete(ctx context.Context, key string) error

Delete removes key from every layer; a missing key is not an error.

func (*Cache) Get

func (c *Cache) Get(ctx context.Context, key string) ([]byte, bool, error)

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

func (c *Cache) Health(ctx context.Context) error

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.

func (*Cache) Name added in v0.2.0

func (c *Cache) Name() string

Name is "cache", its name in the health report.

func (*Cache) Redis added in v0.2.0

func (c *Cache) Redis() *redis.Client

Redis returns the client of the redis layer, nil when the layer is off, for what the cache does not do (a rate limiter, a lock, rbac's policy watcher). It belongs to the Cache: Close closes it.

func (*Cache) Set

func (c *Cache) Set(ctx context.Context, key string, val []byte, ttl time.Duration) error

Set stores val under key in every layer, for ttl; 0 means each layer's configured TTL. The cache keeps its own copy of val.

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.

func (Config) GoString added in v0.2.0

func (c Config) GoString() string

GoString keeps the Redis password out of %#v.

func (Config) String added in v0.2.0

func (c Config) String() string

String keeps the Redis password out of logs.

func (*Config) Validate added in v0.2.0

func (c *Config) Validate() error

Validate checks the layers that are switched on. It runs when chok.Load reads the configuration and again in New; that no layer is on at all is New's error, not the configuration's.

type Option added in v0.2.0

type Option func(*options)

Option configures New.

func Logger added in v0.2.0

func Logger(l *slog.Logger) Option

Logger is where the cache reports, such as the breaker opening; the default is slog.Default().

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL