mirror of
https://github.com/hanzoai/porto.git
synced 2026-11-03 18:08:27 +00:00
92 lines
4.2 KiB
Go
92 lines
4.2 KiB
Go
// Package cache provides a small key/value cache abstraction (Provider)
|
|
// with a TTL per entry, a pattern-based key listing and a minimal
|
|
// publish/subscribe channel, backed either by process memory or by Redis.
|
|
//
|
|
// Values are JSON encoded on Set and decoded into the pointer passed to
|
|
// Get, so both backends behave the same. A missing or expired entry is
|
|
// reported as ErrNotFound (test with IsNotFoundError).
|
|
//
|
|
// Keys: a key is cleaned as a rooted path and joined with the provider
|
|
// prefix, so "x", "/x" and "x/" name the same entry and ".." cannot leave
|
|
// the prefix ("../x" is "<prefix>/x"); a proxy prefix is cleaned the same
|
|
// way. ListKeys takes a Redis glob pattern relative to the provider ('*'
|
|
// and '?' also match '/', "[...]" sets, '\' escapes), matches the prefix
|
|
// literally and returns the matching unexpired keys relative to the
|
|
// provider, in the form Get accepts (the key "" only for an empty pattern);
|
|
// the memory provider implements the Redis matcher, so both backends list
|
|
// the same keys. ListKeys returns one page per call and a cursor for the
|
|
// next one, until the cursor comes back empty: Redis runs one SCAN with
|
|
// COUNT count, so a page can be empty or repeat a key; the memory provider
|
|
// returns up to count keys in order, each once. Keys, which runs Redis
|
|
// KEYS over the whole keyspace in one call, is deprecated.
|
|
//
|
|
// var p cache.Provider
|
|
// if cfg.Provider == "redis" {
|
|
// p, err = cache.NewRedisProvider(*cfg.Redis, "/myapp")
|
|
// } else {
|
|
// p = cache.NewMemoryProvider("/myapp")
|
|
// }
|
|
// err = p.Set(ctx, "user:1", user, 10*time.Minute) // 0 => default TTL, cache.KeepTTL => no expiry
|
|
// var u User
|
|
// err = p.Get(ctx, "user:1", &u)
|
|
//
|
|
// // scope a shared provider to a sub-namespace
|
|
// users := cache.NewProxyProvider("users", p)
|
|
//
|
|
// // page through the keys "user:*"
|
|
// cursor := ""
|
|
// for {
|
|
// keys, next, err := p.ListKeys(ctx, "user:*", cursor, 100)
|
|
// if err != nil {
|
|
// return err
|
|
// }
|
|
// for _, key := range keys {
|
|
// handle(key) // may see a key twice on Redis
|
|
// }
|
|
// if next == "" {
|
|
// break
|
|
// }
|
|
// cursor = next
|
|
// }
|
|
//
|
|
// Config YAML/JSON fields: provider (redis|memory) and redis {server, ttl,
|
|
// client_tls {cert, key, trusted_ca}, user, password}. The package does not
|
|
// itself switch on Config.Provider; the caller picks the constructor.
|
|
//
|
|
// TTL: a ttl of 0 means DefaultTTL for the memory provider and
|
|
// RedisConfig.TTL (default 1h) for Redis; KeepTTL stores the value without
|
|
// expiry (Redis KEEPTTL). The memory provider never evicts on its own: the
|
|
// caller must run CleanExpired periodically, and NowFunc can be overridden
|
|
// in tests to control its clock.
|
|
// GetOrSet reads through the cache on a miss and stores a successful getter
|
|
// result with the provider's default TTL. The getter returns a pointer to the
|
|
// value to store. On a miss, the destination must point to a concrete type;
|
|
// providers cannot reliably restore values into interface destinations.
|
|
// Concurrent misses may run the getter more than once.
|
|
//
|
|
// Pub/Sub: Subscribe returns a Subscription whose ReceiveMessage returns
|
|
// the next message, ctx.Err() as soon as the context is done, or ErrClosed
|
|
// after Close; Close is idempotent, and closing the provider closes its
|
|
// subscriptions (a Subscribe during or after that Close returns a
|
|
// subscription reporting ErrClosed). A message published after Subscribe
|
|
// returns reaches the new subscriber: the Redis provider waits for the
|
|
// server to confirm the subscription, and a subscription it could not
|
|
// establish reports the error from ReceiveMessage. Delivery is at most
|
|
// once and Publish never waits for a subscriber: each subscriber buffers
|
|
// 100 undelivered messages; a memory subscriber whose buffer is full misses
|
|
// the message, and a Redis subscriber follows the go-redis channel policy
|
|
// (its reader waits up to one minute, then drops the message). The memory
|
|
// provider delivers in-process only; the Redis provider uses Redis
|
|
// channels, which are not prefixed.
|
|
//
|
|
// sub := p.Subscribe(ctx, "invalidate")
|
|
// defer sub.Close()
|
|
// for {
|
|
// msg, err := sub.ReceiveMessage(ctx)
|
|
// if err != nil {
|
|
// return err // ctx done, ErrClosed, or the subscription failed
|
|
// }
|
|
// handle(msg)
|
|
// }
|
|
package cache
|