From dd2d23861beae4e134f2072e5bf462820ea052ee Mon Sep 17 00:00:00 2001 From: molon <3739161+molon@users.noreply.github.com> Date: Wed, 7 Oct 2026 02:31:48 +0800 Subject: [PATCH 01/40] feat: add Client.GetMany with batch upstream and batch backends Callers often need dozens of keys at once. With only Client.Get, every miss hits the upstream separately, and callers who batch around the Client lose singleflight, DoubleCheck, Not-Found caching and serve-stale. - BatchUpstream[T] (optional): GetMany(ctx, keys) for upstreams that answer a batch in one call - BatchCache[T] (optional): GetMany/SetMany/DelMany for backends; implemented by RistrettoCache, SyncMap, RedisCache (pipeline) and GORMCache (IN query, multi-row upsert) - Client.GetMany: same semantics as Get per key; claimed keys are fetched with one upstream call; partial failures are reported as *BatchError - Client implements BatchUpstream, so batches travel down layered clients - Get and GetMany share one singleflight; the x/sync singleflight.Group is replaced by a small flight group whose claim is synchronous, which is what lets GetMany claim keys one by one without deadlocking overlapping batches --- README.md | 77 +++++++ README_ZH.md | 76 +++++++ batch.go | 519 ++++++++++++++++++++++++++++++++++++++++++ batch_test.go | 606 ++++++++++++++++++++++++++++++++++++++++++++++++++ client.go | 106 +++++---- error.go | 30 +++ gorm.go | 97 +++++++- redis.go | 178 +++++++++++---- ristretto.go | 31 ++- syncmap.go | 26 ++- types.go | 22 ++ 11 files changed, 1670 insertions(+), 98 deletions(-) create mode 100644 batch.go create mode 100644 batch_test.go diff --git a/README.md b/README.md index 11d56f2..68c264b 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,7 @@ - **🚫 Cache Penetration Defense** - Not-Found caching mechanism prevents malicious queries from overwhelming the database - **🔄 Serve-Stale** - Serves stale data while asynchronously refreshing, ensuring high availability and low latency - **🎪 Layered Caching** - Flexible multi-level caching (L1 Memory + L2 Redis), Client can also be used as upstream +- **📦 Batch Reads** - `GetMany` reads many keys at once and fetches all misses with one upstream call, keeping singleflight, DoubleCheck, Not-Found caching and serve-stale - **🚀 High Performance** - Sub-microsecond latency, 79x~1729x throughput amplification, zero error rate - **🎯 Type-Safe** - Go generics provide compile-time type safety, avoiding runtime type errors - **⏱️ Flexible TTL** - Independent fresh and stale TTL configuration for precise data lifecycle control @@ -225,6 +226,17 @@ type Cache[T any] interface { **Important**: When a key does not exist, the `Get` method must return `cachex.ErrKeyNotFound` error, so the Client can correctly distinguish between cache misses and other error conditions. +Optionally implement `BatchCache[T]` as well, so `Client.GetMany` reads and writes your backend in one call per batch instead of key by key (see [Batch Reads](#batch-reads)): + +```go +type BatchCache[T any] interface { + Cache[T] + GetMany(ctx context.Context, keys []string) (map[string]T, error) // missing keys are absent + SetMany(ctx context.Context, values map[string]T) error + DelMany(ctx context.Context, keys []string) error +} +``` + ## Advanced Features ### Layered Caching @@ -327,6 +339,71 @@ client := cachex.NewClient( ) ``` +### Batch Reads + +`Client.GetMany` reads many keys at once with the same semantics as calling `Get` for each key, but in batches: + +```go +products, err := client.GetMany(ctx, []string{"p1", "p2", "p3"}) +// products holds only the keys that exist; missing keys are absent +``` + +To let the upstream answer a batch in one call, implement `BatchUpstream[T]` on it (it should still implement `Upstream[T]` for `Get`): + +```go +type BatchUpstream[T any] interface { + // Keys absent from the map do not exist (like ErrKeyNotFound for Get). + // A non-nil error fails the whole batch, unless it is a *cachex.BatchError, + // which fails only the keys it lists. + GetMany(ctx context.Context, keys []string) (map[string]T, error) +} + +type productSource struct{ db *gorm.DB } + +func (s productSource) GetMany(ctx context.Context, ids []string) (map[string]*Product, error) { + var rows []*Product + if err := s.db.WithContext(ctx).Where("id IN ?", ids).Find(&rows).Error; err != nil { + return nil, err + } + out := make(map[string]*Product, len(rows)) + for _, p := range rows { + out[p.ID] = p + } + return out, nil +} +``` + +How `GetMany` works: + +1. **Backend**: one batch read (`BatchCache[T]`, otherwise key by key). Each value is classified by staleness: fresh values are returned, stale values are returned and refreshed in the background together (with `WithServeStale`), rotten values and misses go on. +2. **Not-Found cache**: misses are checked against it, exactly like `Get`. +3. **Singleflight**: every key that needs the upstream is claimed in the **same** singleflight `Get` uses. Keys already being fetched by a `Get` or another `GetMany` are waited for, not fetched again; so a `Get` and a `GetMany` (or two overlapping `GetMany`s) fetch a shared key only once. `WithFetchConcurrency` applies per key as usual. +4. **DoubleCheck**: the claimed keys are re-checked against the backend and Not-Found cache, by the same rules as `Get`. +5. **Upstream**: the remaining keys are fetched with **one** `GetMany` call if the upstream implements `BatchUpstream[T]`, otherwise with concurrent `Get` calls. +6. **Write back**: found values go to the backend (`SetMany` when supported), missing keys to the Not-Found cache. Like `Get`, this only touches this layer, never the upstream. + +`Client` implements `BatchUpstream[T]` itself, so in a layered setup a batch travels down as one call per layer: `l1Client.GetMany` → L1 batch read → `l2Client.GetMany` → L2 batch read → one database query. + +**Errors**: the returned map always holds every key that succeeded. If some keys failed (backend, upstream or context errors), the error is a `*cachex.BatchError` whose `Errors` map lists them by key; `errors.Is`/`errors.As` see through it to the per-key errors. + +```go +products, err := client.GetMany(ctx, ids) +var batchErr *cachex.BatchError +if errors.As(err, &batchErr) { + for id, err := range batchErr.Errors { /* id failed */ } +} +// products is usable either way +``` + +Built-in backends implement `BatchCache[T]`: `RistrettoCache`, `SyncMap`, `RedisCache` (one pipeline of `GET`/`SET`/`DEL`, which also works on Redis Cluster) and `GORMCache` (`WHERE key IN (...)` and one multi-row upsert). + +Fetching 100 missing keys through an upstream that costs 1ms per call (`BenchmarkGetManyVsGet`): + +| | upstream calls | time | +|---|---|---| +| `GetMany` | 1 | ~1.2ms | +| loop of `Get` | 100 | ~115ms | + ### Custom Staleness Logic Define custom staleness checks: diff --git a/README_ZH.md b/README_ZH.md index dcf7230..4417750 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -14,6 +14,7 @@ - **🚫 防御缓存穿透** - Not-Found 缓存机制,缓存不存在的 key,避免恶意查询打垮数据库 - **🔄 Serve-Stale** - 提供陈旧数据的同时异步刷新,确保高可用性和低延迟 - **🎪 分层缓存** - 灵活组合多级缓存(L1 内存 + L2 Redis),Client 可作为下层 Upstream +- **📦 批量读取** - `GetMany` 一次读多个 key,未命中的合成一次上游调用,singleflight、DoubleCheck、Not-Found 缓存、serve-stale 照样生效 - **🚀 高性能** - 亚微秒级延迟,79x~1729x 吞吐量放大,零错误率 - **🎯 类型安全** - Go 泛型提供编译时类型安全,避免运行时类型错误 - **⏱️ 灵活 TTL** - 独立的新鲜和陈旧 TTL 配置,精确控制数据生命周期 @@ -225,6 +226,17 @@ type Cache[T any] interface { **重要**:当 key 不存在时,`Get` 方法必须返回 `cachex.ErrKeyNotFound` 错误,以便 Client 能够正确区分缓存未命中和其他错误情况。 +还可以选择实现 `BatchCache[T]`,这样 `Client.GetMany` 读写这个后端时一批只调一次,而不是逐个 key 调(见[批量读取](#批量读取)): + +```go +type BatchCache[T any] interface { + Cache[T] + GetMany(ctx context.Context, keys []string) (map[string]T, error) // 不存在的 key 不出现在结果里 + SetMany(ctx context.Context, values map[string]T) error + DelMany(ctx context.Context, keys []string) error +} +``` + ## 高级特性 ### 分层缓存 @@ -327,6 +339,70 @@ client := cachex.NewClient( ) ``` +### 批量读取 + +`Client.GetMany` 一次读多个 key,语义和逐个 `Get` 一致,只是批量做: + +```go +products, err := client.GetMany(ctx, []string{"p1", "p2", "p3"}) +// products 只包含存在的 key;不存在的 key 不出现 +``` + +要让上游一次答一批,给它实现 `BatchUpstream[T]`(它仍然要实现 `Upstream[T]` 供 `Get` 用): + +```go +type BatchUpstream[T any] interface { + // map 里没有的 key 视为不存在(相当于 Get 的 ErrKeyNotFound)。 + // 返回非 nil error 表示整批失败;如果是 *cachex.BatchError,只有它列出的 key 失败。 + GetMany(ctx context.Context, keys []string) (map[string]T, error) +} + +type productSource struct{ db *gorm.DB } + +func (s productSource) GetMany(ctx context.Context, ids []string) (map[string]*Product, error) { + var rows []*Product + if err := s.db.WithContext(ctx).Where("id IN ?", ids).Find(&rows).Error; err != nil { + return nil, err + } + out := make(map[string]*Product, len(rows)) + for _, p := range rows { + out[p.ID] = p + } + return out, nil +} +``` + +`GetMany` 的流程: + +1. **后端**:一次批量读(实现了 `BatchCache[T]` 就批量,否则逐个)。每个值按新鲜度分类:新鲜的直接返回;陈旧的先返回,再在后台合成一批刷新(开了 `WithServeStale` 时);腐烂的和未命中的往下走。 +2. **Not-Found 缓存**:未命中的先查它,和 `Get` 一样。 +3. **Singleflight**:每个要回源的 key 都在和 `Get` **同一个** singleflight 里认领。已经有 `Get` 或别的 `GetMany` 在取的 key,等那次的结果,不再取一遍;所以 `Get` 和 `GetMany`(或两个有交集的 `GetMany`)同时要同一个 key,只回源一次。`WithFetchConcurrency` 照旧按 key 生效。 +4. **DoubleCheck**:认领到的 key 按和 `Get` 相同的规则再查一次后端和 Not-Found 缓存。 +5. **上游**:剩下的 key,上游实现了 `BatchUpstream[T]` 就调**一次** `GetMany`,否则并发逐个 `Get`。 +6. **回填**:取到的值写回后端(支持就用 `SetMany`),不存在的 key 写进 Not-Found 缓存。和 `Get` 一样只写本层,不写上游。 + +`Client` 自己也实现了 `BatchUpstream[T]`,所以多层缓存时一批 key 每层只走一次调用:`l1Client.GetMany` → L1 批量读 → `l2Client.GetMany` → L2 批量读 → 一次数据库查询。 + +**错误**:返回的 map 总是包含所有成功的 key。有 key 失败(后端、上游或 context 出错)时,error 是 `*cachex.BatchError`,它的 `Errors` 按 key 列出各自的错误;`errors.Is`/`errors.As` 能穿透到每个 key 的错误。 + +```go +products, err := client.GetMany(ctx, ids) +var batchErr *cachex.BatchError +if errors.As(err, &batchErr) { + for id, err := range batchErr.Errors { /* id 失败了 */ } +} +// 不管有没有 err,products 都能用 +``` + +内置后端都实现了 `BatchCache[T]`:`RistrettoCache`、`SyncMap`、`RedisCache`(一个 `GET`/`SET`/`DEL` 的 pipeline,Redis Cluster 下也能用)和 `GORMCache`(`WHERE key IN (...)` 和一条多行 upsert)。 + +上游每次调用耗时 1ms,取 100 个全未命中的 key(`BenchmarkGetManyVsGet`): + +| | 上游调用次数 | 耗时 | +|---|---|---| +| `GetMany` | 1 | ~1.2ms | +| 循环 `Get` | 100 | ~115ms | + ### 自定义陈旧逻辑 定义自定义的陈旧检查: diff --git a/batch.go b/batch.go new file mode 100644 index 0000000..393d40c --- /dev/null +++ b/batch.go @@ -0,0 +1,519 @@ +package cachex + +import ( + "context" + "runtime/debug" + "sync" + "time" + + "github.com/pkg/errors" +) + +var _ BatchUpstream[any] = &Client[any]{} + +// flight is one in-flight upstream fetch of a singleflight key. +type flight[T any] struct { + done chan struct{} + value T + err error +} + +// flightGroup is the singleflight shared by Get and GetMany. Unlike +// x/sync/singleflight, claim tells the caller synchronously whether it now +// owns the fetch, which lets GetMany claim many keys and fetch the ones it +// owns as one batch without waiting on (and deadlocking with) other batches. +type flightGroup[T any] struct { + mu sync.Mutex + flights map[string]*flight[T] +} + +// claim returns the flight for sfKey and whether the caller owns it. The owner +// must call finish exactly once; everyone else waits on flight.done. +func (g *flightGroup[T]) claim(sfKey string) (*flight[T], bool) { + g.mu.Lock() + defer g.mu.Unlock() + if f, ok := g.flights[sfKey]; ok { + return f, false + } + if g.flights == nil { + g.flights = map[string]*flight[T]{} + } + f := &flight[T]{done: make(chan struct{})} + g.flights[sfKey] = f + return f, true +} + +// finish releases the claim before publishing the result, so a request that +// sees the result and comes back starts a new flight (where double-check +// finds the value this flight wrote) instead of joining a finished one. +func (g *flightGroup[T]) finish(sfKey string, f *flight[T], value T, err error) { + g.mu.Lock() + delete(g.flights, sfKey) + g.mu.Unlock() + f.value, f.err = value, err + close(f.done) +} + +type result[T any] struct { + value T + err error +} + +// GetMany retrieves many keys at once, with the same semantics as calling Get +// for each key: +// +// - The backend is read in one call (if it implements BatchCache) and every +// value is classified by staleness: fresh values are returned, stale values +// are returned and refreshed in the background (WithServeStale), rotten +// values and misses are fetched. +// - Misses are checked against the not-found cache first, exactly like Get. +// - Keys that need the upstream are claimed one by one in the same +// singleflight Get uses: a key already being fetched by a Get or another +// GetMany is waited for, not fetched again. The keys this call claims are +// double-checked (WithDoubleCheck) and then fetched together: one +// upstream.GetMany if the upstream implements BatchUpstream, otherwise +// concurrent upstream.Get calls. +// - Fetched values are written to the backend (SetMany if supported) and +// not-found keys to the not-found cache, without touching the upstream, +// exactly like Get. +// +// The returned map holds only the keys that exist; keys that do not exist are +// simply absent. If some keys failed (backend, upstream, or ctx errors), the +// map still holds every key that succeeded and the error is a *BatchError +// listing the failed keys. +// +// Client implements BatchUpstream through GetMany, so in a layered setup +// (memory -> Redis/DB -> source) a batch reaches the bottom upstream as one call. +func (c *Client[T]) GetMany(ctx context.Context, keys []string) (map[string]T, error) { + keys = uniqueKeys(keys) + out := make(map[string]T, len(keys)) + errs := map[string]error{} + + var fetchKeys, refreshKeys []string + for i, r := range c.lookupMany(ctx, keys, false) { + key := keys[i] + switch { + case r.fetch: + fetchKeys = append(fetchKeys, key) + case r.err == nil: + out[key] = r.value + case !IsErrKeyNotFound(r.err): + errs[key] = r.err + } + if r.refresh { + refreshKeys = append(refreshKeys, key) + } + } + + if len(refreshKeys) > 0 { + c.asyncRefreshMany(context.WithoutCancel(ctx), refreshKeys) + } + + if len(fetchKeys) > 0 { + sfKeys := make([]string, len(fetchKeys)) + for i, key := range fetchKeys { + sfKeys[i] = c.makeSFKey(key) + } + for i, r := range c.fetchMany(ctx, fetchKeys, sfKeys) { + key := fetchKeys[i] + switch { + case r.err == nil: + out[key] = r.value + case !IsErrKeyNotFound(r.err): + errs[key] = r.err + } + } + } + + if len(errs) > 0 { + return out, &BatchError{Errors: errs} + } + return out, nil +} + +// lookup is what the caches say about one key. +type lookup[T any] struct { + value T + err error // final error (ErrKeyNotFound for a cached not-found), unless fetch + fetch bool // must be fetched from upstream + refresh bool // served stale, refresh in the background +} + +// lookupMany is the batch form of the cache part of get: it reads the backend +// and the not-found cache and decides, per key, what get would do. +func (c *Client[T]) lookupMany(ctx context.Context, keys []string, doubleCheck bool) []lookup[T] { + res := make([]lookup[T], len(keys)) + + checkDataStale := c.checkDataStale + if checkDataStale == nil { + checkDataStale = alwaysFresh[T] + } + + values, err := getMany(ctx, c.backend, keys) + var missing []int + for i, key := range keys { + if kerr := errForKey(err, key); kerr != nil { + res[i].err = errors.Wrapf(kerr, "get from backend failed for key: %s", key) + continue + } + value, ok := values[key] + if !ok { + missing = append(missing, i) + continue + } + switch checkDataStale(value) { + case StateFresh: + res[i].value = value + case StateStale: + if c.serveStale && !doubleCheck { + res[i].value = value + res[i].refresh = true + } else { + res[i].fetch = true + } + default: + res[i].fetch = true + } + } + + if len(missing) == 0 { + return res + } + if c.notFoundCache == nil { + for _, i := range missing { + res[i].fetch = true + } + return res + } + + checkNotFoundStale := c.checkNotFoundStale + if checkNotFoundStale == nil { + checkNotFoundStale = alwaysFresh[time.Time] + } + + missingKeys := make([]string, len(missing)) + for j, i := range missing { + missingKeys[j] = keys[i] + } + cachedAts, err := getMany(ctx, c.notFoundCache, missingKeys) + for _, i := range missing { + key := keys[i] + if kerr := errForKey(err, key); kerr != nil { + res[i].err = errors.Wrapf(kerr, "get from notFoundCache failed for key: %s", key) + continue + } + cachedAt, ok := cachedAts[key] + if !ok { + res[i].fetch = true + continue + } + switch state := checkNotFoundStale(cachedAt); state { + case StateFresh: + res[i].err = errors.Wrapf(&ErrKeyNotFound{Cached: true, CacheState: state}, "key not found in cache for key: %s", key) + case StateStale: + if c.serveStale && !doubleCheck { + res[i].err = errors.Wrapf(&ErrKeyNotFound{Cached: true, CacheState: state}, "key not found in cache for key: %s", key) + res[i].refresh = true + } else { + res[i].fetch = true + } + default: + res[i].fetch = true + } + } + return res +} + +// fetchMany claims every key in the flight group, fetches the claimed ones as +// one batch, and waits for all of them (including those claimed by others). +func (c *Client[T]) fetchMany(ctx context.Context, keys, sfKeys []string) []result[T] { + flights := make([]*flight[T], len(keys)) + var ownKeys, ownSFKeys []string + var ownFlights []*flight[T] + for i, sfKey := range sfKeys { + f, leader := c.flights.claim(sfKey) + flights[i] = f + if leader { + ownKeys = append(ownKeys, keys[i]) + ownSFKeys = append(ownSFKeys, sfKey) + ownFlights = append(ownFlights, f) + } + } + if len(ownKeys) > 0 { + go c.fetchClaimedMany(ctx, ownKeys, ownSFKeys, ownFlights) + } + + results := make([]result[T], len(keys)) + for i, f := range flights { + select { + case <-f.done: + case <-ctx.Done(): + } + select { + case <-f.done: + results[i] = result[T]{value: f.value, err: f.err} + default: + results[i].err = errors.Wrapf(ctx.Err(), "context cancelled during fetch for key: %s", keys[i]) + } + } + return results +} + +// fetchClaimedMany is the batch form of fetchClaimed: double-check, then fetch +// what is still missing, then finish every flight. +func (c *Client[T]) fetchClaimedMany(ctx context.Context, keys, sfKeys []string, flights []*flight[T]) { + results := make([]result[T], len(keys)) + defer func() { + if r := recover(); r != nil { + c.logger.ErrorContext(ctx, "panic during upstream fetch", + "keys", keys, + "panic", r, + "stack", string(debug.Stack())) + err := errors.Errorf("panic during upstream fetch: %v", r) + for i := range results { + results[i] = result[T]{err: err} + } + } + for i, f := range flights { + c.flights.finish(sfKeys[i], f, results[i].value, results[i].err) + } + }() + + fetchCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), c.fetchTimeout) + defer cancel() + + pending := make([]int, 0, len(keys)) + if c.enableDoubleCheck { + for i, r := range c.lookupMany(fetchCtx, keys, true) { + switch { + case r.fetch: + pending = append(pending, i) + case r.err == nil: + results[i].value = r.value + case isCachedFreshNotFound(r.err): + results[i].err = r.err + default: + pending = append(pending, i) // like Get: a failed double-check falls through to upstream + } + } + } else { + for i := range keys { + pending = append(pending, i) + } + } + if len(pending) == 0 { + return + } + + pendingKeys := make([]string, len(pending)) + for j, i := range pending { + pendingKeys[j] = keys[i] + } + for j, r := range c.doFetchMany(fetchCtx, pendingKeys) { + results[pending[j]] = r + } +} + +// doFetchMany is the batch form of doFetch: fetch from upstream, then write +// the results to this layer only. +func (c *Client[T]) doFetchMany(ctx context.Context, keys []string) []result[T] { + results := make([]result[T], len(keys)) + + if batch, ok := c.upstream.(BatchUpstream[T]); ok { + values, err := batch.GetMany(ctx, keys) + for i, key := range keys { + if kerr := errForKey(err, key); kerr != nil { + results[i].err = errors.Wrapf(kerr, "get from upstream failed for key: %s", key) + } else if value, ok := values[key]; ok { + results[i].value = value + } else { + results[i].err = errors.Wrapf(&ErrKeyNotFound{}, "get from upstream failed for key: %s", key) + } + } + } else { + // ponytail: one goroutine per key, unbounded within a batch; add a limit if + // upstreams without batch support get hammered by large batches. + var wg sync.WaitGroup + for i, key := range keys { + wg.Go(func() { + results[i] = c.getFromUpstream(ctx, key) + }) + } + wg.Wait() + } + + found := map[string]T{} + var notFound []string + for i, key := range keys { + switch { + case results[i].err == nil: + found[key] = results[i].value + case IsErrKeyNotFound(results[i].err): + notFound = append(notFound, key) + } + } + if err := c.setManyWithoutUpstream(ctx, found); err != nil { + c.logger.WarnContext(ctx, "failed to set cache entries", "error", err) + } + if err := c.delManyWithoutUpstream(ctx, notFound); err != nil { + c.logger.WarnContext(ctx, "failed to delete cache entries", "error", err) + } + + return results +} + +func (c *Client[T]) getFromUpstream(ctx context.Context, key string) (res result[T]) { + defer func() { + if r := recover(); r != nil { + c.logger.ErrorContext(ctx, "panic during upstream fetch", + "key", key, + "panic", r, + "stack", string(debug.Stack())) + res = result[T]{err: errors.Errorf("panic during upstream fetch: %v", r)} + } + }() + value, err := c.upstream.Get(ctx, key) + if err != nil { + return result[T]{err: errors.Wrapf(err, "get from upstream failed for key: %s", key)} + } + return result[T]{value: value} +} + +// setManyWithoutUpstream is the batch form of setWithoutUpstream. +func (c *Client[T]) setManyWithoutUpstream(ctx context.Context, values map[string]T) error { + if len(values) == 0 { + return nil + } + if c.notFoundCache != nil { + keys := make([]string, 0, len(values)) + for key := range values { + keys = append(keys, key) + } + if err := delMany(ctx, c.notFoundCache, keys); err != nil { + return errors.Wrap(err, "delete from notFoundCache failed") + } + } + if err := setMany(ctx, c.backend, values); err != nil { + return errors.Wrap(err, "set in backend failed") + } + return nil +} + +// delManyWithoutUpstream is the batch form of delWithoutUpstream. +func (c *Client[T]) delManyWithoutUpstream(ctx context.Context, keys []string) error { + if len(keys) == 0 { + return nil + } + if c.notFoundCache != nil { + now := NowFunc() + cachedAts := make(map[string]time.Time, len(keys)) + for _, key := range keys { + cachedAts[key] = now + } + if err := setMany(ctx, c.notFoundCache, cachedAts); err != nil { + return errors.Wrap(err, "failed to set notFoundCache") + } + } + if err := delMany(ctx, c.backend, keys); err != nil { + return errors.Wrap(err, "delete from backend failed") + } + return nil +} + +// asyncRefreshMany is the batch form of asyncRefresh: the stale keys of one +// GetMany are refreshed together in the background. +func (c *Client[T]) asyncRefreshMany(ctx context.Context, keys []string) { + var refreshKeys, sfKeys []string + for _, key := range keys { + sfKey := c.makeSFKey(key) + if _, loaded := c.asyncRefreshing.LoadOrStore(sfKey, struct{}{}); !loaded { + refreshKeys = append(refreshKeys, key) + sfKeys = append(sfKeys, sfKey) + } + } + if len(refreshKeys) == 0 { + return + } + + go func() { + defer func() { + for _, sfKey := range sfKeys { + c.asyncRefreshing.Delete(sfKey) + } + }() + for i, r := range c.fetchMany(ctx, refreshKeys, sfKeys) { + if r.err != nil && !IsErrKeyNotFound(r.err) { + c.logger.ErrorContext(ctx, "async refresh failed", "key", refreshKeys[i], "error", r.err) + } + } + }() +} + +// getMany reads many keys from a cache or upstream, in one call when it +// implements BatchUpstream, otherwise key by key. +func getMany[T any](ctx context.Context, from Upstream[T], keys []string) (map[string]T, error) { + if batch, ok := from.(BatchUpstream[T]); ok { + return batch.GetMany(ctx, keys) + } + out := make(map[string]T, len(keys)) + errs := map[string]error{} + for _, key := range keys { + value, err := from.Get(ctx, key) + switch { + case err == nil: + out[key] = value + case !IsErrKeyNotFound(err): + errs[key] = err + } + } + if len(errs) > 0 { + return out, &BatchError{Errors: errs} + } + return out, nil +} + +func setMany[T any](ctx context.Context, cache Cache[T], values map[string]T) error { + if batch, ok := cache.(BatchCache[T]); ok { + return batch.SetMany(ctx, values) + } + for key, value := range values { + if err := cache.Set(ctx, key, value); err != nil { + return err + } + } + return nil +} + +func delMany[T any](ctx context.Context, cache Cache[T], keys []string) error { + if batch, ok := cache.(BatchCache[T]); ok { + return batch.DelMany(ctx, keys) + } + for _, key := range keys { + if err := cache.Del(ctx, key); err != nil { + return err + } + } + return nil +} + +// errForKey returns the error a batch call reported for key: the key's own +// entry if err is a *BatchError, otherwise err itself (the whole batch failed). +func errForKey(err error, key string) error { + var batchErr *BatchError + if errors.As(err, &batchErr) { + return batchErr.Errors[key] + } + return err +} + +func uniqueKeys(keys []string) []string { + seen := make(map[string]struct{}, len(keys)) + out := make([]string, 0, len(keys)) + for _, key := range keys { + if _, ok := seen[key]; !ok { + seen[key] = struct{}{} + out = append(out, key) + } + } + return out +} diff --git a/batch_test.go b/batch_test.go new file mode 100644 index 0000000..53aed41 --- /dev/null +++ b/batch_test.go @@ -0,0 +1,606 @@ +package cachex + +import ( + "context" + "fmt" + "maps" + "slices" + "sync" + "sync/atomic" + "testing" + "time" + + "github.com/pkg/errors" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +// testBatchCache checks the BatchCache contract against one implementation. +func testBatchCache(t *testing.T, cache BatchCache[string]) { + t.Helper() + ctx := context.Background() + + got, err := cache.GetMany(ctx, []string{"a", "b"}) + require.NoError(t, err) + assert.Empty(t, got, "nothing written yet, nothing returned") + + require.NoError(t, cache.SetMany(ctx, map[string]string{"a": "1", "b": "2", "c": "3"})) + require.NoError(t, cache.SetMany(ctx, map[string]string{}), "empty SetMany is a no-op") + + got, err = cache.GetMany(ctx, []string{"a", "b", "missing"}) + require.NoError(t, err) + assert.Equal(t, map[string]string{"a": "1", "b": "2"}, got, "missing keys are absent, not errors") + + v, err := cache.Get(ctx, "c") + require.NoError(t, err) + assert.Equal(t, "3", v, "SetMany is visible to Get") + + require.NoError(t, cache.SetMany(ctx, map[string]string{"a": "1b"})) + got, err = cache.GetMany(ctx, []string{"a"}) + require.NoError(t, err) + assert.Equal(t, map[string]string{"a": "1b"}, got, "SetMany overwrites") + + require.NoError(t, cache.DelMany(ctx, []string{"a", "c", "missing"})) + got, err = cache.GetMany(ctx, []string{"a", "b", "c"}) + require.NoError(t, err) + assert.Equal(t, map[string]string{"b": "2"}, got, "DelMany removes only the given keys") + + got, err = cache.GetMany(ctx, nil) + require.NoError(t, err) + assert.Empty(t, got) + require.NoError(t, cache.DelMany(ctx, nil)) +} + +func TestBatchCacheImplementations(t *testing.T) { + t.Run("SyncMap", func(t *testing.T) { + testBatchCache(t, NewSyncMap[string]()) + }) + t.Run("Ristretto", func(t *testing.T) { + testBatchCache(t, newRistrettoCache[string](t)) + }) + t.Run("Redis", func(t *testing.T) { + cache, _ := newRedisCache[string](t) + testBatchCache(t, cache) + }) + t.Run("Redis with prefix", func(t *testing.T) { + cache, mr := newRedisCache[string](t) + cache.keyPrefix = "p:" + testBatchCache(t, cache) + assert.True(t, mr.Exists("p:b"), "keys are stored with the prefix") + }) + t.Run("GORM", func(t *testing.T) { + cache, _ := newGORMCache[string](t, "batch_cache") + testBatchCache(t, cache) + }) + t.Run("GORM with prefix", func(t *testing.T) { + cache, db := newGORMCache[string](t, "batch_cache_prefixed") + cache.keyPrefix = "p:" + testBatchCache(t, cache) + var n int64 + require.NoError(t, db.Table("batch_cache_prefixed").Where("key = ?", "p:b").Count(&n).Error) + assert.Equal(t, int64(1), n, "keys are stored with the prefix") + }) +} + +func TestRedisCacheGetManyStruct(t *testing.T) { + ctx := context.Background() + type item struct{ N int } + cache, mr := newRedisCache[*item](t) + + require.NoError(t, cache.SetMany(ctx, map[string]*item{"a": {N: 1}})) + require.NoError(t, mr.Set("bad", "not json")) + + got, err := cache.GetMany(ctx, []string{"a", "bad"}) + assert.Equal(t, map[string]*item{"a": {N: 1}}, got, "a corrupt entry does not hide the others") + var be *BatchError + require.True(t, errors.As(err, &be)) + assert.Contains(t, be.Errors, "bad") + assert.NotContains(t, be.Errors, "a") +} + +// batchUpstream is a BatchUpstream fake that records every call. +type batchUpstream struct { + mu sync.Mutex + data map[string]string + getCalls [][]string // keys of each GetMany call, sorted + oneCalls []string // keys of each Get call + block func(keys []string) + err error +} + +func (u *batchUpstream) GetMany(_ context.Context, keys []string) (map[string]string, error) { + sorted := slices.Sorted(slices.Values(keys)) + u.mu.Lock() + u.getCalls = append(u.getCalls, sorted) + u.mu.Unlock() + if u.block != nil { + u.block(sorted) + } + if u.err != nil { + return nil, u.err + } + out := map[string]string{} + u.mu.Lock() + defer u.mu.Unlock() + for _, k := range keys { + if v, ok := u.data[k]; ok { + out[k] = v + } + } + return out, nil +} + +func (u *batchUpstream) Get(_ context.Context, key string) (string, error) { + u.mu.Lock() + u.oneCalls = append(u.oneCalls, key) + u.mu.Unlock() + if u.block != nil { + u.block([]string{key}) + } + u.mu.Lock() + defer u.mu.Unlock() + if v, ok := u.data[key]; ok { + return v, nil + } + return "", &ErrKeyNotFound{} +} + +func (u *batchUpstream) calls() ([][]string, []string) { + u.mu.Lock() + defer u.mu.Unlock() + return slices.Clone(u.getCalls), slices.Clone(u.oneCalls) +} + +func TestClientGetMany(t *testing.T) { + ctx := context.Background() + + t.Run("partial hit fetches only the misses, in one upstream call", func(t *testing.T) { + backend := NewSyncMap[string]() + require.NoError(t, backend.Set(ctx, "a", "cached-a")) + up := &batchUpstream{data: map[string]string{"a": "up-a", "b": "up-b", "c": "up-c"}} + cli := NewClient(backend, up) + + got, err := cli.GetMany(ctx, []string{"a", "b", "c", "missing", "b"}) + require.NoError(t, err) + assert.Equal(t, map[string]string{"a": "cached-a", "b": "up-b", "c": "up-c"}, got, + "cached value wins, fetched values are returned, missing keys are absent") + + batches, singles := up.calls() + assert.Equal(t, [][]string{{"b", "c", "missing"}}, batches, "one upstream call with only the misses, deduplicated") + assert.Empty(t, singles) + + v, err := backend.Get(ctx, "b") + require.NoError(t, err) + assert.Equal(t, "up-b", v, "fetched values are written back") + }) + + t.Run("full hit does not touch upstream", func(t *testing.T) { + backend := NewSyncMap[string]() + require.NoError(t, backend.SetMany(ctx, map[string]string{"a": "1", "b": "2"})) + up := &batchUpstream{} + cli := NewClient(backend, up) + + got, err := cli.GetMany(ctx, []string{"a", "b"}) + require.NoError(t, err) + assert.Equal(t, map[string]string{"a": "1", "b": "2"}, got) + batches, singles := up.calls() + assert.Empty(t, batches) + assert.Empty(t, singles) + }) + + t.Run("empty keys", func(t *testing.T) { + cli := NewClient(NewSyncMap[string](), &batchUpstream{}) + got, err := cli.GetMany(ctx, nil) + require.NoError(t, err) + assert.Empty(t, got) + }) + + t.Run("upstream without batch support is called key by key", func(t *testing.T) { + var mu sync.Mutex + var keys []string + up := UpstreamFunc[string](func(_ context.Context, key string) (string, error) { + mu.Lock() + keys = append(keys, key) + mu.Unlock() + if key == "missing" { + return "", &ErrKeyNotFound{} + } + return "v-" + key, nil + }) + backend := NewSyncMap[string]() + cli := NewClient(backend, up) + + got, err := cli.GetMany(ctx, []string{"a", "b", "missing"}) + require.NoError(t, err) + assert.Equal(t, map[string]string{"a": "v-a", "b": "v-b"}, got) + assert.ElementsMatch(t, []string{"a", "b", "missing"}, keys) + v, err := backend.Get(ctx, "a") + require.NoError(t, err) + assert.Equal(t, "v-a", v) + }) + + t.Run("backend batch reads and writes are used", func(t *testing.T) { + backend := &countingBatchCache{SyncMap: NewSyncMap[string]()} + up := &batchUpstream{data: map[string]string{"a": "1", "b": "2"}} + cli := NewClient(backend, up) + + _, err := cli.GetMany(ctx, []string{"a", "b"}) + require.NoError(t, err) + assert.Equal(t, int32(1), backend.getMany.Load(), "one batch read of the backend") + assert.Equal(t, int32(1), backend.setMany.Load(), "one batch write back") + assert.Equal(t, int32(0), backend.gets.Load(), "no per-key reads") + }) +} + +type countingBatchCache struct { + *SyncMap[string] + gets, getMany, setMany atomic.Int32 +} + +func (c *countingBatchCache) Get(ctx context.Context, key string) (string, error) { + c.gets.Add(1) + return c.SyncMap.Get(ctx, key) +} + +func (c *countingBatchCache) GetMany(ctx context.Context, keys []string) (map[string]string, error) { + c.getMany.Add(1) + return c.SyncMap.GetMany(ctx, keys) +} + +func (c *countingBatchCache) SetMany(ctx context.Context, values map[string]string) error { + c.setMany.Add(1) + return c.SyncMap.SetMany(ctx, values) +} + +func TestClientGetManyErrors(t *testing.T) { + ctx := context.Background() + + t.Run("whole upstream failure fails every fetched key", func(t *testing.T) { + backend := NewSyncMap[string]() + require.NoError(t, backend.Set(ctx, "a", "1")) + boom := errors.New("boom") + cli := NewClient(backend, &batchUpstream{err: boom}) + + got, err := cli.GetMany(ctx, []string{"a", "b", "c"}) + assert.Equal(t, map[string]string{"a": "1"}, got, "keys that did not need the upstream are still returned") + var be *BatchError + require.True(t, errors.As(err, &be)) + assert.Len(t, be.Errors, 2) + assert.ErrorIs(t, be.Errors["b"], boom) + assert.ErrorIs(t, err, boom, "errors.Is sees through BatchError") + }) + + t.Run("per-key upstream failure keeps the other keys", func(t *testing.T) { + boom := errors.New("boom") + up := UpstreamFunc[string](func(_ context.Context, key string) (string, error) { + if key == "bad" { + return "", boom + } + return "v-" + key, nil + }) + cli := NewClient(NewSyncMap[string](), up) + + got, err := cli.GetMany(ctx, []string{"a", "bad"}) + assert.Equal(t, map[string]string{"a": "v-a"}, got) + var be *BatchError + require.True(t, errors.As(err, &be)) + assert.Equal(t, []string{"bad"}, slices.Collect(maps.Keys(be.Errors))) + }) + + t.Run("panic in batch upstream is recovered", func(t *testing.T) { + up := &batchUpstream{block: func([]string) { panic("kaboom") }} + cli := NewClient(NewSyncMap[string](), up) + + got, err := cli.GetMany(ctx, []string{"a", "b"}) + assert.Empty(t, got) + require.Error(t, err) + assert.Contains(t, err.Error(), "panic during upstream fetch") + }) +} + +func TestClientGetManyNotFoundCache(t *testing.T) { + ctx := context.Background() + clock := NewMockClock(time.Now()) + defer clock.Install()() + + notFound := NewSyncMap[time.Time]() + up := &batchUpstream{data: map[string]string{"a": "1"}} + cli := NewClient(NewSyncMap[string](), up, + NotFoundWithTTL[string](notFound, time.Minute, 0)) + + got, err := cli.GetMany(ctx, []string{"a", "missing"}) + require.NoError(t, err) + assert.Equal(t, map[string]string{"a": "1"}, got) + _, err = notFound.Get(ctx, "missing") + require.NoError(t, err, "not-found result is cached") + + got, err = cli.GetMany(ctx, []string{"a", "missing"}) + require.NoError(t, err) + assert.Equal(t, map[string]string{"a": "1"}, got) + batches, _ := up.calls() + assert.Len(t, batches, 1, "second call is answered by backend and not-found cache") + + _, err = cli.Get(ctx, "missing") + var e *ErrKeyNotFound + require.True(t, errors.As(err, &e)) + assert.True(t, e.Cached, "single Get sees the not-found entry GetMany wrote") + + clock.Advance(2 * time.Minute) + _, err = cli.GetMany(ctx, []string{"missing"}) + require.NoError(t, err) + batches, _ = up.calls() + assert.Equal(t, []string{"missing"}, batches[len(batches)-1], "rotten not-found entry is refetched") +} + +func TestClientGetManyServeStale(t *testing.T) { + ctx := context.Background() + clock := NewMockClock(time.Now()) + defer clock.Install()() + + var version atomic.Int32 + var mu sync.Mutex + var calls [][]string + refreshed := make(chan struct{}, 10) + up := batchUpstreamFunc[*Entry[string]](func(_ context.Context, keys []string) (map[string]*Entry[string], error) { + mu.Lock() + calls = append(calls, slices.Sorted(slices.Values(keys))) + mu.Unlock() + v := version.Add(1) + out := map[string]*Entry[string]{} + for _, k := range keys { + out[k] = &Entry[string]{Data: fmt.Sprintf("%s-v%d", k, v), CachedAt: NowFunc()} + } + refreshed <- struct{}{} + return out, nil + }) + backend := NewSyncMap[*Entry[string]]() + cli := NewClient(backend, up, + EntryWithTTL[string](time.Minute, time.Hour), + WithServeStale[*Entry[string]](true)) + + got, err := cli.GetMany(ctx, []string{"a", "b"}) + require.NoError(t, err) + assert.Equal(t, "a-v1", got["a"].Data) + <-refreshed + + clock.Advance(2 * time.Minute) // stale + got, err = cli.GetMany(ctx, []string{"a", "b"}) + require.NoError(t, err) + assert.Equal(t, "a-v1", got["a"].Data, "stale value is served immediately") + assert.Equal(t, "b-v1", got["b"].Data) + + select { + case <-refreshed: + case <-time.After(time.Second): + t.Fatal("background refresh did not happen") + } + require.Eventually(t, func() bool { + v, err := backend.Get(ctx, "a") + return err == nil && v.Data == "a-v2" + }, time.Second, 5*time.Millisecond, "background refresh writes the new value") + + mu.Lock() + assert.Equal(t, [][]string{{"a", "b"}, {"a", "b"}}, calls, "stale keys are refreshed in one batch") + mu.Unlock() +} + +type batchUpstreamFunc[T any] func(ctx context.Context, keys []string) (map[string]T, error) + +func (f batchUpstreamFunc[T]) GetMany(ctx context.Context, keys []string) (map[string]T, error) { + return f(ctx, keys) +} + +func (f batchUpstreamFunc[T]) Get(ctx context.Context, key string) (T, error) { + var zero T + m, err := f(ctx, []string{key}) + if err != nil { + return zero, err + } + v, ok := m[key] + if !ok { + return zero, &ErrKeyNotFound{} + } + return v, nil +} + +func TestClientGetManySharesSingleflightWithGet(t *testing.T) { + ctx := context.Background() + release := make(chan struct{}) + entered := make(chan struct{}) + up := &batchUpstream{data: map[string]string{"x": "vx", "y": "vy"}} + up.block = func(keys []string) { + if keys[0] == "x" && len(keys) == 1 { + close(entered) + <-release + } + } + cli := NewClient(NewSyncMap[string](), up) + + var wg sync.WaitGroup + var single string + wg.Go(func() { + var err error + single, err = cli.Get(ctx, "x") + assert.NoError(t, err) + }) + waitFor(t, entered) // single Get owns the fetch of x + + var many map[string]string + wg.Go(func() { + var err error + many, err = cli.GetMany(ctx, []string{"x", "y"}) + assert.NoError(t, err) + }) + require.Eventually(t, func() bool { + batches, _ := up.calls() + return len(batches) == 1 + }, time.Second, time.Millisecond) + close(release) + wg.Wait() + + batches, singles := up.calls() + assert.Equal(t, []string{"x"}, singles, "x is fetched once, by the single Get") + assert.Equal(t, [][]string{{"y"}}, batches, "GetMany waits for the in-flight x and fetches only y") + assert.Equal(t, "vx", single) + assert.Equal(t, map[string]string{"x": "vx", "y": "vy"}, many) +} + +func TestClientGetManyOverlappingBatches(t *testing.T) { + ctx := context.Background() + release := make(chan struct{}) + entered := make(chan struct{}) + up := &batchUpstream{data: map[string]string{"x": "vx", "y": "vy", "z": "vz"}} + up.block = func(keys []string) { + if keys[0] == "x" { + close(entered) + <-release + } + } + cli := NewClient(NewSyncMap[string](), up) + + var wg sync.WaitGroup + var a, b map[string]string + wg.Go(func() { + var err error + a, err = cli.GetMany(ctx, []string{"x", "y"}) + assert.NoError(t, err) + }) + waitFor(t, entered) + + wg.Go(func() { + var err error + b, err = cli.GetMany(ctx, []string{"y", "z"}) + assert.NoError(t, err) + }) + require.Eventually(t, func() bool { + batches, _ := up.calls() + return len(batches) == 2 + }, time.Second, time.Millisecond) + close(release) + wg.Wait() + + batches, _ := up.calls() + assert.Equal(t, [][]string{{"x", "y"}, {"z"}}, batches, "the shared key y is fetched only once") + assert.Equal(t, map[string]string{"x": "vx", "y": "vy"}, a) + assert.Equal(t, map[string]string{"y": "vy", "z": "vz"}, b) +} + +func TestClientGetManyDoubleCheck(t *testing.T) { + ctx := context.Background() + // The backend misses on the first read and hits on the second, as if another + // request wrote the value between the lookup and the claim. + store := NewSyncMap[string]() + var reads atomic.Int32 + backend := &trackedCache[string]{ + onGet: func(key string) (string, error) { + if reads.Add(1) == 1 { + return "", &ErrKeyNotFound{} + } + return store.Get(ctx, key) + }, + onSet: func(key, value string) error { return store.Set(ctx, key, value) }, + onDel: func(key string) error { return store.Del(ctx, key) }, + } + require.NoError(t, store.Set(ctx, "x", "written-meanwhile")) + up := &batchUpstream{data: map[string]string{"x": "from-upstream"}} + cli := NewClient(backend, up, WithDoubleCheck[string](DoubleCheckEnabled)) + + got, err := cli.GetMany(ctx, []string{"x"}) + require.NoError(t, err) + assert.Equal(t, map[string]string{"x": "written-meanwhile"}, got) + batches, _ := up.calls() + assert.Empty(t, batches, "double-check finds the value, so upstream is not called") +} + +func TestClientGetManyLayered(t *testing.T) { + ctx := context.Background() + l2, _ := newGORMCache[string](t, "layered_batch") + bottom := &batchUpstream{data: map[string]string{"a": "1", "b": "2", "c": "3"}} + l2Client := NewClient(l2, bottom) + l1Client := NewClient(newRistrettoCache[string](t), l2Client) + + got, err := l1Client.GetMany(ctx, []string{"a", "b", "c", "missing"}) + require.NoError(t, err) + assert.Equal(t, map[string]string{"a": "1", "b": "2", "c": "3"}, got) + + batches, singles := bottom.calls() + assert.Equal(t, [][]string{{"a", "b", "c", "missing"}}, batches, "the batch reaches the bottom upstream as one call") + assert.Empty(t, singles) + + stored, err := l2.GetMany(ctx, []string{"a", "b", "c"}) + require.NoError(t, err) + assert.Len(t, stored, 3, "the middle layer was filled too") +} + +func TestClientGetManyContextCancel(t *testing.T) { + release := make(chan struct{}) + up := &batchUpstream{data: map[string]string{"a": "1"}, block: func([]string) { <-release }} + defer close(release) + cli := NewClient(NewSyncMap[string](), up) + + ctx, cancel := context.WithTimeout(context.Background(), 20*time.Millisecond) + defer cancel() + got, err := cli.GetMany(ctx, []string{"a"}) + assert.Empty(t, got) + assert.ErrorIs(t, err, context.DeadlineExceeded) +} + +func waitFor(t *testing.T, ch <-chan struct{}) { + t.Helper() + select { + case <-ch: + case <-time.After(time.Second): + require.FailNow(t, "timed out waiting") + } +} + +// BenchmarkGetManyVsGet compares fetching 100 missing keys with one GetMany +// against a loop of Get, with an upstream that costs one round trip per call +// whether it answers one key or many (a DB query, an API call). +func BenchmarkGetManyVsGet(b *testing.B) { + const n = 100 + const roundTrip = time.Millisecond + ctx := context.Background() + keys := make([]string, n) + for i := range keys { + keys[i] = fmt.Sprintf("key-%d", i) + } + + newClient := func(calls *atomic.Int64) *Client[string] { + up := batchUpstreamFunc[string](func(_ context.Context, keys []string) (map[string]string, error) { + calls.Add(1) + time.Sleep(roundTrip) + out := make(map[string]string, len(keys)) + for _, k := range keys { + out[k] = "v-" + k + } + return out, nil + }) + return NewClient(NewSyncMap[string](), up) + } + + b.Run("GetMany", func(b *testing.B) { + var calls atomic.Int64 + for b.Loop() { + cli := newClient(&calls) + got, err := cli.GetMany(ctx, keys) + if err != nil || len(got) != n { + b.Fatal(err, len(got)) + } + } + b.ReportMetric(float64(calls.Load())/float64(b.N), "upstream-calls/op") + }) + + b.Run("loop Get", func(b *testing.B) { + var calls atomic.Int64 + for b.Loop() { + cli := newClient(&calls) + for _, k := range keys { + if _, err := cli.Get(ctx, k); err != nil { + b.Fatal(err) + } + } + } + b.ReportMetric(float64(calls.Load())/float64(b.N), "upstream-calls/op") + }) +} diff --git a/client.go b/client.go index 9962478..59606fb 100644 --- a/client.go +++ b/client.go @@ -10,7 +10,6 @@ import ( "time" "github.com/pkg/errors" - "golang.org/x/sync/singleflight" ) var ( @@ -33,7 +32,7 @@ type Client[T any] struct { fetchConcurrency int logger *slog.Logger - sfg singleflight.Group + flights flightGroup[T] asyncRefreshing sync.Map // Double-check optimization @@ -265,61 +264,74 @@ func (c *Client[T]) fetchFromUpstreamWithSFKey(ctx context.Context, key string, c.testHooks.beforeSingleflightStart(ctx, key) } - resChan := c.sfg.DoChan(sfKey, func() (result any, resultErr error) { - if c.testHooks != nil && c.testHooks.afterSingleflightStart != nil { - c.testHooks.afterSingleflightStart(ctx, key) - } - - defer func() { - if r := recover(); r != nil { - c.logger.ErrorContext(ctx, "panic during upstream fetch", - "key", key, - "panic", r, - "stack", string(debug.Stack())) - var zero T - result = zero - resultErr = errors.Errorf("panic during upstream fetch: %v", r) - } + f, leader := c.flights.claim(sfKey) + if leader { + go func() { + value, err := c.fetchClaimed(ctx, key) + c.flights.finish(sfKey, f, value, err) }() - - // Double-check optimization: check cache again before fetching from upstream - // This handles the narrow window after a write completes but before singleflight releases - // - // Note: We use the original key (not sfKey) because: - // 1. fetchConcurrency allows multiple slots to fetch concurrently (exploration phase) - // 2. Once ANY slot completes, ALL slots should converge to reuse that result (convergence phase) - // 3. Using key ensures cross-slot visibility, maximizing result reuse after first completion - if c.enableDoubleCheck { - cachedValue, err := c.get(ctx, key, true) - - if err == nil { - return cachedValue, nil - } - var e *ErrKeyNotFound - if errors.As(err, &e) && e.Cached && e.CacheState == StateFresh { - var zero T - return zero, err - } - // otherwise, fetch from upstream - } - - fetchCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), c.fetchTimeout) - defer cancel() - return c.doFetch(fetchCtx, key) - }) + } select { case <-ctx.Done(): return zero, errors.Wrapf(ctx.Err(), "context cancelled during fetch for key: %s", key) - case res := <-resChan: + case <-f.done: if c.testHooks != nil && c.testHooks.afterSingleflightEnd != nil { c.testHooks.afterSingleflightEnd(ctx, key) } - if res.Err != nil { - return zero, res.Err + if f.err != nil { + return zero, f.err } - return res.Val.(T), nil + return f.value, nil + } +} + +// fetchClaimed fetches a key this request has claimed in the flight group. +func (c *Client[T]) fetchClaimed(ctx context.Context, key string) (result T, resultErr error) { + if c.testHooks != nil && c.testHooks.afterSingleflightStart != nil { + c.testHooks.afterSingleflightStart(ctx, key) } + + defer func() { + if r := recover(); r != nil { + c.logger.ErrorContext(ctx, "panic during upstream fetch", + "key", key, + "panic", r, + "stack", string(debug.Stack())) + var zero T + result = zero + resultErr = errors.Errorf("panic during upstream fetch: %v", r) + } + }() + + // Double-check optimization: check cache again before fetching from upstream + // This handles the narrow window after a write completes but before singleflight releases + // + // Note: We use the original key (not sfKey) because: + // 1. fetchConcurrency allows multiple slots to fetch concurrently (exploration phase) + // 2. Once ANY slot completes, ALL slots should converge to reuse that result (convergence phase) + // 3. Using key ensures cross-slot visibility, maximizing result reuse after first completion + if c.enableDoubleCheck { + cachedValue, err := c.get(ctx, key, true) + + if err == nil { + return cachedValue, nil + } + if isCachedFreshNotFound(err) { + var zero T + return zero, err + } + // otherwise, fetch from upstream + } + + fetchCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), c.fetchTimeout) + defer cancel() + return c.doFetch(fetchCtx, key) +} + +func isCachedFreshNotFound(err error) bool { + var e *ErrKeyNotFound + return errors.As(err, &e) && e.Cached && e.CacheState == StateFresh } func (c *Client[T]) makeSFKey(key string) string { diff --git a/error.go b/error.go index 8b91e74..71dbe67 100644 --- a/error.go +++ b/error.go @@ -3,6 +3,9 @@ package cachex import ( "errors" "fmt" + "maps" + "slices" + "strings" ) // ErrKeyNotFound indicates that the requested key was not found in the cache @@ -37,3 +40,30 @@ func IsErrKeyNotFound(err error) bool { var e *ErrKeyNotFound return errors.As(err, &e) } + +// BatchError reports, per key, the keys that failed in a batch operation +// (GetMany). Keys that do not exist are not failures: they are just absent +// from the result map. errors.Is and errors.As see through to the per-key errors. +type BatchError struct { + Errors map[string]error // failed key -> its error +} + +// Error lists the failed keys in sorted order +func (e *BatchError) Error() string { + keys := slices.Sorted(maps.Keys(e.Errors)) + parts := make([]string, len(keys)) + for i, key := range keys { + parts[i] = fmt.Sprintf("%s: %v", key, e.Errors[key]) + } + return fmt.Sprintf("%d keys failed: %s", len(keys), strings.Join(parts, "; ")) +} + +// Unwrap returns the per-key errors, in sorted key order +func (e *BatchError) Unwrap() []error { + keys := slices.Sorted(maps.Keys(e.Errors)) + errs := make([]error, len(keys)) + for i, key := range keys { + errs[i] = e.Errors[key] + } + return errs +} diff --git a/gorm.go b/gorm.go index 34b9f33..a4d8d93 100644 --- a/gorm.go +++ b/gorm.go @@ -4,6 +4,7 @@ import ( "cmp" "context" "encoding/json" + "strings" "time" "github.com/pkg/errors" @@ -19,7 +20,7 @@ type GORMCache[T any] struct { keyPrefix string } -var _ Cache[any] = &GORMCache[any]{} +var _ BatchCache[any] = &GORMCache[any]{} type cacheEntry struct { Key string `gorm:"not null;primaryKey;size:255"` @@ -145,3 +146,97 @@ func (g *GORMCache[T]) Del(ctx context.Context, key string) error { } return nil } + +// GetMany retrieves many values with one `WHERE key IN (...)` query. +// Missing keys are absent from the result; a value that fails to unmarshal is +// reported in a *BatchError without hiding the others. +// +// ponytail: no chunking; very large batches can exceed the database's bound +// parameter limit (e.g. 32766 on SQLite, 65535 on PostgreSQL). +func (g *GORMCache[T]) GetMany(ctx context.Context, keys []string) (map[string]T, error) { + out := make(map[string]T, len(keys)) + if len(keys) == 0 { + return out, nil + } + + prefixed := make([]string, len(keys)) + for i, key := range keys { + prefixed[i] = g.prefixedKey(key) + } + + var entries []cacheEntry + tx := cmp.Or(GetGORMTx(ctx), g.db) + if err := tx.WithContext(ctx). + Table(g.tableName). + Where("key IN ?", prefixed). + Find(&entries).Error; err != nil { + return nil, errors.Wrap(err, "failed to get cache entries") + } + + var keyErrs map[string]error + for _, entry := range entries { + key := strings.TrimPrefix(entry.Key, g.keyPrefix) + var value T + if err := json.Unmarshal(entry.Value, &value); err != nil { + if keyErrs == nil { + keyErrs = map[string]error{} + } + keyErrs[key] = errors.Wrapf(err, "failed to unmarshal value for key: %s", key) + continue + } + out[key] = value + } + if keyErrs != nil { + return out, &BatchError{Errors: keyErrs} + } + return out, nil +} + +// SetMany stores many values with one multi-row upsert (same bound parameter limit as GetMany) +func (g *GORMCache[T]) SetMany(ctx context.Context, values map[string]T) error { + if len(values) == 0 { + return nil + } + + entries := make([]cacheEntry, 0, len(values)) + for key, value := range values { + data, err := json.Marshal(value) + if err != nil { + return errors.Wrapf(err, "failed to marshal value for key: %s", key) + } + entries = append(entries, cacheEntry{Key: g.prefixedKey(key), Value: data}) + } + + tx := cmp.Or(GetGORMTx(ctx), g.db) + if err := tx.WithContext(ctx). + Table(g.tableName). + Clauses(clause.OnConflict{ + Columns: []clause.Column{{Name: "key"}}, + UpdateAll: true, + }). + Create(&entries).Error; err != nil { + return errors.Wrap(err, "failed to set cache entries") + } + return nil +} + +// DelMany removes many keys with one `WHERE key IN (...)` delete +func (g *GORMCache[T]) DelMany(ctx context.Context, keys []string) error { + if len(keys) == 0 { + return nil + } + + prefixed := make([]string, len(keys)) + for i, key := range keys { + prefixed[i] = g.prefixedKey(key) + } + + tx := cmp.Or(GetGORMTx(ctx), g.db) + if err := tx.WithContext(ctx). + Table(g.tableName). + Where("key IN ?", prefixed). + Delete(nil).Error; err != nil { + return errors.Wrap(err, "failed to delete cache entries") + } + return nil +} diff --git a/redis.go b/redis.go index e7fe16d..58ac570 100644 --- a/redis.go +++ b/redis.go @@ -18,7 +18,7 @@ type RedisCache[T any] struct { useBinary bool // true if T implements encoding.BinaryMarshaler and encoding.BinaryUnmarshaler } -var _ Cache[any] = &RedisCache[any]{} +var _ BatchCache[any] = &RedisCache[any]{} // RedisCacheConfig holds configuration for RedisCache type RedisCacheConfig struct { @@ -64,32 +64,65 @@ func (r *RedisCache[T]) prefixedKey(key string) string { return r.keyPrefix + key } -// Set stores a value in the cache -func (r *RedisCache[T]) Set(ctx context.Context, key string, value T) error { - var data any - var err error - +func (r *RedisCache[T]) encode(key string, value T) (any, error) { if r.useBinary { // Use BinaryMarshaler interface - if marshaler, ok := any(value).(encoding.BinaryMarshaler); ok { - data, err = marshaler.MarshalBinary() - if err != nil { - return errors.Wrapf(err, "failed to marshal binary for key: %s", key) - } - } else { - return errors.Errorf("value does not implement encoding.BinaryMarshaler for key: %s", key) + marshaler, ok := any(value).(encoding.BinaryMarshaler) + if !ok { + return nil, errors.Errorf("value does not implement encoding.BinaryMarshaler for key: %s", key) + } + data, err := marshaler.MarshalBinary() + if err != nil { + return nil, errors.Wrapf(err, "failed to marshal binary for key: %s", key) } - } else { - switch any(value).(type) { - case string, []byte: - data = value - default: - // For other types: marshal to JSON - data, err = json.Marshal(value) - if err != nil { - return errors.Wrapf(err, "failed to marshal value for key: %s", key) + return data, nil + } + + switch any(value).(type) { + case string, []byte: + return value, nil + default: + // For other types: marshal to JSON + data, err := json.Marshal(value) + if err != nil { + return nil, errors.Wrapf(err, "failed to marshal value for key: %s", key) + } + return data, nil + } +} + +func (r *RedisCache[T]) decode(key string, data string) (T, error) { + var zero T + + switch any(zero).(type) { + case string: + return any(data).(T), nil + case []byte: + return any([]byte(data)).(T), nil + } + + var value T + if r.useBinary { + if unmarshaler, ok := any(&value).(encoding.BinaryUnmarshaler); ok { + if err := unmarshaler.UnmarshalBinary([]byte(data)); err != nil { + return zero, errors.Wrapf(err, "failed to unmarshal binary for key: %s", key) } } + return value, nil + } + + // For other types: unmarshal from JSON + if err := json.Unmarshal([]byte(data), &value); err != nil { + return zero, errors.Wrapf(err, "failed to unmarshal value for key: %s", key) + } + return value, nil +} + +// Set stores a value in the cache +func (r *RedisCache[T]) Set(ctx context.Context, key string, value T) error { + data, err := r.encode(key, value) + if err != nil { + return err } if err := r.client.Set(ctx, r.prefixedKey(key), data, r.ttl).Err(); err != nil { @@ -109,48 +142,97 @@ func (r *RedisCache[T]) handleRedisError(err error, key string) error { // Get retrieves a value from the cache func (r *RedisCache[T]) Get(ctx context.Context, key string) (T, error) { var zero T - cmd := r.client.Get(ctx, r.prefixedKey(key)) + data, err := r.client.Get(ctx, r.prefixedKey(key)).Result() + if err != nil { + return zero, r.handleRedisError(err, key) + } + return r.decode(key, data) +} - if _, ok := any(zero).(string); ok { - str, err := cmd.Result() - if err != nil { - return zero, r.handleRedisError(err, key) - } - return any(str).(T), nil +// Del removes a value from the cache +func (r *RedisCache[T]) Del(ctx context.Context, key string) error { + if err := r.client.Del(ctx, r.prefixedKey(key)).Err(); err != nil { + return errors.Wrapf(err, "failed to delete cache entry for key: %s", key) } + return nil +} - data, err := cmd.Bytes() - if err != nil { - return zero, r.handleRedisError(err, key) +// GetMany retrieves many values in one round trip (a pipeline of GETs, which, +// unlike MGET, also works across slots on Redis Cluster). +// Missing keys are absent from the result; a value that fails to decode is +// reported in a *BatchError without hiding the others. +func (r *RedisCache[T]) GetMany(ctx context.Context, keys []string) (map[string]T, error) { + out := make(map[string]T, len(keys)) + if len(keys) == 0 { + return out, nil } - if _, ok := any(zero).([]byte); ok { - return any(data).(T), nil + pipe := r.client.Pipeline() + cmds := make([]*redis.StringCmd, len(keys)) + for i, key := range keys { + cmds[i] = pipe.Get(ctx, r.prefixedKey(key)) + } + if _, err := pipe.Exec(ctx); err != nil && !errors.Is(err, redis.Nil) { + return nil, errors.Wrap(err, "failed to get cache entries") } - if r.useBinary { + var keyErrs map[string]error + for i, key := range keys { + data, err := cmds[i].Result() + if errors.Is(err, redis.Nil) { + continue + } var value T - if unmarshaler, ok := any(&value).(encoding.BinaryUnmarshaler); ok { - if err := unmarshaler.UnmarshalBinary(data); err != nil { - return zero, errors.Wrapf(err, "failed to unmarshal binary for key: %s", key) + if err == nil { + value, err = r.decode(key, data) + } + if err != nil { + if keyErrs == nil { + keyErrs = map[string]error{} } + keyErrs[key] = err + continue } - return value, nil + out[key] = value + } + if keyErrs != nil { + return out, &BatchError{Errors: keyErrs} } + return out, nil +} - // For other types: unmarshal from JSON - var value T - if err := json.Unmarshal(data, &value); err != nil { - return zero, errors.Wrapf(err, "failed to unmarshal value for key: %s", key) +// SetMany stores many values in one round trip (a pipeline of SETs with the configured TTL) +func (r *RedisCache[T]) SetMany(ctx context.Context, values map[string]T) error { + if len(values) == 0 { + return nil } - return value, nil + pipe := r.client.Pipeline() + for key, value := range values { + data, err := r.encode(key, value) + if err != nil { + return err + } + pipe.Set(ctx, r.prefixedKey(key), data, r.ttl) + } + if _, err := pipe.Exec(ctx); err != nil { + return errors.Wrap(err, "failed to set cache entries") + } + return nil } -// Del removes a value from the cache -func (r *RedisCache[T]) Del(ctx context.Context, key string) error { - if err := r.client.Del(ctx, r.prefixedKey(key)).Err(); err != nil { - return errors.Wrapf(err, "failed to delete cache entry for key: %s", key) +// DelMany removes many keys in one round trip +func (r *RedisCache[T]) DelMany(ctx context.Context, keys []string) error { + if len(keys) == 0 { + return nil + } + + pipe := r.client.Pipeline() + for _, key := range keys { + pipe.Del(ctx, r.prefixedKey(key)) + } + if _, err := pipe.Exec(ctx); err != nil { + return errors.Wrap(err, "failed to delete cache entries") } return nil } diff --git a/ristretto.go b/ristretto.go index 43d56ff..1d1b05b 100644 --- a/ristretto.go +++ b/ristretto.go @@ -14,7 +14,7 @@ type RistrettoCache[T any] struct { ttl time.Duration } -var _ Cache[any] = &RistrettoCache[any]{} +var _ BatchCache[any] = &RistrettoCache[any]{} // RistrettoCacheConfig holds configuration for RistrettoCache type RistrettoCacheConfig[T any] struct { @@ -106,3 +106,32 @@ func (r *RistrettoCache[T]) Close() error { r.cache.Close() return nil } + +// GetMany retrieves the values that are present; missing keys are absent from the result +func (r *RistrettoCache[T]) GetMany(_ context.Context, keys []string) (map[string]T, error) { + out := make(map[string]T, len(keys)) + for _, key := range keys { + if value, found := r.cache.Get(key); found { + out[key] = value + } + } + return out, nil +} + +// SetMany stores the values, waiting once for all buffered writes (see Set) +func (r *RistrettoCache[T]) SetMany(_ context.Context, values map[string]T) error { + for key, value := range values { + r.cache.SetWithTTL(key, value, 1, r.ttl) + } + r.cache.Wait() + return nil +} + +// DelMany removes the keys, waiting once for all buffered deletions (see Del) +func (r *RistrettoCache[T]) DelMany(_ context.Context, keys []string) error { + for _, key := range keys { + r.cache.Del(key) + } + r.cache.Wait() + return nil +} diff --git a/syncmap.go b/syncmap.go index 84e739a..254e16a 100644 --- a/syncmap.go +++ b/syncmap.go @@ -12,7 +12,7 @@ type SyncMap[T any] struct { sync.Map } -var _ Cache[any] = &SyncMap[any]{} +var _ BatchCache[any] = &SyncMap[any]{} func NewSyncMap[T any]() *SyncMap[T] { return &SyncMap[T]{} @@ -36,3 +36,27 @@ func (s *SyncMap[T]) Del(_ context.Context, key string) error { s.Delete(key) return nil } + +func (s *SyncMap[T]) GetMany(_ context.Context, keys []string) (map[string]T, error) { + out := make(map[string]T, len(keys)) + for _, key := range keys { + if v, ok := s.Load(key); ok { + out[key] = v.(T) + } + } + return out, nil +} + +func (s *SyncMap[T]) SetMany(_ context.Context, values map[string]T) error { + for key, value := range values { + s.Store(key, value) + } + return nil +} + +func (s *SyncMap[T]) DelMany(_ context.Context, keys []string) error { + for _, key := range keys { + s.Delete(key) + } + return nil +} diff --git a/types.go b/types.go index 11d4efc..a05699d 100644 --- a/types.go +++ b/types.go @@ -31,3 +31,25 @@ type UpstreamFunc[T any] func(ctx context.Context, key string) (T, error) func (f UpstreamFunc[T]) Get(ctx context.Context, key string) (T, error) { return f(ctx, key) } + +// BatchUpstream is an optional interface for an Upstream (or Cache) that can +// retrieve many keys in one call. Client.GetMany uses it when available and +// falls back to calling Get per key otherwise. +// +// Keys absent from the returned map do not exist (the batch form of +// ErrKeyNotFound). A non-nil error fails the whole batch, unless it is a +// *BatchError, which fails only the keys it lists while the map still carries +// the rest. +type BatchUpstream[T any] interface { + GetMany(ctx context.Context, keys []string) (map[string]T, error) +} + +// BatchCache is an optional interface for a Cache that can read and write many +// keys in one call. Client.GetMany uses it for the backend and the not-found +// cache when available, and falls back to Get/Set/Del per key otherwise. +type BatchCache[T any] interface { + Cache[T] + BatchUpstream[T] + SetMany(ctx context.Context, values map[string]T) error + DelMany(ctx context.Context, keys []string) error +} From 0e05e032813eecd4d2de6432b9602b543d8ad9ca Mon Sep 17 00:00:00 2001 From: molon <3739161+molon@users.noreply.github.com> Date: Wed, 7 Oct 2026 02:55:03 +0800 Subject: [PATCH 02/40] test: fix data races in stale-refresh tests TestClientStaleHandling, TestNotFoundCacheStale and TestEntryWithClient counted upstream calls in a plain int written by the background refresh goroutine and waited for that refresh with a sleep, so they failed under -race on main too. Count with atomic.Int64 and wait until no background refresh is in flight before reading its result or closing the backend. Test-only; no library change. --- client_test.go | 55 ++++++++++++++++++++++++++++++++------------------ entry_test.go | 13 ++++++------ 2 files changed, 42 insertions(+), 26 deletions(-) diff --git a/client_test.go b/client_test.go index b163c63..03f9162 100644 --- a/client_test.go +++ b/client_test.go @@ -5,6 +5,7 @@ import ( "fmt" "log/slog" "strings" + "sync/atomic" "testing" "time" @@ -71,11 +72,11 @@ func TestClientStaleHandling(t *testing.T) { } backend := newRistrettoCache[*testValue](t) - fetchCount := 0 + var fetchCount atomic.Int64 upstream := UpstreamFunc[*testValue](func(ctx context.Context, key string) (*testValue, error) { - fetchCount++ - return &testValue{Data: fmt.Sprintf("fetch-%d", fetchCount), Timestamp: NowFunc()}, nil + n := fetchCount.Add(1) + return &testValue{Data: fmt.Sprintf("fetch-%d", n), Timestamp: NowFunc()}, nil }) checkStale := func(v *testValue) State { @@ -90,7 +91,7 @@ func TestClientStaleHandling(t *testing.T) { } t.Run("without serve stale", func(t *testing.T) { - fetchCount = 0 + fetchCount.Store(0) cli := NewClient(backend, upstream, WithStale(checkStale)) @@ -106,7 +107,7 @@ func TestClientStaleHandling(t *testing.T) { }) t.Run("with serve stale", func(t *testing.T) { - fetchCount = 0 + fetchCount.Store(0) err := backend.Del(ctx, "key2") require.NoError(t, err) @@ -118,7 +119,7 @@ func TestClientStaleHandling(t *testing.T) { value, err := cli.Get(ctx, "key2") require.NoError(t, err) assert.Equal(t, "fetch-1", value.Data) - assert.Equal(t, 1, fetchCount) + assert.Equal(t, int64(1), fetchCount.Load()) clock.Advance(60 * time.Millisecond) @@ -126,8 +127,8 @@ func TestClientStaleHandling(t *testing.T) { require.NoError(t, err) assert.Equal(t, "fetch-1", value.Data, "should serve stale value") - time.Sleep(10 * time.Millisecond) - assert.Equal(t, 2, fetchCount, "async refresh should have completed") + waitAsyncRefreshDone(t, cli) + assert.Equal(t, int64(2), fetchCount.Load(), "async refresh should have completed") clock.Advance(60 * time.Millisecond) @@ -135,15 +136,15 @@ func TestClientStaleHandling(t *testing.T) { require.NoError(t, err) assert.Equal(t, "fetch-2", value.Data, "should serve new stale value after async refresh") - time.Sleep(10 * time.Millisecond) - assert.Equal(t, 3, fetchCount, "second async refresh should have completed") + waitAsyncRefreshDone(t, cli) + assert.Equal(t, int64(3), fetchCount.Load(), "second async refresh should have completed") clock.Advance(200 * time.Millisecond) value, err = cli.Get(ctx, "key2") require.NoError(t, err) assert.Equal(t, "fetch-4", value.Data, "should refetch when rotten") - assert.Equal(t, 4, fetchCount) + assert.Equal(t, int64(4), fetchCount.Load()) }) } @@ -594,9 +595,9 @@ func TestNotFoundCacheStale(t *testing.T) { backend := newRistrettoCache[string](t) notFoundCache := newRistrettoCache[time.Time](t) - fetchCount := 0 + var fetchCount atomic.Int64 upstream := UpstreamFunc[string](func(ctx context.Context, key string) (string, error) { - fetchCount++ + fetchCount.Add(1) if key == "not-exist" { return "", &ErrKeyNotFound{} } @@ -613,7 +614,7 @@ func TestNotFoundCacheStale(t *testing.T) { var e *ErrKeyNotFound assert.True(t, errors.As(err, &e)) assert.False(t, e.Cached, "first fetch should not be cached") - assert.Equal(t, 1, fetchCount) + assert.Equal(t, int64(1), fetchCount.Load()) }) t.Run("second fetch serves from cache", func(t *testing.T) { @@ -622,7 +623,7 @@ func TestNotFoundCacheStale(t *testing.T) { assert.True(t, errors.As(err, &e)) assert.True(t, e.Cached, "second fetch should be from cache") assert.Equal(t, StateFresh, e.CacheState) - assert.Equal(t, 1, fetchCount, "should not refetch") + assert.Equal(t, int64(1), fetchCount.Load(), "should not refetch") }) t.Run("serve stale not found", func(t *testing.T) { @@ -634,11 +635,10 @@ func TestNotFoundCacheStale(t *testing.T) { assert.True(t, e.Cached) assert.Equal(t, StateStale, e.CacheState) // Should still be 1 fetch (serving stale, async refresh will happen) - assert.Equal(t, 1, fetchCount) + assert.Equal(t, int64(1), fetchCount.Load()) - // Wait a bit for async refresh to complete - time.Sleep(50 * time.Millisecond) - assert.Equal(t, 2, fetchCount, "async refresh should have happened") + waitAsyncRefreshDone(t, cli) + assert.Equal(t, int64(2), fetchCount.Load(), "async refresh should have happened") }) t.Run("rotten triggers immediate fetch", func(t *testing.T) { @@ -649,7 +649,7 @@ func TestNotFoundCacheStale(t *testing.T) { assert.True(t, errors.As(err, &e)) // After refetch, error comes from upstream (not cached) assert.False(t, e.Cached, "rotten refetch returns fresh upstream error") - assert.Equal(t, 3, fetchCount, "should refetch immediately when rotten") + assert.Equal(t, int64(3), fetchCount.Load(), "should refetch immediately when rotten") }) } @@ -860,3 +860,18 @@ func TestSetDelWithUpstreamCache(t *testing.T) { assert.NoError(t, err) }) } + +// waitAsyncRefreshDone waits until no serve-stale background refresh is in +// flight, so a test can read what the refresh wrote and close the backend +// without racing it. +func waitAsyncRefreshDone[T any](t *testing.T, cli *Client[T]) { + t.Helper() + require.Eventually(t, func() bool { + idle := true + cli.asyncRefreshing.Range(func(any, any) bool { + idle = false + return false + }) + return idle + }, time.Second, time.Millisecond, "background refresh should finish") +} diff --git a/entry_test.go b/entry_test.go index 939c659..d86a49d 100644 --- a/entry_test.go +++ b/entry_test.go @@ -2,6 +2,7 @@ package cachex import ( "context" + "sync/atomic" "testing" "time" @@ -176,9 +177,9 @@ func TestEntryWithClient(t *testing.T) { defer func() { _ = cache.Close() }() // Mock upstream data source - fetchCount := 0 + var fetchCount atomic.Int64 upstream := UpstreamFunc[*Entry[string]](func(ctx context.Context, key string) (*Entry[string], error) { - fetchCount++ + fetchCount.Add(1) return &Entry[string]{ Data: "value-" + key, CachedAt: NowFunc(), @@ -199,13 +200,13 @@ func TestEntryWithClient(t *testing.T) { entry1, err := client.Get(ctx, "test-key") assert.NoError(t, err) assert.Equal(t, "value-test-key", entry1.Data) - assert.Equal(t, 1, fetchCount) + assert.Equal(t, int64(1), fetchCount.Load()) // Second call: cache hit (fresh) entry2, err := client.Get(ctx, "test-key") assert.NoError(t, err) assert.Equal(t, "value-test-key", entry2.Data) - assert.Equal(t, 1, fetchCount) // No additional fetch + assert.Equal(t, int64(1), fetchCount.Load()) // No additional fetch // Wait for data to become stale time.Sleep(150 * time.Millisecond) @@ -217,12 +218,12 @@ func TestEntryWithClient(t *testing.T) { // fetchCount might be 1 or 2 depending on async refresh timing // Wait for async refresh to complete - time.Sleep(100 * time.Millisecond) + waitAsyncRefreshDone(t, client) // Fourth call: should have fresh data again entry4, err := client.Get(ctx, "test-key") assert.NoError(t, err) assert.Equal(t, "value-test-key", entry4.Data) - assert.GreaterOrEqual(t, fetchCount, 2) // At least 2 fetches (initial + refresh) + assert.GreaterOrEqual(t, fetchCount.Load(), int64(2)) // At least 2 fetches (initial + refresh) }) } From e0339b7593a51d5cb9c25f73d5073688e2d50627 Mon Sep 17 00:00:00 2001 From: molon <3739161+molon@users.noreply.github.com> Date: Wed, 7 Oct 2026 02:59:52 +0800 Subject: [PATCH 03/40] fix: match x/sync/singleflight on Goexit and harden batch backends Review fixes for GetMany: - flightGroup: when the upstream calls runtime.Goexit, release the claim without publishing, as x/sync/singleflight does. Before, the claim was never released and every later Get of that key hung until its ctx. GetMany's batch fetch does the same; its per-key fallback reports the key as failed instead of yielding a zero value. - get_compat_test.go pins the observable single-key behavior (coalescing, fetch-concurrency slots, panic and error propagation, fetch timeout, caller cancellation, test hook counts, double-check, not-found cache, serve-stale, write propagation). It uses only the pre-GetMany API and passes unchanged against the x/sync/singleflight implementation on main. - GetMany treats a backend or not-found cache that answers a whole batch with ErrKeyNotFound as a miss instead of a final not-found. - RedisCache.GetMany reads each pipelined command's own error, so one failing key (e.g. WRONGTYPE) no longer fails the whole batch. - GORMCache batch methods chunk to 1000 keys per statement, staying under the bound parameter limits of SQLite and PostgreSQL. --- README.md | 2 +- README_ZH.md | 2 +- batch.go | 36 +++- batch_test.go | 93 +++++++++ client.go | 9 + get_compat_test.go | 481 +++++++++++++++++++++++++++++++++++++++++++++ gorm.go | 44 +++-- redis.go | 8 +- 8 files changed, 647 insertions(+), 28 deletions(-) create mode 100644 get_compat_test.go diff --git a/README.md b/README.md index 68c264b..ef9f3d6 100644 --- a/README.md +++ b/README.md @@ -395,7 +395,7 @@ if errors.As(err, &batchErr) { // products is usable either way ``` -Built-in backends implement `BatchCache[T]`: `RistrettoCache`, `SyncMap`, `RedisCache` (one pipeline of `GET`/`SET`/`DEL`, which also works on Redis Cluster) and `GORMCache` (`WHERE key IN (...)` and one multi-row upsert). +Built-in backends implement `BatchCache[T]`: `RistrettoCache`, `SyncMap`, `RedisCache` (one pipeline of `GET`/`SET`/`DEL`, which also works on Redis Cluster) and `GORMCache` (`WHERE key IN (...)` and multi-row upserts, 1000 keys per statement to stay under the bound parameter limits). Fetching 100 missing keys through an upstream that costs 1ms per call (`BenchmarkGetManyVsGet`): diff --git a/README_ZH.md b/README_ZH.md index 4417750..f4ade6f 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -394,7 +394,7 @@ if errors.As(err, &batchErr) { // 不管有没有 err,products 都能用 ``` -内置后端都实现了 `BatchCache[T]`:`RistrettoCache`、`SyncMap`、`RedisCache`(一个 `GET`/`SET`/`DEL` 的 pipeline,Redis Cluster 下也能用)和 `GORMCache`(`WHERE key IN (...)` 和一条多行 upsert)。 +内置后端都实现了 `BatchCache[T]`:`RistrettoCache`、`SyncMap`、`RedisCache`(一个 `GET`/`SET`/`DEL` 的 pipeline,Redis Cluster 下也能用)和 `GORMCache`(`WHERE key IN (...)` 和多行 upsert,每条语句 1000 个 key,不会超出数据库的绑定参数上限)。 上游每次调用耗时 1ms,取 100 个全未命中的 key(`BenchmarkGetManyVsGet`): diff --git a/batch.go b/batch.go index 393d40c..62a9f64 100644 --- a/batch.go +++ b/batch.go @@ -47,13 +47,20 @@ func (g *flightGroup[T]) claim(sfKey string) (*flight[T], bool) { // sees the result and comes back starts a new flight (where double-check // finds the value this flight wrote) instead of joining a finished one. func (g *flightGroup[T]) finish(sfKey string, f *flight[T], value T, err error) { - g.mu.Lock() - delete(g.flights, sfKey) - g.mu.Unlock() + g.forget(sfKey, f) f.value, f.err = value, err close(f.done) } +// forget releases the claim without publishing a result. +func (g *flightGroup[T]) forget(sfKey string, f *flight[T]) { + g.mu.Lock() + defer g.mu.Unlock() + if g.flights[sfKey] == f { + delete(g.flights, sfKey) + } +} + type result[T any] struct { value T err error @@ -82,6 +89,9 @@ type result[T any] struct { // map still holds every key that succeeded and the error is a *BatchError // listing the failed keys. // +// As with Get, an upstream must not call back into the same Client for a key +// it is being asked for: that key is claimed by the caller and waits for itself. +// // Client implements BatchUpstream through GetMany, so in a layered setup // (memory -> Redis/DB -> source) a batch reaches the bottom upstream as one call. func (c *Client[T]) GetMany(ctx context.Context, keys []string) (map[string]T, error) { @@ -152,7 +162,7 @@ func (c *Client[T]) lookupMany(ctx context.Context, keys []string, doubleCheck b values, err := getMany(ctx, c.backend, keys) var missing []int for i, key := range keys { - if kerr := errForKey(err, key); kerr != nil { + if kerr := errForKey(err, key); kerr != nil && !IsErrKeyNotFound(kerr) { res[i].err = errors.Wrapf(kerr, "get from backend failed for key: %s", key) continue } @@ -198,7 +208,7 @@ func (c *Client[T]) lookupMany(ctx context.Context, keys []string, doubleCheck b cachedAts, err := getMany(ctx, c.notFoundCache, missingKeys) for _, i := range missing { key := keys[i] - if kerr := errForKey(err, key); kerr != nil { + if kerr := errForKey(err, key); kerr != nil && !IsErrKeyNotFound(kerr) { res[i].err = errors.Wrapf(kerr, "get from notFoundCache failed for key: %s", key) continue } @@ -263,8 +273,18 @@ func (c *Client[T]) fetchMany(ctx context.Context, keys, sfKeys []string) []resu // what is still missing, then finish every flight. func (c *Client[T]) fetchClaimedMany(ctx context.Context, keys, sfKeys []string, flights []*flight[T]) { results := make([]result[T], len(keys)) + returned := false defer func() { - if r := recover(); r != nil { + r := recover() + if r == nil && !returned { + // runtime.Goexit in the upstream: release the keys without + // publishing, like Get; waiters wait for their ctx. + for i, f := range flights { + c.flights.forget(sfKeys[i], f) + } + return + } + if r != nil { c.logger.ErrorContext(ctx, "panic during upstream fetch", "keys", keys, "panic", r, @@ -302,6 +322,7 @@ func (c *Client[T]) fetchClaimedMany(ctx context.Context, keys, sfKeys []string, } } if len(pending) == 0 { + returned = true return } @@ -312,6 +333,7 @@ func (c *Client[T]) fetchClaimedMany(ctx context.Context, keys, sfKeys []string, for j, r := range c.doFetchMany(fetchCtx, pendingKeys) { results[pending[j]] = r } + returned = true } // doFetchMany is the batch form of doFetch: fetch from upstream, then write @@ -335,6 +357,8 @@ func (c *Client[T]) doFetchMany(ctx context.Context, keys []string) []result[T] // upstreams without batch support get hammered by large batches. var wg sync.WaitGroup for i, key := range keys { + // overwritten on return; stays if the upstream calls runtime.Goexit + results[i].err = errors.Errorf("upstream fetch exited without returning for key: %s", key) wg.Go(func() { results[i] = c.getFromUpstream(ctx, key) }) diff --git a/batch_test.go b/batch_test.go index 53aed41..3a87224 100644 --- a/batch_test.go +++ b/batch_test.go @@ -4,6 +4,7 @@ import ( "context" "fmt" "maps" + "runtime" "slices" "sync" "sync/atomic" @@ -604,3 +605,95 @@ func BenchmarkGetManyVsGet(b *testing.B) { b.ReportMetric(float64(calls.Load())/float64(b.N), "upstream-calls/op") }) } + +func TestClientGetManyUpstreamGoexit(t *testing.T) { + t.Run("batch upstream: the claims are released like Get", func(t *testing.T) { + var calls atomic.Int64 + up := batchUpstreamFunc[string](func(_ context.Context, keys []string) (map[string]string, error) { + if calls.Add(1) == 1 { + runtime.Goexit() + } + return map[string]string{"a": "1"}, nil + }) + cli := NewClient(NewSyncMap[string](), up) + + ctx, cancel := context.WithTimeout(context.Background(), 50*time.Millisecond) + defer cancel() + _, err := cli.GetMany(ctx, []string{"a"}) + assert.ErrorIs(t, err, context.DeadlineExceeded) + + ctx2, cancel2 := context.WithTimeout(context.Background(), time.Second) + defer cancel2() + got, err := cli.GetMany(ctx2, []string{"a"}) + require.NoError(t, err, "the next call starts a new fetch") + assert.Equal(t, map[string]string{"a": "1"}, got) + }) + + t.Run("per-key upstream: the key fails instead of yielding a zero value", func(t *testing.T) { + backend := NewSyncMap[string]() + cli := NewClient(backend, UpstreamFunc[string](func(_ context.Context, key string) (string, error) { + if key == "bad" { + runtime.Goexit() + } + return "v-" + key, nil + })) + + got, err := cli.GetMany(context.Background(), []string{"a", "bad"}) + assert.Equal(t, map[string]string{"a": "v-a"}, got) + var be *BatchError + require.ErrorAs(t, err, &be) + assert.Contains(t, be.Errors, "bad") + _, err = backend.Get(context.Background(), "bad") + assert.True(t, IsErrKeyNotFound(err), "nothing is written for the key") + }) +} + +// notFoundBatchBackend answers a whole GetMany with ErrKeyNotFound. +type notFoundBatchBackend struct{ *SyncMap[string] } + +func (notFoundBatchBackend) GetMany(context.Context, []string) (map[string]string, error) { + return nil, &ErrKeyNotFound{} +} + +func TestClientGetManyBackendBatchNotFoundIsAMiss(t *testing.T) { + cli := NewClient[string](notFoundBatchBackend{NewSyncMap[string]()}, &batchUpstream{data: map[string]string{"a": "1"}}) + got, err := cli.GetMany(context.Background(), []string{"a"}) + require.NoError(t, err) + assert.Equal(t, map[string]string{"a": "1"}, got, "a backend that says not-found for the batch is a miss, so the key is fetched") +} + +func TestRedisCacheGetManyPerKeyErrors(t *testing.T) { + ctx := context.Background() + cache, mr := newRedisCache[string](t) + _, err := mr.Lpush("a-list", "x") // GET on a list fails with WRONGTYPE + require.NoError(t, err) + require.NoError(t, mr.Set("b", "2")) + + got, err := cache.GetMany(ctx, []string{"a-list", "b", "missing"}) + assert.Equal(t, map[string]string{"b": "2"}, got, "one failing command does not fail the batch") + var be *BatchError + require.ErrorAs(t, err, &be) + assert.Equal(t, []string{"a-list"}, slices.Collect(maps.Keys(be.Errors))) +} + +func TestGORMCacheBatchLargerThanBindLimit(t *testing.T) { + ctx := context.Background() + cache, _ := newGORMCache[string](t, "batch_large") + const n = 40000 // above SQLite's 32766 bound parameters per statement + values := make(map[string]string, n) + keys := make([]string, 0, n) + for i := range n { + k := fmt.Sprintf("k%d", i) + values[k] = "v" + keys = append(keys, k) + } + + require.NoError(t, cache.SetMany(ctx, values)) + got, err := cache.GetMany(ctx, keys) + require.NoError(t, err) + assert.Len(t, got, n) + require.NoError(t, cache.DelMany(ctx, keys)) + got, err = cache.GetMany(ctx, keys) + require.NoError(t, err) + assert.Empty(t, got) +} diff --git a/client.go b/client.go index 59606fb..4f09f99 100644 --- a/client.go +++ b/client.go @@ -267,7 +267,16 @@ func (c *Client[T]) fetchFromUpstreamWithSFKey(ctx context.Context, key string, f, leader := c.flights.claim(sfKey) if leader { go func() { + returned := false + defer func() { + if !returned { + // runtime.Goexit in the upstream: release the key without + // publishing, like x/sync/singleflight; waiters wait for their ctx. + c.flights.forget(sfKey, f) + } + }() value, err := c.fetchClaimed(ctx, key) + returned = true c.flights.finish(sfKey, f, value, err) }() } diff --git a/get_compat_test.go b/get_compat_test.go new file mode 100644 index 0000000..222f00d --- /dev/null +++ b/get_compat_test.go @@ -0,0 +1,481 @@ +package cachex + +import ( + "bytes" + "context" + "errors" + "log/slog" + "runtime" + "sync" + "sync/atomic" + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +// The tests in this file pin the observable behavior of the single-key path +// (Get/Set/Del, singleflight, fetch timeout, panics, ctx cancellation, test +// hooks, double-check, not-found cache, serve-stale). They use only the API +// that existed before GetMany and pass unchanged against the +// x/sync/singleflight implementation, so any drift in the single-key path +// shows up here. + +// hookCounts counts every test hook call of one client. +type hookCounts struct { + before, start, end atomic.Int64 +} + +func (h *hookCounts) install(c interface{ setHooks(*testHooks) }, before func(ctx context.Context, key string)) { + c.setHooks(&testHooks{ + beforeSingleflightStart: func(ctx context.Context, key string) { + h.before.Add(1) + if before != nil { + before(ctx, key) + } + }, + afterSingleflightStart: func(context.Context, string) { h.start.Add(1) }, + afterSingleflightEnd: func(context.Context, string) { h.end.Add(1) }, + }) +} + +func (c *Client[T]) setHooks(h *testHooks) { c.testHooks = h } + +// gate is an upstream that blocks every call until released. +type gate struct { + calls atomic.Int64 + entered chan struct{} + release chan struct{} +} + +func newGate() *gate { + return &gate{entered: make(chan struct{}, 1000), release: make(chan struct{})} +} + +func (g *gate) upstream(fn func(ctx context.Context, key string) (string, error)) UpstreamFunc[string] { + return func(ctx context.Context, key string) (string, error) { + g.calls.Add(1) + g.entered <- struct{}{} + <-g.release + return fn(ctx, key) + } +} + +func getConcurrently(ctx context.Context, cli *Client[string], key string, n int) ([]string, []error) { + values := make([]string, n) + errs := make([]error, n) + var wg sync.WaitGroup + for i := range n { + wg.Add(1) + go func() { + defer wg.Done() + values[i], errs[i] = cli.Get(ctx, key) + }() + } + wg.Wait() + return values, errs +} + +func TestGetCompatConcurrentMissesCoalesce(t *testing.T) { + ctx := context.Background() + g := newGate() + cli := NewClient(NewSyncMap[string](), g.upstream(func(_ context.Context, key string) (string, error) { + return "v-" + key, nil + })) + var hooks hookCounts + hooks.install(cli, nil) + + go func() { + <-g.entered + require.Eventually(t, func() bool { return hooks.before.Load() == 20 }, time.Second, time.Millisecond) + time.Sleep(50 * time.Millisecond) // let every caller join the flight + close(g.release) + }() + values, errs := getConcurrently(ctx, cli, "k", 20) + + for i := range values { + require.NoError(t, errs[i]) + assert.Equal(t, "v-k", values[i]) + } + assert.Equal(t, int64(1), g.calls.Load(), "20 concurrent misses fetch once") + assert.Equal(t, int64(20), hooks.before.Load(), "beforeSingleflightStart runs once per caller") + assert.Equal(t, int64(1), hooks.start.Load(), "afterSingleflightStart runs once per fetch") + assert.Equal(t, int64(20), hooks.end.Load(), "afterSingleflightEnd runs once per caller that got the result") + + v, err := cli.Get(ctx, "k") + require.NoError(t, err) + assert.Equal(t, "v-k", v) + assert.Equal(t, int64(1), g.calls.Load(), "the fetched value was written to the backend") + assert.Equal(t, int64(20), hooks.before.Load(), "a hit does not reach the fetch path") +} + +func TestGetCompatUpstreamErrorIsSharedAndNotCached(t *testing.T) { + ctx := context.Background() + g := newGate() + boom := errors.New("boom") + backend := NewSyncMap[string]() + cli := NewClient(backend, g.upstream(func(context.Context, string) (string, error) { return "", boom })) + + go func() { + <-g.entered + time.Sleep(50 * time.Millisecond) + close(g.release) + }() + _, errs := getConcurrently(ctx, cli, "k", 5) + for _, err := range errs { + require.Error(t, err) + assert.ErrorIs(t, err, boom) + assert.Equal(t, "get from upstream failed for key: k: boom", err.Error()) + } + assert.Equal(t, int64(1), g.calls.Load()) + + _, err := backend.Get(ctx, "k") + assert.True(t, IsErrKeyNotFound(err), "an upstream error writes nothing") + + _, err = cli.Get(ctx, "k") + require.Error(t, err) + assert.Equal(t, int64(2), g.calls.Load(), "errors are not cached: the next Get fetches again") +} + +func TestGetCompatUpstreamPanic(t *testing.T) { + ctx := context.Background() + var logBuf bytes.Buffer + var calls atomic.Int64 + entered := make(chan struct{}, 10) + release := make(chan struct{}) + backend := NewSyncMap[string]() + cli := NewClient(backend, UpstreamFunc[string](func(context.Context, string) (string, error) { + if calls.Add(1) == 1 { + entered <- struct{}{} + <-release + panic("kaboom") + } + return "ok", nil + }), WithLogger[string](slog.New(slog.NewTextHandler(&logBuf, nil)))) + var hooks hookCounts + hooks.install(cli, nil) + + go func() { + <-entered + require.Eventually(t, func() bool { return hooks.before.Load() == 5 }, time.Second, time.Millisecond) + time.Sleep(50 * time.Millisecond) + close(release) + }() + _, errs := getConcurrently(ctx, cli, "k", 5) + for _, err := range errs { + require.Error(t, err) + assert.Equal(t, "panic during upstream fetch: kaboom", err.Error(), "every waiter gets the panic as an error") + } + assert.Equal(t, int64(5), hooks.end.Load()) + assert.Contains(t, logBuf.String(), `msg="panic during upstream fetch" key=k panic=kaboom stack=`) + + v, err := cli.Get(ctx, "k") + require.NoError(t, err) + assert.Equal(t, "ok", v, "the key is released after a panic") + assert.Equal(t, int64(2), calls.Load()) +} + +func TestGetCompatUpstreamGoexit(t *testing.T) { + var calls atomic.Int64 + cli := NewClient(NewSyncMap[string](), UpstreamFunc[string](func(context.Context, string) (string, error) { + if calls.Add(1) == 1 { + runtime.Goexit() + } + return "ok", nil + })) + + ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond) + defer cancel() + _, err := cli.Get(ctx, "k") + require.Error(t, err) + assert.ErrorIs(t, err, context.DeadlineExceeded, "a fetch that exits without returning publishes nothing; waiters wait for their ctx") + assert.Equal(t, "context cancelled during fetch for key: k: context deadline exceeded", err.Error()) + + ctx2, cancel2 := context.WithTimeout(context.Background(), time.Second) + defer cancel2() + v, err := cli.Get(ctx2, "k") + require.NoError(t, err, "the key is released, so the next Get starts a new fetch") + assert.Equal(t, "ok", v) + assert.Equal(t, int64(2), calls.Load()) +} + +func TestGetCompatFetchTimeout(t *testing.T) { + ctx := context.Background() + var upstreamCtxErr atomic.Value + cli := NewClient(NewSyncMap[string](), UpstreamFunc[string](func(ctx context.Context, _ string) (string, error) { + <-ctx.Done() + upstreamCtxErr.Store(ctx.Err()) + return "", ctx.Err() + }), WithFetchTimeout[string](30*time.Millisecond)) + + start := time.Now() + _, err := cli.Get(ctx, "k") + require.Error(t, err) + assert.Less(t, time.Since(start), time.Second) + assert.ErrorIs(t, err, context.DeadlineExceeded) + assert.Equal(t, "get from upstream failed for key: k: context deadline exceeded", err.Error()) + assert.Equal(t, context.DeadlineExceeded, upstreamCtxErr.Load()) +} + +func TestGetCompatCallerCancelLeavesFetchRunning(t *testing.T) { + g := newGate() + var upstreamCtxErr atomic.Value + backend := NewSyncMap[string]() + cli := NewClient(backend, g.upstream(func(ctx context.Context, key string) (string, error) { + upstreamCtxErr.Store(errors.New("none")) + if ctx.Err() != nil { + upstreamCtxErr.Store(ctx.Err()) + } + return "v-" + key, nil + })) + var hooks hookCounts + hooks.install(cli, nil) + + ctx, cancel := context.WithCancel(context.Background()) + go func() { + <-g.entered + cancel() + }() + _, err := cli.Get(ctx, "k") + require.Error(t, err) + assert.ErrorIs(t, err, context.Canceled) + assert.Equal(t, "context cancelled during fetch for key: k: context canceled", err.Error()) + assert.Equal(t, int64(0), hooks.end.Load(), "afterSingleflightEnd only runs when the result is received") + + close(g.release) + require.Eventually(t, func() bool { + v, err := backend.Get(context.Background(), "k") + return err == nil && v == "v-k" + }, time.Second, time.Millisecond, "the fetch outlives the cancelled caller and fills the backend") + assert.Equal(t, "none", upstreamCtxErr.Load().(error).Error(), "the upstream ctx is detached from the caller's cancellation") + + v, err := cli.Get(context.Background(), "k") + require.NoError(t, err) + assert.Equal(t, "v-k", v) + assert.Equal(t, int64(1), g.calls.Load()) +} + +func TestGetCompatFetchConcurrencySlots(t *testing.T) { + ctx := context.Background() + g := newGate() + cli := NewClient(NewSyncMap[string](), g.upstream(func(_ context.Context, key string) (string, error) { + return "v-" + key, nil + }), WithFetchConcurrency[string](3)) + var hooks hookCounts + hooks.install(cli, nil) + + go func() { + <-g.entered + require.Eventually(t, func() bool { return hooks.before.Load() == 60 }, time.Second, time.Millisecond) + time.Sleep(50 * time.Millisecond) + close(g.release) + }() + values, errs := getConcurrently(ctx, cli, "k", 60) + for i := range values { + require.NoError(t, errs[i]) + assert.Equal(t, "v-k", values[i]) + } + assert.GreaterOrEqual(t, g.calls.Load(), int64(1)) + assert.LessOrEqual(t, g.calls.Load(), int64(3), "at most one fetch per slot") + assert.Equal(t, g.calls.Load(), hooks.start.Load(), "one afterSingleflightStart per slot that fetched") +} + +func TestGetCompatDoubleCheckRaceWindow(t *testing.T) { + for _, tc := range []struct { + name string + mode DoubleCheckMode + calls int64 + }{ + {"enabled: the late request reuses the value just written", DoubleCheckEnabled, 1}, + {"disabled: the late request fetches again", DoubleCheckDisabled, 2}, + } { + t.Run(tc.name, func(t *testing.T) { + ctx := context.Background() + var calls atomic.Int64 + cli := NewClient(NewSyncMap[string](), UpstreamFunc[string](func(_ context.Context, key string) (string, error) { + calls.Add(1) + return "v-" + key, nil + }), WithDoubleCheck[string](tc.mode)) + + lateMissed := make(chan struct{}) + earlyDone := make(chan struct{}) + var first atomic.Bool + var hooks hookCounts + hooks.install(cli, func(context.Context, string) { + if first.CompareAndSwap(false, true) { + close(lateMissed) + <-earlyDone // the late request missed the cache, then waits out the early one + } + }) + + var late string + var lateErr error + done := make(chan struct{}) + go func() { + defer close(done) + late, lateErr = cli.Get(ctx, "k") + }() + <-lateMissed + early, err := cli.Get(ctx, "k") + require.NoError(t, err) + close(earlyDone) + <-done + + require.NoError(t, lateErr) + assert.Equal(t, "v-k", early) + assert.Equal(t, "v-k", late) + assert.Equal(t, tc.calls, calls.Load()) + assert.Equal(t, int64(2), hooks.start.Load(), "two separate flights either way") + }) + } +} + +func TestGetCompatNotFoundCache(t *testing.T) { + ctx := context.Background() + clock := NewMockClock(time.Now()) + defer clock.Install()() + + var calls atomic.Int64 + cli := NewClient(NewSyncMap[string](), UpstreamFunc[string](func(context.Context, string) (string, error) { + calls.Add(1) + return "", &ErrKeyNotFound{} + }), + NotFoundWithTTL[string](NewSyncMap[time.Time](), 100*time.Millisecond, 500*time.Millisecond), + WithServeStale[string](true), + ) + + type step struct { + advance time.Duration + msg string + cached bool + state State + calls int64 + } + for i, s := range []step{ + {0, "get from upstream failed for key: nf: key not found", false, StateFresh, 1}, + {0, "key not found in cache for key: nf: key not found (cached, fresh)", true, StateFresh, 1}, + {150 * time.Millisecond, "key not found in cache for key: nf: key not found (cached, stale)", true, StateStale, 1}, + {600 * time.Millisecond, "get from upstream failed for key: nf: key not found", false, StateFresh, 3}, + } { + clock.Advance(s.advance) + _, err := cli.Get(ctx, "nf") + var e *ErrKeyNotFound + require.ErrorAs(t, err, &e, "step %d", i) + assert.Equal(t, s.msg, err.Error(), "step %d", i) + assert.Equal(t, s.cached, e.Cached, "step %d", i) + if s.cached { + assert.Equal(t, s.state, e.CacheState, "step %d", i) + } + waitAsyncRefreshDone(t, cli) + if i == 2 { + assert.Equal(t, int64(2), calls.Load(), "a stale not-found is served and refreshed in the background") + } else { + assert.Equal(t, s.calls, calls.Load(), "step %d", i) + } + } + + require.NoError(t, cli.Set(ctx, "nf", "now-exists")) + v, err := cli.Get(ctx, "nf") + require.NoError(t, err, "Set clears the cached not-found") + assert.Equal(t, "now-exists", v) + + require.NoError(t, cli.Del(ctx, "nf")) + _, err = cli.Get(ctx, "nf") + var e *ErrKeyNotFound + require.ErrorAs(t, err, &e) + assert.True(t, e.Cached, "Del records a fresh not-found") + assert.Equal(t, int64(3), calls.Load()) +} + +func TestGetCompatServeStale(t *testing.T) { + ctx := context.Background() + clock := NewMockClock(time.Now()) + defer clock.Install()() + + var calls atomic.Int64 + refreshGate := make(chan struct{}) + cli := NewClient(NewSyncMap[*Entry[string]](), UpstreamFunc[*Entry[string]](func(context.Context, string) (*Entry[string], error) { + n := calls.Add(1) + if n == 2 { + <-refreshGate + } + return &Entry[string]{Data: map[int64]string{1: "one", 2: "two"}[n], CachedAt: NowFunc()}, nil + }), + EntryWithTTL[string](100*time.Millisecond, 500*time.Millisecond), + WithServeStale[*Entry[string]](true), + ) + + v, err := cli.Get(ctx, "k") + require.NoError(t, err) + assert.Equal(t, "one", v.Data) + + clock.Advance(150 * time.Millisecond) + var wg sync.WaitGroup + for range 20 { + wg.Go(func() { + v, err := cli.Get(ctx, "k") + assert.NoError(t, err) + assert.Equal(t, "one", v.Data, "stale value is served while refreshing") + }) + } + wg.Wait() + close(refreshGate) + waitAsyncRefreshDone(t, cli) + assert.Equal(t, int64(2), calls.Load(), "20 stale reads trigger one background refresh") + + v, err = cli.Get(ctx, "k") + require.NoError(t, err) + assert.Equal(t, "two", v.Data) + assert.Equal(t, int64(2), calls.Load()) +} + +// errBackend fails every Get. +type errBackend struct{ Cache[string] } + +func (errBackend) Get(context.Context, string) (string, error) { return "", errors.New("disk") } + +func TestGetCompatBackendError(t *testing.T) { + var calls atomic.Int64 + cli := NewClient[string](errBackend{NewSyncMap[string]()}, UpstreamFunc[string](func(context.Context, string) (string, error) { + calls.Add(1) + return "v", nil + })) + _, err := cli.Get(context.Background(), "k") + require.Error(t, err) + assert.Equal(t, "get from backend failed for key: k: disk", err.Error()) + assert.Equal(t, int64(0), calls.Load(), "a backend error does not fall through to the upstream") +} + +func TestGetCompatWritePropagation(t *testing.T) { + ctx := context.Background() + source := map[string]string{"k": "src"} + l2Backend := NewSyncMap[string]() + l2 := NewClient(l2Backend, UpstreamFunc[string](func(_ context.Context, key string) (string, error) { + if v, ok := source[key]; ok { + return v, nil + } + return "", &ErrKeyNotFound{} + })) + l1Backend := NewSyncMap[string]() + l1 := NewClient[string](l1Backend, l2) + + v, err := l1.Get(ctx, "k") + require.NoError(t, err) + assert.Equal(t, "src", v) + v, _ = l2Backend.Get(ctx, "k") + assert.Equal(t, "src", v, "a miss fills every layer on the way back") + + require.NoError(t, l1.Set(ctx, "k", "new")) + v, _ = l1Backend.Get(ctx, "k") + assert.Equal(t, "new", v) + v, _ = l2Backend.Get(ctx, "k") + assert.Equal(t, "new", v, "Set propagates to the cache layer below") + assert.Equal(t, "src", source["k"], "and stops at the data source") + + require.NoError(t, l1.Del(ctx, "k")) + _, err = l1Backend.Get(ctx, "k") + assert.True(t, IsErrKeyNotFound(err)) + _, err = l2Backend.Get(ctx, "k") + assert.True(t, IsErrKeyNotFound(err), "Del propagates to the cache layer below") +} diff --git a/gorm.go b/gorm.go index a4d8d93..a3fa529 100644 --- a/gorm.go +++ b/gorm.go @@ -4,6 +4,7 @@ import ( "cmp" "context" "encoding/json" + "slices" "strings" "time" @@ -147,12 +148,15 @@ func (g *GORMCache[T]) Del(ctx context.Context, key string) error { return nil } -// GetMany retrieves many values with one `WHERE key IN (...)` query. +// gormBatchSize bounds the keys per statement, keeping every batch statement +// well under the databases' bound parameter limits (32766 on SQLite, 65535 on +// PostgreSQL, 65535 on MySQL). +const gormBatchSize = 1000 + +// GetMany retrieves many values with `WHERE key IN (...)` queries of up to +// gormBatchSize keys each. // Missing keys are absent from the result; a value that fails to unmarshal is // reported in a *BatchError without hiding the others. -// -// ponytail: no chunking; very large batches can exceed the database's bound -// parameter limit (e.g. 32766 on SQLite, 65535 on PostgreSQL). func (g *GORMCache[T]) GetMany(ctx context.Context, keys []string) (map[string]T, error) { out := make(map[string]T, len(keys)) if len(keys) == 0 { @@ -166,11 +170,15 @@ func (g *GORMCache[T]) GetMany(ctx context.Context, keys []string) (map[string]T var entries []cacheEntry tx := cmp.Or(GetGORMTx(ctx), g.db) - if err := tx.WithContext(ctx). - Table(g.tableName). - Where("key IN ?", prefixed). - Find(&entries).Error; err != nil { - return nil, errors.Wrap(err, "failed to get cache entries") + for chunk := range slices.Chunk(prefixed, gormBatchSize) { + var found []cacheEntry + if err := tx.WithContext(ctx). + Table(g.tableName). + Where("key IN ?", chunk). + Find(&found).Error; err != nil { + return nil, errors.Wrap(err, "failed to get cache entries") + } + entries = append(entries, found...) } var keyErrs map[string]error @@ -192,7 +200,7 @@ func (g *GORMCache[T]) GetMany(ctx context.Context, keys []string) (map[string]T return out, nil } -// SetMany stores many values with one multi-row upsert (same bound parameter limit as GetMany) +// SetMany stores many values with multi-row upserts of up to gormBatchSize rows each func (g *GORMCache[T]) SetMany(ctx context.Context, values map[string]T) error { if len(values) == 0 { return nil @@ -214,13 +222,13 @@ func (g *GORMCache[T]) SetMany(ctx context.Context, values map[string]T) error { Columns: []clause.Column{{Name: "key"}}, UpdateAll: true, }). - Create(&entries).Error; err != nil { + CreateInBatches(&entries, gormBatchSize).Error; err != nil { return errors.Wrap(err, "failed to set cache entries") } return nil } -// DelMany removes many keys with one `WHERE key IN (...)` delete +// DelMany removes many keys with `WHERE key IN (...)` deletes of up to gormBatchSize keys each func (g *GORMCache[T]) DelMany(ctx context.Context, keys []string) error { if len(keys) == 0 { return nil @@ -232,11 +240,13 @@ func (g *GORMCache[T]) DelMany(ctx context.Context, keys []string) error { } tx := cmp.Or(GetGORMTx(ctx), g.db) - if err := tx.WithContext(ctx). - Table(g.tableName). - Where("key IN ?", prefixed). - Delete(nil).Error; err != nil { - return errors.Wrap(err, "failed to delete cache entries") + for chunk := range slices.Chunk(prefixed, gormBatchSize) { + if err := tx.WithContext(ctx). + Table(g.tableName). + Where("key IN ?", chunk). + Delete(nil).Error; err != nil { + return errors.Wrap(err, "failed to delete cache entries") + } } return nil } diff --git a/redis.go b/redis.go index 58ac570..6b7f8fa 100644 --- a/redis.go +++ b/redis.go @@ -172,9 +172,9 @@ func (r *RedisCache[T]) GetMany(ctx context.Context, keys []string) (map[string] for i, key := range keys { cmds[i] = pipe.Get(ctx, r.prefixedKey(key)) } - if _, err := pipe.Exec(ctx); err != nil && !errors.Is(err, redis.Nil) { - return nil, errors.Wrap(err, "failed to get cache entries") - } + // Exec reports only the first failed command; every command carries its own + // error (a connection failure is set on all of them), so read them per key. + _, _ = pipe.Exec(ctx) var keyErrs map[string]error for i, key := range keys { @@ -185,6 +185,8 @@ func (r *RedisCache[T]) GetMany(ctx context.Context, keys []string) (map[string] var value T if err == nil { value, err = r.decode(key, data) + } else { + err = r.handleRedisError(err, key) } if err != nil { if keyErrs == nil { From 350346fa81743bea9cfd06f086e17789e3405595 Mon Sep 17 00:00:00 2001 From: molon <3739161+molon@users.noreply.github.com> Date: Wed, 7 Oct 2026 03:04:28 +0800 Subject: [PATCH 04/40] fix: per-key failure handling in GetMany - Only an unwrapped *BatchError makes a batch error partial. A wrapped or joined one may sit next to an error that failed the whole batch; reading it as partial cached not-found entries for keys the upstream never answered. - A panic in the batch upstream fails only the keys still being fetched, not the ones the double-check already found. - The batch double-check reads with the request ctx, like Get. - Writing back key by key keeps going after one key fails, and RedisCache.SetMany writes the values it can encode, like Get per key. - A serve-stale batch refresh bounds its wait by fetchTimeout, so one fetch that never finishes cannot pin the other keys' refresh slots. --- README.md | 4 +- README_ZH.md | 2 +- batch.go | 49 +++++++++++++++-------- batch_test.go | 107 ++++++++++++++++++++++++++++++++++++++++++++++++++ redis.go | 14 +++++-- types.go | 4 +- 6 files changed, 155 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index ef9f3d6..94d386d 100644 --- a/README.md +++ b/README.md @@ -353,8 +353,8 @@ To let the upstream answer a batch in one call, implement `BatchUpstream[T]` on ```go type BatchUpstream[T any] interface { // Keys absent from the map do not exist (like ErrKeyNotFound for Get). - // A non-nil error fails the whole batch, unless it is a *cachex.BatchError, - // which fails only the keys it lists. + // A non-nil error fails the whole batch, unless it is a *cachex.BatchError + // returned as is (not wrapped), which fails only the keys it lists. GetMany(ctx context.Context, keys []string) (map[string]T, error) } diff --git a/README_ZH.md b/README_ZH.md index f4ade6f..d81e927 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -353,7 +353,7 @@ products, err := client.GetMany(ctx, []string{"p1", "p2", "p3"}) ```go type BatchUpstream[T any] interface { // map 里没有的 key 视为不存在(相当于 Get 的 ErrKeyNotFound)。 - // 返回非 nil error 表示整批失败;如果是 *cachex.BatchError,只有它列出的 key 失败。 + // 返回非 nil error 表示整批失败;如果是原样返回(没有再包一层)的 *cachex.BatchError,只有它列出的 key 失败。 GetMany(ctx context.Context, keys []string) (map[string]T, error) } diff --git a/batch.go b/batch.go index 62a9f64..d765936 100644 --- a/batch.go +++ b/batch.go @@ -2,6 +2,7 @@ package cachex import ( "context" + stderrors "errors" "runtime/debug" "sync" "time" @@ -273,6 +274,7 @@ func (c *Client[T]) fetchMany(ctx context.Context, keys, sfKeys []string) []resu // what is still missing, then finish every flight. func (c *Client[T]) fetchClaimedMany(ctx context.Context, keys, sfKeys []string, flights []*flight[T]) { results := make([]result[T], len(keys)) + var pending []int // keys still to fetch after the double-check; nil until it ran returned := false defer func() { r := recover() @@ -290,7 +292,14 @@ func (c *Client[T]) fetchClaimedMany(ctx context.Context, keys, sfKeys []string, "panic", r, "stack", string(debug.Stack())) err := errors.Errorf("panic during upstream fetch: %v", r) - for i := range results { + failed := pending + if failed == nil { + failed = make([]int, len(keys)) + for i := range failed { + failed[i] = i + } + } + for _, i := range failed { results[i] = result[T]{err: err} } } @@ -302,25 +311,27 @@ func (c *Client[T]) fetchClaimedMany(ctx context.Context, keys, sfKeys []string, fetchCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), c.fetchTimeout) defer cancel() - pending := make([]int, 0, len(keys)) + checked := make([]int, 0, len(keys)) if c.enableDoubleCheck { - for i, r := range c.lookupMany(fetchCtx, keys, true) { + // like Get, the double-check reads with the request ctx + for i, r := range c.lookupMany(ctx, keys, true) { switch { case r.fetch: - pending = append(pending, i) + checked = append(checked, i) case r.err == nil: results[i].value = r.value case isCachedFreshNotFound(r.err): results[i].err = r.err default: - pending = append(pending, i) // like Get: a failed double-check falls through to upstream + checked = append(checked, i) // like Get: a failed double-check falls through to upstream } } } else { for i := range keys { - pending = append(pending, i) + checked = append(checked, i) } } + pending = checked if len(pending) == 0 { returned = true return @@ -465,6 +476,10 @@ func (c *Client[T]) asyncRefreshMany(ctx context.Context, keys []string) { c.asyncRefreshing.Delete(sfKey) } }() + // Bound the wait: some keys may be fetched by other callers, and a fetch + // that never finishes (runtime.Goexit) must not pin the whole batch. + ctx, cancel := context.WithTimeout(ctx, c.fetchTimeout) + defer cancel() for i, r := range c.fetchMany(ctx, refreshKeys, sfKeys) { if r.err != nil && !IsErrKeyNotFound(r.err) { c.logger.ErrorContext(ctx, "async refresh failed", "key", refreshKeys[i], "error", r.err) @@ -496,35 +511,37 @@ func getMany[T any](ctx context.Context, from Upstream[T], keys []string) (map[s return out, nil } +// setMany writes many keys, in one call when cache implements BatchCache, +// otherwise key by key; like Get, one key failing does not stop the others. func setMany[T any](ctx context.Context, cache Cache[T], values map[string]T) error { if batch, ok := cache.(BatchCache[T]); ok { return batch.SetMany(ctx, values) } + var errs []error for key, value := range values { - if err := cache.Set(ctx, key, value); err != nil { - return err - } + errs = append(errs, cache.Set(ctx, key, value)) } - return nil + return stderrors.Join(errs...) } +// delMany is the delete counterpart of setMany. func delMany[T any](ctx context.Context, cache Cache[T], keys []string) error { if batch, ok := cache.(BatchCache[T]); ok { return batch.DelMany(ctx, keys) } + var errs []error for _, key := range keys { - if err := cache.Del(ctx, key); err != nil { - return err - } + errs = append(errs, cache.Del(ctx, key)) } - return nil + return stderrors.Join(errs...) } // errForKey returns the error a batch call reported for key: the key's own // entry if err is a *BatchError, otherwise err itself (the whole batch failed). +// Only an unwrapped *BatchError is partial: a wrapped or joined one may sit +// next to an error that failed the whole batch. func errForKey(err error, key string) error { - var batchErr *BatchError - if errors.As(err, &batchErr) { + if batchErr, ok := err.(*BatchError); ok { //nolint:errorlint // see above return batchErr.Errors[key] } return err diff --git a/batch_test.go b/batch_test.go index 3a87224..275902f 100644 --- a/batch_test.go +++ b/batch_test.go @@ -2,6 +2,7 @@ package cachex import ( "context" + stderrors "errors" "fmt" "maps" "runtime" @@ -697,3 +698,109 @@ func TestGORMCacheBatchLargerThanBindLimit(t *testing.T) { require.NoError(t, err) assert.Empty(t, got) } + +// missFirstBatch is a SyncMap whose first GetMany misses everything, as if +// the values were written right after it. +type missFirstBatch struct { + *SyncMap[string] + calls atomic.Int64 +} + +func (m *missFirstBatch) GetMany(ctx context.Context, keys []string) (map[string]string, error) { + if m.calls.Add(1) == 1 { + return map[string]string{}, nil + } + return m.SyncMap.GetMany(ctx, keys) +} + +// hookedCache is a plain Cache (no batch methods) whose Set/Del can be intercepted. +type hookedCache struct { + m *SyncMap[string] + beforeSet func(key, value string) error + beforeDel func(key string) error +} + +func newHookedCache() *hookedCache { return &hookedCache{m: NewSyncMap[string]()} } + +func (h *hookedCache) Get(ctx context.Context, key string) (string, error) { return h.m.Get(ctx, key) } + +func (h *hookedCache) Set(ctx context.Context, key, value string) error { + if h.beforeSet != nil { + if err := h.beforeSet(key, value); err != nil { + return err + } + } + return h.m.Set(ctx, key, value) +} + +func (h *hookedCache) Del(ctx context.Context, key string) error { + if h.beforeDel != nil { + if err := h.beforeDel(key); err != nil { + return err + } + } + return h.m.Del(ctx, key) +} + +func TestClientGetManyReviewFixes(t *testing.T) { + ctx := context.Background() + + t.Run("a whole-batch error that merely contains a BatchError fails every key", func(t *testing.T) { + notFound := NewSyncMap[time.Time]() + conn := errors.New("conn reset") + up := batchUpstreamFunc[string](func(context.Context, []string) (map[string]string, error) { + return nil, stderrors.Join(conn, &BatchError{Errors: map[string]error{"a": errors.New("x")}}) + }) + cli := NewClient(NewSyncMap[string](), up, NotFoundWithTTL[string](notFound, time.Hour, 0)) + + got, err := cli.GetMany(ctx, []string{"a", "b"}) + assert.Empty(t, got) + var be *BatchError + require.ErrorAs(t, err, &be) + assert.Len(t, be.Errors, 2, "b is a failure, not a not-found") + _, err = notFound.Get(ctx, "b") + assert.True(t, IsErrKeyNotFound(err), "no not-found is cached for a key the upstream never answered") + }) + + t.Run("a panic in the batch upstream keeps the keys the double-check found", func(t *testing.T) { + backend := &missFirstBatch{SyncMap: NewSyncMap[string]()} + require.NoError(t, backend.Set(ctx, "a", "1")) + up := batchUpstreamFunc[string](func(context.Context, []string) (map[string]string, error) { + panic("kaboom") + }) + cli := NewClient[string](backend, up, WithDoubleCheck[string](DoubleCheckEnabled)) + + got, err := cli.GetMany(ctx, []string{"a", "b"}) + assert.Equal(t, map[string]string{"a": "1"}, got, "the double-check found a before the upstream panicked") + var be *BatchError + require.ErrorAs(t, err, &be) + assert.Equal(t, []string{"b"}, slices.Collect(maps.Keys(be.Errors))) + }) + + t.Run("a per-key backend write failure does not skip the other keys", func(t *testing.T) { + backend := newHookedCache() + backend.beforeSet = func(key, _ string) error { + if key == "bad" { + return errors.New("too large") + } + return nil + } + up := &batchUpstream{data: map[string]string{"a": "1", "bad": "2", "c": "3"}} + cli := NewClient[string](backend, up) + got, err := cli.GetMany(ctx, []string{"a", "bad", "c"}) + require.NoError(t, err) + assert.Len(t, got, 3) + for _, k := range []string{"a", "c"} { + _, err := backend.Get(ctx, k) + assert.NoError(t, err, "%s is cached", k) + } + }) +} + +func TestRedisCacheSetManyEncodeErrorKeepsOthers(t *testing.T) { + ctx := context.Background() + cache, mr := newRedisCache[any](t) + err := cache.SetMany(ctx, map[string]any{"ok": 1, "bad": make(chan int)}) + require.Error(t, err) + assert.True(t, mr.Exists("ok"), "the encodable value is still written") +} diff --git a/redis.go b/redis.go index 6b7f8fa..ef26af9 100644 --- a/redis.go +++ b/redis.go @@ -4,6 +4,7 @@ import ( "context" "encoding" "encoding/json" + stderrors "errors" "time" "github.com/pkg/errors" @@ -209,18 +210,23 @@ func (r *RedisCache[T]) SetMany(ctx context.Context, values map[string]T) error return nil } + // A value that fails to encode is reported without holding back the others. + var encodeErrs []error pipe := r.client.Pipeline() for key, value := range values { data, err := r.encode(key, value) if err != nil { - return err + encodeErrs = append(encodeErrs, err) + continue } pipe.Set(ctx, r.prefixedKey(key), data, r.ttl) } - if _, err := pipe.Exec(ctx); err != nil { - return errors.Wrap(err, "failed to set cache entries") + if pipe.Len() > 0 { + if _, err := pipe.Exec(ctx); err != nil { + return errors.Wrap(err, "failed to set cache entries") + } } - return nil + return stderrors.Join(encodeErrs...) } // DelMany removes many keys in one round trip diff --git a/types.go b/types.go index a05699d..d0acc8c 100644 --- a/types.go +++ b/types.go @@ -38,8 +38,8 @@ func (f UpstreamFunc[T]) Get(ctx context.Context, key string) (T, error) { // // Keys absent from the returned map do not exist (the batch form of // ErrKeyNotFound). A non-nil error fails the whole batch, unless it is a -// *BatchError, which fails only the keys it lists while the map still carries -// the rest. +// *BatchError returned as is (not wrapped), which fails only the keys it lists +// while the map still carries the rest. type BatchUpstream[T any] interface { GetMany(ctx context.Context, keys []string) (map[string]T, error) } From c7dca4e319112dc03b6cc8d7a0333a631a96b94c Mon Sep 17 00:00:00 2001 From: molon <3739161+molon@users.noreply.github.com> Date: Thu, 8 Oct 2026 15:28:49 +0800 Subject: [PATCH 05/40] fix: bound GetMany's per-key fallback and tighten its error and timeout handling - WithGetManyConcurrency (default 16) bounds the concurrent upstream.Get calls one GetMany makes when the upstream has no batch support. Before, every missing key got its own goroutine and its own upstream call at once. - A whole-batch upstream error fails every key even when an ErrKeyNotFound sits in its chain (wrapped or joined). Before, such an error was read as "every key is missing" and cached as not-found. - The fetch timeout starts after the double-check, like Get, so a slow re-check no longer eats into the upstream's time. --- README.md | 3 +- README_ZH.md | 3 +- batch.go | 19 ++++++++---- batch_test.go | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++ client.go | 20 ++++++++++++- types.go | 3 +- 6 files changed, 118 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 94d386d..a0e4788 100644 --- a/README.md +++ b/README.md @@ -355,6 +355,7 @@ type BatchUpstream[T any] interface { // Keys absent from the map do not exist (like ErrKeyNotFound for Get). // A non-nil error fails the whole batch, unless it is a *cachex.BatchError // returned as is (not wrapped), which fails only the keys it lists. + // A whole-batch error fails every key, even if it wraps an ErrKeyNotFound. GetMany(ctx context.Context, keys []string) (map[string]T, error) } @@ -379,7 +380,7 @@ How `GetMany` works: 2. **Not-Found cache**: misses are checked against it, exactly like `Get`. 3. **Singleflight**: every key that needs the upstream is claimed in the **same** singleflight `Get` uses. Keys already being fetched by a `Get` or another `GetMany` are waited for, not fetched again; so a `Get` and a `GetMany` (or two overlapping `GetMany`s) fetch a shared key only once. `WithFetchConcurrency` applies per key as usual. 4. **DoubleCheck**: the claimed keys are re-checked against the backend and Not-Found cache, by the same rules as `Get`. -5. **Upstream**: the remaining keys are fetched with **one** `GetMany` call if the upstream implements `BatchUpstream[T]`, otherwise with concurrent `Get` calls. +5. **Upstream**: the remaining keys are fetched with **one** `GetMany` call if the upstream implements `BatchUpstream[T]`, otherwise with concurrent `Get` calls, at most `WithGetManyConcurrency` (default 16) at a time. 6. **Write back**: found values go to the backend (`SetMany` when supported), missing keys to the Not-Found cache. Like `Get`, this only touches this layer, never the upstream. `Client` implements `BatchUpstream[T]` itself, so in a layered setup a batch travels down as one call per layer: `l1Client.GetMany` → L1 batch read → `l2Client.GetMany` → L2 batch read → one database query. diff --git a/README_ZH.md b/README_ZH.md index d81e927..a7f9c44 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -354,6 +354,7 @@ products, err := client.GetMany(ctx, []string{"p1", "p2", "p3"}) type BatchUpstream[T any] interface { // map 里没有的 key 视为不存在(相当于 Get 的 ErrKeyNotFound)。 // 返回非 nil error 表示整批失败;如果是原样返回(没有再包一层)的 *cachex.BatchError,只有它列出的 key 失败。 + // 整批失败的 error 即使包着 ErrKeyNotFound,也算所有 key 失败,不算不存在。 GetMany(ctx context.Context, keys []string) (map[string]T, error) } @@ -378,7 +379,7 @@ func (s productSource) GetMany(ctx context.Context, ids []string) (map[string]*P 2. **Not-Found 缓存**:未命中的先查它,和 `Get` 一样。 3. **Singleflight**:每个要回源的 key 都在和 `Get` **同一个** singleflight 里认领。已经有 `Get` 或别的 `GetMany` 在取的 key,等那次的结果,不再取一遍;所以 `Get` 和 `GetMany`(或两个有交集的 `GetMany`)同时要同一个 key,只回源一次。`WithFetchConcurrency` 照旧按 key 生效。 4. **DoubleCheck**:认领到的 key 按和 `Get` 相同的规则再查一次后端和 Not-Found 缓存。 -5. **上游**:剩下的 key,上游实现了 `BatchUpstream[T]` 就调**一次** `GetMany`,否则并发逐个 `Get`。 +5. **上游**:剩下的 key,上游实现了 `BatchUpstream[T]` 就调**一次** `GetMany`,否则并发逐个 `Get`,同时最多 `WithGetManyConcurrency` 个(默认 16)。 6. **回填**:取到的值写回后端(支持就用 `SetMany`),不存在的 key 写进 Not-Found 缓存。和 `Get` 一样只写本层,不写上游。 `Client` 自己也实现了 `BatchUpstream[T]`,所以多层缓存时一批 key 每层只走一次调用:`l1Client.GetMany` → L1 批量读 → `l2Client.GetMany` → L2 批量读 → 一次数据库查询。 diff --git a/batch.go b/batch.go index d765936..8c39f78 100644 --- a/batch.go +++ b/batch.go @@ -80,7 +80,7 @@ type result[T any] struct { // GetMany is waited for, not fetched again. The keys this call claims are // double-checked (WithDoubleCheck) and then fetched together: one // upstream.GetMany if the upstream implements BatchUpstream, otherwise -// concurrent upstream.Get calls. +// concurrent upstream.Get calls (at most WithGetManyConcurrency at a time). // - Fetched values are written to the backend (SetMany if supported) and // not-found keys to the not-found cache, without touching the upstream, // exactly like Get. @@ -308,9 +308,6 @@ func (c *Client[T]) fetchClaimedMany(ctx context.Context, keys, sfKeys []string, } }() - fetchCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), c.fetchTimeout) - defer cancel() - checked := make([]int, 0, len(keys)) if c.enableDoubleCheck { // like Get, the double-check reads with the request ctx @@ -341,6 +338,9 @@ func (c *Client[T]) fetchClaimedMany(ctx context.Context, keys, sfKeys []string, for j, i := range pending { pendingKeys[j] = keys[i] } + // like Get, the fetch timeout starts after the double-check + fetchCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), c.fetchTimeout) + defer cancel() for j, r := range c.doFetchMany(fetchCtx, pendingKeys) { results[pending[j]] = r } @@ -354,8 +354,14 @@ func (c *Client[T]) doFetchMany(ctx context.Context, keys []string) []result[T] if batch, ok := c.upstream.(BatchUpstream[T]); ok { values, err := batch.GetMany(ctx, keys) + _, partial := err.(*BatchError) //nolint:errorlint // see errForKey for i, key := range keys { if kerr := errForKey(err, key); kerr != nil { + if !partial && IsErrKeyNotFound(kerr) { + // A whole-batch failure is not a not-found for every key, even if + // a not-found sits somewhere in its chain: keep only its message. + kerr = errors.New(kerr.Error()) + } results[i].err = errors.Wrapf(kerr, "get from upstream failed for key: %s", key) } else if value, ok := values[key]; ok { results[i].value = value @@ -364,13 +370,14 @@ func (c *Client[T]) doFetchMany(ctx context.Context, keys []string) []result[T] } } } else { - // ponytail: one goroutine per key, unbounded within a batch; add a limit if - // upstreams without batch support get hammered by large batches. var wg sync.WaitGroup + sem := make(chan struct{}, c.getManyConc) for i, key := range keys { // overwritten on return; stays if the upstream calls runtime.Goexit results[i].err = errors.Errorf("upstream fetch exited without returning for key: %s", key) + sem <- struct{}{} wg.Go(func() { + defer func() { <-sem }() results[i] = c.getFromUpstream(ctx, key) }) } diff --git a/batch_test.go b/batch_test.go index 275902f..2847b57 100644 --- a/batch_test.go +++ b/batch_test.go @@ -804,3 +804,83 @@ func TestRedisCacheSetManyEncodeErrorKeepsOthers(t *testing.T) { require.Error(t, err) assert.True(t, mr.Exists("ok"), "the encodable value is still written") } + +// slowSecondBatch is a SyncMap whose GetMany sleeps from the second call on +// (the double-check), as if the backend were slow to answer it. +type slowSecondBatch struct { + *SyncMap[string] + calls atomic.Int64 + delay time.Duration +} + +func (m *slowSecondBatch) GetMany(ctx context.Context, keys []string) (map[string]string, error) { + if m.calls.Add(1) > 1 { + time.Sleep(m.delay) + } + return m.SyncMap.GetMany(ctx, keys) +} + +func TestClientGetManyReviewFixes2(t *testing.T) { + ctx := context.Background() + + t.Run("the per-key fallback fetches at most WithGetManyConcurrency keys at once", func(t *testing.T) { + var cur, peak atomic.Int64 + up := UpstreamFunc[string](func(_ context.Context, key string) (string, error) { + n := cur.Add(1) + for { + p := peak.Load() + if n <= p || peak.CompareAndSwap(p, n) { + break + } + } + time.Sleep(5 * time.Millisecond) + cur.Add(-1) + return key, nil + }) + cli := NewClient[string](NewSyncMap[string](), up, WithGetManyConcurrency[string](4)) + keys := make([]string, 50) + for i := range keys { + keys[i] = fmt.Sprintf("k%d", i) + } + got, err := cli.GetMany(ctx, keys) + require.NoError(t, err) + assert.Len(t, got, 50) + assert.LessOrEqual(t, peak.Load(), int64(4)) + assert.Greater(t, peak.Load(), int64(1), "still concurrent") + }) + + t.Run("a whole-batch error that contains a not-found is a failure, not a not-found", func(t *testing.T) { + notFound := NewSyncMap[time.Time]() + up := batchUpstreamFunc[string](func(context.Context, []string) (map[string]string, error) { + return nil, stderrors.Join(errors.New("conn reset"), &ErrKeyNotFound{}) + }) + cli := NewClient(NewSyncMap[string](), up, NotFoundWithTTL[string](notFound, time.Hour, 0)) + + got, err := cli.GetMany(ctx, []string{"a", "b"}) + assert.Empty(t, got) + var be *BatchError + require.ErrorAs(t, err, &be) + assert.Len(t, be.Errors, 2) + for _, kerr := range be.Errors { + assert.False(t, IsErrKeyNotFound(kerr), "a whole-batch failure must not read as not-found") + } + _, err = notFound.Get(ctx, "a") + assert.True(t, IsErrKeyNotFound(err), "no not-found is cached for a key the upstream never answered") + }) + + t.Run("the fetch timeout starts after the double-check, like Get", func(t *testing.T) { + backend := &slowSecondBatch{SyncMap: NewSyncMap[string](), delay: 100 * time.Millisecond} + up := batchUpstreamFunc[string](func(ctx context.Context, keys []string) (map[string]string, error) { + if err := ctx.Err(); err != nil { + return nil, err + } + return map[string]string{"a": "1"}, nil + }) + cli := NewClient[string](backend, up, + WithDoubleCheck[string](DoubleCheckEnabled), + WithFetchTimeout[string](50*time.Millisecond)) + got, err := cli.GetMany(ctx, []string{"a"}) + require.NoError(t, err) + assert.Equal(t, map[string]string{"a": "1"}, got) + }) +} diff --git a/client.go b/client.go index 4f09f99..29bdad0 100644 --- a/client.go +++ b/client.go @@ -15,7 +15,10 @@ import ( var ( DefaultFetchTimeout = 60 * time.Second DefaultFetchConcurrency = 1 - NowFunc = time.Now + // DefaultGetManyConcurrency bounds the concurrent upstream.Get calls of one + // GetMany when the upstream does not implement BatchUpstream. + DefaultGetManyConcurrency = 16 + NowFunc = time.Now ) // Client manages cache operations with automatic upstream fetching @@ -30,6 +33,7 @@ type Client[T any] struct { serveStale bool fetchTimeout time.Duration fetchConcurrency int + getManyConc int logger *slog.Logger flights flightGroup[T] @@ -63,6 +67,7 @@ func NewClient[T any](backend Cache[T], upstream Upstream[T], opts ...ClientOpti upstream: upstream, fetchTimeout: DefaultFetchTimeout, fetchConcurrency: DefaultFetchConcurrency, + getManyConc: DefaultGetManyConcurrency, logger: slog.Default(), doubleCheckMode: DoubleCheckAuto, // Default: auto (smart heuristic) } @@ -81,6 +86,9 @@ func NewClient[T any](backend Cache[T], upstream Upstream[T], opts ...ClientOpti if c.fetchConcurrency <= 0 { panic("fetchConcurrency must be positive") } + if c.getManyConc <= 0 { + panic("getManyConcurrency must be positive") + } return c } @@ -471,6 +479,16 @@ func WithFetchConcurrency[T any](concurrency int) ClientOption[T] { } } +// WithGetManyConcurrency sets the maximum number of concurrent upstream.Get +// calls one GetMany makes for its missing keys when the upstream does not +// implement BatchUpstream (default DefaultGetManyConcurrency). It does not +// apply to a BatchUpstream, which gets one GetMany call. +func WithGetManyConcurrency[T any](concurrency int) ClientOption[T] { + return func(c *Client[T]) { + c.getManyConc = concurrency + } +} + // WithLogger sets the logger for the client. // If not set, slog.Default() is used. func WithLogger[T any](logger *slog.Logger) ClientOption[T] { diff --git a/types.go b/types.go index d0acc8c..0986b9d 100644 --- a/types.go +++ b/types.go @@ -39,7 +39,8 @@ func (f UpstreamFunc[T]) Get(ctx context.Context, key string) (T, error) { // Keys absent from the returned map do not exist (the batch form of // ErrKeyNotFound). A non-nil error fails the whole batch, unless it is a // *BatchError returned as is (not wrapped), which fails only the keys it lists -// while the map still carries the rest. +// while the map still carries the rest. A whole-batch error fails every key +// even if it wraps an ErrKeyNotFound. type BatchUpstream[T any] interface { GetMany(ctx context.Context, keys []string) (map[string]T, error) } From d83a40d7ebd0a8f01ebc94492059f982f9c23426 Mon Sep 17 00:00:00 2001 From: molon <3739161+molon@users.noreply.github.com> Date: Thu, 8 Oct 2026 15:55:47 +0800 Subject: [PATCH 06/40] fix: keep whole-batch errors intact while never reading them as not-found - A whole-batch error from the backend or the not-found cache fails every key, like one from the upstream already did. Before, an error with an ErrKeyNotFound in its chain (or a bare one) was read as "every key is missing", hiding e.g. a connection error behind a fetch. - The per-key error keeps the original error, so errors.Is/As still find its causes; IsErrKeyNotFound reports false for it. Before, the upstream path kept only the error's message. - README: GetMany fetches misses in one call only with BatchUpstream. - Tests release their gates even when the wait assertion fails. --- README.md | 5 +-- README_ZH.md | 5 +-- batch.go | 19 ++++++++--- batch_test.go | 84 +++++++++++++++++++++++++++++++++++++++++----- client.go | 2 +- error.go | 7 +++- get_compat_test.go | 6 ++-- types.go | 3 +- 8 files changed, 108 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index a0e4788..e8c3c5e 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ - **🚫 Cache Penetration Defense** - Not-Found caching mechanism prevents malicious queries from overwhelming the database - **🔄 Serve-Stale** - Serves stale data while asynchronously refreshing, ensuring high availability and low latency - **🎪 Layered Caching** - Flexible multi-level caching (L1 Memory + L2 Redis), Client can also be used as upstream -- **📦 Batch Reads** - `GetMany` reads many keys at once and fetches all misses with one upstream call, keeping singleflight, DoubleCheck, Not-Found caching and serve-stale +- **📦 Batch Reads** - `GetMany` reads many keys at once and fetches all misses together (one upstream call if the upstream implements `BatchUpstream`), keeping singleflight, DoubleCheck, Not-Found caching and serve-stale - **🚀 High Performance** - Sub-microsecond latency, 79x~1729x throughput amplification, zero error rate - **🎯 Type-Safe** - Go generics provide compile-time type safety, avoiding runtime type errors - **⏱️ Flexible TTL** - Independent fresh and stale TTL configuration for precise data lifecycle control @@ -355,7 +355,8 @@ type BatchUpstream[T any] interface { // Keys absent from the map do not exist (like ErrKeyNotFound for Get). // A non-nil error fails the whole batch, unless it is a *cachex.BatchError // returned as is (not wrapped), which fails only the keys it lists. - // A whole-batch error fails every key, even if it wraps an ErrKeyNotFound. + // A whole-batch error fails every key, even if it wraps an ErrKeyNotFound: + // errors.Is/As still see it, but IsErrKeyNotFound reports false. GetMany(ctx context.Context, keys []string) (map[string]T, error) } diff --git a/README_ZH.md b/README_ZH.md index a7f9c44..94540c6 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -14,7 +14,7 @@ - **🚫 防御缓存穿透** - Not-Found 缓存机制,缓存不存在的 key,避免恶意查询打垮数据库 - **🔄 Serve-Stale** - 提供陈旧数据的同时异步刷新,确保高可用性和低延迟 - **🎪 分层缓存** - 灵活组合多级缓存(L1 内存 + L2 Redis),Client 可作为下层 Upstream -- **📦 批量读取** - `GetMany` 一次读多个 key,未命中的合成一次上游调用,singleflight、DoubleCheck、Not-Found 缓存、serve-stale 照样生效 +- **📦 批量读取** - `GetMany` 一次读多个 key,未命中的一起拉取(上游实现了 `BatchUpstream` 就合成一次调用),singleflight、DoubleCheck、Not-Found 缓存、serve-stale 照样生效 - **🚀 高性能** - 亚微秒级延迟,79x~1729x 吞吐量放大,零错误率 - **🎯 类型安全** - Go 泛型提供编译时类型安全,避免运行时类型错误 - **⏱️ 灵活 TTL** - 独立的新鲜和陈旧 TTL 配置,精确控制数据生命周期 @@ -354,7 +354,8 @@ products, err := client.GetMany(ctx, []string{"p1", "p2", "p3"}) type BatchUpstream[T any] interface { // map 里没有的 key 视为不存在(相当于 Get 的 ErrKeyNotFound)。 // 返回非 nil error 表示整批失败;如果是原样返回(没有再包一层)的 *cachex.BatchError,只有它列出的 key 失败。 - // 整批失败的 error 即使包着 ErrKeyNotFound,也算所有 key 失败,不算不存在。 + // 整批失败的 error 即使包着 ErrKeyNotFound,也算所有 key 失败,不算不存在: + // errors.Is/As 仍能找到原来的 error,只是 IsErrKeyNotFound 返回 false。 GetMany(ctx context.Context, keys []string) (map[string]T, error) } diff --git a/batch.go b/batch.go index 8c39f78..57cbe29 100644 --- a/batch.go +++ b/batch.go @@ -544,16 +544,27 @@ func delMany[T any](ctx context.Context, cache Cache[T], keys []string) error { } // errForKey returns the error a batch call reported for key: the key's own -// entry if err is a *BatchError, otherwise err itself (the whole batch failed). -// Only an unwrapped *BatchError is partial: a wrapped or joined one may sit -// next to an error that failed the whole batch. +// entry if err is a *BatchError, otherwise err itself (the whole batch failed) +// marked as a wholeBatchError. Only an unwrapped *BatchError is partial: a +// wrapped or joined one may sit next to an error that failed the whole batch. func errForKey(err error, key string) error { if batchErr, ok := err.(*BatchError); ok { //nolint:errorlint // see above return batchErr.Errors[key] } - return err + if err == nil { + return nil + } + return &wholeBatchError{err: err} } +// wholeBatchError is a whole-batch failure reported for one key. It is never +// a not-found (see IsErrKeyNotFound), even if one sits in its chain, while +// errors.Is and errors.As still see the original error. +type wholeBatchError struct{ err error } + +func (e *wholeBatchError) Error() string { return e.err.Error() } +func (e *wholeBatchError) Unwrap() error { return e.err } + func uniqueKeys(keys []string) []string { seen := make(map[string]struct{}, len(keys)) out := make([]string, 0, len(keys)) diff --git a/batch_test.go b/batch_test.go index 2847b57..c3c0bd8 100644 --- a/batch_test.go +++ b/batch_test.go @@ -649,18 +649,84 @@ func TestClientGetManyUpstreamGoexit(t *testing.T) { }) } -// notFoundBatchBackend answers a whole GetMany with ErrKeyNotFound. -type notFoundBatchBackend struct{ *SyncMap[string] } +// failingBatchGet answers every GetMany with err. +type failingBatchGet[T any] struct { + *SyncMap[T] + err error +} -func (notFoundBatchBackend) GetMany(context.Context, []string) (map[string]string, error) { - return nil, &ErrKeyNotFound{} +func (f failingBatchGet[T]) GetMany(context.Context, []string) (map[string]T, error) { + return nil, f.err } -func TestClientGetManyBackendBatchNotFoundIsAMiss(t *testing.T) { - cli := NewClient[string](notFoundBatchBackend{NewSyncMap[string]()}, &batchUpstream{data: map[string]string{"a": "1"}}) - got, err := cli.GetMany(context.Background(), []string{"a"}) - require.NoError(t, err) - assert.Equal(t, map[string]string{"a": "1"}, got, "a backend that says not-found for the batch is a miss, so the key is fetched") +func TestClientGetManyWholeBatchErrors(t *testing.T) { + ctx := context.Background() + conn := errors.New("conn reset") + joined := stderrors.Join(conn, &ErrKeyNotFound{}) + + // requireFailedAll checks every key failed with an error that still is conn + // but never reads as not-found. + requireFailedAll := func(t *testing.T, got map[string]string, err error, keys ...string) { + t.Helper() + assert.Empty(t, got) + var be *BatchError + require.ErrorAs(t, err, &be) + assert.ElementsMatch(t, keys, slices.Collect(maps.Keys(be.Errors))) + for _, kerr := range be.Errors { + assert.ErrorIs(t, kerr, conn, "the cause keeps its identity") + assert.False(t, IsErrKeyNotFound(kerr), "a whole-batch failure must not read as not-found") + } + } + + for name, batchErr := range map[string]error{"bare not-found": &ErrKeyNotFound{}, "joined": joined} { + t.Run("backend: "+name+" fails every key instead of reading as misses", func(t *testing.T) { + up := &batchUpstream{data: map[string]string{"a": "1"}} + cli := NewClient[string](failingBatchGet[string]{NewSyncMap[string](), batchErr}, up) + got, err := cli.GetMany(ctx, []string{"a"}) + assert.Empty(t, got) + var be *BatchError + require.ErrorAs(t, err, &be) + assert.False(t, IsErrKeyNotFound(be.Errors["a"])) + batches, ones := up.calls() + assert.Empty(t, batches, "a failed backend read is not a miss") + assert.Empty(t, ones) + }) + } + + t.Run("not-found cache: a joined error fails every key", func(t *testing.T) { + up := &batchUpstream{data: map[string]string{"a": "1"}} + cli := NewClient(NewSyncMap[string](), up, + NotFoundWithTTL[string](failingBatchGet[time.Time]{NewSyncMap[time.Time](), joined}, time.Hour, 0)) + got, err := cli.GetMany(ctx, []string{"a", "b"}) + requireFailedAll(t, got, err, "a", "b") + batches, ones := up.calls() + assert.Empty(t, batches, "a failed not-found cache read is not a miss") + assert.Empty(t, ones) + }) + + t.Run("upstream: a joined error keeps its cause and caches nothing", func(t *testing.T) { + notFound := NewSyncMap[time.Time]() + up := batchUpstreamFunc[string](func(context.Context, []string) (map[string]string, error) { + return nil, joined + }) + cli := NewClient(NewSyncMap[string](), up, NotFoundWithTTL[string](notFound, time.Hour, 0)) + got, err := cli.GetMany(ctx, []string{"a", "b"}) + requireFailedAll(t, got, err, "a", "b") + _, err = notFound.Get(ctx, "a") + assert.True(t, IsErrKeyNotFound(err), "no not-found is cached for a key the upstream never answered") + }) + + t.Run("layered: a lower layer's whole-batch failure stays a failure", func(t *testing.T) { + lower := NewClient(NewSyncMap[string](), batchUpstreamFunc[string](func(context.Context, []string) (map[string]string, error) { + return nil, joined + })) + notFound := NewSyncMap[time.Time]() + cli := NewClient(NewSyncMap[string](), lower, NotFoundWithTTL[string](notFound, time.Hour, 0)) + got, err := cli.GetMany(ctx, []string{"a"}) + requireFailedAll(t, got, err, "a") + _, err = notFound.Get(ctx, "a") + assert.True(t, IsErrKeyNotFound(err)) + }) } func TestRedisCacheGetManyPerKeyErrors(t *testing.T) { diff --git a/client.go b/client.go index 29bdad0..15e81d3 100644 --- a/client.go +++ b/client.go @@ -348,7 +348,7 @@ func (c *Client[T]) fetchClaimed(ctx context.Context, key string) (result T, res func isCachedFreshNotFound(err error) bool { var e *ErrKeyNotFound - return errors.As(err, &e) && e.Cached && e.CacheState == StateFresh + return IsErrKeyNotFound(err) && errors.As(err, &e) && e.Cached && e.CacheState == StateFresh } func (c *Client[T]) makeSFKey(key string) string { diff --git a/error.go b/error.go index 71dbe67..7d7de57 100644 --- a/error.go +++ b/error.go @@ -32,11 +32,16 @@ func (e *ErrKeyNotFound) Error() string { } } -// IsErrKeyNotFound checks if the error is an ErrKeyNotFound +// IsErrKeyNotFound checks if the error is an ErrKeyNotFound. An error that +// failed a whole batch (see BatchUpstream) is never one, even if it wraps one. func IsErrKeyNotFound(err error) bool { if err == nil { return false } + var w *wholeBatchError + if errors.As(err, &w) { + return false + } var e *ErrKeyNotFound return errors.As(err, &e) } diff --git a/get_compat_test.go b/get_compat_test.go index 222f00d..1fa79de 100644 --- a/get_compat_test.go +++ b/get_compat_test.go @@ -88,7 +88,7 @@ func TestGetCompatConcurrentMissesCoalesce(t *testing.T) { go func() { <-g.entered - require.Eventually(t, func() bool { return hooks.before.Load() == 20 }, time.Second, time.Millisecond) + assert.Eventually(t, func() bool { return hooks.before.Load() == 20 }, time.Second, time.Millisecond) time.Sleep(50 * time.Millisecond) // let every caller join the flight close(g.release) }() @@ -158,7 +158,7 @@ func TestGetCompatUpstreamPanic(t *testing.T) { go func() { <-entered - require.Eventually(t, func() bool { return hooks.before.Load() == 5 }, time.Second, time.Millisecond) + assert.Eventually(t, func() bool { return hooks.before.Load() == 5 }, time.Second, time.Millisecond) time.Sleep(50 * time.Millisecond) close(release) }() @@ -267,7 +267,7 @@ func TestGetCompatFetchConcurrencySlots(t *testing.T) { go func() { <-g.entered - require.Eventually(t, func() bool { return hooks.before.Load() == 60 }, time.Second, time.Millisecond) + assert.Eventually(t, func() bool { return hooks.before.Load() == 60 }, time.Second, time.Millisecond) time.Sleep(50 * time.Millisecond) close(g.release) }() diff --git a/types.go b/types.go index 0986b9d..20ec77e 100644 --- a/types.go +++ b/types.go @@ -40,7 +40,8 @@ func (f UpstreamFunc[T]) Get(ctx context.Context, key string) (T, error) { // ErrKeyNotFound). A non-nil error fails the whole batch, unless it is a // *BatchError returned as is (not wrapped), which fails only the keys it lists // while the map still carries the rest. A whole-batch error fails every key -// even if it wraps an ErrKeyNotFound. +// even if it wraps an ErrKeyNotFound: errors.Is and errors.As still see it, +// but IsErrKeyNotFound reports false. type BatchUpstream[T any] interface { GetMany(ctx context.Context, keys []string) (map[string]T, error) } From ca6885c45ed405b6505dcddc4981d5f763af57b0 Mon Sep 17 00:00:00 2001 From: molon <3739161+molon@users.noreply.github.com> Date: Thu, 8 Oct 2026 16:11:08 +0800 Subject: [PATCH 07/40] test: cover how whole-batch errors meet the double-check and Get, and document the BatchCache contract - A double-check whose batch read fails falls through to the upstream, like Get, even if the error looks like a cached fresh not-found. - A Get that joins a GetMany's fetch gets that batch's failure, not a not-found, and nothing is cached as not-found. - README and BatchCache doc: a backend's GetMany follows the BatchUpstream error contract, and a per-key error in BatchError is never a not-found. --- README.md | 7 ++++-- README_ZH.md | 7 ++++-- batch_test.go | 67 +++++++++++++++++++++++++++++++++++++++++++++++++++ types.go | 2 ++ 4 files changed, 79 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index e8c3c5e..46148d8 100644 --- a/README.md +++ b/README.md @@ -231,7 +231,10 @@ Optionally implement `BatchCache[T]` as well, so `Client.GetMany` reads and writ ```go type BatchCache[T any] interface { Cache[T] - GetMany(ctx context.Context, keys []string) (map[string]T, error) // missing keys are absent + // Missing keys are absent from the map; do not report them as ErrKeyNotFound. + // Errors follow BatchUpstream below: any error other than an unwrapped + // *cachex.BatchError fails every key (it is not read as all misses). + GetMany(ctx context.Context, keys []string) (map[string]T, error) SetMany(ctx context.Context, values map[string]T) error DelMany(ctx context.Context, keys []string) error } @@ -386,7 +389,7 @@ How `GetMany` works: `Client` implements `BatchUpstream[T]` itself, so in a layered setup a batch travels down as one call per layer: `l1Client.GetMany` → L1 batch read → `l2Client.GetMany` → L2 batch read → one database query. -**Errors**: the returned map always holds every key that succeeded. If some keys failed (backend, upstream or context errors), the error is a `*cachex.BatchError` whose `Errors` map lists them by key; `errors.Is`/`errors.As` see through it to the per-key errors. +**Errors**: the returned map always holds every key that succeeded. If some keys failed (backend, upstream or context errors), the error is a `*cachex.BatchError` whose `Errors` map lists them by key; `errors.Is`/`errors.As` see through it to the per-key errors. A per-key error is always a real failure, never a not-found: keys that do not exist are just absent from the map. ```go products, err := client.GetMany(ctx, ids) diff --git a/README_ZH.md b/README_ZH.md index 94540c6..da68458 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -231,7 +231,10 @@ type Cache[T any] interface { ```go type BatchCache[T any] interface { Cache[T] - GetMany(ctx context.Context, keys []string) (map[string]T, error) // 不存在的 key 不出现在结果里 + // 不存在的 key 不出现在结果里,不要用 ErrKeyNotFound 表示。 + // 错误约定同下文的 BatchUpstream:除了原样返回的 *cachex.BatchError, + // 其他 error 都算所有 key 失败(不会当成全部未命中)。 + GetMany(ctx context.Context, keys []string) (map[string]T, error) SetMany(ctx context.Context, values map[string]T) error DelMany(ctx context.Context, keys []string) error } @@ -385,7 +388,7 @@ func (s productSource) GetMany(ctx context.Context, ids []string) (map[string]*P `Client` 自己也实现了 `BatchUpstream[T]`,所以多层缓存时一批 key 每层只走一次调用:`l1Client.GetMany` → L1 批量读 → `l2Client.GetMany` → L2 批量读 → 一次数据库查询。 -**错误**:返回的 map 总是包含所有成功的 key。有 key 失败(后端、上游或 context 出错)时,error 是 `*cachex.BatchError`,它的 `Errors` 按 key 列出各自的错误;`errors.Is`/`errors.As` 能穿透到每个 key 的错误。 +**错误**:返回的 map 总是包含所有成功的 key。有 key 失败(后端、上游或 context 出错)时,error 是 `*cachex.BatchError`,它的 `Errors` 按 key 列出各自的错误;`errors.Is`/`errors.As` 能穿透到每个 key 的错误。每个 key 的错误都是真正的失败,不会是「不存在」:不存在的 key 只是不出现在 map 里。 ```go products, err := client.GetMany(ctx, ids) diff --git a/batch_test.go b/batch_test.go index c3c0bd8..bb12c18 100644 --- a/batch_test.go +++ b/batch_test.go @@ -729,6 +729,73 @@ func TestClientGetManyWholeBatchErrors(t *testing.T) { }) } +// missThenFailBatchGet misses every key on its first GetMany and answers +// later ones with err. +type missThenFailBatchGet struct { + *SyncMap[string] + calls atomic.Int32 + err error +} + +func (m *missThenFailBatchGet) GetMany(context.Context, []string) (map[string]string, error) { + if m.calls.Add(1) == 1 { + return map[string]string{}, nil + } + return nil, m.err +} + +func TestClientGetManyWholeBatchErrorInterplay(t *testing.T) { + ctx := context.Background() + + t.Run("a failed double-check falls through to the upstream, even if the error looks like a cached not-found", func(t *testing.T) { + backend := &missThenFailBatchGet{SyncMap: NewSyncMap[string](), err: &ErrKeyNotFound{Cached: true, CacheState: StateFresh}} + up := &batchUpstream{data: map[string]string{"a": "1"}} + cli := NewClient[string](backend, up, WithDoubleCheck[string](DoubleCheckEnabled)) + + got, err := cli.GetMany(ctx, []string{"a"}) + require.NoError(t, err) + assert.Equal(t, map[string]string{"a": "1"}, got, "like Get, a failed double-check is not an answer") + assert.Equal(t, int32(2), backend.calls.Load(), "precondition: the double-check ran") + }) + + t.Run("a Get that joins a failed batch fetch gets the failure, not a not-found", func(t *testing.T) { + conn := errors.New("conn reset") + entered, release := make(chan struct{}), make(chan struct{}) + var calls atomic.Int32 + up := batchUpstreamFunc[string](func(context.Context, []string) (map[string]string, error) { + if calls.Add(1) == 1 { + close(entered) + <-release + } + return nil, stderrors.Join(conn, &ErrKeyNotFound{}) + }) + notFound := NewSyncMap[time.Time]() + cli := NewClient(NewSyncMap[string](), up, NotFoundWithTTL[string](notFound, time.Hour, 0)) + var hooks hookCounts + hooks.install(cli, nil) + + var wg sync.WaitGroup + wg.Go(func() { + _, err := cli.GetMany(ctx, []string{"a"}) + assert.ErrorIs(t, err, conn) + }) + waitFor(t, entered) // GetMany owns the fetch of a + var getErr error + wg.Go(func() { _, getErr = cli.Get(ctx, "a") }) + require.Eventually(t, func() bool { return hooks.before.Load() == 1 }, time.Second, time.Millisecond) + time.Sleep(50 * time.Millisecond) // let the Get join the flight + close(release) + wg.Wait() + + assert.Equal(t, int32(1), calls.Load(), "the Get joined the batch's fetch") + require.Error(t, getErr) + assert.ErrorIs(t, getErr, conn) + assert.False(t, IsErrKeyNotFound(getErr)) + _, err := notFound.Get(ctx, "a") + assert.True(t, IsErrKeyNotFound(err), "no not-found is cached") + }) +} + func TestRedisCacheGetManyPerKeyErrors(t *testing.T) { ctx := context.Background() cache, mr := newRedisCache[string](t) diff --git a/types.go b/types.go index 20ec77e..9961e1e 100644 --- a/types.go +++ b/types.go @@ -49,6 +49,8 @@ type BatchUpstream[T any] interface { // BatchCache is an optional interface for a Cache that can read and write many // keys in one call. Client.GetMany uses it for the backend and the not-found // cache when available, and falls back to Get/Set/Del per key otherwise. +// Its GetMany follows the BatchUpstream contract: missing keys are absent, and +// a whole-batch error is a failure of every key, not a batch of misses. type BatchCache[T any] interface { Cache[T] BatchUpstream[T] From 5e99f15b433435a755c0654489aafbb34be92655 Mon Sep 17 00:00:00 2001 From: molon <3739161+molon@users.noreply.github.com> Date: Tue, 6 Oct 2026 22:13:59 +0800 Subject: [PATCH 08/40] docs: align README examples with the current API - NewRedisCache and NewGORMCache take a config struct, not positional args - Cache[T].Set has no ttl parameter; expiry belongs to the Client or the backend config - missing keys are signalled with *cachex.ErrKeyNotFound, checked via IsErrKeyNotFound - the string JSON transform is StringJSONTransform[T], JSONTransform takes Cache[[]byte] --- README.md | 47 +++++++++++++++++++++++++++++------------------ README_ZH.md | 47 +++++++++++++++++++++++++++++------------------ 2 files changed, 58 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index 46148d8..92da0e1 100644 --- a/README.md +++ b/README.md @@ -64,7 +64,7 @@ func main() { upstream := cachex.UpstreamFunc[*cachex.Entry[*Product]]( func(ctx context.Context, key string) (*cachex.Entry[*Product], error) { // Fetch from database or API - // Return cachex.ErrKeyNotFound for non-existent keys + // Return &cachex.ErrKeyNotFound{} for non-existent keys product := &Product{ID: key, Name: "Product " + key, Price: 9900} return &cachex.Entry[*Product]{ Data: product, @@ -193,11 +193,11 @@ defer cache.Close() Distributed cache with customizable serialization. ```go -cache := cachex.NewRedisCache[*Product]( - redisClient, - "product:", // key prefix - 30*time.Second, // TTL -) +cache := cachex.NewRedisCache[*Product](&cachex.RedisCacheConfig{ + Client: redisClient, + KeyPrefix: "product:", // key prefix + TTL: 30*time.Second, +}) ``` ### GORM (Database) @@ -205,11 +205,14 @@ cache := cachex.NewRedisCache[*Product]( Use your database as a cache layer (useful for persistence). ```go -cache := cachex.NewGORMCache( - db, - "cache_products", - 30*time.Second, -) +cache := cachex.NewGORMCache[*Product](&cachex.GORMCacheConfig{ + DB: db, + TableName: "cache_products", +}) +// Create the table if needed +if err := cache.Migrate(ctx); err != nil { + // handle error +} ``` ### Custom Cache @@ -218,13 +221,15 @@ Implement the `Cache[T]` interface: ```go type Cache[T any] interface { - Set(ctx context.Context, key string, value T, ttl time.Duration) error Get(ctx context.Context, key string) (T, error) + Set(ctx context.Context, key string, value T) error Del(ctx context.Context, key string) error } ``` -**Important**: When a key does not exist, the `Get` method must return `cachex.ErrKeyNotFound` error, so the Client can correctly distinguish between cache misses and other error conditions. +**Important**: When a key does not exist, the `Get` method must return a `*cachex.ErrKeyNotFound` error (for example `&cachex.ErrKeyNotFound{}`, optionally wrapped), so the Client can correctly distinguish between cache misses and other error conditions. Use `cachex.IsErrKeyNotFound(err)` to check for it. + +`Set` takes no TTL: expiry is decided by the Client (`WithStale` / `EntryWithTTL`), and backends that support a hard TTL take it in their config (`RistrettoCacheConfig.TTL`, `RedisCacheConfig.TTL`). Optionally implement `BatchCache[T]` as well, so `Client.GetMany` reads and writes your backend in one call per batch instead of key by key (see [Batch Reads](#batch-reads)): @@ -248,9 +253,11 @@ Combine multiple cache layers for optimal performance. Client implements both `C ```go // L2: Redis cache with database upstream -l2Cache := cachex.NewRedisCache[*cachex.Entry[*Product]]( - redisClient, "product:", 10*time.Minute, -) +l2Cache := cachex.NewRedisCache[*cachex.Entry[*Product]](&cachex.RedisCacheConfig{ + Client: redisClient, + KeyPrefix: "product:", + TTL: 10 * time.Minute, +}) dbUpstream := cachex.UpstreamFunc[*cachex.Entry[*Product]]( func(ctx context.Context, key string) (*cachex.Entry[*Product], error) { @@ -437,10 +444,14 @@ Transform between different cache types: ```go // Cache stores JSON strings -stringCache := cachex.NewRedisCache[string](client, "user:", time.Hour) +stringCache := cachex.NewRedisCache[string](&cachex.RedisCacheConfig{ + Client: client, + KeyPrefix: "user:", + TTL: time.Hour, +}) // Transform to User objects -userCache := cachex.JSONTransform[string, *User](stringCache) +userCache := cachex.StringJSONTransform[*User](stringCache) // Use as Cache[*User] user, err := userCache.Get(ctx, "user:123") diff --git a/README_ZH.md b/README_ZH.md index da68458..a71817b 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -64,7 +64,7 @@ func main() { upstream := cachex.UpstreamFunc[*cachex.Entry[*Product]]( func(ctx context.Context, key string) (*cachex.Entry[*Product], error) { // Fetch from database or API - // Return cachex.ErrKeyNotFound for non-existent keys + // Return &cachex.ErrKeyNotFound{} for non-existent keys product := &Product{ID: key, Name: "Product " + key, Price: 9900} return &cachex.Entry[*Product]{ Data: product, @@ -193,11 +193,11 @@ defer cache.Close() 支持自定义序列化的分布式缓存。 ```go -cache := cachex.NewRedisCache[*Product]( - redisClient, - "product:", // key 前缀 - 30*time.Second, // TTL -) +cache := cachex.NewRedisCache[*Product](&cachex.RedisCacheConfig{ + Client: redisClient, + KeyPrefix: "product:", // key 前缀 + TTL: 30*time.Second, +}) ``` ### GORM(数据库) @@ -205,11 +205,14 @@ cache := cachex.NewRedisCache[*Product]( 将数据库用作缓存层(适用于持久化需求)。 ```go -cache := cachex.NewGORMCache( - db, - "cache_products", - 30*time.Second, -) +cache := cachex.NewGORMCache[*Product](&cachex.GORMCacheConfig{ + DB: db, + TableName: "cache_products", +}) +// 需要时建表 +if err := cache.Migrate(ctx); err != nil { + // 处理错误 +} ``` ### 自定义缓存 @@ -218,13 +221,15 @@ cache := cachex.NewGORMCache( ```go type Cache[T any] interface { - Set(ctx context.Context, key string, value T, ttl time.Duration) error Get(ctx context.Context, key string) (T, error) + Set(ctx context.Context, key string, value T) error Del(ctx context.Context, key string) error } ``` -**重要**:当 key 不存在时,`Get` 方法必须返回 `cachex.ErrKeyNotFound` 错误,以便 Client 能够正确区分缓存未命中和其他错误情况。 +**重要**:当 key 不存在时,`Get` 方法必须返回 `*cachex.ErrKeyNotFound` 类型的错误(比如 `&cachex.ErrKeyNotFound{}`,可以再包一层),以便 Client 能够正确区分缓存未命中和其他错误情况。判断时用 `cachex.IsErrKeyNotFound(err)`。 + +`Set` 不带 TTL 参数:过期由 Client 判断(`WithStale` / `EntryWithTTL`),支持硬过期的后端在各自的配置里设(`RistrettoCacheConfig.TTL`、`RedisCacheConfig.TTL`)。 还可以选择实现 `BatchCache[T]`,这样 `Client.GetMany` 读写这个后端时一批只调一次,而不是逐个 key 调(见[批量读取](#批量读取)): @@ -248,9 +253,11 @@ type BatchCache[T any] interface { ```go // L2: Redis cache with database upstream -l2Cache := cachex.NewRedisCache[*cachex.Entry[*Product]]( - redisClient, "product:", 10*time.Minute, -) +l2Cache := cachex.NewRedisCache[*cachex.Entry[*Product]](&cachex.RedisCacheConfig{ + Client: redisClient, + KeyPrefix: "product:", + TTL: 10 * time.Minute, +}) dbUpstream := cachex.UpstreamFunc[*cachex.Entry[*Product]]( func(ctx context.Context, key string) (*cachex.Entry[*Product], error) { @@ -436,10 +443,14 @@ client := cachex.NewClient( ```go // 缓存存储 JSON 字符串 -stringCache := cachex.NewRedisCache[string](client, "user:", time.Hour) +stringCache := cachex.NewRedisCache[string](&cachex.RedisCacheConfig{ + Client: client, + KeyPrefix: "user:", + TTL: time.Hour, +}) // 转换为 User 对象 -userCache := cachex.JSONTransform[string, *User](stringCache) +userCache := cachex.StringJSONTransform[*User](stringCache) // 作为 Cache[*User] 使用 user, err := userCache.Get(ctx, "user:123") From d6b12d46fe2fd352d5e4747101ff21893094c673 Mon Sep 17 00:00:00 2001 From: molon <3739161+molon@users.noreply.github.com> Date: Thu, 8 Oct 2026 17:34:24 +0800 Subject: [PATCH 09/40] fix: fetch each key as Get would when the upstream has no batch support - Without BatchUpstream, GetMany now runs each claimed key through the same path as Get: its own double-check, fetch timeout and write-back, and its waiters get it as soon as it is fetched. Before, the whole batch shared one fetch timeout (late keys failed with deadline exceeded) and a Get joining one key waited for every other key. A key whose upstream calls runtime.Goexit is now released like Get. - A failed not-found cache write no longer stops the backend write-back of the other keys, nor the delete of keys gone upstream. - Remove a leftover branch that could no longer run since whole-batch errors are marked. - README: a compilable BatchUpstream example (with Get, in the Quick Start's type), the timeout of a batch call, and which built-in backends fall back to per-key calls. - Tests for WithFetchConcurrency, a stale not-found and the refresh shared by Get and GetMany. --- README.md | 27 +++++-- README_ZH.md | 27 +++++-- batch.go | 111 ++++++++++++---------------- batch_test.go | 201 +++++++++++++++++++++++++++++++++++++++++++++++++- client.go | 37 +++++----- 5 files changed, 308 insertions(+), 95 deletions(-) diff --git a/README.md b/README.md index 92da0e1..ed91ea3 100644 --- a/README.md +++ b/README.md @@ -372,17 +372,32 @@ type BatchUpstream[T any] interface { type productSource struct{ db *gorm.DB } -func (s productSource) GetMany(ctx context.Context, ids []string) (map[string]*Product, error) { +func (s productSource) GetMany(ctx context.Context, ids []string) (map[string]*cachex.Entry[*Product], error) { var rows []*Product if err := s.db.WithContext(ctx).Where("id IN ?", ids).Find(&rows).Error; err != nil { return nil, err } - out := make(map[string]*Product, len(rows)) + now := time.Now() + out := make(map[string]*cachex.Entry[*Product], len(rows)) for _, p := range rows { - out[p.ID] = p + out[p.ID] = &cachex.Entry[*Product]{Data: p, CachedAt: now} } - return out, nil + return out, nil // ids not found are simply absent } + +// Get is still required (Upstream[T]); it can reuse GetMany. +func (s productSource) Get(ctx context.Context, id string) (*cachex.Entry[*Product], error) { + entries, err := s.GetMany(ctx, []string{id}) + if err != nil { + return nil, err + } + if e, ok := entries[id]; ok { + return e, nil + } + return nil, &cachex.ErrKeyNotFound{} +} + +client := cachex.NewClient(cache, productSource{db: db} /* , options as in Quick Start */) ``` How `GetMany` works: @@ -391,7 +406,7 @@ How `GetMany` works: 2. **Not-Found cache**: misses are checked against it, exactly like `Get`. 3. **Singleflight**: every key that needs the upstream is claimed in the **same** singleflight `Get` uses. Keys already being fetched by a `Get` or another `GetMany` are waited for, not fetched again; so a `Get` and a `GetMany` (or two overlapping `GetMany`s) fetch a shared key only once. `WithFetchConcurrency` applies per key as usual. 4. **DoubleCheck**: the claimed keys are re-checked against the backend and Not-Found cache, by the same rules as `Get`. -5. **Upstream**: the remaining keys are fetched with **one** `GetMany` call if the upstream implements `BatchUpstream[T]`, otherwise with concurrent `Get` calls, at most `WithGetManyConcurrency` (default 16) at a time. +5. **Upstream**: if the upstream implements `BatchUpstream[T]`, the remaining keys are fetched with **one** `GetMany` call (one `WithFetchTimeout` for the whole call). Otherwise each key is fetched exactly as `Get` would (its own double-check, fetch timeout and write-back, and handed to its waiters as soon as it arrives), at most `WithGetManyConcurrency` (default 16) at a time. 6. **Write back**: found values go to the backend (`SetMany` when supported), missing keys to the Not-Found cache. Like `Get`, this only touches this layer, never the upstream. `Client` implements `BatchUpstream[T]` itself, so in a layered setup a batch travels down as one call per layer: `l1Client.GetMany` → L1 batch read → `l2Client.GetMany` → L2 batch read → one database query. @@ -407,7 +422,7 @@ if errors.As(err, &batchErr) { // products is usable either way ``` -Built-in backends implement `BatchCache[T]`: `RistrettoCache`, `SyncMap`, `RedisCache` (one pipeline of `GET`/`SET`/`DEL`, which also works on Redis Cluster) and `GORMCache` (`WHERE key IN (...)` and multi-row upserts, 1000 keys per statement to stay under the bound parameter limits). +These built-in backends implement `BatchCache[T]`: `RistrettoCache`, `SyncMap`, `RedisCache` (one pipeline of `GET`/`SET`/`DEL`, which also works on Redis Cluster) and `GORMCache` (`WHERE key IN (...)` and multi-row upserts, 1000 keys per statement to stay under the bound parameter limits). `BigCache` and the `Transform` wrappers do not, so `GetMany` reads and writes them key by key (wrapping a `RedisCache` in `Transform` means one round trip per key). Fetching 100 missing keys through an upstream that costs 1ms per call (`BenchmarkGetManyVsGet`): diff --git a/README_ZH.md b/README_ZH.md index a71817b..4f9c42c 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -371,17 +371,32 @@ type BatchUpstream[T any] interface { type productSource struct{ db *gorm.DB } -func (s productSource) GetMany(ctx context.Context, ids []string) (map[string]*Product, error) { +func (s productSource) GetMany(ctx context.Context, ids []string) (map[string]*cachex.Entry[*Product], error) { var rows []*Product if err := s.db.WithContext(ctx).Where("id IN ?", ids).Find(&rows).Error; err != nil { return nil, err } - out := make(map[string]*Product, len(rows)) + now := time.Now() + out := make(map[string]*cachex.Entry[*Product], len(rows)) for _, p := range rows { - out[p.ID] = p + out[p.ID] = &cachex.Entry[*Product]{Data: p, CachedAt: now} } - return out, nil + return out, nil // 查不到的 id 不放进 map 即可 } + +// Get 仍然必须实现(Upstream[T]),可以复用 GetMany。 +func (s productSource) Get(ctx context.Context, id string) (*cachex.Entry[*Product], error) { + entries, err := s.GetMany(ctx, []string{id}) + if err != nil { + return nil, err + } + if e, ok := entries[id]; ok { + return e, nil + } + return nil, &cachex.ErrKeyNotFound{} +} + +client := cachex.NewClient(cache, productSource{db: db} /* , options as in Quick Start */) ``` `GetMany` 的流程: @@ -390,7 +405,7 @@ func (s productSource) GetMany(ctx context.Context, ids []string) (map[string]*P 2. **Not-Found 缓存**:未命中的先查它,和 `Get` 一样。 3. **Singleflight**:每个要回源的 key 都在和 `Get` **同一个** singleflight 里认领。已经有 `Get` 或别的 `GetMany` 在取的 key,等那次的结果,不再取一遍;所以 `Get` 和 `GetMany`(或两个有交集的 `GetMany`)同时要同一个 key,只回源一次。`WithFetchConcurrency` 照旧按 key 生效。 4. **DoubleCheck**:认领到的 key 按和 `Get` 相同的规则再查一次后端和 Not-Found 缓存。 -5. **上游**:剩下的 key,上游实现了 `BatchUpstream[T]` 就调**一次** `GetMany`,否则并发逐个 `Get`,同时最多 `WithGetManyConcurrency` 个(默认 16)。 +5. **上游**:上游实现了 `BatchUpstream[T]`,剩下的 key 就调**一次** `GetMany`(整次调用共用一个 `WithFetchTimeout`)。否则每个 key 都和 `Get` 完全一样地拉取(各自 double check、各自超时、各自回填,拉到就交给等它的调用方),同时最多 `WithGetManyConcurrency` 个(默认 16)。 6. **回填**:取到的值写回后端(支持就用 `SetMany`),不存在的 key 写进 Not-Found 缓存。和 `Get` 一样只写本层,不写上游。 `Client` 自己也实现了 `BatchUpstream[T]`,所以多层缓存时一批 key 每层只走一次调用:`l1Client.GetMany` → L1 批量读 → `l2Client.GetMany` → L2 批量读 → 一次数据库查询。 @@ -406,7 +421,7 @@ if errors.As(err, &batchErr) { // 不管有没有 err,products 都能用 ``` -内置后端都实现了 `BatchCache[T]`:`RistrettoCache`、`SyncMap`、`RedisCache`(一个 `GET`/`SET`/`DEL` 的 pipeline,Redis Cluster 下也能用)和 `GORMCache`(`WHERE key IN (...)` 和多行 upsert,每条语句 1000 个 key,不会超出数据库的绑定参数上限)。 +以下内置后端实现了 `BatchCache[T]`:`RistrettoCache`、`SyncMap`、`RedisCache`(一个 `GET`/`SET`/`DEL` 的 pipeline,Redis Cluster 下也能用)和 `GORMCache`(`WHERE key IN (...)` 和多行 upsert,每条语句 1000 个 key,不会超出数据库的绑定参数上限)。`BigCache` 和 `Transform` 包装没有实现,`GetMany` 对它们逐个 key 读写(用 `Transform` 包一层 `RedisCache`,就是每个 key 一次往返)。 上游每次调用耗时 1ms,取 100 个全未命中的 key(`BenchmarkGetManyVsGet`): diff --git a/batch.go b/batch.go index 57cbe29..69de26c 100644 --- a/batch.go +++ b/batch.go @@ -77,10 +77,11 @@ type result[T any] struct { // - Misses are checked against the not-found cache first, exactly like Get. // - Keys that need the upstream are claimed one by one in the same // singleflight Get uses: a key already being fetched by a Get or another -// GetMany is waited for, not fetched again. The keys this call claims are -// double-checked (WithDoubleCheck) and then fetched together: one -// upstream.GetMany if the upstream implements BatchUpstream, otherwise -// concurrent upstream.Get calls (at most WithGetManyConcurrency at a time). +// GetMany is waited for, not fetched again. If the upstream implements +// BatchUpstream, the keys this call claims are double-checked +// (WithDoubleCheck) and fetched together with one upstream.GetMany under +// one fetch timeout. Otherwise each claimed key is fetched exactly as Get +// would, at most WithGetManyConcurrency at a time. // - Fetched values are written to the backend (SetMany if supported) and // not-found keys to the not-found cache, without touching the upstream, // exactly like Get. @@ -251,7 +252,11 @@ func (c *Client[T]) fetchMany(ctx context.Context, keys, sfKeys []string) []resu } } if len(ownKeys) > 0 { - go c.fetchClaimedMany(ctx, ownKeys, ownSFKeys, ownFlights) + if _, ok := c.upstream.(BatchUpstream[T]); ok { + go c.fetchClaimedMany(ctx, ownKeys, ownSFKeys, ownFlights) + } else { + go c.runClaimedEach(ctx, ownKeys, ownSFKeys, ownFlights) + } } results := make([]result[T], len(keys)) @@ -270,8 +275,22 @@ func (c *Client[T]) fetchMany(ctx context.Context, keys, sfKeys []string) []resu return results } -// fetchClaimedMany is the batch form of fetchClaimed: double-check, then fetch -// what is still missing, then finish every flight. +// runClaimedEach fetches claimed keys from an upstream without batch support: +// each key exactly as Get would (own double-check, fetch timeout, write-back, +// published as soon as it is done), at most getManyConc at a time. +func (c *Client[T]) runClaimedEach(ctx context.Context, keys, sfKeys []string, flights []*flight[T]) { + sem := make(chan struct{}, c.getManyConc) + for i, key := range keys { + sem <- struct{}{} + go func() { + defer func() { <-sem }() + c.runClaimed(ctx, key, sfKeys[i], flights[i]) + }() + } +} + +// fetchClaimedMany is the batch form of fetchClaimed for a BatchUpstream: +// double-check, then fetch what is still missing, then finish every flight. func (c *Client[T]) fetchClaimedMany(ctx context.Context, keys, sfKeys []string, flights []*flight[T]) { results := make([]result[T], len(keys)) var pending []int // keys still to fetch after the double-check; nil until it ran @@ -347,41 +366,19 @@ func (c *Client[T]) fetchClaimedMany(ctx context.Context, keys, sfKeys []string, returned = true } -// doFetchMany is the batch form of doFetch: fetch from upstream, then write -// the results to this layer only. +// doFetchMany is the batch form of doFetch: fetch from the batch upstream, +// then write the results to this layer only. func (c *Client[T]) doFetchMany(ctx context.Context, keys []string) []result[T] { results := make([]result[T], len(keys)) - - if batch, ok := c.upstream.(BatchUpstream[T]); ok { - values, err := batch.GetMany(ctx, keys) - _, partial := err.(*BatchError) //nolint:errorlint // see errForKey - for i, key := range keys { - if kerr := errForKey(err, key); kerr != nil { - if !partial && IsErrKeyNotFound(kerr) { - // A whole-batch failure is not a not-found for every key, even if - // a not-found sits somewhere in its chain: keep only its message. - kerr = errors.New(kerr.Error()) - } - results[i].err = errors.Wrapf(kerr, "get from upstream failed for key: %s", key) - } else if value, ok := values[key]; ok { - results[i].value = value - } else { - results[i].err = errors.Wrapf(&ErrKeyNotFound{}, "get from upstream failed for key: %s", key) - } - } - } else { - var wg sync.WaitGroup - sem := make(chan struct{}, c.getManyConc) - for i, key := range keys { - // overwritten on return; stays if the upstream calls runtime.Goexit - results[i].err = errors.Errorf("upstream fetch exited without returning for key: %s", key) - sem <- struct{}{} - wg.Go(func() { - defer func() { <-sem }() - results[i] = c.getFromUpstream(ctx, key) - }) + values, err := c.upstream.(BatchUpstream[T]).GetMany(ctx, keys) + for i, key := range keys { + if kerr := errForKey(err, key); kerr != nil { + results[i].err = errors.Wrapf(kerr, "get from upstream failed for key: %s", key) + } else if value, ok := values[key]; ok { + results[i].value = value + } else { + results[i].err = errors.Wrapf(&ErrKeyNotFound{}, "get from upstream failed for key: %s", key) } - wg.Wait() } found := map[string]T{} @@ -404,41 +401,27 @@ func (c *Client[T]) doFetchMany(ctx context.Context, keys []string) []result[T] return results } -func (c *Client[T]) getFromUpstream(ctx context.Context, key string) (res result[T]) { - defer func() { - if r := recover(); r != nil { - c.logger.ErrorContext(ctx, "panic during upstream fetch", - "key", key, - "panic", r, - "stack", string(debug.Stack())) - res = result[T]{err: errors.Errorf("panic during upstream fetch: %v", r)} - } - }() - value, err := c.upstream.Get(ctx, key) - if err != nil { - return result[T]{err: errors.Wrapf(err, "get from upstream failed for key: %s", key)} - } - return result[T]{value: value} -} - -// setManyWithoutUpstream is the batch form of setWithoutUpstream. +// setManyWithoutUpstream is the batch form of setWithoutUpstream. A failed +// not-found cleanup does not stop the backend write: reads check the backend +// first, so caching the value is right either way. func (c *Client[T]) setManyWithoutUpstream(ctx context.Context, values map[string]T) error { if len(values) == 0 { return nil } + var errs []error if c.notFoundCache != nil { keys := make([]string, 0, len(values)) for key := range values { keys = append(keys, key) } if err := delMany(ctx, c.notFoundCache, keys); err != nil { - return errors.Wrap(err, "delete from notFoundCache failed") + errs = append(errs, errors.Wrap(err, "delete from notFoundCache failed")) } } if err := setMany(ctx, c.backend, values); err != nil { - return errors.Wrap(err, "set in backend failed") + errs = append(errs, errors.Wrap(err, "set in backend failed")) } - return nil + return stderrors.Join(errs...) } // delManyWithoutUpstream is the batch form of delWithoutUpstream. @@ -446,6 +429,7 @@ func (c *Client[T]) delManyWithoutUpstream(ctx context.Context, keys []string) e if len(keys) == 0 { return nil } + var errs []error if c.notFoundCache != nil { now := NowFunc() cachedAts := make(map[string]time.Time, len(keys)) @@ -453,13 +437,14 @@ func (c *Client[T]) delManyWithoutUpstream(ctx context.Context, keys []string) e cachedAts[key] = now } if err := setMany(ctx, c.notFoundCache, cachedAts); err != nil { - return errors.Wrap(err, "failed to set notFoundCache") + errs = append(errs, errors.Wrap(err, "failed to set notFoundCache")) } } + // the key is gone upstream, so its old value goes even if no not-found was recorded if err := delMany(ctx, c.backend, keys); err != nil { - return errors.Wrap(err, "delete from backend failed") + errs = append(errs, errors.Wrap(err, "delete from backend failed")) } - return nil + return stderrors.Join(errs...) } // asyncRefreshMany is the batch form of asyncRefresh: the stale keys of one diff --git a/batch_test.go b/batch_test.go index bb12c18..c322772 100644 --- a/batch_test.go +++ b/batch_test.go @@ -630,7 +630,7 @@ func TestClientGetManyUpstreamGoexit(t *testing.T) { assert.Equal(t, map[string]string{"a": "1"}, got) }) - t.Run("per-key upstream: the key fails instead of yielding a zero value", func(t *testing.T) { + t.Run("per-key upstream: the key is released like Get, the others are served", func(t *testing.T) { backend := NewSyncMap[string]() cli := NewClient(backend, UpstreamFunc[string](func(_ context.Context, key string) (string, error) { if key == "bad" { @@ -639,11 +639,13 @@ func TestClientGetManyUpstreamGoexit(t *testing.T) { return "v-" + key, nil })) - got, err := cli.GetMany(context.Background(), []string{"a", "bad"}) + ctx, cancel := context.WithTimeout(context.Background(), 50*time.Millisecond) + defer cancel() + got, err := cli.GetMany(ctx, []string{"a", "bad"}) assert.Equal(t, map[string]string{"a": "v-a"}, got) var be *BatchError require.ErrorAs(t, err, &be) - assert.Contains(t, be.Errors, "bad") + assert.ErrorIs(t, be.Errors["bad"], context.DeadlineExceeded, "waiters wait for their ctx, like Get") _, err = backend.Get(context.Background(), "bad") assert.True(t, IsErrKeyNotFound(err), "nothing is written for the key") }) @@ -796,6 +798,199 @@ func TestClientGetManyWholeBatchErrorInterplay(t *testing.T) { }) } +// keyFailingCache is a Cache (not a BatchCache) whose Set and Del fail for bad. +type keyFailingCache[T any] struct { + m *SyncMap[T] + bad string +} + +func (c keyFailingCache[T]) Get(ctx context.Context, key string) (T, error) { return c.m.Get(ctx, key) } + +func (c keyFailingCache[T]) Set(ctx context.Context, key string, value T) error { + if key == c.bad { + return errors.New("boom") + } + return c.m.Set(ctx, key, value) +} + +func (c keyFailingCache[T]) Del(ctx context.Context, key string) error { + if key == c.bad { + return errors.New("boom") + } + return c.m.Del(ctx, key) +} + +func TestClientGetManyPerKeyFallbackIsPerKey(t *testing.T) { + ctx := context.Background() + + t.Run("every key gets its own fetch timeout", func(t *testing.T) { + up := UpstreamFunc[string](func(ctx context.Context, key string) (string, error) { + select { + case <-time.After(30 * time.Millisecond): + return key, nil + case <-ctx.Done(): + return "", ctx.Err() + } + }) + cli := NewClient[string](NewSyncMap[string](), up, + WithFetchTimeout[string](100*time.Millisecond), WithGetManyConcurrency[string](1)) + keys := make([]string, 10) + for i := range keys { + keys[i] = fmt.Sprintf("k%d", i) + } + got, err := cli.GetMany(ctx, keys) + require.NoError(t, err, "10 fetches of 30ms each run one at a time; none exceeds 100ms on its own") + assert.Len(t, got, 10) + }) + + t.Run("a key is published as soon as it is fetched, not when the whole batch is", func(t *testing.T) { + slowEntered, releaseSlow := make(chan struct{}), make(chan struct{}) + up := UpstreamFunc[string](func(_ context.Context, key string) (string, error) { + if key == "slow" { + close(slowEntered) + <-releaseSlow + } + return "v-" + key, nil + }) + cli := NewClient[string](NewSyncMap[string](), up, WithGetManyConcurrency[string](2)) + + done := make(chan struct{}) + go func() { + defer close(done) + _, _ = cli.GetMany(ctx, []string{"fast", "slow"}) + }() + waitFor(t, slowEntered) + getCtx, cancel := context.WithTimeout(ctx, time.Second) + defer cancel() + v, err := cli.Get(getCtx, "fast") + close(releaseSlow) + <-done + require.NoError(t, err, "a Get of fast does not wait for slow") + assert.Equal(t, "v-fast", v) + }) +} + +func TestClientGetManyNotFoundCacheFailureKeepsBackendWrites(t *testing.T) { + ctx := context.Background() + + t.Run("found values are still cached", func(t *testing.T) { + backend := NewSyncMap[string]() + notFound := keyFailingCache[time.Time]{m: NewSyncMap[time.Time](), bad: "bad"} + up := &batchUpstream{data: map[string]string{"a": "1", "bad": "2"}} + cli := NewClient(backend, up, NotFoundWithTTL[string](notFound, time.Hour, 0)) + + got, err := cli.GetMany(ctx, []string{"a", "bad"}) + require.NoError(t, err, "a failed cache write is logged, like Get") + assert.Equal(t, map[string]string{"a": "1", "bad": "2"}, got) + v, err := backend.Get(ctx, "a") + require.NoError(t, err, "one key's not-found cleanup failing does not stop the others being cached") + assert.Equal(t, "1", v) + }) + + t.Run("keys gone upstream are still deleted from the backend", func(t *testing.T) { + backend := NewSyncMap[string]() + require.NoError(t, backend.Set(ctx, "a", "old")) + require.NoError(t, backend.Set(ctx, "bad", "old")) + notFound := keyFailingCache[time.Time]{m: NewSyncMap[time.Time](), bad: "bad"} + up := &batchUpstream{data: map[string]string{}} + cli := NewClient(backend, up, NotFoundWithTTL[string](notFound, time.Hour, 0), + WithStale[string](func(string) State { return StateRotten })) + + got, err := cli.GetMany(ctx, []string{"a", "bad"}) + require.NoError(t, err) + assert.Empty(t, got) + _, err = backend.Get(ctx, "a") + assert.True(t, IsErrKeyNotFound(err), "one key's not-found write failing does not keep the others' old values") + _, err = backend.Get(ctx, "bad") + assert.True(t, IsErrKeyNotFound(err), "nor its own") + }) +} + +func TestClientGetManyCoverageGaps(t *testing.T) { + ctx := context.Background() + + t.Run("WithFetchConcurrency bounds the fetches of one key across GetMany calls", func(t *testing.T) { + var calls atomic.Int32 + release := make(chan struct{}) + up := UpstreamFunc[string](func(_ context.Context, key string) (string, error) { + calls.Add(1) + <-release + return "v-" + key, nil + }) + // DoubleCheck makes a caller that claims after a slot finished reuse its value + cli := NewClient[string](NewSyncMap[string](), up, WithFetchConcurrency[string](3), + WithDoubleCheck[string](DoubleCheckEnabled)) + + var wg sync.WaitGroup + for range 30 { + wg.Go(func() { + got, err := cli.GetMany(ctx, []string{"k"}) + assert.NoError(t, err) + assert.Equal(t, map[string]string{"k": "v-k"}, got) + }) + } + require.Eventually(t, func() bool { return calls.Load() >= 1 }, time.Second, time.Millisecond) + close(release) + wg.Wait() + assert.LessOrEqual(t, calls.Load(), int32(3), "at most one fetch per slot") + }) + + t.Run("a stale not-found is served as absent and refreshed in the background", func(t *testing.T) { + clock := NewMockClock(time.Now()) + defer clock.Install()() + notFound := NewSyncMap[time.Time]() + require.NoError(t, notFound.Set(ctx, "k", NowFunc())) + clock.Advance(time.Minute) // past fresh, within stale + backend := NewSyncMap[string]() + up := &batchUpstream{data: map[string]string{"k": "now-exists"}} + cli := NewClient(backend, up, + NotFoundWithTTL[string](notFound, time.Second, time.Hour), + WithServeStale[string](true)) + + got, err := cli.GetMany(ctx, []string{"k"}) + require.NoError(t, err) + assert.Empty(t, got, "the stale not-found is served") + require.Eventually(t, func() bool { + v, err := backend.Get(ctx, "k") + return err == nil && v == "now-exists" + }, time.Second, time.Millisecond, "and refreshed in the background") + }) + + t.Run("Get and GetMany share the background refresh of a stale key", func(t *testing.T) { + clock := NewMockClock(time.Now()) + defer clock.Install()() + var calls atomic.Int32 + entered, release := make(chan struct{}), make(chan struct{}) + up := UpstreamFunc[*Entry[string]](func(context.Context, string) (*Entry[string], error) { + if calls.Add(1) == 1 { + close(entered) + <-release + } + return &Entry[string]{Data: "new", CachedAt: NowFunc()}, nil + }) + backend := NewSyncMap[*Entry[string]]() + require.NoError(t, backend.Set(ctx, "k", &Entry[string]{Data: "old", CachedAt: NowFunc()})) + clock.Advance(2 * time.Minute) // stale + cli := NewClient(backend, up, + EntryWithTTL[string](time.Minute, time.Hour), + WithServeStale[*Entry[string]](true)) + + v, err := cli.Get(ctx, "k") + require.NoError(t, err) + assert.Equal(t, "old", v.Data) + waitFor(t, entered) // Get's refresh is in flight + got, err := cli.GetMany(ctx, []string{"k"}) + require.NoError(t, err) + assert.Equal(t, "old", got["k"].Data) + close(release) + require.Eventually(t, func() bool { + e, err := backend.Get(ctx, "k") + return err == nil && e.Data == "new" + }, time.Second, time.Millisecond) + assert.Equal(t, int32(1), calls.Load(), "GetMany does not start a second refresh") + }) +} + func TestRedisCacheGetManyPerKeyErrors(t *testing.T) { ctx := context.Background() cache, mr := newRedisCache[string](t) diff --git a/client.go b/client.go index 15e81d3..3fc801b 100644 --- a/client.go +++ b/client.go @@ -274,19 +274,7 @@ func (c *Client[T]) fetchFromUpstreamWithSFKey(ctx context.Context, key string, f, leader := c.flights.claim(sfKey) if leader { - go func() { - returned := false - defer func() { - if !returned { - // runtime.Goexit in the upstream: release the key without - // publishing, like x/sync/singleflight; waiters wait for their ctx. - c.flights.forget(sfKey, f) - } - }() - value, err := c.fetchClaimed(ctx, key) - returned = true - c.flights.finish(sfKey, f, value, err) - }() + go c.runClaimed(ctx, key, sfKey, f) } select { @@ -303,6 +291,21 @@ func (c *Client[T]) fetchFromUpstreamWithSFKey(ctx context.Context, key string, } } +// runClaimed fetches a key this request has claimed and publishes the result. +func (c *Client[T]) runClaimed(ctx context.Context, key, sfKey string, f *flight[T]) { + returned := false + defer func() { + if !returned { + // runtime.Goexit in the upstream: release the key without + // publishing, like x/sync/singleflight; waiters wait for their ctx. + c.flights.forget(sfKey, f) + } + }() + value, err := c.fetchClaimed(ctx, key) + returned = true + c.flights.finish(sfKey, f, value, err) +} + // fetchClaimed fetches a key this request has claimed in the flight group. func (c *Client[T]) fetchClaimed(ctx context.Context, key string) (result T, resultErr error) { if c.testHooks != nil && c.testHooks.afterSingleflightStart != nil { @@ -479,10 +482,10 @@ func WithFetchConcurrency[T any](concurrency int) ClientOption[T] { } } -// WithGetManyConcurrency sets the maximum number of concurrent upstream.Get -// calls one GetMany makes for its missing keys when the upstream does not -// implement BatchUpstream (default DefaultGetManyConcurrency). It does not -// apply to a BatchUpstream, which gets one GetMany call. +// WithGetManyConcurrency sets the maximum number of keys one GetMany fetches +// at a time when the upstream does not implement BatchUpstream (default +// DefaultGetManyConcurrency); each is fetched as Get would, with its own fetch +// timeout. It does not apply to a BatchUpstream, which gets one GetMany call. func WithGetManyConcurrency[T any](concurrency int) ClientOption[T] { return func(c *Client[T]) { c.getManyConc = concurrency From c4ba2d3ff9d66580c487fae9bf07fc69ffbc0788 Mon Sep 17 00:00:00 2001 From: molon <3739161+molon@users.noreply.github.com> Date: Thu, 8 Oct 2026 18:00:21 +0800 Subject: [PATCH 10/40] fix: claim per-key fetches only when they start, and stop on a canceled GetMany - Without BatchUpstream, GetMany claims each key only when a slot is free and then fetches it exactly as Get would. Before, every key was claimed up front, so a plain Get of a key still queued there waited for the whole queue; and a canceled GetMany kept fetching every queued key. - A serve-stale refresh of many keys key by key is no longer bounded as a whole (each key has its own fetch timeout, as in Get's refresh), and a batch refresh no longer logs keys it merely stopped waiting for as failed. - GORMCache.GetMany answers under the requested key when a case-insensitive key column (e.g. MySQL's _ci collations) returns the row under its stored key, as Get does. - README: the error-handling example compiles, and the batch example notes chunking very large id lists. --- README.md | 8 ++-- README_ZH.md | 8 ++-- batch.go | 68 ++++++++++++++++++---------- batch_test.go | 121 ++++++++++++++++++++++++++++++++++++++++++++++++++ gorm.go | 32 ++++++++++++- gorm_test.go | 27 +++++++++++ 6 files changed, 232 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index ed91ea3..8df9000 100644 --- a/README.md +++ b/README.md @@ -373,7 +373,7 @@ type BatchUpstream[T any] interface { type productSource struct{ db *gorm.DB } func (s productSource) GetMany(ctx context.Context, ids []string) (map[string]*cachex.Entry[*Product], error) { - var rows []*Product + var rows []*Product // for very large batches, query in chunks to stay under the bound-parameter limit if err := s.db.WithContext(ctx).Where("id IN ?", ids).Find(&rows).Error; err != nil { return nil, err } @@ -406,7 +406,7 @@ How `GetMany` works: 2. **Not-Found cache**: misses are checked against it, exactly like `Get`. 3. **Singleflight**: every key that needs the upstream is claimed in the **same** singleflight `Get` uses. Keys already being fetched by a `Get` or another `GetMany` are waited for, not fetched again; so a `Get` and a `GetMany` (or two overlapping `GetMany`s) fetch a shared key only once. `WithFetchConcurrency` applies per key as usual. 4. **DoubleCheck**: the claimed keys are re-checked against the backend and Not-Found cache, by the same rules as `Get`. -5. **Upstream**: if the upstream implements `BatchUpstream[T]`, the remaining keys are fetched with **one** `GetMany` call (one `WithFetchTimeout` for the whole call). Otherwise each key is fetched exactly as `Get` would (its own double-check, fetch timeout and write-back, and handed to its waiters as soon as it arrives), at most `WithGetManyConcurrency` (default 16) at a time. +5. **Upstream**: if the upstream implements `BatchUpstream[T]`, the remaining keys are fetched with **one** `GetMany` call (one `WithFetchTimeout` for the whole call). Otherwise each key is fetched exactly as `Get` would (its own double-check, fetch timeout and write-back, and handed to its waiters as soon as it arrives), at most `WithGetManyConcurrency` (default 16) at a time; a key is claimed only when its turn comes, so a concurrent `Get` of a key still queued here does not wait for the queue, and a canceled `GetMany` starts no more keys. 6. **Write back**: found values go to the backend (`SetMany` when supported), missing keys to the Not-Found cache. Like `Get`, this only touches this layer, never the upstream. `Client` implements `BatchUpstream[T]` itself, so in a layered setup a batch travels down as one call per layer: `l1Client.GetMany` → L1 batch read → `l2Client.GetMany` → L2 batch read → one database query. @@ -417,7 +417,9 @@ How `GetMany` works: products, err := client.GetMany(ctx, ids) var batchErr *cachex.BatchError if errors.As(err, &batchErr) { - for id, err := range batchErr.Errors { /* id failed */ } + for id, err := range batchErr.Errors { + log.Printf("product %s failed: %v", id, err) + } } // products is usable either way ``` diff --git a/README_ZH.md b/README_ZH.md index 4f9c42c..3d79517 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -372,7 +372,7 @@ type BatchUpstream[T any] interface { type productSource struct{ db *gorm.DB } func (s productSource) GetMany(ctx context.Context, ids []string) (map[string]*cachex.Entry[*Product], error) { - var rows []*Product + var rows []*Product // 批量很大时分块查询,免得超出数据库的绑定参数上限 if err := s.db.WithContext(ctx).Where("id IN ?", ids).Find(&rows).Error; err != nil { return nil, err } @@ -405,7 +405,7 @@ client := cachex.NewClient(cache, productSource{db: db} /* , options as in Quick 2. **Not-Found 缓存**:未命中的先查它,和 `Get` 一样。 3. **Singleflight**:每个要回源的 key 都在和 `Get` **同一个** singleflight 里认领。已经有 `Get` 或别的 `GetMany` 在取的 key,等那次的结果,不再取一遍;所以 `Get` 和 `GetMany`(或两个有交集的 `GetMany`)同时要同一个 key,只回源一次。`WithFetchConcurrency` 照旧按 key 生效。 4. **DoubleCheck**:认领到的 key 按和 `Get` 相同的规则再查一次后端和 Not-Found 缓存。 -5. **上游**:上游实现了 `BatchUpstream[T]`,剩下的 key 就调**一次** `GetMany`(整次调用共用一个 `WithFetchTimeout`)。否则每个 key 都和 `Get` 完全一样地拉取(各自 double check、各自超时、各自回填,拉到就交给等它的调用方),同时最多 `WithGetManyConcurrency` 个(默认 16)。 +5. **上游**:上游实现了 `BatchUpstream[T]`,剩下的 key 就调**一次** `GetMany`(整次调用共用一个 `WithFetchTimeout`)。否则每个 key 都和 `Get` 完全一样地拉取(各自 double check、各自超时、各自回填,拉到就交给等它的调用方),同时最多 `WithGetManyConcurrency` 个(默认 16);每个 key 轮到时才认领,所以并发的 `Get` 碰上还在这里排队的 key 不用等整个队列,`GetMany` 被取消后也不再开始新的 key。 6. **回填**:取到的值写回后端(支持就用 `SetMany`),不存在的 key 写进 Not-Found 缓存。和 `Get` 一样只写本层,不写上游。 `Client` 自己也实现了 `BatchUpstream[T]`,所以多层缓存时一批 key 每层只走一次调用:`l1Client.GetMany` → L1 批量读 → `l2Client.GetMany` → L2 批量读 → 一次数据库查询。 @@ -416,7 +416,9 @@ client := cachex.NewClient(cache, productSource{db: db} /* , options as in Quick products, err := client.GetMany(ctx, ids) var batchErr *cachex.BatchError if errors.As(err, &batchErr) { - for id, err := range batchErr.Errors { /* id 失败了 */ } + for id, err := range batchErr.Errors { + log.Printf("product %s failed: %v", id, err) + } } // 不管有没有 err,products 都能用 ``` diff --git a/batch.go b/batch.go index 69de26c..e428b01 100644 --- a/batch.go +++ b/batch.go @@ -80,8 +80,9 @@ type result[T any] struct { // GetMany is waited for, not fetched again. If the upstream implements // BatchUpstream, the keys this call claims are double-checked // (WithDoubleCheck) and fetched together with one upstream.GetMany under -// one fetch timeout. Otherwise each claimed key is fetched exactly as Get -// would, at most WithGetManyConcurrency at a time. +// one fetch timeout. Otherwise each key is fetched exactly as Get would +// (claimed only when its turn comes), at most WithGetManyConcurrency at a +// time, and a canceled GetMany starts no more keys. // - Fetched values are written to the backend (SetMany if supported) and // not-found keys to the not-found cache, without touching the upstream, // exactly like Get. @@ -236,9 +237,13 @@ func (c *Client[T]) lookupMany(ctx context.Context, keys []string, doubleCheck b return res } -// fetchMany claims every key in the flight group, fetches the claimed ones as -// one batch, and waits for all of them (including those claimed by others). +// fetchMany fetches keys through the flight group. For a BatchUpstream it +// claims every key, fetches the claimed ones as one batch, and waits for all +// of them (including those claimed by others); otherwise see fetchEach. func (c *Client[T]) fetchMany(ctx context.Context, keys, sfKeys []string) []result[T] { + if _, ok := c.upstream.(BatchUpstream[T]); !ok { + return c.fetchEach(ctx, keys, sfKeys) + } flights := make([]*flight[T], len(keys)) var ownKeys, ownSFKeys []string var ownFlights []*flight[T] @@ -252,11 +257,7 @@ func (c *Client[T]) fetchMany(ctx context.Context, keys, sfKeys []string) []resu } } if len(ownKeys) > 0 { - if _, ok := c.upstream.(BatchUpstream[T]); ok { - go c.fetchClaimedMany(ctx, ownKeys, ownSFKeys, ownFlights) - } else { - go c.runClaimedEach(ctx, ownKeys, ownSFKeys, ownFlights) - } + go c.fetchClaimedMany(ctx, ownKeys, ownSFKeys, ownFlights) } results := make([]result[T], len(keys)) @@ -275,18 +276,31 @@ func (c *Client[T]) fetchMany(ctx context.Context, keys, sfKeys []string) []resu return results } -// runClaimedEach fetches claimed keys from an upstream without batch support: -// each key exactly as Get would (own double-check, fetch timeout, write-back, -// published as soon as it is done), at most getManyConc at a time. -func (c *Client[T]) runClaimedEach(ctx context.Context, keys, sfKeys []string, flights []*flight[T]) { +// fetchEach fetches keys from an upstream without batch support, each exactly +// as Get would, at most getManyConc at a time. A key is claimed only when its +// turn comes, so a Get of a key still queued here does not wait for the queue, +// and once ctx is done no more keys are started. +func (c *Client[T]) fetchEach(ctx context.Context, keys, sfKeys []string) []result[T] { + results := make([]result[T], len(keys)) sem := make(chan struct{}, c.getManyConc) + var wg sync.WaitGroup for i, key := range keys { - sem <- struct{}{} - go func() { - defer func() { <-sem }() - c.runClaimed(ctx, key, sfKeys[i], flights[i]) - }() + if ctx.Err() == nil { + select { + case sem <- struct{}{}: + wg.Go(func() { + defer func() { <-sem }() + value, err := c.fetchFromUpstreamWithSFKey(ctx, key, sfKeys[i]) + results[i] = result[T]{value: value, err: err} + }) + continue + case <-ctx.Done(): + } + } + results[i].err = errors.Wrapf(ctx.Err(), "context cancelled during fetch for key: %s", key) } + wg.Wait() + return results } // fetchClaimedMany is the batch form of fetchClaimed for a BatchUpstream: @@ -468,14 +482,20 @@ func (c *Client[T]) asyncRefreshMany(ctx context.Context, keys []string) { c.asyncRefreshing.Delete(sfKey) } }() - // Bound the wait: some keys may be fetched by other callers, and a fetch - // that never finishes (runtime.Goexit) must not pin the whole batch. - ctx, cancel := context.WithTimeout(ctx, c.fetchTimeout) - defer cancel() + if _, ok := c.upstream.(BatchUpstream[T]); ok { + // Bound the wait: some keys may be fetched by other callers, and a + // fetch that never finishes (runtime.Goexit) must not pin the whole + // batch. Keys key by key need no bound: each has its own fetch + // timeout, as in Get's refresh. + var cancel context.CancelFunc + ctx, cancel = context.WithTimeout(ctx, c.fetchTimeout) + defer cancel() + } for i, r := range c.fetchMany(ctx, refreshKeys, sfKeys) { - if r.err != nil && !IsErrKeyNotFound(r.err) { - c.logger.ErrorContext(ctx, "async refresh failed", "key", refreshKeys[i], "error", r.err) + if r.err == nil || IsErrKeyNotFound(r.err) || ctx.Err() != nil && stderrors.Is(r.err, ctx.Err()) { + continue // a key no longer waited for is still being fetched, not failed } + c.logger.ErrorContext(ctx, "async refresh failed", "key", refreshKeys[i], "error", r.err) } }() } diff --git a/batch_test.go b/batch_test.go index c322772..a2d651e 100644 --- a/batch_test.go +++ b/batch_test.go @@ -1,9 +1,11 @@ package cachex import ( + "bytes" "context" stderrors "errors" "fmt" + "log/slog" "maps" "runtime" "slices" @@ -991,6 +993,107 @@ func TestClientGetManyCoverageGaps(t *testing.T) { }) } +func TestClientGetManyPerKeyFallbackDoesNotQueueOthers(t *testing.T) { + keys := make([]string, 20) + for i := range keys { + keys[i] = fmt.Sprintf("k%02d", i) + } + + t.Run("a Get of a key still queued in a GetMany does not wait for the queue", func(t *testing.T) { + entered, release := make(chan struct{}), make(chan struct{}) + var calls atomic.Int32 + up := UpstreamFunc[string](func(_ context.Context, key string) (string, error) { + if key == "k00" { + close(entered) + <-release + } + calls.Add(1) + return "v-" + key, nil + }) + cli := NewClient[string](NewSyncMap[string](), up, WithGetManyConcurrency[string](1)) + done := make(chan struct{}) + go func() { + defer close(done) + _, _ = cli.GetMany(context.Background(), keys) + }() + waitFor(t, entered) // the GetMany's only slot is busy with k00 + + ctx, cancel := context.WithTimeout(context.Background(), time.Second) + defer cancel() + v, err := cli.Get(ctx, "k19") + close(release) + <-done + require.NoError(t, err, "k19 is not claimed until the GetMany gets to it") + assert.Equal(t, "v-k19", v) + }) + + t.Run("a canceled GetMany starts no more fetches", func(t *testing.T) { + entered, release := make(chan struct{}), make(chan struct{}) + var calls atomic.Int32 + up := UpstreamFunc[string](func(_ context.Context, key string) (string, error) { + if calls.Add(1) == 1 { + close(entered) + <-release + } + return "v-" + key, nil + }) + cli := NewClient[string](NewSyncMap[string](), up, WithGetManyConcurrency[string](1)) + ctx, cancel := context.WithCancel(context.Background()) + errc := make(chan error, 1) + go func() { + _, err := cli.GetMany(ctx, keys) + errc <- err + }() + waitFor(t, entered) + cancel() + err := <-errc + var be *BatchError + require.ErrorAs(t, err, &be) + assert.Len(t, be.Errors, 20, "every key reports the cancellation") + close(release) + assert.Never(t, func() bool { return calls.Load() > 1 }, 100*time.Millisecond, 5*time.Millisecond, + "only the fetch already started runs on") + }) +} + +func TestClientGetManyRefreshOfManyKeysLogsNoFalseFailures(t *testing.T) { + ctx := context.Background() + keys := []string{"k0", "k1", "k2", "k3", "k4", "k5"} + backend := NewSyncMap[string]() + for _, k := range keys { + require.NoError(t, backend.Set(ctx, k, "old")) + } + var logBuf syncBuffer + up := UpstreamFunc[string](func(_ context.Context, key string) (string, error) { + time.Sleep(40 * time.Millisecond) + return "v-" + key, nil + }) + cli := NewClient[string](backend, up, + WithStale[string](func(v string) State { + if v == "old" { + return StateStale + } + return StateFresh + }), + WithServeStale[string](true), + WithFetchTimeout[string](100*time.Millisecond), // each key fits, the six together do not + WithGetManyConcurrency[string](1), + WithLogger[string](slog.New(slog.NewTextHandler(&logBuf, nil)))) + + _, err := cli.GetMany(ctx, keys) + require.NoError(t, err) + require.Eventually(t, func() bool { + got, _ := backend.GetMany(ctx, keys) + for _, k := range keys { + if got[k] != "v-"+k { + return false + } + } + return true + }, 2*time.Second, 5*time.Millisecond, "every key is refreshed, each within its own fetch timeout") + assert.NotContains(t, logBuf.String(), "async refresh failed") +} + func TestRedisCacheGetManyPerKeyErrors(t *testing.T) { ctx := context.Background() cache, mr := newRedisCache[string](t) @@ -1212,3 +1315,21 @@ func TestClientGetManyReviewFixes2(t *testing.T) { assert.Equal(t, map[string]string{"a": "1"}, got) }) } + +// syncBuffer is a bytes.Buffer safe for a logger and a test to share. +type syncBuffer struct { + mu sync.Mutex + buf bytes.Buffer +} + +func (b *syncBuffer) Write(p []byte) (int, error) { + b.mu.Lock() + defer b.mu.Unlock() + return b.buf.Write(p) +} + +func (b *syncBuffer) String() string { + b.mu.Lock() + defer b.mu.Unlock() + return b.buf.String() +} diff --git a/gorm.go b/gorm.go index a3fa529..1c01b37 100644 --- a/gorm.go +++ b/gorm.go @@ -181,9 +181,37 @@ func (g *GORMCache[T]) GetMany(ctx context.Context, keys []string) (map[string]T entries = append(entries, found...) } - var keyErrs map[string]error + stored := make(map[string]cacheEntry, len(entries)) for _, entry := range entries { - key := strings.TrimPrefix(entry.Key, g.keyPrefix) + stored[entry.Key] = entry + } + var folded map[string]cacheEntry + var keyErrs map[string]error + for i, key := range keys { + entry, ok := stored[prefixed[i]] + if !ok && len(entries) > 0 { + // A case-insensitive key column (e.g. MySQL's default _ci collations) + // returns the row under its stored key; answer under the requested + // one, as Get does. + // Only rows no requested key matched exactly can be such rows; a + // case-sensitive column never returns them. + if folded == nil { + requested := make(map[string]bool, len(prefixed)) + for _, p := range prefixed { + requested[p] = true + } + folded = map[string]cacheEntry{} + for _, e := range entries { + if !requested[e.Key] { + folded[strings.ToLower(e.Key)] = e + } + } + } + entry, ok = folded[strings.ToLower(prefixed[i])] + } + if !ok { + continue + } var value T if err := json.Unmarshal(entry.Value, &value); err != nil { if keyErrs == nil { diff --git a/gorm_test.go b/gorm_test.go index 044b19e..61ea1b9 100644 --- a/gorm_test.go +++ b/gorm_test.go @@ -222,3 +222,30 @@ func TestGORMCacheWithClientTransaction(t *testing.T) { assert.True(t, IsErrKeyNotFound(err), "should not find value in cache after transaction rollback") assert.Equal(t, 0, fetchCount, "should not fetch from upstream during rollback test") } + +func TestGORMCacheGetManyCaseInsensitiveKeyColumn(t *testing.T) { + // SQLite's NOCASE stands in for MySQL's default _ci collations + db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{}) + require.NoError(t, err) + require.NoError(t, db.Exec(`CREATE TABLE ci (key TEXT COLLATE NOCASE PRIMARY KEY, value JSON NOT NULL, updated_at DATETIME)`).Error) + c := NewGORMCache[string](&GORMCacheConfig{DB: db, TableName: "ci", KeyPrefix: "p:"}) + ctx := context.Background() + require.NoError(t, c.Set(ctx, "ABC", "v")) + + v, err := c.Get(ctx, "abc") + require.NoError(t, err) + require.Equal(t, "v", v, "precondition: Get matches case-insensitively here") + got, err := c.GetMany(ctx, []string{"abc", "missing"}) + require.NoError(t, err) + assert.Equal(t, map[string]string{"abc": "v"}, got, "GetMany answers under the requested key, like Get") +} + +func TestGORMCacheGetManyCaseSensitiveKeyColumn(t *testing.T) { + c, _ := newGORMCache[string](t, "cs") + ctx := context.Background() + require.NoError(t, c.Set(ctx, "abc", "lower")) + require.NoError(t, c.Set(ctx, "ABC", "upper")) + got, err := c.GetMany(ctx, []string{"abc", "ABC", "Abc"}) + require.NoError(t, err) + assert.Equal(t, map[string]string{"abc": "lower", "ABC": "upper"}, got, "distinct keys stay distinct") +} From a3e687e79e89b3d549ad4e1b4ccb5c93cd83b74c Mon Sep 17 00:00:00 2001 From: molon <3739161+molon@users.noreply.github.com> Date: Thu, 8 Oct 2026 18:31:04 +0800 Subject: [PATCH 11/40] fix: GORMCache never serves another key's row on a case-insensitive key column Cache keys are case-sensitive, but on MySQL the key column Migrate creates inherits the table's (usually *_ci) collation, so "abc" and "ABC" are one row: Get("abc") returned ABC's value, and Set("abc") wrote into ABC's row. This was already so for Get on main. - Get and GetMany only return a row stored under exactly the requested key (replacing the case-folding GetMany did since c4ba2d3). - Set and SetMany rewrite the key column on conflict, so a shared row belongs to the key written last. - README and GORMCacheConfig: give the key column a byte-exact collation (MySQL: *_bin); without it keys differing in case only cost misses. --- README.md | 2 ++ README_ZH.md | 2 ++ gorm.go | 51 ++++++++++++++++++++------------------------------- gorm_test.go | 40 +++++++++++++++++++++++++++++++--------- 4 files changed, 55 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index 8df9000..22f97b7 100644 --- a/README.md +++ b/README.md @@ -215,6 +215,8 @@ if err := cache.Migrate(ctx); err != nil { } ``` +Cache keys are case-sensitive, so the `key` column should compare byte for byte. PostgreSQL and SQLite do by default; on MySQL, `Migrate` creates a `varchar(255)` with the table's collation, usually case- and accent-insensitive (`*_ci`), so give the table or the column a `*_bin` collation (e.g. `utf8mb4_bin`). Without it nothing wrong is ever served: `GORMCache` only returns the row stored under exactly the requested key, so keys differing only in case just take the row over from each other (extra misses). + ### Custom Cache Implement the `Cache[T]` interface: diff --git a/README_ZH.md b/README_ZH.md index 3d79517..1ee507f 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -215,6 +215,8 @@ if err := cache.Migrate(ctx); err != nil { } ``` +缓存 key 区分大小写,所以 `key` 列应当逐字节比较。PostgreSQL 和 SQLite 默认如此;MySQL 上 `Migrate` 建的是沿用表排序规则的 `varchar(255)`,通常不区分大小写和重音(`*_ci`),请给表或这一列设 `*_bin` 排序规则(例如 `utf8mb4_bin`)。不设也不会读到错的值:`GORMCache` 只返回 key 完全相等的那一行,只差大小写的几个 key 只会互相挤占这一行(多几次未命中)。 + ### 自定义缓存 实现 `Cache[T]` 接口: diff --git a/gorm.go b/gorm.go index 1c01b37..4036b1c 100644 --- a/gorm.go +++ b/gorm.go @@ -5,7 +5,6 @@ import ( "context" "encoding/json" "slices" - "strings" "time" "github.com/pkg/errors" @@ -14,6 +13,13 @@ import ( "gorm.io/gorm/clause" ) +// upsertEntry also rewrites the key column, so on a key column that is not +// byte-exact the row belongs to the key written last, never to another one. +var upsertEntry = clause.OnConflict{ + Columns: []clause.Column{{Name: "key"}}, + DoUpdates: clause.AssignmentColumns([]string{"key", "value", "updated_at"}), +} + // GORMCache is a cache implementation using GORM type GORMCache[T any] struct { db *gorm.DB @@ -29,7 +35,10 @@ type cacheEntry struct { UpdatedAt time.Time `gorm:"not null;index"` } -// GORMCacheConfig holds configuration for GORMCache +// GORMCacheConfig holds configuration for GORMCache. Keys are case-sensitive: +// give the key column a byte-exact collation (MySQL: *_bin). Otherwise keys +// that the column considers equal share one row, served only to the key that +// wrote it last. type GORMCacheConfig struct { // DB is the GORM database connection DB *gorm.DB @@ -101,10 +110,7 @@ func (g *GORMCache[T]) Set(ctx context.Context, key string, value T) error { tx := cmp.Or(GetGORMTx(ctx), g.db) if err := tx.WithContext(ctx). Table(g.tableName). - Clauses(clause.OnConflict{ - Columns: []clause.Column{{Name: "key"}}, - UpdateAll: true, - }). + Clauses(upsertEntry). Create(&entry).Error; err != nil { return errors.Wrapf(err, "failed to set cache entry for key: %s", key) } @@ -127,6 +133,11 @@ func (g *GORMCache[T]) Get(ctx context.Context, key string) (T, error) { } return zero, errors.Wrapf(err, "failed to get cache entry for key: %s", key) } + if entry.Key != g.prefixedKey(key) { + // a key column that is not byte-exact (e.g. MySQL's _ci collations) + // matched another key's row + return zero, errors.Wrapf(&ErrKeyNotFound{}, "key not found in gorm cache for key: %s", key) + } var value T if err := json.Unmarshal(entry.Value, &value); err != nil { @@ -185,30 +196,11 @@ func (g *GORMCache[T]) GetMany(ctx context.Context, keys []string) (map[string]T for _, entry := range entries { stored[entry.Key] = entry } - var folded map[string]cacheEntry var keyErrs map[string]error for i, key := range keys { + // exact lookup: a key column that is not byte-exact (e.g. MySQL's _ci + // collations) can return another key's row, which is not this key's value entry, ok := stored[prefixed[i]] - if !ok && len(entries) > 0 { - // A case-insensitive key column (e.g. MySQL's default _ci collations) - // returns the row under its stored key; answer under the requested - // one, as Get does. - // Only rows no requested key matched exactly can be such rows; a - // case-sensitive column never returns them. - if folded == nil { - requested := make(map[string]bool, len(prefixed)) - for _, p := range prefixed { - requested[p] = true - } - folded = map[string]cacheEntry{} - for _, e := range entries { - if !requested[e.Key] { - folded[strings.ToLower(e.Key)] = e - } - } - } - entry, ok = folded[strings.ToLower(prefixed[i])] - } if !ok { continue } @@ -246,10 +238,7 @@ func (g *GORMCache[T]) SetMany(ctx context.Context, values map[string]T) error { tx := cmp.Or(GetGORMTx(ctx), g.db) if err := tx.WithContext(ctx). Table(g.tableName). - Clauses(clause.OnConflict{ - Columns: []clause.Column{{Name: "key"}}, - UpdateAll: true, - }). + Clauses(upsertEntry). CreateInBatches(&entries, gormBatchSize).Error; err != nil { return errors.Wrap(err, "failed to set cache entries") } diff --git a/gorm_test.go b/gorm_test.go index 61ea1b9..9f5564c 100644 --- a/gorm_test.go +++ b/gorm_test.go @@ -223,21 +223,43 @@ func TestGORMCacheWithClientTransaction(t *testing.T) { assert.Equal(t, 0, fetchCount, "should not fetch from upstream during rollback test") } -func TestGORMCacheGetManyCaseInsensitiveKeyColumn(t *testing.T) { - // SQLite's NOCASE stands in for MySQL's default _ci collations +func TestGORMCacheNeverServesAnotherKeysValue(t *testing.T) { + // SQLite's NOCASE stands in for MySQL's default _ci collations, where "abc" and "ABC" are one row db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{}) require.NoError(t, err) require.NoError(t, db.Exec(`CREATE TABLE ci (key TEXT COLLATE NOCASE PRIMARY KEY, value JSON NOT NULL, updated_at DATETIME)`).Error) c := NewGORMCache[string](&GORMCacheConfig{DB: db, TableName: "ci", KeyPrefix: "p:"}) ctx := context.Background() - require.NoError(t, c.Set(ctx, "ABC", "v")) - v, err := c.Get(ctx, "abc") - require.NoError(t, err) - require.Equal(t, "v", v, "precondition: Get matches case-insensitively here") - got, err := c.GetMany(ctx, []string{"abc", "missing"}) - require.NoError(t, err) - assert.Equal(t, map[string]string{"abc": "v"}, got, "GetMany answers under the requested key, like Get") + requireMiss := func(key string) { + t.Helper() + _, err := c.Get(ctx, key) + assert.True(t, IsErrKeyNotFound(err), "Get(%q) must not see another key's row: %v", key, err) + got, err := c.GetMany(ctx, []string{key}) + require.NoError(t, err) + assert.Empty(t, got, "GetMany(%q) must not see another key's row", key) + } + requireHit := func(key, want string) { + t.Helper() + v, err := c.Get(ctx, key) + require.NoError(t, err) + assert.Equal(t, want, v) + got, err := c.GetMany(ctx, []string{key}) + require.NoError(t, err) + assert.Equal(t, map[string]string{key: want}, got) + } + + require.NoError(t, c.Set(ctx, "ABC", "upper")) + requireHit("ABC", "upper") + requireMiss("abc") + + require.NoError(t, c.Set(ctx, "abc", "lower")) // takes the shared row over + requireHit("abc", "lower") + requireMiss("ABC") + + require.NoError(t, c.SetMany(ctx, map[string]string{"ABC": "upper2"})) + requireHit("ABC", "upper2") + requireMiss("abc") } func TestGORMCacheGetManyCaseSensitiveKeyColumn(t *testing.T) { From 112cd9cb874c30bd335989e2b62814c6fcf5fb0d Mon Sep 17 00:00:00 2001 From: molon <3739161+molon@users.noreply.github.com> Date: Thu, 8 Oct 2026 19:12:51 +0800 Subject: [PATCH 12/40] fix: quote GORMCache's key column, which MySQL reserves "key" is a reserved word in MySQL, and the conditions were raw SQL fragments ("key = ?", "key IN ?"), so Get, GetMany, Del and DelMany failed with a syntax error on MySQL; this was already so on main for Get and Del. Build them from clauses so GORM quotes the column. SQLite accepts the bare word, so the test checks the SQL itself. Checked against MySQL 8.4 (default *_ci collation), PostgreSQL 16 and Redis 7: the BatchCache contract, 2500 keys across statements, keys differing only in case, and Client.GetMany over each. --- gorm.go | 22 +++++++++++++++++----- gorm_test.go | 25 +++++++++++++++++++++++++ 2 files changed, 42 insertions(+), 5 deletions(-) diff --git a/gorm.go b/gorm.go index 4036b1c..2372b97 100644 --- a/gorm.go +++ b/gorm.go @@ -13,10 +13,22 @@ import ( "gorm.io/gorm/clause" ) +// keyColumn is the key column as a clause, so GORM quotes it: "key" is a +// reserved word in MySQL. +var keyColumn = clause.Column{Name: "key"} + +func anys(keys []string) []any { + out := make([]any, len(keys)) + for i, key := range keys { + out[i] = key + } + return out +} + // upsertEntry also rewrites the key column, so on a key column that is not // byte-exact the row belongs to the key written last, never to another one. var upsertEntry = clause.OnConflict{ - Columns: []clause.Column{{Name: "key"}}, + Columns: []clause.Column{keyColumn}, DoUpdates: clause.AssignmentColumns([]string{"key", "value", "updated_at"}), } @@ -126,7 +138,7 @@ func (g *GORMCache[T]) Get(ctx context.Context, key string) (T, error) { tx := cmp.Or(GetGORMTx(ctx), g.db) if err := tx.WithContext(ctx). Table(g.tableName). - Where("key = ?", g.prefixedKey(key)). + Where(clause.Eq{Column: keyColumn, Value: g.prefixedKey(key)}). First(&entry).Error; err != nil { if errors.Is(err, gorm.ErrRecordNotFound) { return zero, errors.Wrapf(&ErrKeyNotFound{}, "key not found in gorm cache for key: %s", key) @@ -152,7 +164,7 @@ func (g *GORMCache[T]) Del(ctx context.Context, key string) error { tx := cmp.Or(GetGORMTx(ctx), g.db) if err := tx.WithContext(ctx). Table(g.tableName). - Where("key = ?", g.prefixedKey(key)). + Where(clause.Eq{Column: keyColumn, Value: g.prefixedKey(key)}). Delete(nil).Error; err != nil { return errors.Wrapf(err, "failed to delete cache entry for key: %s", key) } @@ -185,7 +197,7 @@ func (g *GORMCache[T]) GetMany(ctx context.Context, keys []string) (map[string]T var found []cacheEntry if err := tx.WithContext(ctx). Table(g.tableName). - Where("key IN ?", chunk). + Where(clause.IN{Column: keyColumn, Values: anys(chunk)}). Find(&found).Error; err != nil { return nil, errors.Wrap(err, "failed to get cache entries") } @@ -260,7 +272,7 @@ func (g *GORMCache[T]) DelMany(ctx context.Context, keys []string) error { for chunk := range slices.Chunk(prefixed, gormBatchSize) { if err := tx.WithContext(ctx). Table(g.tableName). - Where("key IN ?", chunk). + Where(clause.IN{Column: keyColumn, Values: anys(chunk)}). Delete(nil).Error; err != nil { return errors.Wrap(err, "failed to delete cache entries") } diff --git a/gorm_test.go b/gorm_test.go index 9f5564c..6d47937 100644 --- a/gorm_test.go +++ b/gorm_test.go @@ -2,6 +2,7 @@ package cachex import ( "context" + "regexp" "strings" "testing" @@ -271,3 +272,27 @@ func TestGORMCacheGetManyCaseSensitiveKeyColumn(t *testing.T) { require.NoError(t, err) assert.Equal(t, map[string]string{"abc": "lower", "ABC": "upper"}, got, "distinct keys stay distinct") } + +func TestGORMCacheQuotesTheKeyColumn(t *testing.T) { + // "key" is reserved in MySQL; SQLite accepts it bare, so check the SQL itself + cache, db := newGORMCache[string](t, "quoted") + var sqls []string + capture := func(tx *gorm.DB) { sqls = append(sqls, tx.Statement.SQL.String()) } + require.NoError(t, db.Callback().Query().After("gorm:query").Register("test:capture", capture)) + require.NoError(t, db.Callback().Delete().After("gorm:delete").Register("test:capture", capture)) + require.NoError(t, db.Callback().Create().After("gorm:create").Register("test:capture", capture)) + + ctx := context.Background() + require.NoError(t, cache.Set(ctx, "a", "1")) + _, _ = cache.Get(ctx, "a") + _, _ = cache.GetMany(ctx, []string{"a", "b"}) + require.NoError(t, cache.SetMany(ctx, map[string]string{"b": "2"})) + require.NoError(t, cache.Del(ctx, "a")) + require.NoError(t, cache.DelMany(ctx, []string{"b"})) + + require.Len(t, sqls, 6) + bare := regexp.MustCompile("(^|[^`\"])\\bkey\\b($|[^`\"])") + for _, sql := range sqls { + assert.NotRegexp(t, bare, sql, "the key column must be quoted") + } +} From fac0a92ab126815c597e4f3027ade4a0eeb029fb Mon Sep 17 00:00:00 2001 From: molon <3739161+molon@users.noreply.github.com> Date: Thu, 8 Oct 2026 19:16:16 +0800 Subject: [PATCH 13/40] fix: keep the single-key write-back in line with GetMany, and don't hide a batch refresh that times out - setWithoutUpstream/delWithoutUpstream no longer stop at a failed not-found cache write: the backend is still written, or its old value deleted, as the batch write-back already does. Before, Get (and GetMany without a BatchUpstream) kept a deleted value when the not-found cache was down. - A batch serve-stale refresh that does not finish within the fetch timeout is logged at Warn instead of not at all. - Docs: the write-back is batched only with a BatchUpstream. --- README.md | 2 +- README_ZH.md | 2 +- batch.go | 17 ++++++++++------ batch_test.go | 56 +++++++++++++++++++++++++++++++++++++++++++++++++++ client.go | 23 ++++++++++++--------- 5 files changed, 82 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 22f97b7..4432af4 100644 --- a/README.md +++ b/README.md @@ -409,7 +409,7 @@ How `GetMany` works: 3. **Singleflight**: every key that needs the upstream is claimed in the **same** singleflight `Get` uses. Keys already being fetched by a `Get` or another `GetMany` are waited for, not fetched again; so a `Get` and a `GetMany` (or two overlapping `GetMany`s) fetch a shared key only once. `WithFetchConcurrency` applies per key as usual. 4. **DoubleCheck**: the claimed keys are re-checked against the backend and Not-Found cache, by the same rules as `Get`. 5. **Upstream**: if the upstream implements `BatchUpstream[T]`, the remaining keys are fetched with **one** `GetMany` call (one `WithFetchTimeout` for the whole call). Otherwise each key is fetched exactly as `Get` would (its own double-check, fetch timeout and write-back, and handed to its waiters as soon as it arrives), at most `WithGetManyConcurrency` (default 16) at a time; a key is claimed only when its turn comes, so a concurrent `Get` of a key still queued here does not wait for the queue, and a canceled `GetMany` starts no more keys. -6. **Write back**: found values go to the backend (`SetMany` when supported), missing keys to the Not-Found cache. Like `Get`, this only touches this layer, never the upstream. +6. **Write back**: found values go to the backend, missing keys to the Not-Found cache. With a `BatchUpstream` this is one `SetMany`/`DelMany` per batch (when the backend supports it); without one, each key is written back on its own, like `Get`. Either way this only touches this layer, never the upstream. `Client` implements `BatchUpstream[T]` itself, so in a layered setup a batch travels down as one call per layer: `l1Client.GetMany` → L1 batch read → `l2Client.GetMany` → L2 batch read → one database query. diff --git a/README_ZH.md b/README_ZH.md index 1ee507f..a9c4481 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -408,7 +408,7 @@ client := cachex.NewClient(cache, productSource{db: db} /* , options as in Quick 3. **Singleflight**:每个要回源的 key 都在和 `Get` **同一个** singleflight 里认领。已经有 `Get` 或别的 `GetMany` 在取的 key,等那次的结果,不再取一遍;所以 `Get` 和 `GetMany`(或两个有交集的 `GetMany`)同时要同一个 key,只回源一次。`WithFetchConcurrency` 照旧按 key 生效。 4. **DoubleCheck**:认领到的 key 按和 `Get` 相同的规则再查一次后端和 Not-Found 缓存。 5. **上游**:上游实现了 `BatchUpstream[T]`,剩下的 key 就调**一次** `GetMany`(整次调用共用一个 `WithFetchTimeout`)。否则每个 key 都和 `Get` 完全一样地拉取(各自 double check、各自超时、各自回填,拉到就交给等它的调用方),同时最多 `WithGetManyConcurrency` 个(默认 16);每个 key 轮到时才认领,所以并发的 `Get` 碰上还在这里排队的 key 不用等整个队列,`GetMany` 被取消后也不再开始新的 key。 -6. **回填**:取到的值写回后端(支持就用 `SetMany`),不存在的 key 写进 Not-Found 缓存。和 `Get` 一样只写本层,不写上游。 +6. **回填**:取到的值写回后端,不存在的 key 写进 Not-Found 缓存。上游实现了 `BatchUpstream` 时,一批只调一次 `SetMany`/`DelMany`(后端支持的话);否则每个 key 各自回填,和 `Get` 一样。两种情况都只写本层,不写上游。 `Client` 自己也实现了 `BatchUpstream[T]`,所以多层缓存时一批 key 每层只走一次调用:`l1Client.GetMany` → L1 批量读 → `l2Client.GetMany` → L2 批量读 → 一次数据库查询。 diff --git a/batch.go b/batch.go index e428b01..a33e47a 100644 --- a/batch.go +++ b/batch.go @@ -83,9 +83,10 @@ type result[T any] struct { // one fetch timeout. Otherwise each key is fetched exactly as Get would // (claimed only when its turn comes), at most WithGetManyConcurrency at a // time, and a canceled GetMany starts no more keys. -// - Fetched values are written to the backend (SetMany if supported) and -// not-found keys to the not-found cache, without touching the upstream, -// exactly like Get. +// - Fetched values are written to the backend and not-found keys to the +// not-found cache, without touching the upstream, exactly like Get: in +// one SetMany/DelMany per batch with a BatchUpstream (if the backend is a +// BatchCache), key by key otherwise. // // The returned map holds only the keys that exist; keys that do not exist are // simply absent. If some keys failed (backend, upstream, or ctx errors), the @@ -492,10 +493,14 @@ func (c *Client[T]) asyncRefreshMany(ctx context.Context, keys []string) { defer cancel() } for i, r := range c.fetchMany(ctx, refreshKeys, sfKeys) { - if r.err == nil || IsErrKeyNotFound(r.err) || ctx.Err() != nil && stderrors.Is(r.err, ctx.Err()) { - continue // a key no longer waited for is still being fetched, not failed + switch { + case r.err == nil || IsErrKeyNotFound(r.err): + case ctx.Err() != nil && stderrors.Is(r.err, ctx.Err()): + // no longer waited for; it may still finish (or fail) on its own + c.logger.WarnContext(ctx, "async refresh not finished within the fetch timeout", "key", refreshKeys[i]) + default: + c.logger.ErrorContext(ctx, "async refresh failed", "key", refreshKeys[i], "error", r.err) } - c.logger.ErrorContext(ctx, "async refresh failed", "key", refreshKeys[i], "error", r.err) } }() } diff --git a/batch_test.go b/batch_test.go index a2d651e..1a65d36 100644 --- a/batch_test.go +++ b/batch_test.go @@ -9,6 +9,7 @@ import ( "maps" "runtime" "slices" + "strings" "sync" "sync/atomic" "testing" @@ -1094,6 +1095,61 @@ func TestClientGetManyRefreshOfManyKeysLogsNoFalseFailures(t *testing.T) { assert.NotContains(t, logBuf.String(), "async refresh failed") } +func TestClientGetNotFoundCacheFailureKeepsBackendWrites(t *testing.T) { + ctx := context.Background() + + t.Run("a found value is still cached", func(t *testing.T) { + backend := NewSyncMap[string]() + notFound := keyFailingCache[time.Time]{m: NewSyncMap[time.Time](), bad: "k"} + cli := NewClient(backend, UpstreamFunc[string](func(context.Context, string) (string, error) { return "v", nil }), + NotFoundWithTTL[string](notFound, time.Hour, 0)) + v, err := cli.Get(ctx, "k") + require.NoError(t, err) + assert.Equal(t, "v", v) + v, err = backend.Get(ctx, "k") + require.NoError(t, err, "like GetMany, a failed not-found cleanup does not stop the backend write") + assert.Equal(t, "v", v) + }) + + t.Run("a key gone upstream is still deleted from the backend", func(t *testing.T) { + backend := NewSyncMap[string]() + require.NoError(t, backend.Set(ctx, "k", "old")) + notFound := keyFailingCache[time.Time]{m: NewSyncMap[time.Time](), bad: "k"} + cli := NewClient(backend, UpstreamFunc[string](func(context.Context, string) (string, error) { return "", &ErrKeyNotFound{} }), + NotFoundWithTTL[string](notFound, time.Hour, 0), + WithStale[string](func(string) State { return StateRotten })) + _, err := cli.Get(ctx, "k") + require.True(t, IsErrKeyNotFound(err)) + _, err = backend.Get(ctx, "k") + assert.True(t, IsErrKeyNotFound(err), "like GetMany, the old value goes even if no not-found was recorded") + }) +} + +func TestClientGetManyBatchRefreshThatTimesOutIsLogged(t *testing.T) { + ctx := context.Background() + clock := NewMockClock(time.Now()) + defer clock.Install()() + backend := NewSyncMap[*Entry[string]]() + require.NoError(t, backend.Set(ctx, "k", &Entry[string]{Data: "old", CachedAt: NowFunc()})) + clock.Advance(2 * time.Minute) // stale + var logBuf syncBuffer + up := batchUpstreamFunc[*Entry[string]](func(ctx context.Context, _ []string) (map[string]*Entry[string], error) { + <-ctx.Done() // hangs until its fetch timeout + return nil, ctx.Err() + }) + cli := NewClient(backend, up, + EntryWithTTL[string](time.Minute, time.Hour), + WithServeStale[*Entry[string]](true), + WithFetchTimeout[*Entry[string]](50*time.Millisecond), + WithLogger[*Entry[string]](slog.New(slog.NewTextHandler(&logBuf, nil)))) + + got, err := cli.GetMany(ctx, []string{"k"}) + require.NoError(t, err) + assert.Equal(t, "old", got["k"].Data) + require.Eventually(t, func() bool { return strings.Contains(logBuf.String(), "async refresh") }, + 2*time.Second, 5*time.Millisecond, "a refresh that never finishes in time is not silent") +} + func TestRedisCacheGetManyPerKeyErrors(t *testing.T) { ctx := context.Background() cache, mr := newRedisCache[string](t) diff --git a/client.go b/client.go index 3fc801b..d4e5ca1 100644 --- a/client.go +++ b/client.go @@ -2,6 +2,7 @@ package cachex import ( "context" + stderrors "errors" "fmt" "log/slog" "math/rand/v2" @@ -200,18 +201,19 @@ func (c *Client[T]) Del(ctx context.Context, key string) error { return nil } +// delWithoutUpstream records a not-found and deletes the backend entry; a +// failed not-found write does not keep the old value. func (c *Client[T]) delWithoutUpstream(ctx context.Context, key string) error { + var errs []error if c.notFoundCache != nil { if err := c.notFoundCache.Set(ctx, key, NowFunc()); err != nil { - return errors.Wrapf(err, "failed to set notFoundCache for key: %s", key) + errs = append(errs, errors.Wrapf(err, "failed to set notFoundCache for key: %s", key)) } } - if err := c.backend.Del(ctx, key); err != nil { - return errors.Wrapf(err, "delete from backend failed for key: %s", key) + errs = append(errs, errors.Wrapf(err, "delete from backend failed for key: %s", key)) } - - return nil + return stderrors.Join(errs...) } // Set stores a value in the cache and propagates through cache layers. @@ -247,18 +249,19 @@ func (c *Client[T]) Set(ctx context.Context, key string, value T) error { return nil } +// setWithoutUpstream clears a cached not-found and writes the backend; a failed +// not-found cleanup does not stop the write, since reads check the backend first. func (c *Client[T]) setWithoutUpstream(ctx context.Context, key string, value T) error { + var errs []error if c.notFoundCache != nil { if err := c.notFoundCache.Del(ctx, key); err != nil { - return errors.Wrapf(err, "delete from notFoundCache failed for key: %s", key) + errs = append(errs, errors.Wrapf(err, "delete from notFoundCache failed for key: %s", key)) } } - if err := c.backend.Set(ctx, key, value); err != nil { - return errors.Wrapf(err, "set in backend failed for key: %s", key) + errs = append(errs, errors.Wrapf(err, "set in backend failed for key: %s", key)) } - - return nil + return stderrors.Join(errs...) } func (c *Client[T]) fetchFromUpstream(ctx context.Context, key string) (T, error) { From 750d0527b81e01a44607b292b1e11af5cd041356 Mon Sep 17 00:00:00 2001 From: molon <3739161+molon@users.noreply.github.com> Date: Wed, 7 Oct 2026 03:08:20 +0800 Subject: [PATCH 14/40] feat: write the upstream before this layer, and guard backfills Set and Del now write the upstream first (when it is a Cache[T]) and this layer only after it succeeds. If the upstream write fails its state is unknown, so this layer drops its entry and cached not-found for the key and returns the error; the next read goes down. A failed Del drops this layer's entry without caching a not-found. Concurrent Set/Del of one key through the same Client are serialized (striped locks), so every layer applies them in the same order. Backfills are guarded by a per-key write generation (striped atomic counters, fixed size): Get, GetMany and the serve-stale refresh take it before reading the upstream, skip the backfill if a Set/Del happened since, and undo a backfill that raced one. A read that fetched an old value still returns it but no longer overwrites a newer one. Behavior change (intended): a Set becomes visible in this layer only after the write below succeeds; a failed upstream write no longer leaves the new value in this layer (it leaves no entry); a failed upstream Del no longer records a not-found in this layer. --- README.md | 10 +- README_ZH.md | 10 +- batch.go | 20 +++ client.go | 127 ++++++++++++--- write_order_test.go | 368 ++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 511 insertions(+), 24 deletions(-) create mode 100644 write_order_test.go diff --git a/README.md b/README.md index 4432af4..2b997ef 100644 --- a/README.md +++ b/README.md @@ -317,7 +317,7 @@ This design naturally supports both caching patterns: ```go // All cache layers stay in sync - l1Client.Set(ctx, key, value) // → L1 → L2 → ... → (stops at data source) + l1Client.Set(ctx, key, value) // writes ... → L2 → L1, bottom layer first (stops at data source) ``` - **Cache-Aside Pattern (Cache + Database):** @@ -329,6 +329,14 @@ This design naturally supports both caching patterns: The key insight: **cache writes propagate through `Cache[T]` chains but stop when upstream doesn't implement `Cache[T]`**, making it safe and correct for both patterns. +**Write order and consistency:** + +- `Set`/`Del` write the **upstream first**, then this layer, so an upper layer never holds a value the layer below does not. A `Set` becomes visible in this layer only after the write below has succeeded. +- If the upstream write fails, its state is unknown (it may have been applied with only the reply lost), so this layer **drops** its entry for the key (and any cached Not-Found) and returns the error; the next read goes down. A failed `Del` likewise drops this layer's entry but caches no Not-Found. +- Concurrent `Set`/`Del` of one key through the same `Client` are applied one at a time, in the same order on every layer. +- A read that fetched a value **before** a concurrent `Set`/`Del` still returns what it fetched, but does not write it back over the newer value (each `Client` keeps a per-key write generation; `Get`, `GetMany` and the serve-stale refresh all check it before backfilling). The cost is at most an extra cache miss. +- These guarantees hold within one process; separate processes sharing a lower layer (e.g. Redis) can still briefly disagree in their memory layers. + ### Not-Found Caching Prevent repeated lookups for non-existent keys: diff --git a/README_ZH.md b/README_ZH.md index a9c4481..df7b7e7 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -317,7 +317,7 @@ L1 缓存 → L2 缓存 → L3 缓存 → 数据库 ```go // 所有缓存层保持同步 - l1Client.Set(ctx, key, value) // → L1 → L2 → ... → (在数据源处停止) + l1Client.Set(ctx, key, value) // 按 ... → L2 → L1 的顺序写,先写下层(在数据源处停止) ``` - **Cache-Aside 模式(缓存 + 数据库):** @@ -329,6 +329,14 @@ L1 缓存 → L2 缓存 → L3 缓存 → 数据库 核心机制:**缓存写操作会在 `Cache[T]` 链上传播,但在 upstream 未实现 `Cache[T]` 时自动停止**,这使得两种模式都安全正确。 +**写入顺序与一致性:** + +- `Set`/`Del` **先写 upstream**,再写本层,所以上层永远不会持有下层没有的值。`Set` 的新值要等下层写成功后才在本层可见。 +- upstream 写失败时,它的状态不明(可能已经写进去了,只是回复丢了),所以本层会**删掉**这个 key 的条目(连同缓存的 Not-Found),并返回错误;下次读会回源到下层。`Del` 失败时同样删掉本层条目,但不记 Not-Found。 +- 通过同一个 `Client` 并发 `Set`/`Del` 同一个 key 时,逐个执行,各层的写入顺序一致。 +- 回源读到值**之后**、写回本层**之前**如果发生了 `Set`/`Del`,这次读仍然返回它读到的值,但不会用它覆盖更新的值(每个 `Client` 给每个 key 记一个写入代数,`Get`、`GetMany` 和 serve-stale 的后台刷新回填前都会核对)。代价最多是多一次缓存未命中。 +- 这些保证在单个进程内成立;多个进程共用同一个下层(例如 Redis)时,各自的内存层仍可能短暂不一致。 + ### Not-Found 缓存 防止对不存在 key 的重复查询: diff --git a/batch.go b/batch.go index a33e47a..37d7e97 100644 --- a/batch.go +++ b/batch.go @@ -385,6 +385,11 @@ func (c *Client[T]) fetchClaimedMany(ctx context.Context, keys, sfKeys []string, // then write the results to this layer only. func (c *Client[T]) doFetchMany(ctx context.Context, keys []string) []result[T] { results := make([]result[T], len(keys)) + gens := make([]uint64, len(keys)) + for i, key := range keys { + gens[i] = c.stripe(key).gen.Load() + } + values, err := c.upstream.(BatchUpstream[T]).GetMany(ctx, keys) for i, key := range keys { if kerr := errForKey(err, key); kerr != nil { @@ -396,15 +401,25 @@ func (c *Client[T]) doFetchMany(ctx context.Context, keys []string) []result[T] } } + // The batch form of backfill: skip keys written since their gen was taken, + // and undo the ones written while the backfill ran. + written := func(i int) bool { return c.stripe(keys[i]).gen.Load() != gens[i] } found := map[string]T{} var notFound []string + var filled []int for i, key := range keys { + if written(i) { + continue + } switch { case results[i].err == nil: found[key] = results[i].value case IsErrKeyNotFound(results[i].err): notFound = append(notFound, key) + default: + continue } + filled = append(filled, i) } if err := c.setManyWithoutUpstream(ctx, found); err != nil { c.logger.WarnContext(ctx, "failed to set cache entries", "error", err) @@ -412,6 +427,11 @@ func (c *Client[T]) doFetchMany(ctx context.Context, keys []string) []result[T] if err := c.delManyWithoutUpstream(ctx, notFound); err != nil { c.logger.WarnContext(ctx, "failed to delete cache entries", "error", err) } + for _, i := range filled { + if written(i) { + c.invalidate(ctx, keys[i]) + } + } return results } diff --git a/client.go b/client.go index d4e5ca1..8d340fb 100644 --- a/client.go +++ b/client.go @@ -4,10 +4,12 @@ import ( "context" stderrors "errors" "fmt" + "hash/maphash" "log/slog" "math/rand/v2" "runtime/debug" "sync" + "sync/atomic" "time" "github.com/pkg/errors" @@ -40,6 +42,10 @@ type Client[T any] struct { flights flightGroup[T] asyncRefreshing sync.Map + // Write ordering, see Set and backfill + writeSeed maphash.Seed + writes [writeStripeCount]writeStripe + // Double-check optimization doubleCheckMode DoubleCheckMode // User configuration (immutable) enableDoubleCheck bool // Resolved execution decision @@ -71,6 +77,7 @@ func NewClient[T any](backend Cache[T], upstream Upstream[T], opts ...ClientOpti getManyConc: DefaultGetManyConcurrency, logger: slog.Default(), doubleCheckMode: DoubleCheckAuto, // Default: auto (smart heuristic) + writeSeed: maphash.MakeSeed(), } // Apply user options @@ -187,18 +194,20 @@ func (c *Client[T]) get(ctx context.Context, key string, doubleCheck bool) (T, e // // This supports both write-through and cache-aside patterns, as the chain // naturally terminates when upstream is not a Cache[T] implementation. +// +// Order: the upstream is deleted first, then this layer. If the upstream +// delete fails, this layer's entry is still dropped but no not-found is +// cached, since the upstream may still hold the key. func (c *Client[T]) Del(ctx context.Context, key string) error { - if err := c.delWithoutUpstream(ctx, key); err != nil { - return err - } - - if upstreamCache, ok := c.upstream.(Cache[T]); ok { - if err := upstreamCache.Del(ctx, key); err != nil { - return errors.Wrapf(err, "delete from upstream failed for key: %s", key) - } - } - - return nil + return c.write(ctx, key, + func(upstream Cache[T]) error { + if err := upstream.Del(ctx, key); err != nil { + return errors.Wrapf(err, "delete from upstream failed for key: %s", key) + } + return nil + }, + func() error { return c.delWithoutUpstream(ctx, key) }, + ) } // delWithoutUpstream records a not-found and deletes the backend entry; a @@ -235,20 +244,97 @@ func (c *Client[T]) delWithoutUpstream(ctx context.Context, key string) error { // // The type-based propagation automatically handles both write-through (multi-level caches) // and cache-aside (with data source) patterns correctly. +// +// Order: the upstream is written first, then this layer, so this layer never +// holds a value the layer below does not. If the upstream write fails, its +// state is unknown (it may have been applied and only the reply lost), so this +// layer's entry is dropped and the next read goes down. Concurrent writes to +// one key through the same Client are applied one at a time, in the same order +// on every layer. func (c *Client[T]) Set(ctx context.Context, key string, value T) error { - if err := c.setWithoutUpstream(ctx, key, value); err != nil { - return err - } + return c.write(ctx, key, + func(upstream Cache[T]) error { + if err := upstream.Set(ctx, key, value); err != nil { + return errors.Wrapf(err, "set in upstream failed for key: %s", key) + } + return nil + }, + func() error { return c.setWithoutUpstream(ctx, key, value) }, + ) +} + +// writeStripeCount is the number of write stripes per Client. +// +// ponytail: keys share stripes by hash, so two keys in one stripe serialize +// their writes and a write to one can skip the other's backfill (a spare +// cache miss, never a stale value); raise it if that shows up. +const writeStripeCount = 1024 + +// writeStripe orders writes and backfills of the keys that hash to it. +type writeStripe struct { + mu sync.Mutex // serializes Set/Del, so all layers apply them in one order + gen atomic.Uint64 // bumped by every Set/Del, checked by backfills +} + +func (c *Client[T]) stripe(key string) *writeStripe { + return &c.writes[maphash.String(c.writeSeed, key)%writeStripeCount] +} + +// write runs a Set or Del: the upstream first (if it is a Cache), then this +// layer. Any failure leaves this layer without an entry for the key. +func (c *Client[T]) write(ctx context.Context, key string, toUpstream func(Cache[T]) error, toLayer func() error) error { + s := c.stripe(key) + s.mu.Lock() + defer s.mu.Unlock() if upstreamCache, ok := c.upstream.(Cache[T]); ok { - if err := upstreamCache.Set(ctx, key, value); err != nil { - return errors.Wrapf(err, "set in upstream failed for key: %s", key) + if err := toUpstream(upstreamCache); err != nil { + s.gen.Add(1) + c.invalidate(ctx, key) + return err } } + // Bumped after the upstream write and before this layer's: a backfill that + // read the upstream before the write either lands before this layer's + // write (and is overwritten) or sees the bump (and is skipped or undone). + s.gen.Add(1) + if err := toLayer(); err != nil { + c.invalidate(ctx, key) + return err + } return nil } +// invalidate drops this layer's entry and cached not-found for key, best effort. +func (c *Client[T]) invalidate(ctx context.Context, key string) { + if c.notFoundCache != nil { + if err := c.notFoundCache.Del(ctx, key); err != nil { + c.logger.WarnContext(ctx, "failed to invalidate notFoundCache entry", "key", key, "error", err) + } + } + if err := c.backend.Del(ctx, key); err != nil { + c.logger.WarnContext(ctx, "failed to invalidate cache entry", "key", key, "error", err) + } +} + +// backfill writes what a fetch read into this layer, unless a Set or Del of +// the key happened since gen was taken (before reading the upstream). A +// write that slips in between the check and the backfill is caught right +// after, and the backfill is undone, leaving a miss rather than a stale value. +func (c *Client[T]) backfill(ctx context.Context, key string, gen uint64, fill func() error, failMsg string) { + s := c.stripe(key) + if s.gen.Load() != gen { + return + } + if err := fill(); err != nil { + c.logger.WarnContext(ctx, failMsg, "key", key, "error", err) + } + if s.gen.Load() != gen { + c.invalidate(ctx, key) + } +} + // setWithoutUpstream clears a cached not-found and writes the backend; a failed // not-found cleanup does not stop the write, since reads check the backend first. func (c *Client[T]) setWithoutUpstream(ctx context.Context, key string, value T) error { @@ -382,20 +468,17 @@ func (c *Client[T]) asyncRefresh(ctx context.Context, key string) { } func (c *Client[T]) doFetch(ctx context.Context, key string) (T, error) { + gen := c.stripe(key).gen.Load() value, err := c.upstream.Get(ctx, key) if err != nil { if IsErrKeyNotFound(err) { - if delErr := c.delWithoutUpstream(ctx, key); delErr != nil { - c.logger.WarnContext(ctx, "failed to delete cache entry", "key", key, "error", delErr) - } + c.backfill(ctx, key, gen, func() error { return c.delWithoutUpstream(ctx, key) }, "failed to delete cache entry") } var zero T return zero, errors.Wrapf(err, "get from upstream failed for key: %s", key) } - if setErr := c.setWithoutUpstream(ctx, key, value); setErr != nil { - c.logger.WarnContext(ctx, "failed to set cache entry", "key", key, "error", setErr) - } + c.backfill(ctx, key, gen, func() error { return c.setWithoutUpstream(ctx, key, value) }, "failed to set cache entry") return value, nil } diff --git a/write_order_test.go b/write_order_test.go new file mode 100644 index 0000000..5605871 --- /dev/null +++ b/write_order_test.go @@ -0,0 +1,368 @@ +package cachex + +import ( + "context" + "errors" + "fmt" + "math/rand/v2" + "sync" + "sync/atomic" + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func assertMissing(t *testing.T, c Cache[string], key string, msg string) { + t.Helper() + v, err := c.Get(context.Background(), key) + assert.True(t, IsErrKeyNotFound(err), "%s (got %q, %v)", msg, v, err) +} + +func TestSetWritesUpstreamBeforeThisLayer(t *testing.T) { + ctx := context.Background() + backend := NewSyncMap[string]() + require.NoError(t, backend.Set(ctx, "k", "old")) + up := newHookedCache() + var seenInLayer string + up.beforeSet = func(key, _ string) error { + seenInLayer, _ = backend.Get(ctx, key) + return nil + } + cli := NewClient[string](backend, up) + + require.NoError(t, cli.Set(ctx, "k", "new")) + assert.Equal(t, "old", seenInLayer, "this layer still has the old value while the upstream is written") + v, _ := backend.Get(ctx, "k") + assert.Equal(t, "new", v) + v, _ = up.Get(ctx, "k") + assert.Equal(t, "new", v) +} + +func TestSetUpstreamFailureDropsThisLayersEntry(t *testing.T) { + ctx := context.Background() + boom := errors.New("boom") + + t.Run("cached value", func(t *testing.T) { + backend := NewSyncMap[string]() + require.NoError(t, backend.Set(ctx, "k", "old")) + up := newHookedCache() + up.beforeSet = func(string, string) error { return boom } + cli := NewClient[string](backend, up) + + err := cli.Set(ctx, "k", "new") + require.ErrorIs(t, err, boom) + assert.Equal(t, "set in upstream failed for key: k: boom", err.Error()) + assertMissing(t, backend, "k", "neither the new value nor the old one stays: the upstream state is unknown") + }) + + t.Run("cached not-found", func(t *testing.T) { + notFound := NewSyncMap[time.Time]() + backend := NewSyncMap[string]() + up := newHookedCache() + cli := NewClient[string](backend, up, NotFoundWithTTL[string](notFound, time.Hour, 0)) + _, err := cli.Get(ctx, "k") + require.True(t, IsErrKeyNotFound(err)) + _, err = notFound.Get(ctx, "k") + require.NoError(t, err, "precondition: not-found is cached") + + up.beforeSet = func(string, string) error { return boom } + require.ErrorIs(t, cli.Set(ctx, "k", "new"), boom) + _, err = notFound.Get(ctx, "k") + assert.True(t, IsErrKeyNotFound(err), "the cached not-found is dropped too, so the next read goes down") + }) +} + +func TestDelUpstreamFirst(t *testing.T) { + ctx := context.Background() + boom := errors.New("boom") + + t.Run("deletes the upstream before this layer", func(t *testing.T) { + backend := NewSyncMap[string]() + require.NoError(t, backend.Set(ctx, "k", "v")) + up := newHookedCache() + var seenInLayer string + up.beforeDel = func(key string) error { + seenInLayer, _ = backend.Get(ctx, key) + return nil + } + cli := NewClient[string](backend, up) + require.NoError(t, cli.Del(ctx, "k")) + assert.Equal(t, "v", seenInLayer) + assertMissing(t, backend, "k", "deleted from this layer afterwards") + require.NoError(t, cli.Del(ctx, "k"), "Del stays idempotent") + }) + + t.Run("upstream failure still drops this layer's entry but caches no not-found", func(t *testing.T) { + notFound := NewSyncMap[time.Time]() + backend := NewSyncMap[string]() + require.NoError(t, backend.Set(ctx, "k", "v")) + up := newHookedCache() + up.beforeDel = func(string) error { return boom } + cli := NewClient[string](backend, up, NotFoundWithTTL[string](notFound, time.Hour, 0)) + + err := cli.Del(ctx, "k") + require.ErrorIs(t, err, boom) + assert.Equal(t, "delete from upstream failed for key: k: boom", err.Error()) + assertMissing(t, backend, "k", "this layer's value is dropped") + _, err = notFound.Get(ctx, "k") + assert.True(t, IsErrKeyNotFound(err), "the upstream may still have the key, so no not-found is cached") + }) +} + +// slowSource is a data source whose reads can be held after they have read +// the value, to let a write slip in between the read and the backfill. +type slowSource struct { + mu sync.Mutex + data map[string]string + hold chan struct{} // when non-nil, reads wait on it after reading + entered chan struct{} +} + +func (s *slowSource) read(key string) (string, bool) { + s.mu.Lock() + v, ok := s.data[key] + hold := s.hold + s.mu.Unlock() + if hold != nil { + s.entered <- struct{}{} + <-hold + } + return v, ok +} + +func (s *slowSource) Get(_ context.Context, key string) (string, error) { + if v, ok := s.read(key); ok { + return v, nil + } + return "", &ErrKeyNotFound{} +} + +func (s *slowSource) GetMany(_ context.Context, keys []string) (map[string]string, error) { + out := map[string]string{} + for _, k := range keys { + if v, ok := s.read(k); ok { + out[k] = v + } + } + return out, nil +} + +func (s *slowSource) write(key, value string) { + s.mu.Lock() + defer s.mu.Unlock() + s.data[key] = value +} + +func (s *slowSource) holdReads() { + s.mu.Lock() + defer s.mu.Unlock() + s.hold = make(chan struct{}) + s.entered = make(chan struct{}, 100) +} + +func (s *slowSource) releaseReads() { + s.mu.Lock() + defer s.mu.Unlock() + close(s.hold) + s.hold = nil +} + +func TestBackfillDoesNotOverwriteAConcurrentSet(t *testing.T) { + ctx := context.Background() + + for _, tc := range []struct { + name string + read func(cli *Client[string]) (string, error) + }{ + {"Get", func(cli *Client[string]) (string, error) { return cli.Get(ctx, "k") }}, + {"GetMany", func(cli *Client[string]) (string, error) { + got, err := cli.GetMany(ctx, []string{"k"}) + return got["k"], err + }}, + } { + t.Run(tc.name, func(t *testing.T) { + src := &slowSource{data: map[string]string{"k": "old"}} + backend := NewSyncMap[string]() + cli := NewClient[string](backend, src) + + src.holdReads() + type res struct { + v string + err error + } + done := make(chan res, 1) + go func() { + v, err := tc.read(cli) + done <- res{v, err} + }() + <-src.entered // the fetch has read "old" + + src.write("k", "new") // cache-aside: update the source, then the cache + require.NoError(t, cli.Set(ctx, "k", "new")) + src.releaseReads() + + r := <-done + require.NoError(t, r.err) + assert.Equal(t, "old", r.v, "the read still returns what it fetched") + v, err := backend.Get(ctx, "k") + require.NoError(t, err) + assert.Equal(t, "new", v, "but does not write it over the newer value") + }) + } + + t.Run("serve-stale refresh", func(t *testing.T) { + clock := NewMockClock(time.Now()) + defer clock.Install()() + src := &slowSource{data: map[string]string{"k": "old"}} + backend := NewSyncMap[*Entry[string]]() + up := UpstreamFunc[*Entry[string]](func(ctx context.Context, key string) (*Entry[string], error) { + v, err := src.Get(ctx, key) + if err != nil { + return nil, err + } + return &Entry[string]{Data: v, CachedAt: NowFunc()}, nil + }) + cli := NewClient(backend, up, + EntryWithTTL[string](time.Minute, time.Hour), + WithServeStale[*Entry[string]](true)) + + _, err := cli.Get(ctx, "k") + require.NoError(t, err) + clock.Advance(2 * time.Minute) + + src.holdReads() + v, err := cli.Get(ctx, "k") + require.NoError(t, err) + assert.Equal(t, "old", v.Data, "stale value served") + <-src.entered // the background refresh has read "old" + + src.write("k", "new") + require.NoError(t, cli.Set(ctx, "k", &Entry[string]{Data: "new", CachedAt: NowFunc()})) + src.releaseReads() + waitAsyncRefreshDone(t, cli) + + e, err := backend.Get(ctx, "k") + require.NoError(t, err) + assert.Equal(t, "new", e.Data, "the refresh does not overwrite the newer value") + }) + + t.Run("not-found backfill", func(t *testing.T) { + src := &slowSource{data: map[string]string{}} + notFound := NewSyncMap[time.Time]() + backend := NewSyncMap[string]() + cli := NewClient[string](backend, src, NotFoundWithTTL[string](notFound, time.Hour, 0)) + + src.holdReads() + done := make(chan error, 1) + go func() { + _, err := cli.Get(ctx, "k") + done <- err + }() + <-src.entered + src.write("k", "new") + require.NoError(t, cli.Set(ctx, "k", "new")) + src.releaseReads() + assert.True(t, IsErrKeyNotFound(<-done)) + + _, err := notFound.Get(ctx, "k") + assert.True(t, IsErrKeyNotFound(err), "no not-found is cached over the value just set") + v, err := cli.Get(ctx, "k") + require.NoError(t, err) + assert.Equal(t, "new", v) + }) +} + +func TestBackfillRacingASetIsUndone(t *testing.T) { + ctx := context.Background() + for _, tc := range []struct { + name string + read func(cli *Client[string]) (string, error) + }{ + {"Get", func(cli *Client[string]) (string, error) { return cli.Get(ctx, "k") }}, + {"GetMany", func(cli *Client[string]) (string, error) { + got, err := cli.GetMany(ctx, []string{"k"}) + return got["k"], err + }}, + } { + t.Run(tc.name, func(t *testing.T) { + src := &slowSource{data: map[string]string{"k": "old"}} + backend := newHookedCache() + cli := NewClient[string](backend, src) + + // The backfill passes its check, then a Set completes before the + // backfill's own write lands. + backfillReached := make(chan struct{}) + setDone := make(chan struct{}) + var first atomic.Bool + backend.beforeSet = func(_, value string) error { + if value == "old" && first.CompareAndSwap(false, true) { + close(backfillReached) + <-setDone + } + return nil + } + + done := make(chan struct{}) + go func() { + defer close(done) + v, err := tc.read(cli) + assert.NoError(t, err) + assert.Equal(t, "old", v) + }() + <-backfillReached + src.write("k", "new") + require.NoError(t, cli.Set(ctx, "k", "new")) + close(setDone) + <-done + + v, err := cli.Get(ctx, "k") + require.NoError(t, err) + assert.Equal(t, "new", v, "the late backfill is undone, so the next read sees the new value") + }) + } +} + +func TestInterleavedSetsKeepLayersConsistent(t *testing.T) { + ctx := context.Background() + for round := range 20 { + l2Backend := newHookedCache() + l2Backend.beforeSet = func(string, string) error { + time.Sleep(time.Duration(rand.IntN(300)) * time.Microsecond) + return nil + } + l2 := NewClient[string](l2Backend, UpstreamFunc[string](func(context.Context, string) (string, error) { + return "", &ErrKeyNotFound{} + })) + l1Backend := newHookedCache() + l1Backend.beforeSet = l2Backend.beforeSet + l1 := NewClient[string](l1Backend, l2) + + var wg sync.WaitGroup + for i := range 20 { + wg.Go(func() { + if i%5 == 4 { + _ = l1.Del(ctx, "k") + } else { + _ = l1.Set(ctx, "k", fmt.Sprintf("v%d", i)) + } + }) + } + wg.Wait() + + v1, err1 := l1Backend.Get(ctx, "k") + v2, err2 := l2Backend.Get(ctx, "k") + if err1 == nil { + require.NoError(t, err2, "round %d: L1 has %q but L2 has nothing", round, v1) + assert.Equal(t, v2, v1, "round %d: L1 never holds a value L2 does not", round) + } + got, err := l1.Get(ctx, "k") + if err2 == nil { + require.NoError(t, err) + assert.Equal(t, v2, got, "round %d", round) + } else { + assert.True(t, IsErrKeyNotFound(err), "round %d", round) + } + } +} From dbdadadd9178576edd3a66fdc3a572cddcbfe2a0 Mon Sep 17 00:00:00 2001 From: molon <3739161+molon@users.noreply.github.com> Date: Thu, 8 Oct 2026 15:33:44 +0800 Subject: [PATCH 15/40] fix: serialize backfills with writes instead of undoing them afterwards - A backfill (Get, GetMany, serve-stale refresh) now holds its key's write stripe for reading while it checks the write generation and fills, and Set/Del hold it for writing. The fill either lands before a write (which then overwrites it) or is skipped; it can no longer write an old value after a Set returned, so no reader sees it. The after-the-fact undo is gone. A backfill uses TryRLock and is skipped while a write to the stripe is in progress, so reads never wait on writes. - GetMany holds every stripe of its batch for the whole fill, so the batch write and its not-found write are atomic with respect to Set/Del too. - The cleanup after a failed write runs on a detached ctx bounded by the fetch timeout, so a write that failed because its ctx was canceled still drops this layer's entry on ctx-aware backends (Redis, GORM). - README: the old value of this layer stays visible to readers until this layer's own write lands; the docs no longer claim otherwise. --- README.md | 4 +-- README_ZH.md | 4 +-- batch.go | 31 ++++++++++++++---------- batch_test.go | 9 ++++++- client.go | 35 ++++++++++++++++----------- write_order_test.go | 59 +++++++++++++++++++++++++++++++++++++++------ 6 files changed, 102 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index 2b997ef..56ef5d1 100644 --- a/README.md +++ b/README.md @@ -331,10 +331,10 @@ The key insight: **cache writes propagate through `Cache[T]` chains but stop whe **Write order and consistency:** -- `Set`/`Del` write the **upstream first**, then this layer, so an upper layer never holds a value the layer below does not. A `Set` becomes visible in this layer only after the write below has succeeded. +- `Set`/`Del` write the **upstream first**, then this layer, so a new value never shows up in an upper layer before the layer below has it: a `Set` becomes visible in this layer only after the write below has succeeded. The flip side is a short window while the write runs: until this layer's own write lands, a concurrent reader of this layer still sees its **old** value (after a `Del`, the deleted one), even though the layer below has already changed. Once `Set`/`Del` returns, the window is closed. - If the upstream write fails, its state is unknown (it may have been applied with only the reply lost), so this layer **drops** its entry for the key (and any cached Not-Found) and returns the error; the next read goes down. A failed `Del` likewise drops this layer's entry but caches no Not-Found. - Concurrent `Set`/`Del` of one key through the same `Client` are applied one at a time, in the same order on every layer. -- A read that fetched a value **before** a concurrent `Set`/`Del` still returns what it fetched, but does not write it back over the newer value (each `Client` keeps a per-key write generation; `Get`, `GetMany` and the serve-stale refresh all check it before backfilling). The cost is at most an extra cache miss. +- A read that fetched a value **before** a concurrent `Set`/`Del` still returns what it fetched, but never writes it back over the newer value: each `Client` keeps a per-key write generation, and `Get`, `GetMany` and the serve-stale refresh check it while holding the key's write lock for reading, so a backfill either lands before a `Set`/`Del` (which then overwrites it) or is skipped. A backfill is also skipped while a write to the key is in progress, so reads never wait on writes. The cost is at most an extra cache miss. - These guarantees hold within one process; separate processes sharing a lower layer (e.g. Redis) can still briefly disagree in their memory layers. ### Not-Found Caching diff --git a/README_ZH.md b/README_ZH.md index df7b7e7..e31a5bd 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -331,10 +331,10 @@ L1 缓存 → L2 缓存 → L3 缓存 → 数据库 **写入顺序与一致性:** -- `Set`/`Del` **先写 upstream**,再写本层,所以上层永远不会持有下层没有的值。`Set` 的新值要等下层写成功后才在本层可见。 +- `Set`/`Del` **先写 upstream**,再写本层,所以新值不会先于下层出现在上层:`Set` 的新值要等下层写成功后才在本层可见。代价是写入过程中有一个短暂的窗口:本层自己的写入落下之前,并发读本层仍会读到它的**旧值**(`Del` 时是已删掉的值),尽管下层已经变了。`Set`/`Del` 返回后窗口就关闭了。 - upstream 写失败时,它的状态不明(可能已经写进去了,只是回复丢了),所以本层会**删掉**这个 key 的条目(连同缓存的 Not-Found),并返回错误;下次读会回源到下层。`Del` 失败时同样删掉本层条目,但不记 Not-Found。 - 通过同一个 `Client` 并发 `Set`/`Del` 同一个 key 时,逐个执行,各层的写入顺序一致。 -- 回源读到值**之后**、写回本层**之前**如果发生了 `Set`/`Del`,这次读仍然返回它读到的值,但不会用它覆盖更新的值(每个 `Client` 给每个 key 记一个写入代数,`Get`、`GetMany` 和 serve-stale 的后台刷新回填前都会核对)。代价最多是多一次缓存未命中。 +- 回源读到值**之后**、写回本层**之前**如果发生了 `Set`/`Del`,这次读仍然返回它读到的值,但绝不会用它覆盖更新的值:每个 `Client` 给每个 key 记一个写入代数,`Get`、`GetMany` 和 serve-stale 的后台刷新在持有这个 key 所在写锁的读锁时核对它,所以回填要么在 `Set`/`Del` 之前落下(随后被覆盖),要么被跳过。这个 key 正在写入时回填也直接跳过,所以读永远不等写。代价最多是多一次缓存未命中。 - 这些保证在单个进程内成立;多个进程共用同一个下层(例如 Redis)时,各自的内存层仍可能短暂不一致。 ### Not-Found 缓存 diff --git a/batch.go b/batch.go index 37d7e97..e6e60d8 100644 --- a/batch.go +++ b/batch.go @@ -401,14 +401,27 @@ func (c *Client[T]) doFetchMany(ctx context.Context, keys []string) []result[T] } } - // The batch form of backfill: skip keys written since their gen was taken, - // and undo the ones written while the backfill ran. - written := func(i int) bool { return c.stripe(keys[i]).gen.Load() != gens[i] } + // The batch form of backfill: hold each key's stripe for reading (TryRLock + // never blocks, so no lock order is needed) and skip the keys whose stripe + // has a write in progress or whose gen moved since it was taken. + held := map[*writeStripe]bool{} + defer func() { + for s, ok := range held { + if ok { + s.mu.RUnlock() + } + } + }() found := map[string]T{} var notFound []string - var filled []int for i, key := range keys { - if written(i) { + s := c.stripe(key) + ok, seen := held[s] + if !seen { + ok = s.mu.TryRLock() + held[s] = ok + } + if !ok || s.gen.Load() != gens[i] { continue } switch { @@ -416,10 +429,7 @@ func (c *Client[T]) doFetchMany(ctx context.Context, keys []string) []result[T] found[key] = results[i].value case IsErrKeyNotFound(results[i].err): notFound = append(notFound, key) - default: - continue } - filled = append(filled, i) } if err := c.setManyWithoutUpstream(ctx, found); err != nil { c.logger.WarnContext(ctx, "failed to set cache entries", "error", err) @@ -427,11 +437,6 @@ func (c *Client[T]) doFetchMany(ctx context.Context, keys []string) []result[T] if err := c.delManyWithoutUpstream(ctx, notFound); err != nil { c.logger.WarnContext(ctx, "failed to delete cache entries", "error", err) } - for _, i := range filled { - if written(i) { - c.invalidate(ctx, keys[i]) - } - } return results } diff --git a/batch_test.go b/batch_test.go index 1a65d36..680a7af 100644 --- a/batch_test.go +++ b/batch_test.go @@ -1204,6 +1204,7 @@ func (m *missFirstBatch) GetMany(ctx context.Context, keys []string) (map[string type hookedCache struct { m *SyncMap[string] beforeSet func(key, value string) error + afterSet func(key, value string) beforeDel func(key string) error } @@ -1217,7 +1218,13 @@ func (h *hookedCache) Set(ctx context.Context, key, value string) error { return err } } - return h.m.Set(ctx, key, value) + if err := h.m.Set(ctx, key, value); err != nil { + return err + } + if h.afterSet != nil { + h.afterSet(key, value) + } + return nil } func (h *hookedCache) Del(ctx context.Context, key string) error { diff --git a/client.go b/client.go index 8d340fb..fe95b57 100644 --- a/client.go +++ b/client.go @@ -195,7 +195,8 @@ func (c *Client[T]) get(ctx context.Context, key string, doubleCheck bool) (T, e // This supports both write-through and cache-aside patterns, as the chain // naturally terminates when upstream is not a Cache[T] implementation. // -// Order: the upstream is deleted first, then this layer. If the upstream +// Order: the upstream is deleted first, then this layer, so until this layer's +// delete lands its readers still see the deleted value. If the upstream // delete fails, this layer's entry is still dropped but no not-found is // cached, since the upstream may still hold the key. func (c *Client[T]) Del(ctx context.Context, key string) error { @@ -245,8 +246,9 @@ func (c *Client[T]) delWithoutUpstream(ctx context.Context, key string) error { // The type-based propagation automatically handles both write-through (multi-level caches) // and cache-aside (with data source) patterns correctly. // -// Order: the upstream is written first, then this layer, so this layer never -// holds a value the layer below does not. If the upstream write fails, its +// Order: the upstream is written first, then this layer, so a new value never +// shows up here before it is below; until this layer's write lands, readers of +// this layer still see the old value. If the upstream write fails, its // state is unknown (it may have been applied and only the reply lost), so this // layer's entry is dropped and the next read goes down. Concurrent writes to // one key through the same Client are applied one at a time, in the same order @@ -272,7 +274,7 @@ const writeStripeCount = 1024 // writeStripe orders writes and backfills of the keys that hash to it. type writeStripe struct { - mu sync.Mutex // serializes Set/Del, so all layers apply them in one order + mu sync.RWMutex // Set/Del hold it, so all layers apply them in one order; backfills hold it for reading gen atomic.Uint64 // bumped by every Set/Del, checked by backfills } @@ -295,9 +297,8 @@ func (c *Client[T]) write(ctx context.Context, key string, toUpstream func(Cache } } - // Bumped after the upstream write and before this layer's: a backfill that - // read the upstream before the write either lands before this layer's - // write (and is overwritten) or sees the bump (and is skipped or undone). + // Bumped after the upstream write: a backfill that read the upstream before + // it took a gen older than this, so it is skipped once this lock is released. s.gen.Add(1) if err := toLayer(); err != nil { c.invalidate(ctx, key) @@ -306,8 +307,12 @@ func (c *Client[T]) write(ctx context.Context, key string, toUpstream func(Cache return nil } -// invalidate drops this layer's entry and cached not-found for key, best effort. +// invalidate drops this layer's entry and cached not-found for key, best +// effort. It runs after a failed write, often failed by ctx itself, so it does +// not reuse ctx's cancellation. func (c *Client[T]) invalidate(ctx context.Context, key string) { + ctx, cancel := context.WithTimeout(context.WithoutCancel(ctx), c.fetchTimeout) + defer cancel() if c.notFoundCache != nil { if err := c.notFoundCache.Del(ctx, key); err != nil { c.logger.WarnContext(ctx, "failed to invalidate notFoundCache entry", "key", key, "error", err) @@ -319,20 +324,22 @@ func (c *Client[T]) invalidate(ctx context.Context, key string) { } // backfill writes what a fetch read into this layer, unless a Set or Del of -// the key happened since gen was taken (before reading the upstream). A -// write that slips in between the check and the backfill is caught right -// after, and the backfill is undone, leaving a miss rather than a stale value. +// the key happened since gen was taken (before reading the upstream). It holds +// the key's stripe for reading, so a write waits for it, and the fill either +// lands before the write or is skipped. A write in progress skips it too +// (TryRLock): reads never wait on writes, at the cost of a spare cache miss. func (c *Client[T]) backfill(ctx context.Context, key string, gen uint64, fill func() error, failMsg string) { s := c.stripe(key) + if !s.mu.TryRLock() { + return + } + defer s.mu.RUnlock() if s.gen.Load() != gen { return } if err := fill(); err != nil { c.logger.WarnContext(ctx, failMsg, "key", key, "error", err) } - if s.gen.Load() != gen { - c.invalidate(ctx, key) - } } // setWithoutUpstream clears a cached not-found and writes the backend; a failed diff --git a/write_order_test.go b/write_order_test.go index 5605871..f30c6c8 100644 --- a/write_order_test.go +++ b/write_order_test.go @@ -274,7 +274,7 @@ func TestBackfillDoesNotOverwriteAConcurrentSet(t *testing.T) { }) } -func TestBackfillRacingASetIsUndone(t *testing.T) { +func TestBackfillIsSerializedWithSet(t *testing.T) { ctx := context.Background() for _, tc := range []struct { name string @@ -291,18 +291,27 @@ func TestBackfillRacingASetIsUndone(t *testing.T) { backend := newHookedCache() cli := NewClient[string](backend, src) - // The backfill passes its check, then a Set completes before the - // backfill's own write lands. + // The backfill passes its check and is about to write "old" when a + // Set of "new" starts. Either the Set waits for the backfill, or the + // backfill lands after the Set returned and a reader sees "old". backfillReached := make(chan struct{}) - setDone := make(chan struct{}) + release := make(chan struct{}) var first atomic.Bool + var setReturned atomic.Bool + var staleAfterSet atomic.Value backend.beforeSet = func(_, value string) error { if value == "old" && first.CompareAndSwap(false, true) { close(backfillReached) - <-setDone + <-release } return nil } + backend.afterSet = func(key, value string) { + if value == "old" && setReturned.Load() { + v, _ := cli.Get(ctx, key) + staleAfterSet.Store(v) + } + } done := make(chan struct{}) go func() { @@ -313,17 +322,51 @@ func TestBackfillRacingASetIsUndone(t *testing.T) { }() <-backfillReached src.write("k", "new") - require.NoError(t, cli.Set(ctx, "k", "new")) - close(setDone) + setDone := make(chan struct{}) + go func() { + defer close(setDone) + assert.NoError(t, cli.Set(ctx, "k", "new")) + setReturned.Store(true) + }() + select { + case <-setDone: + case <-time.After(50 * time.Millisecond): + } + close(release) <-done + <-setDone + assert.Nil(t, staleAfterSet.Load(), "no reader sees the old value after Set returned") v, err := cli.Get(ctx, "k") require.NoError(t, err) - assert.Equal(t, "new", v, "the late backfill is undone, so the next read sees the new value") + assert.Equal(t, "new", v) }) } } +// ctxCache is a SyncMap whose Del, like Redis or GORM, refuses a done ctx. +type ctxCache struct{ *SyncMap[string] } + +func (c ctxCache) Del(ctx context.Context, key string) error { + if err := ctx.Err(); err != nil { + return err + } + return c.SyncMap.Del(ctx, key) +} + +func TestFailedWriteInvalidatesWithACanceledCtx(t *testing.T) { + backend := ctxCache{NewSyncMap[string]()} + require.NoError(t, backend.Set(context.Background(), "k", "old")) + up := newHookedCache() + up.beforeSet = func(string, string) error { return context.Canceled } + cli := NewClient[string](backend, up) + + ctx, cancel := context.WithCancel(context.Background()) + cancel() + require.ErrorIs(t, cli.Set(ctx, "k", "new"), context.Canceled) + assertMissing(t, backend, "k", "the cleanup does not reuse the canceled ctx") +} + func TestInterleavedSetsKeepLayersConsistent(t *testing.T) { ctx := context.Background() for round := range 20 { From 5c1b087596461e0cc7bf52e5f9c743fc84ee8c67 Mon Sep 17 00:00:00 2001 From: molon <3739161+molon@users.noreply.github.com> Date: Thu, 8 Oct 2026 15:59:13 +0800 Subject: [PATCH 16/40] docs: describe the write stripes, and test local write failures - README: the write generation and lock are per stripe (1,024 per Client), not per key, so keys sharing a stripe serialize their writes and can skip each other's backfills. - Test that when the upstream write succeeds but this layer's Set or Del fails, the upstream keeps the change, the error is returned, and this layer's entry and cached not-found are dropped. --- README.md | 2 +- README_ZH.md | 2 +- client.go | 2 +- write_order_test.go | 49 +++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 52 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 56ef5d1..36211c6 100644 --- a/README.md +++ b/README.md @@ -334,7 +334,7 @@ The key insight: **cache writes propagate through `Cache[T]` chains but stop whe - `Set`/`Del` write the **upstream first**, then this layer, so a new value never shows up in an upper layer before the layer below has it: a `Set` becomes visible in this layer only after the write below has succeeded. The flip side is a short window while the write runs: until this layer's own write lands, a concurrent reader of this layer still sees its **old** value (after a `Del`, the deleted one), even though the layer below has already changed. Once `Set`/`Del` returns, the window is closed. - If the upstream write fails, its state is unknown (it may have been applied with only the reply lost), so this layer **drops** its entry for the key (and any cached Not-Found) and returns the error; the next read goes down. A failed `Del` likewise drops this layer's entry but caches no Not-Found. - Concurrent `Set`/`Del` of one key through the same `Client` are applied one at a time, in the same order on every layer. -- A read that fetched a value **before** a concurrent `Set`/`Del` still returns what it fetched, but never writes it back over the newer value: each `Client` keeps a per-key write generation, and `Get`, `GetMany` and the serve-stale refresh check it while holding the key's write lock for reading, so a backfill either lands before a `Set`/`Del` (which then overwrites it) or is skipped. A backfill is also skipped while a write to the key is in progress, so reads never wait on writes. The cost is at most an extra cache miss. +- A read that fetched a value **before** a concurrent `Set`/`Del` still returns what it fetched, but never writes it back over the newer value: each `Client` hashes keys into 1,024 stripes, each with a write lock and a write generation, and `Get`, `GetMany` and the serve-stale refresh check the key's stripe generation while holding its lock for reading, so a backfill either lands before a `Set`/`Del` (which then overwrites it) or is skipped. A backfill is also skipped while a write to the stripe is in progress, so reads never wait on writes. Keys that share a stripe share this state: their writes run one at a time, and a write to one key can skip a backfill of another. The cost is at most an extra cache miss, or a write waiting on a write to an unrelated key. - These guarantees hold within one process; separate processes sharing a lower layer (e.g. Redis) can still briefly disagree in their memory layers. ### Not-Found Caching diff --git a/README_ZH.md b/README_ZH.md index e31a5bd..7a55d47 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -334,7 +334,7 @@ L1 缓存 → L2 缓存 → L3 缓存 → 数据库 - `Set`/`Del` **先写 upstream**,再写本层,所以新值不会先于下层出现在上层:`Set` 的新值要等下层写成功后才在本层可见。代价是写入过程中有一个短暂的窗口:本层自己的写入落下之前,并发读本层仍会读到它的**旧值**(`Del` 时是已删掉的值),尽管下层已经变了。`Set`/`Del` 返回后窗口就关闭了。 - upstream 写失败时,它的状态不明(可能已经写进去了,只是回复丢了),所以本层会**删掉**这个 key 的条目(连同缓存的 Not-Found),并返回错误;下次读会回源到下层。`Del` 失败时同样删掉本层条目,但不记 Not-Found。 - 通过同一个 `Client` 并发 `Set`/`Del` 同一个 key 时,逐个执行,各层的写入顺序一致。 -- 回源读到值**之后**、写回本层**之前**如果发生了 `Set`/`Del`,这次读仍然返回它读到的值,但绝不会用它覆盖更新的值:每个 `Client` 给每个 key 记一个写入代数,`Get`、`GetMany` 和 serve-stale 的后台刷新在持有这个 key 所在写锁的读锁时核对它,所以回填要么在 `Set`/`Del` 之前落下(随后被覆盖),要么被跳过。这个 key 正在写入时回填也直接跳过,所以读永远不等写。代价最多是多一次缓存未命中。 +- 回源读到值**之后**、写回本层**之前**如果发生了 `Set`/`Del`,这次读仍然返回它读到的值,但绝不会用它覆盖更新的值:每个 `Client` 把 key 按哈希分到 1,024 个分片,每个分片有一把写锁和一个写入代数,`Get`、`GetMany` 和 serve-stale 的后台刷新在持有 key 所在分片的读锁时核对分片的写入代数,所以回填要么在 `Set`/`Del` 之前落下(随后被覆盖),要么被跳过。分片正在写入时回填也直接跳过,所以读永远不等写。落在同一分片的 key 共用这份状态:它们的写入逐个执行,写一个 key 可能让另一个 key 的回填被跳过。代价最多是多一次缓存未命中,或者一次写入要等另一个不相干 key 的写入。 - 这些保证在单个进程内成立;多个进程共用同一个下层(例如 Redis)时,各自的内存层仍可能短暂不一致。 ### Not-Found 缓存 diff --git a/client.go b/client.go index fe95b57..3b8d11d 100644 --- a/client.go +++ b/client.go @@ -267,7 +267,7 @@ func (c *Client[T]) Set(ctx context.Context, key string, value T) error { // writeStripeCount is the number of write stripes per Client. // -// ponytail: keys share stripes by hash, so two keys in one stripe serialize +// Keys share stripes by hash, so two keys in one stripe serialize // their writes and a write to one can skip the other's backfill (a spare // cache miss, never a stale value); raise it if that shows up. const writeStripeCount = 1024 diff --git a/write_order_test.go b/write_order_test.go index f30c6c8..61f61fa 100644 --- a/write_order_test.go +++ b/write_order_test.go @@ -111,6 +111,55 @@ func TestDelUpstreamFirst(t *testing.T) { }) } +func TestLayerWriteFailureAfterUpstreamSuccess(t *testing.T) { + ctx := context.Background() + boom := errors.New("boom") + + t.Run("Set", func(t *testing.T) { + notFound := NewSyncMap[time.Time]() + require.NoError(t, notFound.Set(ctx, "k", time.Now())) + backend := newHookedCache() + require.NoError(t, backend.Set(ctx, "k", "old")) + backend.beforeSet = func(string, string) error { return boom } + up := newHookedCache() + cli := NewClient[string](backend, up, NotFoundWithTTL[string](notFound, time.Hour, 0)) + + err := cli.Set(ctx, "k", "new") + require.ErrorIs(t, err, boom) + assert.Equal(t, "set in backend failed for key: k: boom", err.Error()) + v, err := up.Get(ctx, "k") + require.NoError(t, err) + assert.Equal(t, "new", v, "the upstream keeps the write") + assertMissing(t, backend, "k", "this layer's old value is dropped") + _, err = notFound.Get(ctx, "k") + assert.True(t, IsErrKeyNotFound(err), "the cached not-found is dropped") + }) + + t.Run("Del", func(t *testing.T) { + notFound := NewSyncMap[time.Time]() + backend := newHookedCache() + require.NoError(t, backend.Set(ctx, "k", "old")) + var failed atomic.Bool + backend.beforeDel = func(string) error { + if failed.CompareAndSwap(false, true) { + return boom // only this layer's own Del fails, not the cleanup + } + return nil + } + up := newHookedCache() + require.NoError(t, up.Set(ctx, "k", "old")) + cli := NewClient[string](backend, up, NotFoundWithTTL[string](notFound, time.Hour, 0)) + + err := cli.Del(ctx, "k") + require.ErrorIs(t, err, boom) + assert.Equal(t, "delete from backend failed for key: k: boom", err.Error()) + assertMissing(t, up, "k", "the upstream keeps the delete") + assertMissing(t, backend, "k", "this layer's old value is dropped") + _, err = notFound.Get(ctx, "k") + assert.True(t, IsErrKeyNotFound(err), "the not-found written before the failure is dropped too") + }) +} + // slowSource is a data source whose reads can be held after they have read // the value, to let a write slip in between the read and the backfill. type slowSource struct { From 5b2c8f1296d3b4121045e692f6746381c8e72d94 Mon Sep 17 00:00:00 2001 From: molon <3739161+molon@users.noreply.github.com> Date: Thu, 8 Oct 2026 16:14:32 +0800 Subject: [PATCH 17/40] docs: say that Set/Del keep the upstream change when this layer's write fails --- README.md | 1 + README_ZH.md | 1 + client.go | 8 ++++++-- 3 files changed, 8 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 36211c6..a9c51e3 100644 --- a/README.md +++ b/README.md @@ -333,6 +333,7 @@ The key insight: **cache writes propagate through `Cache[T]` chains but stop whe - `Set`/`Del` write the **upstream first**, then this layer, so a new value never shows up in an upper layer before the layer below has it: a `Set` becomes visible in this layer only after the write below has succeeded. The flip side is a short window while the write runs: until this layer's own write lands, a concurrent reader of this layer still sees its **old** value (after a `Del`, the deleted one), even though the layer below has already changed. Once `Set`/`Del` returns, the window is closed. - If the upstream write fails, its state is unknown (it may have been applied with only the reply lost), so this layer **drops** its entry for the key (and any cached Not-Found) and returns the error; the next read goes down. A failed `Del` likewise drops this layer's entry but caches no Not-Found. +- If the upstream write succeeds but this layer's own write fails, `Set`/`Del` still return the error, yet the change below is **kept** (nothing is rolled back): an error does not mean nothing was written. This layer drops its entry and cached Not-Found for the key, so the next read goes down and sees the change. - Concurrent `Set`/`Del` of one key through the same `Client` are applied one at a time, in the same order on every layer. - A read that fetched a value **before** a concurrent `Set`/`Del` still returns what it fetched, but never writes it back over the newer value: each `Client` hashes keys into 1,024 stripes, each with a write lock and a write generation, and `Get`, `GetMany` and the serve-stale refresh check the key's stripe generation while holding its lock for reading, so a backfill either lands before a `Set`/`Del` (which then overwrites it) or is skipped. A backfill is also skipped while a write to the stripe is in progress, so reads never wait on writes. Keys that share a stripe share this state: their writes run one at a time, and a write to one key can skip a backfill of another. The cost is at most an extra cache miss, or a write waiting on a write to an unrelated key. - These guarantees hold within one process; separate processes sharing a lower layer (e.g. Redis) can still briefly disagree in their memory layers. diff --git a/README_ZH.md b/README_ZH.md index 7a55d47..7747740 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -333,6 +333,7 @@ L1 缓存 → L2 缓存 → L3 缓存 → 数据库 - `Set`/`Del` **先写 upstream**,再写本层,所以新值不会先于下层出现在上层:`Set` 的新值要等下层写成功后才在本层可见。代价是写入过程中有一个短暂的窗口:本层自己的写入落下之前,并发读本层仍会读到它的**旧值**(`Del` 时是已删掉的值),尽管下层已经变了。`Set`/`Del` 返回后窗口就关闭了。 - upstream 写失败时,它的状态不明(可能已经写进去了,只是回复丢了),所以本层会**删掉**这个 key 的条目(连同缓存的 Not-Found),并返回错误;下次读会回源到下层。`Del` 失败时同样删掉本层条目,但不记 Not-Found。 +- upstream 写成功、本层自己的写入失败时,`Set`/`Del` 仍返回错误,但下层的改动**保留**(不回滚):返回错误不代表什么都没写进去。本层会删掉这个 key 的条目和缓存的 Not-Found,下次读会回源到下层,读到改动后的结果。 - 通过同一个 `Client` 并发 `Set`/`Del` 同一个 key 时,逐个执行,各层的写入顺序一致。 - 回源读到值**之后**、写回本层**之前**如果发生了 `Set`/`Del`,这次读仍然返回它读到的值,但绝不会用它覆盖更新的值:每个 `Client` 把 key 按哈希分到 1,024 个分片,每个分片有一把写锁和一个写入代数,`Get`、`GetMany` 和 serve-stale 的后台刷新在持有 key 所在分片的读锁时核对分片的写入代数,所以回填要么在 `Set`/`Del` 之前落下(随后被覆盖),要么被跳过。分片正在写入时回填也直接跳过,所以读永远不等写。落在同一分片的 key 共用这份状态:它们的写入逐个执行,写一个 key 可能让另一个 key 的回填被跳过。代价最多是多一次缓存未命中,或者一次写入要等另一个不相干 key 的写入。 - 这些保证在单个进程内成立;多个进程共用同一个下层(例如 Redis)时,各自的内存层仍可能短暂不一致。 diff --git a/client.go b/client.go index 3b8d11d..6405b0a 100644 --- a/client.go +++ b/client.go @@ -198,7 +198,9 @@ func (c *Client[T]) get(ctx context.Context, key string, doubleCheck bool) (T, e // Order: the upstream is deleted first, then this layer, so until this layer's // delete lands its readers still see the deleted value. If the upstream // delete fails, this layer's entry is still dropped but no not-found is -// cached, since the upstream may still hold the key. +// cached, since the upstream may still hold the key. If the upstream delete +// succeeds but this layer's fails, the error is returned and the upstream +// stays deleted. func (c *Client[T]) Del(ctx context.Context, key string) error { return c.write(ctx, key, func(upstream Cache[T]) error { @@ -250,7 +252,9 @@ func (c *Client[T]) delWithoutUpstream(ctx context.Context, key string) error { // shows up here before it is below; until this layer's write lands, readers of // this layer still see the old value. If the upstream write fails, its // state is unknown (it may have been applied and only the reply lost), so this -// layer's entry is dropped and the next read goes down. Concurrent writes to +// layer's entry is dropped and the next read goes down. If the upstream write +// succeeds but this layer's fails, the error is returned too (the upstream +// keeps the new value) and this layer's entry is dropped. Concurrent writes to // one key through the same Client are applied one at a time, in the same order // on every layer. func (c *Client[T]) Set(ctx context.Context, key string, value T) error { From 3dc6b40e2c2f3958e14b9b45664ba2d230c27d33 Mon Sep 17 00:00:00 2001 From: molon <3739161+molon@users.noreply.github.com> Date: Thu, 8 Oct 2026 17:40:18 +0800 Subject: [PATCH 18/40] fix: a read after Set/Del never gets a value fetched before it, and waiting to write respects ctx - After the upstream write, Set/Del release the key's in-flight fetches (without interrupting them), so a read that starts after Set/Del returned fetches anew instead of joining a fetch that read the old value. Before, e.g. a Get after Del (no not-found cache) could still return the deleted value. - A Set/Del waiting for another write to its stripe gives up when its ctx is done, and a done ctx writes nothing. Before, the wait ignored ctx, so one hung upstream write blocked the others past their deadlines. - Docs: the failure cleanup outlives ctx for at most the fetch timeout. - Test that a layered Set's generation bump comes after the upstream write. --- README.md | 4 +- README_ZH.md | 4 +- batch.go | 8 +++ client.go | 53 +++++++++++++++---- write_order_test.go | 124 ++++++++++++++++++++++++++++++++++++++++++-- 5 files changed, 177 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index a9c51e3..94e2a78 100644 --- a/README.md +++ b/README.md @@ -331,10 +331,10 @@ The key insight: **cache writes propagate through `Cache[T]` chains but stop whe **Write order and consistency:** -- `Set`/`Del` write the **upstream first**, then this layer, so a new value never shows up in an upper layer before the layer below has it: a `Set` becomes visible in this layer only after the write below has succeeded. The flip side is a short window while the write runs: until this layer's own write lands, a concurrent reader of this layer still sees its **old** value (after a `Del`, the deleted one), even though the layer below has already changed. Once `Set`/`Del` returns, the window is closed. +- `Set`/`Del` write the **upstream first**, then this layer, so a new value never shows up in an upper layer before the layer below has it: a `Set` becomes visible in this layer only after the write below has succeeded. The flip side is a short window while the write runs: until this layer's own write lands, a concurrent reader of this layer still sees its **old** value (after a `Del`, the deleted one), even though the layer below has already changed. Once `Set`/`Del` returns, the window is closed: a read that starts afterwards never gets a value fetched before the write (it does not join an older in-flight fetch, it starts a new one). - If the upstream write fails, its state is unknown (it may have been applied with only the reply lost), so this layer **drops** its entry for the key (and any cached Not-Found) and returns the error; the next read goes down. A failed `Del` likewise drops this layer's entry but caches no Not-Found. - If the upstream write succeeds but this layer's own write fails, `Set`/`Del` still return the error, yet the change below is **kept** (nothing is rolled back): an error does not mean nothing was written. This layer drops its entry and cached Not-Found for the key, so the next read goes down and sees the change. -- Concurrent `Set`/`Del` of one key through the same `Client` are applied one at a time, in the same order on every layer. +- Concurrent `Set`/`Del` of one key through the same `Client` are applied one at a time, in the same order on every layer. A `Set`/`Del` that has to wait for another one gives up when its ctx is done, having written nothing. Once a write has started, the cleanup after a failure (dropping this layer's entry) runs even if ctx is done, for at most `WithFetchTimeout`. - A read that fetched a value **before** a concurrent `Set`/`Del` still returns what it fetched, but never writes it back over the newer value: each `Client` hashes keys into 1,024 stripes, each with a write lock and a write generation, and `Get`, `GetMany` and the serve-stale refresh check the key's stripe generation while holding its lock for reading, so a backfill either lands before a `Set`/`Del` (which then overwrites it) or is skipped. A backfill is also skipped while a write to the stripe is in progress, so reads never wait on writes. Keys that share a stripe share this state: their writes run one at a time, and a write to one key can skip a backfill of another. The cost is at most an extra cache miss, or a write waiting on a write to an unrelated key. - These guarantees hold within one process; separate processes sharing a lower layer (e.g. Redis) can still briefly disagree in their memory layers. diff --git a/README_ZH.md b/README_ZH.md index 7747740..243a3fe 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -331,10 +331,10 @@ L1 缓存 → L2 缓存 → L3 缓存 → 数据库 **写入顺序与一致性:** -- `Set`/`Del` **先写 upstream**,再写本层,所以新值不会先于下层出现在上层:`Set` 的新值要等下层写成功后才在本层可见。代价是写入过程中有一个短暂的窗口:本层自己的写入落下之前,并发读本层仍会读到它的**旧值**(`Del` 时是已删掉的值),尽管下层已经变了。`Set`/`Del` 返回后窗口就关闭了。 +- `Set`/`Del` **先写 upstream**,再写本层,所以新值不会先于下层出现在上层:`Set` 的新值要等下层写成功后才在本层可见。代价是写入过程中有一个短暂的窗口:本层自己的写入落下之前,并发读本层仍会读到它的**旧值**(`Del` 时是已删掉的值),尽管下层已经变了。`Set`/`Del` 返回后窗口就关闭了:之后开始的读不会拿到写入之前回源读到的值(它不会加入更早的那次回源,而是重新回源)。 - upstream 写失败时,它的状态不明(可能已经写进去了,只是回复丢了),所以本层会**删掉**这个 key 的条目(连同缓存的 Not-Found),并返回错误;下次读会回源到下层。`Del` 失败时同样删掉本层条目,但不记 Not-Found。 - upstream 写成功、本层自己的写入失败时,`Set`/`Del` 仍返回错误,但下层的改动**保留**(不回滚):返回错误不代表什么都没写进去。本层会删掉这个 key 的条目和缓存的 Not-Found,下次读会回源到下层,读到改动后的结果。 -- 通过同一个 `Client` 并发 `Set`/`Del` 同一个 key 时,逐个执行,各层的写入顺序一致。 +- 通过同一个 `Client` 并发 `Set`/`Del` 同一个 key 时,逐个执行,各层的写入顺序一致。需要等前一个写入的 `Set`/`Del`,在 ctx 结束时放弃等待,什么都不写。写入一旦开始,失败后的清理(删掉本层条目)即使 ctx 已结束也会执行,最长 `WithFetchTimeout`。 - 回源读到值**之后**、写回本层**之前**如果发生了 `Set`/`Del`,这次读仍然返回它读到的值,但绝不会用它覆盖更新的值:每个 `Client` 把 key 按哈希分到 1,024 个分片,每个分片有一把写锁和一个写入代数,`Get`、`GetMany` 和 serve-stale 的后台刷新在持有 key 所在分片的读锁时核对分片的写入代数,所以回填要么在 `Set`/`Del` 之前落下(随后被覆盖),要么被跳过。分片正在写入时回填也直接跳过,所以读永远不等写。落在同一分片的 key 共用这份状态:它们的写入逐个执行,写一个 key 可能让另一个 key 的回填被跳过。代价最多是多一次缓存未命中,或者一次写入要等另一个不相干 key 的写入。 - 这些保证在单个进程内成立;多个进程共用同一个下层(例如 Redis)时,各自的内存层仍可能短暂不一致。 diff --git a/batch.go b/batch.go index e6e60d8..ae9eb74 100644 --- a/batch.go +++ b/batch.go @@ -53,6 +53,14 @@ func (g *flightGroup[T]) finish(sfKey string, f *flight[T], value T, err error) close(f.done) } +// drop releases whatever flight holds sfKey without publishing a result: its +// waiters still get its result, and the next claim starts a new flight. +func (g *flightGroup[T]) drop(sfKey string) { + g.mu.Lock() + defer g.mu.Unlock() + delete(g.flights, sfKey) +} + // forget releases the claim without publishing a result. func (g *flightGroup[T]) forget(sfKey string, f *flight[T]) { g.mu.Lock() diff --git a/client.go b/client.go index 6405b0a..429cee4 100644 --- a/client.go +++ b/client.go @@ -79,6 +79,9 @@ func NewClient[T any](backend Cache[T], upstream Upstream[T], opts ...ClientOpti doubleCheckMode: DoubleCheckAuto, // Default: auto (smart heuristic) writeSeed: maphash.MakeSeed(), } + for i := range c.writes { + c.writes[i].writer = make(chan struct{}, 1) + } // Apply user options for _, opt := range opts { @@ -201,6 +204,7 @@ func (c *Client[T]) get(ctx context.Context, key string, doubleCheck bool) (T, e // cached, since the upstream may still hold the key. If the upstream delete // succeeds but this layer's fails, the error is returned and the upstream // stays deleted. +// Reads after it and waiting for other writes behave as for Set. func (c *Client[T]) Del(ctx context.Context, key string) error { return c.write(ctx, key, func(upstream Cache[T]) error { @@ -254,9 +258,11 @@ func (c *Client[T]) delWithoutUpstream(ctx context.Context, key string) error { // state is unknown (it may have been applied and only the reply lost), so this // layer's entry is dropped and the next read goes down. If the upstream write // succeeds but this layer's fails, the error is returned too (the upstream -// keeps the new value) and this layer's entry is dropped. Concurrent writes to +// keeps the new value) and this layer's entry is dropped. A read that starts +// after Set returned never gets a value fetched before it. Concurrent writes to // one key through the same Client are applied one at a time, in the same order -// on every layer. +// on every layer; waiting for another write respects ctx, but once started, a +// failed write's cleanup outlives ctx, for at most the fetch timeout. func (c *Client[T]) Set(ctx context.Context, key string, value T) error { return c.write(ctx, key, func(upstream Cache[T]) error { @@ -278,8 +284,9 @@ const writeStripeCount = 1024 // writeStripe orders writes and backfills of the keys that hash to it. type writeStripe struct { - mu sync.RWMutex // Set/Del hold it, so all layers apply them in one order; backfills hold it for reading - gen atomic.Uint64 // bumped by every Set/Del, checked by backfills + writer chan struct{} // capacity 1, held by the Set/Del in progress; waiting for it respects ctx + mu sync.RWMutex // that Set/Del holds it too, so all layers apply writes in one order; backfills hold it for reading + gen atomic.Uint64 // bumped by every Set/Del, checked by backfills } func (c *Client[T]) stripe(key string) *writeStripe { @@ -290,20 +297,36 @@ func (c *Client[T]) stripe(key string) *writeStripe { // layer. Any failure leaves this layer without an entry for the key. func (c *Client[T]) write(ctx context.Context, key string, toUpstream func(Cache[T]) error, toLayer func() error) error { s := c.stripe(key) - s.mu.Lock() + if err := ctx.Err(); err != nil { // a done ctx writes nothing, even if no write is in progress + return errors.Wrapf(err, "context cancelled while waiting for a write in progress for key: %s", key) + } + select { + case s.writer <- struct{}{}: + case <-ctx.Done(): + return errors.Wrapf(ctx.Err(), "context cancelled while waiting for a write in progress for key: %s", key) + } + defer func() { <-s.writer }() + s.mu.Lock() // only waits for backfills already writing this layer defer s.mu.Unlock() + // Called once the upstream is written: a backfill that read the upstream + // before took an older gen, so it is skipped once this lock is released, and + // a read that starts from now on fetches anew instead of joining a fetch + // that may have read the upstream before the write. + written := func() { + s.gen.Add(1) + c.dropFlights(key) + } + if upstreamCache, ok := c.upstream.(Cache[T]); ok { if err := toUpstream(upstreamCache); err != nil { - s.gen.Add(1) + written() c.invalidate(ctx, key) return err } } - // Bumped after the upstream write: a backfill that read the upstream before - // it took a gen older than this, so it is skipped once this lock is released. - s.gen.Add(1) + written() if err := toLayer(); err != nil { c.invalidate(ctx, key) return err @@ -311,6 +334,18 @@ func (c *Client[T]) write(ctx context.Context, key string, toUpstream func(Cache return nil } +// dropFlights releases the in-flight fetches of key (every fetch slot) without +// interrupting them: callers already waiting still get their result. +func (c *Client[T]) dropFlights(key string) { + if c.fetchConcurrency <= 1 { + c.flights.drop(key) + return + } + for i := range c.fetchConcurrency { + c.flights.drop(fmt.Sprintf("%d:%s", i, key)) + } +} + // invalidate drops this layer's entry and cached not-found for key, best // effort. It runs after a failed write, often failed by ctx itself, so it does // not reuse ctx's cancellation. diff --git a/write_order_test.go b/write_order_test.go index 61f61fa..7faca5d 100644 --- a/write_order_test.go +++ b/write_order_test.go @@ -406,12 +406,14 @@ func (c ctxCache) Del(ctx context.Context, key string) error { func TestFailedWriteInvalidatesWithACanceledCtx(t *testing.T) { backend := ctxCache{NewSyncMap[string]()} require.NoError(t, backend.Set(context.Background(), "k", "old")) + ctx, cancel := context.WithCancel(context.Background()) up := newHookedCache() - up.beforeSet = func(string, string) error { return context.Canceled } + up.beforeSet = func(string, string) error { + cancel() // the caller gives up while the upstream is being written + return context.Canceled + } cli := NewClient[string](backend, up) - ctx, cancel := context.WithCancel(context.Background()) - cancel() require.ErrorIs(t, cli.Set(ctx, "k", "new"), context.Canceled) assertMissing(t, backend, "k", "the cleanup does not reuse the canceled ctx") } @@ -458,3 +460,119 @@ func TestInterleavedSetsKeepLayersConsistent(t *testing.T) { } } } + +func TestReadAfterWriteDoesNotJoinAnOlderFetch(t *testing.T) { + ctx := context.Background() + src := &slowSource{data: map[string]string{"k": "old"}} + cli := NewClient[string](NewSyncMap[string](), src) // no not-found cache: Del leaves this layer empty + + src.holdReads() + go func() { _, _ = cli.Get(ctx, "k") }() + waitFor(t, src.entered) // A has read "old" and is held + + src.mu.Lock() + delete(src.data, "k") + src.mu.Unlock() + require.NoError(t, cli.Del(ctx, "k")) + + type res struct { + v string + err error + } + got := make(chan res, 1) + go func() { + v, err := cli.Get(ctx, "k") + got <- res{v, err} + }() + waitFor(t, src.entered) // B started its own read instead of joining A's + src.releaseReads() + r := <-got + assert.True(t, IsErrKeyNotFound(r.err), "a Get that starts after Del returned sees the delete (got %q, %v)", r.v, r.err) +} + +func TestWriteWaitingForTheStripeRespectsCtx(t *testing.T) { + ctx := context.Background() + up := newHookedCache() + entered, release := make(chan struct{}), make(chan struct{}) + up.beforeSet = func(_, value string) error { + if value == "first" { + close(entered) + <-release + } + return nil + } + cli := NewClient[string](NewSyncMap[string](), up) + firstDone := make(chan struct{}) + go func() { + defer close(firstDone) + assert.NoError(t, cli.Set(ctx, "k", "first")) + }() + waitFor(t, entered) + + secondErr := make(chan error, 1) + go func() { + ctx, cancel := context.WithTimeout(ctx, 50*time.Millisecond) + defer cancel() + secondErr <- cli.Set(ctx, "k", "second") + }() + select { + case err := <-secondErr: + require.ErrorIs(t, err, context.DeadlineExceeded) + assert.Equal(t, "context cancelled while waiting for a write in progress for key: k: context deadline exceeded", err.Error()) + case <-time.After(5 * time.Second): + t.Fatal("Set kept waiting past its ctx") + } + close(release) + <-firstDone + v, _ := up.Get(ctx, "k") + assert.Equal(t, "first", v, "the cancelled Set wrote nothing") + + done, cancel := context.WithCancel(ctx) + cancel() + err := cli.Set(done, "k", "third") + require.ErrorIs(t, err, context.Canceled, "a done ctx writes nothing even when the stripe is free") + v, _ = up.Get(ctx, "k") + assert.Equal(t, "first", v) +} + +// holdGetCache is a hookedCache whose Get can be held after reading. +type holdGetCache struct { + *hookedCache + onGet func(key string) +} + +func (h *holdGetCache) Get(ctx context.Context, key string) (string, error) { + v, err := h.hookedCache.Get(ctx, key) + if h.onGet != nil { + h.onGet(key) + } + return v, err +} + +func TestWriteThroughBackfillDuringUpstreamWrite(t *testing.T) { + ctx := context.Background() + l2 := &holdGetCache{hookedCache: newHookedCache()} + require.NoError(t, l2.Set(ctx, "k", "old")) + l1Backend := NewSyncMap[string]() + l1 := NewClient[string](l1Backend, l2) + + read, release, getDone := make(chan struct{}), make(chan struct{}), make(chan struct{}) + l2.beforeSet = func(string, string) error { + // while L1's Set holds the stripe and before L2 is written, an L1 Get reads L2's old value + l2.onGet = func(string) { close(read); <-release } + go func() { + defer close(getDone) + _, _ = l1.Get(ctx, "k") + }() + <-read + return nil + } + require.NoError(t, l1.Set(ctx, "k", "new")) + l2.beforeSet = nil + close(release) + <-getDone + + v, err := l1Backend.Get(ctx, "k") + require.NoError(t, err) + assert.Equal(t, "new", v, "the Get that read L2 before the write does not backfill the old value") +} From caafebaf5b11644186ddd3d83ab69cf19c9c1df6 Mon Sep 17 00:00:00 2001 From: molon <3739161+molon@users.noreply.github.com> Date: Thu, 8 Oct 2026 17:51:32 +0800 Subject: [PATCH 19/40] fix: let a write with a done ctx through when it need not wait, and respect ctx while waiting for a backfill - Waiting for the stripe now covers both another write and a backfill writing this layer, and gives up when ctx is done. Before, a backfill (e.g. a GetMany holding many stripes) blocked Set/Del past their ctx. - A Set/Del that need not wait is applied even with a done ctx, as before this PR, so an invalidating Del after the request was canceled still lands in in-memory layers. - Drop the per-stripe channel: no extra allocations per Client. - Test releasing in-flight fetches for Get and GetMany with WithFetchConcurrency 1 and 4. --- README.md | 2 +- README_ZH.md | 2 +- client.go | 48 +++++++++----- write_order_test.go | 154 ++++++++++++++++++++++++++++++++++++-------- 4 files changed, 159 insertions(+), 47 deletions(-) diff --git a/README.md b/README.md index 94e2a78..4e68325 100644 --- a/README.md +++ b/README.md @@ -334,7 +334,7 @@ The key insight: **cache writes propagate through `Cache[T]` chains but stop whe - `Set`/`Del` write the **upstream first**, then this layer, so a new value never shows up in an upper layer before the layer below has it: a `Set` becomes visible in this layer only after the write below has succeeded. The flip side is a short window while the write runs: until this layer's own write lands, a concurrent reader of this layer still sees its **old** value (after a `Del`, the deleted one), even though the layer below has already changed. Once `Set`/`Del` returns, the window is closed: a read that starts afterwards never gets a value fetched before the write (it does not join an older in-flight fetch, it starts a new one). - If the upstream write fails, its state is unknown (it may have been applied with only the reply lost), so this layer **drops** its entry for the key (and any cached Not-Found) and returns the error; the next read goes down. A failed `Del` likewise drops this layer's entry but caches no Not-Found. - If the upstream write succeeds but this layer's own write fails, `Set`/`Del` still return the error, yet the change below is **kept** (nothing is rolled back): an error does not mean nothing was written. This layer drops its entry and cached Not-Found for the key, so the next read goes down and sees the change. -- Concurrent `Set`/`Del` of one key through the same `Client` are applied one at a time, in the same order on every layer. A `Set`/`Del` that has to wait for another one gives up when its ctx is done, having written nothing. Once a write has started, the cleanup after a failure (dropping this layer's entry) runs even if ctx is done, for at most `WithFetchTimeout`. +- Concurrent `Set`/`Del` of one key through the same `Client` are applied one at a time, in the same order on every layer. A `Set`/`Del` that has to wait (for another write to its stripe, or a read writing back to this layer) gives up when its ctx is done, having written nothing; one that does not have to wait is applied even if its ctx is already done, so e.g. an invalidating `Del` after the request was canceled still lands in in-memory layers. Once a write has started, the cleanup after a failure (dropping this layer's entry) runs even if ctx is done, for at most `WithFetchTimeout`. - A read that fetched a value **before** a concurrent `Set`/`Del` still returns what it fetched, but never writes it back over the newer value: each `Client` hashes keys into 1,024 stripes, each with a write lock and a write generation, and `Get`, `GetMany` and the serve-stale refresh check the key's stripe generation while holding its lock for reading, so a backfill either lands before a `Set`/`Del` (which then overwrites it) or is skipped. A backfill is also skipped while a write to the stripe is in progress, so reads never wait on writes. Keys that share a stripe share this state: their writes run one at a time, and a write to one key can skip a backfill of another. The cost is at most an extra cache miss, or a write waiting on a write to an unrelated key. - These guarantees hold within one process; separate processes sharing a lower layer (e.g. Redis) can still briefly disagree in their memory layers. diff --git a/README_ZH.md b/README_ZH.md index 243a3fe..0dac468 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -334,7 +334,7 @@ L1 缓存 → L2 缓存 → L3 缓存 → 数据库 - `Set`/`Del` **先写 upstream**,再写本层,所以新值不会先于下层出现在上层:`Set` 的新值要等下层写成功后才在本层可见。代价是写入过程中有一个短暂的窗口:本层自己的写入落下之前,并发读本层仍会读到它的**旧值**(`Del` 时是已删掉的值),尽管下层已经变了。`Set`/`Del` 返回后窗口就关闭了:之后开始的读不会拿到写入之前回源读到的值(它不会加入更早的那次回源,而是重新回源)。 - upstream 写失败时,它的状态不明(可能已经写进去了,只是回复丢了),所以本层会**删掉**这个 key 的条目(连同缓存的 Not-Found),并返回错误;下次读会回源到下层。`Del` 失败时同样删掉本层条目,但不记 Not-Found。 - upstream 写成功、本层自己的写入失败时,`Set`/`Del` 仍返回错误,但下层的改动**保留**(不回滚):返回错误不代表什么都没写进去。本层会删掉这个 key 的条目和缓存的 Not-Found,下次读会回源到下层,读到改动后的结果。 -- 通过同一个 `Client` 并发 `Set`/`Del` 同一个 key 时,逐个执行,各层的写入顺序一致。需要等前一个写入的 `Set`/`Del`,在 ctx 结束时放弃等待,什么都不写。写入一旦开始,失败后的清理(删掉本层条目)即使 ctx 已结束也会执行,最长 `WithFetchTimeout`。 +- 通过同一个 `Client` 并发 `Set`/`Del` 同一个 key 时,逐个执行,各层的写入顺序一致。需要等待的 `Set`/`Del`(等同一分片的其他写入,或者等正在回填本层的读),在 ctx 结束时放弃,什么都不写;不需要等待的照常执行,即使 ctx 已经结束。比如请求取消后再调 `Del` 做失效,内存层照样会删掉。写入一旦开始,失败后的清理(删掉本层条目)即使 ctx 已结束也会执行,最长 `WithFetchTimeout`。 - 回源读到值**之后**、写回本层**之前**如果发生了 `Set`/`Del`,这次读仍然返回它读到的值,但绝不会用它覆盖更新的值:每个 `Client` 把 key 按哈希分到 1,024 个分片,每个分片有一把写锁和一个写入代数,`Get`、`GetMany` 和 serve-stale 的后台刷新在持有 key 所在分片的读锁时核对分片的写入代数,所以回填要么在 `Set`/`Del` 之前落下(随后被覆盖),要么被跳过。分片正在写入时回填也直接跳过,所以读永远不等写。落在同一分片的 key 共用这份状态:它们的写入逐个执行,写一个 key 可能让另一个 key 的回填被跳过。代价最多是多一次缓存未命中,或者一次写入要等另一个不相干 key 的写入。 - 这些保证在单个进程内成立;多个进程共用同一个下层(例如 Redis)时,各自的内存层仍可能短暂不一致。 diff --git a/client.go b/client.go index 429cee4..95376dd 100644 --- a/client.go +++ b/client.go @@ -79,9 +79,6 @@ func NewClient[T any](backend Cache[T], upstream Upstream[T], opts ...ClientOpti doubleCheckMode: DoubleCheckAuto, // Default: auto (smart heuristic) writeSeed: maphash.MakeSeed(), } - for i := range c.writes { - c.writes[i].writer = make(chan struct{}, 1) - } // Apply user options for _, opt := range opts { @@ -261,8 +258,10 @@ func (c *Client[T]) delWithoutUpstream(ctx context.Context, key string) error { // keeps the new value) and this layer's entry is dropped. A read that starts // after Set returned never gets a value fetched before it. Concurrent writes to // one key through the same Client are applied one at a time, in the same order -// on every layer; waiting for another write respects ctx, but once started, a -// failed write's cleanup outlives ctx, for at most the fetch timeout. +// on every layer. Waiting for another write or a backfill of the key's stripe +// gives up when ctx is done (writing nothing); a write that need not wait runs +// even with a done ctx. Once started, a failed write's cleanup outlives ctx, +// for at most the fetch timeout. func (c *Client[T]) Set(ctx context.Context, key string, value T) error { return c.write(ctx, key, func(upstream Cache[T]) error { @@ -284,9 +283,31 @@ const writeStripeCount = 1024 // writeStripe orders writes and backfills of the keys that hash to it. type writeStripe struct { - writer chan struct{} // capacity 1, held by the Set/Del in progress; waiting for it respects ctx - mu sync.RWMutex // that Set/Del holds it too, so all layers apply writes in one order; backfills hold it for reading - gen atomic.Uint64 // bumped by every Set/Del, checked by backfills + mu sync.RWMutex // Set/Del hold it, so all layers apply them in one order; backfills hold it for reading + gen atomic.Uint64 // bumped by every Set/Del, checked by backfills +} + +// lock takes the stripe for writing. Waiting for another write or a backfill +// gives up when ctx is done; a free stripe is taken even with a done ctx. +func (s *writeStripe) lock(ctx context.Context) error { + if s.mu.TryLock() { + return nil + } + locked := make(chan struct{}) + go func() { + s.mu.Lock() + close(locked) + }() + select { + case <-locked: + return nil + case <-ctx.Done(): + go func() { // hand the lock back once it is taken + <-locked + s.mu.Unlock() + }() + return ctx.Err() + } } func (c *Client[T]) stripe(key string) *writeStripe { @@ -297,16 +318,9 @@ func (c *Client[T]) stripe(key string) *writeStripe { // layer. Any failure leaves this layer without an entry for the key. func (c *Client[T]) write(ctx context.Context, key string, toUpstream func(Cache[T]) error, toLayer func() error) error { s := c.stripe(key) - if err := ctx.Err(); err != nil { // a done ctx writes nothing, even if no write is in progress - return errors.Wrapf(err, "context cancelled while waiting for a write in progress for key: %s", key) - } - select { - case s.writer <- struct{}{}: - case <-ctx.Done(): - return errors.Wrapf(ctx.Err(), "context cancelled while waiting for a write in progress for key: %s", key) + if err := s.lock(ctx); err != nil { + return errors.Wrapf(err, "context cancelled while waiting to write key: %s", key) } - defer func() { <-s.writer }() - s.mu.Lock() // only waits for backfills already writing this layer defer s.mu.Unlock() // Called once the upstream is written: a backfill that read the upstream diff --git a/write_order_test.go b/write_order_test.go index 7faca5d..38a57ee 100644 --- a/write_order_test.go +++ b/write_order_test.go @@ -462,32 +462,58 @@ func TestInterleavedSetsKeepLayersConsistent(t *testing.T) { } func TestReadAfterWriteDoesNotJoinAnOlderFetch(t *testing.T) { - ctx := context.Background() - src := &slowSource{data: map[string]string{"k": "old"}} - cli := NewClient[string](NewSyncMap[string](), src) // no not-found cache: Del leaves this layer empty - - src.holdReads() - go func() { _, _ = cli.Get(ctx, "k") }() - waitFor(t, src.entered) // A has read "old" and is held - - src.mu.Lock() - delete(src.data, "k") - src.mu.Unlock() - require.NoError(t, cli.Del(ctx, "k")) + for _, conc := range []int{1, 4} { + for _, many := range []bool{false, true} { + t.Run(fmt.Sprintf("concurrency=%d GetMany=%v", conc, many), func(t *testing.T) { + ctx := context.Background() + src := &slowSource{data: map[string]string{"k": "old"}} + // no not-found cache: Del leaves this layer empty + cli := NewClient[string](NewSyncMap[string](), src, WithFetchConcurrency[string](conc)) + + // older reads hold a fetch in every slot, each having read "old" + src.holdReads() + require.Eventually(t, func() bool { + go func() { _, _ = cli.Get(ctx, "k") }() + cli.flights.mu.Lock() + defer cli.flights.mu.Unlock() + return len(cli.flights.flights) == conc + }, time.Second, time.Millisecond) + for range conc { + waitFor(t, src.entered) + } - type res struct { - v string - err error + src.mu.Lock() + delete(src.data, "k") + src.mu.Unlock() + require.NoError(t, cli.Del(ctx, "k")) + + got := make(chan error, 1) + go func() { + if many { + m, err := cli.GetMany(ctx, []string{"k"}) + if err == nil && len(m) > 0 { + err = fmt.Errorf("got %v", m) + } + got <- err + return + } + v, err := cli.Get(ctx, "k") + if err == nil { + err = fmt.Errorf("got %q", v) + } + got <- err + }() + waitFor(t, src.entered) // the new read started its own fetch instead of joining an older one + src.releaseReads() + err := <-got + if many { + assert.NoError(t, err, "a GetMany after Del sees the delete") + } else { + assert.True(t, IsErrKeyNotFound(err), "a Get after Del sees the delete: %v", err) + } + }) + } } - got := make(chan res, 1) - go func() { - v, err := cli.Get(ctx, "k") - got <- res{v, err} - }() - waitFor(t, src.entered) // B started its own read instead of joining A's - src.releaseReads() - r := <-got - assert.True(t, IsErrKeyNotFound(r.err), "a Get that starts after Del returned sees the delete (got %q, %v)", r.v, r.err) } func TestWriteWaitingForTheStripeRespectsCtx(t *testing.T) { @@ -518,7 +544,7 @@ func TestWriteWaitingForTheStripeRespectsCtx(t *testing.T) { select { case err := <-secondErr: require.ErrorIs(t, err, context.DeadlineExceeded) - assert.Equal(t, "context cancelled while waiting for a write in progress for key: k: context deadline exceeded", err.Error()) + assert.Equal(t, "context cancelled while waiting to write key: k: context deadline exceeded", err.Error()) case <-time.After(5 * time.Second): t.Fatal("Set kept waiting past its ctx") } @@ -527,12 +553,84 @@ func TestWriteWaitingForTheStripeRespectsCtx(t *testing.T) { v, _ := up.Get(ctx, "k") assert.Equal(t, "first", v, "the cancelled Set wrote nothing") + s := cli.stripe("k") + require.Eventually(t, func() bool { // the given-up Set hands the lock back once it gets it + if !s.mu.TryLock() { + return false + } + s.mu.Unlock() + return true + }, time.Second, time.Millisecond) done, cancel := context.WithCancel(ctx) cancel() - err := cli.Set(done, "k", "third") - require.ErrorIs(t, err, context.Canceled, "a done ctx writes nothing even when the stripe is free") + require.NoError(t, cli.Set(done, "k", "third"), "a done ctx only gives up waiting; a free stripe is written as before") v, _ = up.Get(ctx, "k") - assert.Equal(t, "first", v) + assert.Equal(t, "third", v) +} + +func TestWriteWaitingForABackfillRespectsCtx(t *testing.T) { + src := &slowSource{data: map[string]string{"k": "old"}} + backend := newHookedCache() + cli := NewClient[string](backend, src) + reached, release := make(chan struct{}), make(chan struct{}) + backend.beforeSet = func(_, v string) error { + if v == "old" { // the GetMany backfill, holding the stripe for reading + close(reached) + <-release + } + return nil + } + getDone := make(chan struct{}) + go func() { + defer close(getDone) + _, _ = cli.GetMany(context.Background(), []string{"k"}) + }() + waitFor(t, reached) + + ctx, cancel := context.WithTimeout(context.Background(), 50*time.Millisecond) + defer cancel() + errc := make(chan error, 1) + go func() { errc <- cli.Set(ctx, "k", "new") }() + select { + case err := <-errc: + require.ErrorIs(t, err, context.DeadlineExceeded) + case <-time.After(5 * time.Second): + t.Error("Set kept waiting past its ctx") + } + close(release) + <-getDone + + v, err := backend.Get(context.Background(), "k") + require.NoError(t, err) + assert.Equal(t, "old", v, "the given-up Set wrote nothing") + require.NoError(t, cli.Set(context.Background(), "k", "new"), "the stripe is free again") +} + +func TestDelWithADoneCtxStillInvalidates(t *testing.T) { + backend := NewSyncMap[string]() + db := map[string]string{"k": "v1"} + var mu sync.Mutex + cli := NewClient[string](backend, UpstreamFunc[string](func(_ context.Context, key string) (string, error) { + mu.Lock() + defer mu.Unlock() + if v, ok := db[key]; ok { + return v, nil + } + return "", &ErrKeyNotFound{} + })) + _, err := cli.Get(context.Background(), "k") + require.NoError(t, err) + + // cache-aside: the DB is updated, then the request's ctx is canceled before the invalidation + mu.Lock() + db["k"] = "v2" + mu.Unlock() + ctx, cancel := context.WithCancel(context.Background()) + cancel() + require.NoError(t, cli.Del(ctx, "k")) + v, err := cli.Get(context.Background(), "k") + require.NoError(t, err) + assert.Equal(t, "v2", v) } // holdGetCache is a hookedCache whose Get can be held after reading. From a9797ea96ff8d27b6a6e7bdbe84cb1d7376d3735 Mon Sep 17 00:00:00 2001 From: molon <3739161+molon@users.noreply.github.com> Date: Thu, 8 Oct 2026 19:21:00 +0800 Subject: [PATCH 20/40] fix: a write that gives up waiting still drops this layer's entry, and late fetches are released too - A Set/Del that gave up waiting for its stripe wrote nothing, so this layer kept the old value: a cache-aside Del after the request was canceled could miss whenever another key of the stripe was being written or backfilled. The lock it gave up on is still taken in the background, and then drops this layer's entry like any failed write. - Release the key's in-flight fetches again after this layer is written: a fetch claimed in between may have double-checked the old value, and a read after Set/Del returned could join it. --- README.md | 2 +- README_ZH.md | 2 +- client.go | 26 ++++++--- write_order_test.go | 130 +++++++++++++++++++++++++++++++++++++++++++- 4 files changed, 148 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 4e68325..78c1027 100644 --- a/README.md +++ b/README.md @@ -334,7 +334,7 @@ The key insight: **cache writes propagate through `Cache[T]` chains but stop whe - `Set`/`Del` write the **upstream first**, then this layer, so a new value never shows up in an upper layer before the layer below has it: a `Set` becomes visible in this layer only after the write below has succeeded. The flip side is a short window while the write runs: until this layer's own write lands, a concurrent reader of this layer still sees its **old** value (after a `Del`, the deleted one), even though the layer below has already changed. Once `Set`/`Del` returns, the window is closed: a read that starts afterwards never gets a value fetched before the write (it does not join an older in-flight fetch, it starts a new one). - If the upstream write fails, its state is unknown (it may have been applied with only the reply lost), so this layer **drops** its entry for the key (and any cached Not-Found) and returns the error; the next read goes down. A failed `Del` likewise drops this layer's entry but caches no Not-Found. - If the upstream write succeeds but this layer's own write fails, `Set`/`Del` still return the error, yet the change below is **kept** (nothing is rolled back): an error does not mean nothing was written. This layer drops its entry and cached Not-Found for the key, so the next read goes down and sees the change. -- Concurrent `Set`/`Del` of one key through the same `Client` are applied one at a time, in the same order on every layer. A `Set`/`Del` that has to wait (for another write to its stripe, or a read writing back to this layer) gives up when its ctx is done, having written nothing; one that does not have to wait is applied even if its ctx is already done, so e.g. an invalidating `Del` after the request was canceled still lands in in-memory layers. Once a write has started, the cleanup after a failure (dropping this layer's entry) runs even if ctx is done, for at most `WithFetchTimeout`. +- Concurrent `Set`/`Del` of one key through the same `Client` are applied one at a time, in the same order on every layer. A `Set`/`Del` that has to wait (for another write to its stripe, or a read writing back to this layer) gives up when its ctx is done and returns the ctx error: it writes nothing upstream, and, like any failed write, drops this layer's entry for the key as soon as the stripe is free. One that does not have to wait is applied even if its ctx is already done. So an invalidating `Del` after the request was canceled always clears this layer, at worst a moment after it returns. Once a write has started, the cleanup after a failure (dropping this layer's entry) runs even if ctx is done, for at most `WithFetchTimeout`. - A read that fetched a value **before** a concurrent `Set`/`Del` still returns what it fetched, but never writes it back over the newer value: each `Client` hashes keys into 1,024 stripes, each with a write lock and a write generation, and `Get`, `GetMany` and the serve-stale refresh check the key's stripe generation while holding its lock for reading, so a backfill either lands before a `Set`/`Del` (which then overwrites it) or is skipped. A backfill is also skipped while a write to the stripe is in progress, so reads never wait on writes. Keys that share a stripe share this state: their writes run one at a time, and a write to one key can skip a backfill of another. The cost is at most an extra cache miss, or a write waiting on a write to an unrelated key. - These guarantees hold within one process; separate processes sharing a lower layer (e.g. Redis) can still briefly disagree in their memory layers. diff --git a/README_ZH.md b/README_ZH.md index 0dac468..4d28f29 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -334,7 +334,7 @@ L1 缓存 → L2 缓存 → L3 缓存 → 数据库 - `Set`/`Del` **先写 upstream**,再写本层,所以新值不会先于下层出现在上层:`Set` 的新值要等下层写成功后才在本层可见。代价是写入过程中有一个短暂的窗口:本层自己的写入落下之前,并发读本层仍会读到它的**旧值**(`Del` 时是已删掉的值),尽管下层已经变了。`Set`/`Del` 返回后窗口就关闭了:之后开始的读不会拿到写入之前回源读到的值(它不会加入更早的那次回源,而是重新回源)。 - upstream 写失败时,它的状态不明(可能已经写进去了,只是回复丢了),所以本层会**删掉**这个 key 的条目(连同缓存的 Not-Found),并返回错误;下次读会回源到下层。`Del` 失败时同样删掉本层条目,但不记 Not-Found。 - upstream 写成功、本层自己的写入失败时,`Set`/`Del` 仍返回错误,但下层的改动**保留**(不回滚):返回错误不代表什么都没写进去。本层会删掉这个 key 的条目和缓存的 Not-Found,下次读会回源到下层,读到改动后的结果。 -- 通过同一个 `Client` 并发 `Set`/`Del` 同一个 key 时,逐个执行,各层的写入顺序一致。需要等待的 `Set`/`Del`(等同一分片的其他写入,或者等正在回填本层的读),在 ctx 结束时放弃,什么都不写;不需要等待的照常执行,即使 ctx 已经结束。比如请求取消后再调 `Del` 做失效,内存层照样会删掉。写入一旦开始,失败后的清理(删掉本层条目)即使 ctx 已结束也会执行,最长 `WithFetchTimeout`。 +- 通过同一个 `Client` 并发 `Set`/`Del` 同一个 key 时,逐个执行,各层的写入顺序一致。需要等待的 `Set`/`Del`(等同一分片的其他写入,或者等正在回填本层的读),在 ctx 结束时放弃并返回 ctx 错误:它不写 upstream,并且和其他失败的写入一样,等分片空出来就删掉本层这个 key 的条目。不需要等待的照常执行,即使 ctx 已经结束。所以请求取消后再调 `Del` 做失效,本层总会被清掉,最多是在它返回后稍晚一点。写入一旦开始,失败后的清理(删掉本层条目)即使 ctx 已结束也会执行,最长 `WithFetchTimeout`。 - 回源读到值**之后**、写回本层**之前**如果发生了 `Set`/`Del`,这次读仍然返回它读到的值,但绝不会用它覆盖更新的值:每个 `Client` 把 key 按哈希分到 1,024 个分片,每个分片有一把写锁和一个写入代数,`Get`、`GetMany` 和 serve-stale 的后台刷新在持有 key 所在分片的读锁时核对分片的写入代数,所以回填要么在 `Set`/`Del` 之前落下(随后被覆盖),要么被跳过。分片正在写入时回填也直接跳过,所以读永远不等写。落在同一分片的 key 共用这份状态:它们的写入逐个执行,写一个 key 可能让另一个 key 的回填被跳过。代价最多是多一次缓存未命中,或者一次写入要等另一个不相干 key 的写入。 - 这些保证在单个进程内成立;多个进程共用同一个下层(例如 Redis)时,各自的内存层仍可能短暂不一致。 diff --git a/client.go b/client.go index 95376dd..6e57407 100644 --- a/client.go +++ b/client.go @@ -259,7 +259,8 @@ func (c *Client[T]) delWithoutUpstream(ctx context.Context, key string) error { // after Set returned never gets a value fetched before it. Concurrent writes to // one key through the same Client are applied one at a time, in the same order // on every layer. Waiting for another write or a backfill of the key's stripe -// gives up when ctx is done (writing nothing); a write that need not wait runs +// gives up when ctx is done: nothing is written upstream, and this layer's +// entry is dropped once the stripe is free. A write that need not wait runs // even with a done ctx. Once started, a failed write's cleanup outlives ctx, // for at most the fetch timeout. func (c *Client[T]) Set(ctx context.Context, key string, value T) error { @@ -288,8 +289,10 @@ type writeStripe struct { } // lock takes the stripe for writing. Waiting for another write or a backfill -// gives up when ctx is done; a free stripe is taken even with a done ctx. -func (s *writeStripe) lock(ctx context.Context) error { +// gives up when ctx is done; a free stripe is taken even with a done ctx. A +// lock given up on is still taken in the background, runs late while holding +// it, and is released. +func (s *writeStripe) lock(ctx context.Context, late func()) error { if s.mu.TryLock() { return nil } @@ -302,8 +305,9 @@ func (s *writeStripe) lock(ctx context.Context) error { case <-locked: return nil case <-ctx.Done(): - go func() { // hand the lock back once it is taken + go func() { <-locked + late() s.mu.Unlock() }() return ctx.Err() @@ -318,10 +322,6 @@ func (c *Client[T]) stripe(key string) *writeStripe { // layer. Any failure leaves this layer without an entry for the key. func (c *Client[T]) write(ctx context.Context, key string, toUpstream func(Cache[T]) error, toLayer func() error) error { s := c.stripe(key) - if err := s.lock(ctx); err != nil { - return errors.Wrapf(err, "context cancelled while waiting to write key: %s", key) - } - defer s.mu.Unlock() // Called once the upstream is written: a backfill that read the upstream // before took an older gen, so it is skipped once this lock is released, and @@ -332,6 +332,16 @@ func (c *Client[T]) write(ctx context.Context, key string, toUpstream func(Cache c.dropFlights(key) } + // A write that gave up waiting writes nothing upstream, but like any failed + // write it leaves this layer without an entry, once the stripe is free. + if err := s.lock(ctx, func() { written(); c.invalidate(ctx, key) }); err != nil { + return errors.Wrapf(err, "context cancelled while waiting to write key: %s", key) + } + defer s.mu.Unlock() + // also drop fetches claimed while this layer was being written: their + // double-check may have read the old value + defer c.dropFlights(key) + if upstreamCache, ok := c.upstream.(Cache[T]); ok { if err := toUpstream(upstreamCache); err != nil { written() diff --git a/write_order_test.go b/write_order_test.go index 38a57ee..8e6663a 100644 --- a/write_order_test.go +++ b/write_order_test.go @@ -600,9 +600,13 @@ func TestWriteWaitingForABackfillRespectsCtx(t *testing.T) { close(release) <-getDone - v, err := backend.Get(context.Background(), "k") + require.Eventually(t, func() bool { + _, err := backend.Get(context.Background(), "k") + return IsErrKeyNotFound(err) + }, time.Second, time.Millisecond, "the given-up Set drops this layer's entry once the stripe is free") + v, err := src.Get(context.Background(), "k") require.NoError(t, err) - assert.Equal(t, "old", v, "the given-up Set wrote nothing") + assert.Equal(t, "old", v, "and writes nothing upstream") require.NoError(t, cli.Set(context.Background(), "k", "new"), "the stripe is free again") } @@ -674,3 +678,125 @@ func TestWriteThroughBackfillDuringUpstreamWrite(t *testing.T) { require.NoError(t, err) assert.Equal(t, "new", v, "the Get that read L2 before the write does not backfill the old value") } + +func TestGivenUpDelStillInvalidates(t *testing.T) { + ctx := context.Background() + var mu sync.Mutex + db := map[string]string{"k": "v1"} + backend := newHookedCache() + cli := NewClient[string](backend, UpstreamFunc[string](func(_ context.Context, key string) (string, error) { + mu.Lock() + defer mu.Unlock() + if v, ok := db[key]; ok { + return v, nil + } + return "v-" + key, nil + })) + _, err := cli.Get(ctx, "k") + require.NoError(t, err) + + other := "" // an unrelated key in k's stripe + for i := 0; other == ""; i++ { + if k := fmt.Sprintf("o%d", i); cli.stripe(k) == cli.stripe("k") { + other = k + } + } + reached, release := make(chan struct{}), make(chan struct{}) + backend.beforeSet = func(key, _ string) error { + if key == other { // its backfill holds the stripe for reading + close(reached) + <-release + } + return nil + } + getDone := make(chan struct{}) + go func() { + defer close(getDone) + _, _ = cli.Get(ctx, other) + }() + waitFor(t, reached) + + // cache-aside: the DB changes, then the request's ctx is canceled before the invalidation + mu.Lock() + db["k"] = "v2" + mu.Unlock() + canceled, cancel := context.WithCancel(ctx) + cancel() + require.ErrorIs(t, cli.Del(canceled, "k"), context.Canceled, "the stripe is busy, so the Del gives up waiting") + close(release) + <-getDone + + require.Eventually(t, func() bool { + v, err := cli.Get(ctx, "k") + return err == nil && v == "v2" + }, time.Second, time.Millisecond, "the old value is dropped once the stripe is free") +} + +func TestReadAfterDelDoesNotJoinAFetchStartedDuringIt(t *testing.T) { + ctx := context.Background() + var mu sync.Mutex + db := map[string]string{"k": "v1"} + var armed atomic.Bool + r0Read, releaseR0 := make(chan struct{}), make(chan struct{}) + backend := &holdGetCache{hookedCache: newHookedCache()} + backend.onGet = func(string) { + if armed.CompareAndSwap(true, false) { // R0's double-check, after reading "v1" + close(r0Read) + <-releaseR0 + } + } + cli := NewClient[string](backend, UpstreamFunc[string](func(_ context.Context, key string) (string, error) { + mu.Lock() + defer mu.Unlock() + if v, ok := db[key]; ok { + return v, nil + } + return "", &ErrKeyNotFound{} + }), WithDoubleCheck[string](DoubleCheckEnabled)) + + var starts atomic.Int32 + r0AtClaim, r0Go := make(chan struct{}), make(chan struct{}) + cli.testHooks = &testHooks{beforeSingleflightStart: func(context.Context, string) { + if starts.Add(1) == 1 { // R0 missed before anything was cached; hold it before it claims + close(r0AtClaim) + <-r0Go + } + }} + go func() { _, _ = cli.Get(ctx, "k") }() // R0 + waitFor(t, r0AtClaim) + v, err := cli.Get(ctx, "k") // R1 caches "v1" + require.NoError(t, err) + require.Equal(t, "v1", v) + + mu.Lock() + delete(db, "k") + mu.Unlock() + backend.beforeDel = func(string) error { + // between the upstream write and this layer's delete, R0 claims a fetch + // whose double-check reads "v1" from this layer + armed.Store(true) + close(r0Go) + <-r0Read + return nil + } + require.NoError(t, cli.Del(ctx, "k")) + backend.beforeDel = nil + + got := make(chan error, 1) + go func() { // R2 starts after Del returned + v, err := cli.Get(ctx, "k") + if err == nil { + err = fmt.Errorf("got %q", v) + } + got <- err + }() + var r2 error + select { + case r2 = <-got: + close(releaseR0) + case <-time.After(time.Second): // R2 joined R0's fetch + close(releaseR0) + r2 = <-got + } + assert.True(t, IsErrKeyNotFound(r2), "a Get after Del returned sees the delete: %v", r2) +} From ee66cc127277cf8ffcd43cc07bc321fa60acf51e Mon Sep 17 00:00:00 2001 From: molon <3739161+molon@users.noreply.github.com> Date: Thu, 8 Oct 2026 19:25:50 +0800 Subject: [PATCH 21/40] test: randomized interleavings never read older than a completed write One writer per key Sets and Dels increasing versions through L1 -> L2 -> a source with random latency, while readers Get and GetMany. A read that starts after write n returned must see version n or a later one that had started (a Del being the version "absent"), and once quiet every layer agrees with the source. Runs with and without a not-found cache and double-check. It catches a disabled dropFlights in most runs and a backfill that skips the generation check occasionally. --- write_order_test.go | 155 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 155 insertions(+) diff --git a/write_order_test.go b/write_order_test.go index 8e6663a..adca0d1 100644 --- a/write_order_test.go +++ b/write_order_test.go @@ -800,3 +800,158 @@ func TestReadAfterDelDoesNotJoinAFetchStartedDuringIt(t *testing.T) { } assert.True(t, IsErrKeyNotFound(r2), "a Get after Del returned sees the delete: %v", r2) } + +// jitterCache is a Cache with random latency, to shake out interleavings. +type jitterCache struct{ m *SyncMap[string] } + +func jitter() { time.Sleep(time.Duration(rand.IntN(200)) * time.Microsecond) } + +func (j jitterCache) Get(ctx context.Context, key string) (string, error) { + jitter() + v, err := j.m.Get(ctx, key) + jitter() // between reading and returning: where a write can slip in before the backfill + jitter() + jitter() + return v, err +} + +func (j jitterCache) Set(ctx context.Context, key, value string) error { + jitter() + return j.m.Set(ctx, key, value) +} + +func (j jitterCache) Del(ctx context.Context, key string) error { + jitter() + return j.m.Del(ctx, key) +} + +// TestRandomInterleavingsNeverReadOlderThanACompletedWrite: one writer per +// key Sets and Dels versions 1, 2, 3...; readers Get and GetMany through two +// layers. A read that starts after write n returned must see version n or a +// later one that had started (a Del is the version "absent"). +func TestRandomInterleavingsNeverReadOlderThanACompletedWrite(t *testing.T) { + for _, notFound := range []bool{false, true} { + for _, dc := range []DoubleCheckMode{DoubleCheckDisabled, DoubleCheckEnabled} { + t.Run(fmt.Sprintf("notFoundCache=%v doubleCheck=%v", notFound, dc == DoubleCheckEnabled), func(t *testing.T) { + testRandomInterleavings(t, notFound, dc) + }) + } + } +} + +func testRandomInterleavings(t *testing.T, withNotFound bool, dc DoubleCheckMode) { + ctx := context.Background() + keys := []string{"a", "b"} + type history struct { + mu sync.Mutex + isDel []bool // by version; version 0 is the initial "absent" + started int + done int + } + hist := map[string]*history{} + for _, k := range keys { + hist[k] = &history{isDel: []bool{true}} + } + + src := jitterCache{m: NewSyncMap[string]()} + l2 := NewClient[string](jitterCache{m: NewSyncMap[string]()}, src) + opts := []ClientOption[string]{WithDoubleCheck[string](dc)} + if withNotFound { + opts = append(opts, NotFoundWithTTL[string](NewSyncMap[time.Time](), time.Hour, 0)) + } + l1 := NewClient[string](NewSyncMap[string](), l2, opts...) + + // check reports whether what a read saw for key is allowed, given the + // version completed before it started. + check := func(key string, floor int, v string, found bool) error { + h := hist[key] + h.mu.Lock() + defer h.mu.Unlock() + if found { + var n int + if _, err := fmt.Sscanf(v, key+":%d", &n); err != nil || n < floor || n > h.started || h.isDel[n] { + return fmt.Errorf("%s: got %q, but write %d had completed before the read", key, v, floor) + } + return nil + } + for n := floor; n <= h.started; n++ { + if h.isDel[n] { + return nil + } + } + return fmt.Errorf("%s: got absent, but write %d (a Set) had completed and no later Del had started", key, floor) + } + + var wg sync.WaitGroup + for _, k := range keys { + wg.Go(func() { + h := hist[k] + for n := 1; n <= 300; n++ { + del := rand.IntN(2) == 0 + h.mu.Lock() + h.isDel = append(h.isDel, del) + h.started = n + h.mu.Unlock() + var err error + if del { + err = l1.Del(ctx, k) + } else { + err = l1.Set(ctx, k, fmt.Sprintf("%s:%d", k, n)) + } + if !assert.NoError(t, err) { + return + } + h.mu.Lock() + h.done = n + h.mu.Unlock() + } + }) + } + var violations atomic.Int32 + for range 12 { + wg.Go(func() { + for range 400 { + floors := map[string]int{} + for _, k := range keys { + hist[k].mu.Lock() + floors[k] = hist[k].done + hist[k].mu.Unlock() + } + if rand.IntN(2) == 0 { + k := keys[rand.IntN(len(keys))] + v, err := l1.Get(ctx, k) + if err != nil && !IsErrKeyNotFound(err) { + t.Errorf("Get(%s): %v", k, err) + return + } + if err := check(k, floors[k], v, err == nil); err != nil { + violations.Add(1) + t.Error(err) + } + continue + } + got, err := l1.GetMany(ctx, keys) + if err != nil { + t.Errorf("GetMany: %v", err) + return + } + for _, k := range keys { + v, ok := got[k] + if err := check(k, floors[k], v, ok); err != nil { + violations.Add(1) + t.Error(err) + } + } + } + }) + } + wg.Wait() + require.Zero(t, violations.Load()) + + for _, k := range keys { // quiesced: every layer agrees with the source + want, wantErr := src.Get(ctx, k) + got, err := l1.Get(ctx, k) + assert.Equal(t, IsErrKeyNotFound(wantErr), IsErrKeyNotFound(err), k) + assert.Equal(t, want, got, k) + } +} From 4e7cac25efee0f30c2563e569f928ae90dea8f08 Mon Sep 17 00:00:00 2001 From: molon <3739161+molon@users.noreply.github.com> Date: Thu, 8 Oct 2026 20:01:36 +0800 Subject: [PATCH 22/40] feat: create MySQL cache tables case-sensitive, and test GORMCache on MySQL and PostgreSQL - Migrate creates the table with utf8mb4_bin on MySQL, whose default collations are case-insensitive while cache keys are not. Only a new table gets it; an existing one is left as it is (README shows the ALTER), and GORMCache still never serves another key's row there. - TestGORMCacheOnRealDatabases runs MySQL 8.4 and PostgreSQL 16 in testcontainers (skipped without Docker; CI has it): the BatchCache contract, a batch over several statements, case-sensitive keys, an existing case-insensitive MySQL table, and Client reads and writes. - Fix a test that could see the stripe free just before a given-up write's background lock took it. --- README.md | 2 +- README_ZH.md | 2 +- go.mod | 53 ++++++++++++- go.sum | 167 ++++++++++++++++++++++++++++++++++++++++- gorm.go | 15 ++-- gorm_container_test.go | 120 +++++++++++++++++++++++++++++ write_order_test.go | 5 +- 7 files changed, 351 insertions(+), 13 deletions(-) create mode 100644 gorm_container_test.go diff --git a/README.md b/README.md index 78c1027..1b82565 100644 --- a/README.md +++ b/README.md @@ -215,7 +215,7 @@ if err := cache.Migrate(ctx); err != nil { } ``` -Cache keys are case-sensitive, so the `key` column should compare byte for byte. PostgreSQL and SQLite do by default; on MySQL, `Migrate` creates a `varchar(255)` with the table's collation, usually case- and accent-insensitive (`*_ci`), so give the table or the column a `*_bin` collation (e.g. `utf8mb4_bin`). Without it nothing wrong is ever served: `GORMCache` only returns the row stored under exactly the requested key, so keys differing only in case just take the row over from each other (extra misses). +Cache keys are case-sensitive, so the `key` column should compare byte for byte. PostgreSQL and SQLite do by default, and on MySQL `Migrate` creates the table with `utf8mb4_bin`. A table created before that (or by hand) keeps its collation, usually case- and accent-insensitive (`*_ci`); convert it with `ALTER TABLE cache_products CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_bin`. Even without it nothing wrong is ever served: `GORMCache` only returns the row stored under exactly the requested key, so keys differing only in case just take the row over from each other (extra misses). ### Custom Cache diff --git a/README_ZH.md b/README_ZH.md index 4d28f29..69e598f 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -215,7 +215,7 @@ if err := cache.Migrate(ctx); err != nil { } ``` -缓存 key 区分大小写,所以 `key` 列应当逐字节比较。PostgreSQL 和 SQLite 默认如此;MySQL 上 `Migrate` 建的是沿用表排序规则的 `varchar(255)`,通常不区分大小写和重音(`*_ci`),请给表或这一列设 `*_bin` 排序规则(例如 `utf8mb4_bin`)。不设也不会读到错的值:`GORMCache` 只返回 key 完全相等的那一行,只差大小写的几个 key 只会互相挤占这一行(多几次未命中)。 +缓存 key 区分大小写,所以 `key` 列应当逐字节比较。PostgreSQL 和 SQLite 默认如此;MySQL 上 `Migrate` 建表时会用 `utf8mb4_bin`。在这之前建的表(或手工建的表)保留原来的排序规则,通常不区分大小写和重音(`*_ci`),可以用 `ALTER TABLE cache_products CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_bin` 转换。即使不转换也不会读到错的值:`GORMCache` 只返回 key 完全相等的那一行,只差大小写的几个 key 只会互相挤占这一行(多几次未命中)。 ### 自定义缓存 diff --git a/go.mod b/go.mod index 8b6998d..6bfcdb6 100644 --- a/go.mod +++ b/go.mod @@ -9,31 +9,78 @@ require ( github.com/pkg/errors v0.9.1 github.com/redis/go-redis/v9 v9.16.0 github.com/stretchr/testify v1.11.1 + github.com/testcontainers/testcontainers-go v0.44.0 + github.com/testcontainers/testcontainers-go/modules/mysql v0.44.0 + github.com/testcontainers/testcontainers-go/modules/postgres v0.44.0 golang.org/x/sync v0.23.0 gorm.io/datatypes v1.2.7 + gorm.io/driver/mysql v1.5.6 + gorm.io/driver/postgres v1.5.0 gorm.io/driver/sqlite v1.6.0 gorm.io/gorm v1.31.1 ) require ( + dario.cat/mergo v1.0.2 // indirect filippo.io/edwards25519 v1.1.1 // indirect + github.com/Azure/go-ansiterm v0.0.0-20250102033503-faa5f7b0171c // indirect + github.com/Microsoft/go-winio v0.6.2 // indirect + github.com/cenkalti/backoff/v4 v4.3.0 // indirect github.com/cespare/xxhash/v2 v2.3.0 // indirect + github.com/containerd/errdefs v1.0.0 // indirect + github.com/containerd/errdefs/pkg v0.3.0 // indirect + github.com/containerd/log v0.1.0 // indirect + github.com/containerd/platforms v0.2.1 // indirect + github.com/cpuguy83/dockercfg v0.3.2 // indirect github.com/davecgh/go-spew v1.1.1 // indirect github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f // indirect + github.com/distribution/reference v0.6.0 // indirect + github.com/docker/go-connections v0.7.0 // indirect + github.com/docker/go-units v0.5.0 // indirect github.com/dustin/go-humanize v1.0.1 // indirect + github.com/ebitengine/purego v0.10.1 // indirect + github.com/felixge/httpsnoop v1.1.0 // indirect + github.com/go-logr/logr v1.4.3 // indirect + github.com/go-logr/stdr v1.2.2 // indirect + github.com/go-ole/go-ole v1.3.0 // indirect github.com/go-sql-driver/mysql v1.8.1 // indirect github.com/google/uuid v1.6.0 // indirect + github.com/jackc/pgpassfile v1.0.0 // indirect + github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect github.com/jackc/pgx/v5 v5.11.0 // indirect + github.com/jackc/puddle/v2 v2.2.2 // indirect github.com/jinzhu/inflection v1.0.0 // indirect github.com/jinzhu/now v1.1.5 // indirect - github.com/kr/pretty v0.3.0 // indirect + github.com/klauspost/compress v1.18.6 // indirect + github.com/lufia/plan9stats v0.0.0-20260330125221-c963978e514e // indirect + github.com/magiconair/properties v1.8.10 // indirect github.com/mattn/go-sqlite3 v1.14.22 // indirect + github.com/moby/docker-image-spec v1.3.1 // indirect + github.com/moby/go-archive v0.2.0 // indirect + github.com/moby/moby/api v1.55.0 // indirect + github.com/moby/moby/client v0.5.0 // indirect + github.com/moby/patternmatcher v0.6.1 // indirect + github.com/moby/sys/sequential v0.7.0 // indirect + github.com/moby/sys/user v0.4.0 // indirect + github.com/moby/sys/userns v0.1.0 // indirect + github.com/moby/term v0.5.2 // indirect + github.com/opencontainers/go-digest v1.0.0 // indirect + github.com/opencontainers/image-spec v1.1.1 // indirect github.com/pmezard/go-difflib v1.0.0 // indirect + github.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55 // indirect + github.com/shirou/gopsutil/v4 v4.26.6 // indirect + github.com/sirupsen/logrus v1.9.4 // indirect + github.com/tklauser/go-sysconf v0.4.0 // indirect + github.com/tklauser/numcpus v0.12.0 // indirect github.com/yuin/gopher-lua v1.1.1 // indirect + github.com/yusufpapurcu/wmi v1.2.4 // indirect + go.opentelemetry.io/auto/sdk v1.2.1 // indirect + go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.69.0 // indirect + go.opentelemetry.io/otel v1.44.0 // indirect + go.opentelemetry.io/otel/metric v1.44.0 // indirect + go.opentelemetry.io/otel/trace v1.44.0 // indirect golang.org/x/crypto v0.57.0 // indirect golang.org/x/sys v0.48.0 // indirect golang.org/x/text v0.42.0 // indirect - gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c // indirect gopkg.in/yaml.v3 v3.0.1 // indirect - gorm.io/driver/mysql v1.5.6 // indirect ) diff --git a/go.sum b/go.sum index fc5b218..84a9c67 100644 --- a/go.sum +++ b/go.sum @@ -1,5 +1,13 @@ +dario.cat/mergo v1.0.2 h1:85+piFYR1tMbRrLcDwR18y4UKJ3aH1Tbzi24VRW1TK8= +dario.cat/mergo v1.0.2/go.mod h1:E/hbnu0NxMFBjpMIE34DRGLWqDy0g5FuKDhCb31ngxA= filippo.io/edwards25519 v1.1.1 h1:YpjwWWlNmGIDyXOn8zLzqiD+9TyIlPhGFG96P39uBpw= filippo.io/edwards25519 v1.1.1/go.mod h1:BxyFTGdWcka3PhytdK4V28tE5sGfRvvvRV7EaN4VDT4= +github.com/AdaLogics/go-fuzz-headers v0.0.0-20240806141605-e8a1dd7889d6 h1:He8afgbRMd7mFxO99hRNu+6tazq8nFF9lIwo9JFroBk= +github.com/AdaLogics/go-fuzz-headers v0.0.0-20240806141605-e8a1dd7889d6/go.mod h1:8o94RPi1/7XTJvwPpRSzSUedZrtlirdB3r9Z20bi2f8= +github.com/Azure/go-ansiterm v0.0.0-20250102033503-faa5f7b0171c h1:udKWzYgxTojEKWjV8V+WSxDXJ4NFATAsZjh8iIbsQIg= +github.com/Azure/go-ansiterm v0.0.0-20250102033503-faa5f7b0171c/go.mod h1:xomTg63KZ2rFqZQzSB4Vz2SUXa1BpHTVz9L5PTmPC4E= +github.com/Microsoft/go-winio v0.6.2 h1:F2VQgta7ecxGYO8k3ZZz3RS8fVIXVxONVUPlNERoyfY= +github.com/Microsoft/go-winio v0.6.2/go.mod h1:yd8OoFMLzJbo9gZq8j5qaps8bJ9aShtEA8Ipt1oGCvU= github.com/alicebob/miniredis/v2 v2.35.0 h1:QwLphYqCEAo1eu1TqPRN2jgVMPBweeQcR21jeqDCONI= github.com/alicebob/miniredis/v2 v2.35.0/go.mod h1:TcL7YfarKPGDAthEtl5NBeHZfeUQj6OXMm/+iu5cLMM= github.com/allegro/bigcache/v3 v3.1.0 h1:H2Vp8VOvxcrB91o86fUSVJFqeuz8kpyyB02eH3bSzwk= @@ -8,9 +16,24 @@ github.com/bsm/ginkgo/v2 v2.12.0 h1:Ny8MWAHyOepLGlLKYmXG4IEkioBysk6GpaRTLC8zwWs= github.com/bsm/ginkgo/v2 v2.12.0/go.mod h1:SwYbGRRDovPVboqFv0tPTcG1sN61LM1Z4ARdbAV9g4c= github.com/bsm/gomega v1.27.10 h1:yeMWxP2pV2fG3FgAODIY8EiRE3dy0aeFYt4l7wh6yKA= github.com/bsm/gomega v1.27.10/go.mod h1:JyEr/xRbxbtgWNi8tIEVPUYZ5Dzef52k01W3YH0H+O0= +github.com/cenkalti/backoff/v4 v4.3.0 h1:MyRJ/UdXutAwSAT+s3wNd7MfTIcy71VQueUuFK343L8= +github.com/cenkalti/backoff/v4 v4.3.0/go.mod h1:Y3VNntkOUPxTVeUxJ/G5vcM//AlwfmyYozVcomhLiZE= github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs= github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs= +github.com/containerd/errdefs v1.0.0 h1:tg5yIfIlQIrxYtu9ajqY42W3lpS19XqdxRQeEwYG8PI= +github.com/containerd/errdefs v1.0.0/go.mod h1:+YBYIdtsnF4Iw6nWZhJcqGSg/dwvV7tyJ/kCkyJ2k+M= +github.com/containerd/errdefs/pkg v0.3.0 h1:9IKJ06FvyNlexW690DXuQNx2KA2cUJXx151Xdx3ZPPE= +github.com/containerd/errdefs/pkg v0.3.0/go.mod h1:NJw6s9HwNuRhnjJhM7pylWwMyAkmCQvQ4GpJHEqRLVk= +github.com/containerd/log v0.1.0 h1:TCJt7ioM2cr/tfR8GPbGf9/VRAX8D2B4PjzCpfX540I= +github.com/containerd/log v0.1.0/go.mod h1:VRRf09a7mHDIRezVKTRCrOq78v577GXq3bSa3EhrzVo= +github.com/containerd/platforms v0.2.1 h1:zvwtM3rz2YHPQsF2CHYM8+KtB5dvhISiXh5ZpSBQv6A= +github.com/containerd/platforms v0.2.1/go.mod h1:XHCb+2/hzowdiut9rkudds9bE5yJ7npe7dG/wG+uFPw= +github.com/cpuguy83/dockercfg v0.3.2 h1:DlJTyZGBDlXqUZ2Dk2Q3xHs/FtnooJJVaad2S9GKorA= +github.com/cpuguy83/dockercfg v0.3.2/go.mod h1:sugsbF4//dDlL/i+S+rtpIWp+5h0BHJHfjj5/jFyUJc= github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E= +github.com/creack/pty v1.1.24 h1:bJrF4RRfyJnbTJqzRLHzcGaZK1NeM5kTC9jGgovnR1s= +github.com/creack/pty v1.1.24/go.mod h1:08sCNb52WyoAwi2QDyzUCTgcvVFhUzewun7wtTfvcwE= +github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c= github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= github.com/dgraph-io/ristretto/v2 v2.3.0 h1:qTQ38m7oIyd4GAed/QkUZyPFNMnvVWyazGXRwvOt5zk= @@ -19,8 +42,26 @@ github.com/dgryski/go-farm v0.0.0-20240924180020-3414d57e47da h1:aIftn67I1fkbMa5 github.com/dgryski/go-farm v0.0.0-20240924180020-3414d57e47da/go.mod h1:SqUrOPUnsFjfmXRMNPybcSiG0BgUW2AuFH8PAnS2iTw= github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f h1:lO4WD4F/rVNCu3HqELle0jiPLLBs70cWOduZpkS1E78= github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f/go.mod h1:cuUVRXasLTGF7a8hSLbxyZXjz+1KgoB3wDUb6vlszIc= +github.com/distribution/reference v0.6.0 h1:0IXCQ5g4/QMHHkarYzh5l+u8T3t73zM5QvfrDyIgxBk= +github.com/distribution/reference v0.6.0/go.mod h1:BbU0aIcezP1/5jX/8MP0YiH4SdvB5Y4f/wlDRiLyi3E= +github.com/docker/go-connections v0.7.0 h1:6SsRfJddP22WMrCkj19x9WKjEDTB+ahsdiGYf0mN39c= +github.com/docker/go-connections v0.7.0/go.mod h1:no1qkHdjq7kLMGUXYAduOhYPSJxxvgWBh7ogVvptn3Q= +github.com/docker/go-units v0.5.0 h1:69rxXcBk27SvSaaxTtLh/8llcHD8vYHT7WSdRZ/jvr4= +github.com/docker/go-units v0.5.0/go.mod h1:fgPhTUdO+D/Jk86RDLlptpiXQzgHJF7gydDDbaIK4Dk= github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY= github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto= +github.com/ebitengine/purego v0.10.1 h1:dewVBCBT2GaMu1SrNTYxQhgQBethzfhiwvZiLGP/qyY= +github.com/ebitengine/purego v0.10.1/go.mod h1:iIjxzd6CiRiOG0UyXP+V1+jWqUXVjPKLAI0mRfJZTmQ= +github.com/felixge/httpsnoop v1.1.0 h1:3YtUj32ZZkqZtt3sZZsClsymw/QDuVfpNhoA31zeORc= +github.com/felixge/httpsnoop v1.1.0/go.mod h1:Zqxgdd+1Rkcz8euOqdr7lqgCRJztwr5hp9vDSi5UZCE= +github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A= +github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI= +github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY= +github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag= +github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE= +github.com/go-ole/go-ole v1.2.6/go.mod h1:pprOEPIfldk/42T2oK7lQ4v4JSDwmV0As9GaiUsvbm0= +github.com/go-ole/go-ole v1.3.0 h1:Dt6ye7+vXGIKZ7Xtk4s6/xVdGDQynvom7xCFEdWr6uE= +github.com/go-ole/go-ole v1.3.0/go.mod h1:5LS6F96DhAwUc7C+1HLexzMXY1xGRSryjyPPKW6zv78= github.com/go-sql-driver/mysql v1.7.0/go.mod h1:OXbVy3sEdcQ2Doequ6Z5BW6fXNQTmx+9S1MCJN5yJMI= github.com/go-sql-driver/mysql v1.8.1 h1:LedoTUt/eveggdHS9qUFC1EFSa8bU2+1pZjSRpvNJ1Y= github.com/go-sql-driver/mysql v1.8.1/go.mod h1:wEBSXgmK//2ZFJyE+qWnIsVGmvmEKlqwuVSjsCm7DZg= @@ -28,57 +69,174 @@ github.com/golang-sql/civil v0.0.0-20220223132316-b832511892a9 h1:au07oEsX2xN0kt github.com/golang-sql/civil v0.0.0-20220223132316-b832511892a9/go.mod h1:8vg3r2VgvsThLBIFL93Qb5yWzgyZWhEmBwUJWevAkK0= github.com/golang-sql/sqlexp v0.1.0 h1:ZCD6MBpcuOVfGVqsEmY5/4FtYiKz6tSyUv9LPEDei6A= github.com/golang-sql/sqlexp v0.1.0/go.mod h1:J4ad9Vo8ZCWQ2GMrC4UCQy1JpCbwU9m3EOqtpKwwwHI= +github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8= +github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU= github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0= github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo= github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsIM= github.com/jackc/pgpassfile v1.0.0/go.mod h1:CEx0iS5ambNFdcRtxPj5JhEz+xB6uRky5eyVu/W2HEg= +github.com/jackc/pgservicefile v0.0.0-20221227161230-091c0ba34f0a/go.mod h1:5TJZWKEWniPve33vlWYSoGYefn3gLQRzjfDlhSJ9ZKM= github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 h1:iCEnooe7UlwOQYpKFhBabPMi4aNAfoODPEFNiAnClxo= github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761/go.mod h1:5TJZWKEWniPve33vlWYSoGYefn3gLQRzjfDlhSJ9ZKM= +github.com/jackc/pgx/v5 v5.3.0/go.mod h1:t3JDKnCBlYIc0ewLF0Q7B8MXmoIaBOZj/ic7iHozM/8= github.com/jackc/pgx/v5 v5.11.0 h1:IzBBtyK9AHqf98cctWFifYSci2hgQR/cd56wB4p+ogg= github.com/jackc/pgx/v5 v5.11.0/go.mod h1:mal1tBGAFfLHvZzaYh77YS/eC6IX9OWbRV1QIIM0Jn4= +github.com/jackc/puddle/v2 v2.2.0/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4= github.com/jackc/puddle/v2 v2.2.2 h1:PR8nw+E/1w0GLuRFSmiioY6UooMp6KJv0/61nB7icHo= github.com/jackc/puddle/v2 v2.2.2/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4= github.com/jinzhu/inflection v1.0.0 h1:K317FqzuhWc8YvSVlFMCCUb36O/S9MCKRDI7QkRKD/E= github.com/jinzhu/inflection v1.0.0/go.mod h1:h+uFLlag+Qp1Va5pdKtLDYj+kHp5pxUVkryuEj+Srlc= github.com/jinzhu/now v1.1.5 h1:/o9tlHleP7gOFmsnYNz3RGnqzefHA47wQpKrrdTIwXQ= github.com/jinzhu/now v1.1.5/go.mod h1:d3SSVoowX0Lcu0IBviAWJpolVfI5UJVZZ7cO71lE/z8= +github.com/klauspost/compress v1.18.6 h1:2jupLlAwFm95+YDR+NwD2MEfFO9d4z4Prjl1XXDjuao= +github.com/klauspost/compress v1.18.6/go.mod h1:cwPg85FWrGar70rWktvGQj8/hthj3wpl0PGDogxkrSQ= github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORNo= github.com/kr/pretty v0.2.1/go.mod h1:ipq/a2n7PKx3OHsz4KJII5eveXtPO4qwEXGdVfWzfnI= -github.com/kr/pretty v0.3.0 h1:WgNl7dwNpEZ6jJ9k1snq4pZsg7DOEN8hP9Xw0Tsjwk0= github.com/kr/pretty v0.3.0/go.mod h1:640gp4NfQd8pI5XOwp5fnNeVWj67G7CFk/SaSQn7NBk= +github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE= +github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk= github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ= github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI= github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY= github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE= +github.com/lib/pq v1.10.9 h1:YXG7RB+JIjhP29X+OtkiDnYaXQwpS4JEWq7dtCCRUEw= +github.com/lib/pq v1.10.9/go.mod h1:AlVN5x4E4T544tWzH6hKfbfQvm3HdbOxrmggDNAPY9o= +github.com/lufia/plan9stats v0.0.0-20260330125221-c963978e514e h1:Q6MvJtQK/iRcRtzAscm/zF23XxJlbECiGPyRicsX+Ak= +github.com/lufia/plan9stats v0.0.0-20260330125221-c963978e514e/go.mod h1:autxFIvghDt3jPTLoqZ9OZ7s9qTGNAWmYCjVFWPX/zg= +github.com/magiconair/properties v1.8.10 h1:s31yESBquKXCV9a/ScB3ESkOjUYYv+X0rg8SYxI99mE= +github.com/magiconair/properties v1.8.10/go.mod h1:Dhd985XPs7jluiymwWYZ0G4Z61jb3vdS329zhj2hYo0= github.com/mattn/go-sqlite3 v1.14.22 h1:2gZY6PC6kBnID23Tichd1K+Z0oS6nE/XwU+Vz/5o4kU= github.com/mattn/go-sqlite3 v1.14.22/go.mod h1:Uh1q+B4BYcTPb+yiD3kU8Ct7aC0hY9fxUwlHK0RXw+Y= +github.com/mdelapenya/tlscert v0.2.0 h1:7H81W6Z/4weDvZBNOfQte5GpIMo0lGYEeWbkGp5LJHI= +github.com/mdelapenya/tlscert v0.2.0/go.mod h1:O4njj3ELLnJjGdkN7M/vIVCpZ+Cf0L6muqOG4tLSl8o= github.com/microsoft/go-mssqldb v1.7.2 h1:CHkFJiObW7ItKTJfHo1QX7QBBD1iV+mn1eOyRP3b/PA= github.com/microsoft/go-mssqldb v1.7.2/go.mod h1:kOvZKUdrhhFQmxLZqbwUV0rHkNkZpthMITIb2Ko1IoA= +github.com/moby/docker-image-spec v1.3.1 h1:jMKff3w6PgbfSa69GfNg+zN/XLhfXJGnEx3Nl2EsFP0= +github.com/moby/docker-image-spec v1.3.1/go.mod h1:eKmb5VW8vQEh/BAr2yvVNvuiJuY6UIocYsFu/DxxRpo= +github.com/moby/go-archive v0.2.0 h1:zg5QDUM2mi0JIM9fdQZWC7U8+2ZfixfTYoHL7rWUcP8= +github.com/moby/go-archive v0.2.0/go.mod h1:mNeivT14o8xU+5q1YnNrkQVpK+dnNe/K6fHqnTg4qPU= +github.com/moby/moby/api v1.55.0 h1:2/sexvQyqIWS8pRSCFddBfpW2qE7vR7FCL+vN8pxwMc= +github.com/moby/moby/api v1.55.0/go.mod h1:+RQ6wluLwtYaTd1WnPLykIDPekkuyD/ROWQClE83pzs= +github.com/moby/moby/client v0.5.0 h1:5XhyPk2fuOWf6RlSFa3MkIIgDZkF25xToXW8Q/BH7cc= +github.com/moby/moby/client v0.5.0/go.mod h1:rcVpF8ncl9vo5gaIBdol6CnbEtSj1uxMvEV/UrykF/s= +github.com/moby/patternmatcher v0.6.1 h1:qlhtafmr6kgMIJjKJMDmMWq7WLkKIo23hsrpR3x084U= +github.com/moby/patternmatcher v0.6.1/go.mod h1:hDPoyOpDY7OrrMDLaYoY3hf52gNCR/YOUYxkhApJIxc= +github.com/moby/sys/sequential v0.7.0 h1:ASQNGNROJSuOO6LL6bPHbKvuZu6NU8P4ldPWk31zj/8= +github.com/moby/sys/sequential v0.7.0/go.mod h1:NfSTAp6V3fw4tmkD62PEcOKeZKquXT8VKCkf7aVR79o= +github.com/moby/sys/user v0.4.0 h1:jhcMKit7SA80hivmFJcbB1vqmw//wU61Zdui2eQXuMs= +github.com/moby/sys/user v0.4.0/go.mod h1:bG+tYYYJgaMtRKgEmuueC0hJEAZWwtIbZTB+85uoHjs= +github.com/moby/sys/userns v0.1.0 h1:tVLXkFOxVu9A64/yh59slHVv9ahO9UIev4JZusOLG/g= +github.com/moby/sys/userns v0.1.0/go.mod h1:IHUYgu/kao6N8YZlp9Cf444ySSvCmDlmzUcYfDHOl28= +github.com/moby/term v0.5.2 h1:6qk3FJAFDs6i/q3W/pQ97SX192qKfZgGjCQqfCJkgzQ= +github.com/moby/term v0.5.2/go.mod h1:d3djjFCrjnB+fl8NJux+EJzu0msscUP+f8it8hPkFLc= +github.com/opencontainers/go-digest v1.0.0 h1:apOUWs51W5PlhuyGyz9FCeeBIOUDA/6nW8Oi/yOhh5U= +github.com/opencontainers/go-digest v1.0.0/go.mod h1:0JzlMkj0TRzQZfJkVvzbP0HBR3IKzErnv2BNG4W4MAM= +github.com/opencontainers/image-spec v1.1.1 h1:y0fUlFfIZhPF1W537XOLg0/fcx6zcHCJwooC2xJA040= +github.com/opencontainers/image-spec v1.1.1/go.mod h1:qpqAh3Dmcf36wStyyWU+kCeDgrGnAve2nCC8+7h8Q0M= github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4= github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0= github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= +github.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55 h1:o4JXh1EVt9k/+g42oCprj/FisM4qX9L3sZB3upGN2ZU= +github.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55/go.mod h1:OmDBASR4679mdNQnz2pUhc2G8CO2JrUAVFDRBDP/hJE= github.com/redis/go-redis/v9 v9.16.0 h1:OotgqgLSRCmzfqChbQyG1PHC3tLNR89DG4jdOERSEP4= github.com/redis/go-redis/v9 v9.16.0/go.mod h1:u410H11HMLoB+TP67dz8rL9s6QW2j76l0//kSOd3370= -github.com/rogpeppe/go-internal v1.6.1 h1:/FiVV8dS/e+YqF2JvO3yXRFbBLTIuSDkuC7aBOAvL+k= github.com/rogpeppe/go-internal v1.6.1/go.mod h1:xXDCJY+GAPziupqXw64V24skbSoqbTEfhy4qGm1nDQc= +github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ= +github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc= +github.com/shirou/gopsutil/v4 v4.26.6 h1:Mzr/npDtQC/xpeEuQKHZt8Zo9CmPvhTj8nkR8w5TLDs= +github.com/shirou/gopsutil/v4 v4.26.6/go.mod h1:LZ6ewCSkBqUpvSOf+LsTGnRinC6iaNUNMGBtDkJBaLQ= +github.com/sirupsen/logrus v1.9.4 h1:TsZE7l11zFCLZnZ+teH4Umoq5BhEIfIzfRDZ1Uzql2w= +github.com/sirupsen/logrus v1.9.4/go.mod h1:ftWc9WdOfJ0a92nsE2jF5u5ZwH8Bv2zdeOC42RjbV2g= +github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME= +github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw= +github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo= +github.com/stretchr/objx v0.5.3 h1:jmXUvGomnU1o3W/V5h2VEradbpJDwGrzugQQvL0POH4= +github.com/stretchr/objx v0.5.3/go.mod h1:rDQraq+vQZU7Fde9LOZLr8Tax6zZvy4kuNKF+QYS+U0= +github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI= +github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg= +github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg= +github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU= +github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4= github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U= github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U= +github.com/testcontainers/testcontainers-go v0.44.0 h1:/Fwh6HY1mIikhnm9e7HwoxGycx0lzRAE0f5VQpjFxzI= +github.com/testcontainers/testcontainers-go v0.44.0/go.mod h1:IcnwQrYTO86xHXu5bvMaBH7ATlbS3Qn1M1QWW3c66rE= +github.com/testcontainers/testcontainers-go/modules/mysql v0.44.0 h1:oJPJPxNE6YQ0zlq6mZKh06JOlyimCky4ruQUimdDet4= +github.com/testcontainers/testcontainers-go/modules/mysql v0.44.0/go.mod h1:MSOAU6ukCpehJVHQDN1k9JgOZXZuqHD+2pT20M3JkIg= +github.com/testcontainers/testcontainers-go/modules/postgres v0.44.0 h1:8fdv/9y3JMxjQ+ULAcOG8RtgeNu5t9XF9LolSXDuTwM= +github.com/testcontainers/testcontainers-go/modules/postgres v0.44.0/go.mod h1:CFr2LncGYokw+OKjXcr8ARCKG1SaC2UEnGxFBovE86g= +github.com/tklauser/go-sysconf v0.4.0 h1:7H0uAN+7RkwWRaxhYXDLqa5V3LPrJeV8wmD9dRUgPQU= +github.com/tklauser/go-sysconf v0.4.0/go.mod h1:8mTNWyog7H+MpKijp4VmKJAd2bbYQ2zuUwkYRbUArPI= +github.com/tklauser/numcpus v0.12.0 h1:NR85qdvHA9pFse3x3weVZ0r0ST8R6l5RHbZrlRaqob4= +github.com/tklauser/numcpus v0.12.0/go.mod h1:ABHeXzJnr/qqwguhClkZKT1/8VABcYrsyUiUGobwWJg= +github.com/yuin/goldmark v1.4.13/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY= github.com/yuin/gopher-lua v1.1.1 h1:kYKnWBjvbNP4XLT3+bPEwAXJx262OhaHDWDVOPjL46M= github.com/yuin/gopher-lua v1.1.1/go.mod h1:GBR0iDaNXjAgGg9zfCvksxSRnQx76gclCIb7kdAd1Pw= +github.com/yusufpapurcu/wmi v1.2.4 h1:zFUKzehAFReQwLys1b/iSMl+JQGSCSjtVqQn9bBrPo0= +github.com/yusufpapurcu/wmi v1.2.4/go.mod h1:SBZ9tNy3G9/m5Oi98Zks0QjeHVDvuK0qfxQmPyzfmi0= +go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64= +go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y= +go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.69.0 h1:8tvICD4vSTOOsNrsI4Ljf6C+6UKvpTEH5XY3JMoyPoo= +go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.69.0/go.mod h1:z9+yiacE0IHRqM4qFfkbt/JYlmYXgss8GY/jXoNuPJI= +go.opentelemetry.io/otel v1.44.0 h1:JjwHmHpA4iZ3wBxluu2fbbE7j4kqlE8jXyAyPXH7HqU= +go.opentelemetry.io/otel v1.44.0/go.mod h1:BMgjTHL9WPRlRjL2oZCBTL4whCGtXch2H4BhOPIAyYc= +go.opentelemetry.io/otel/metric v1.44.0 h1:1w0gILTcHdr3YI+ixLyjemwrVnsMURbTZFrSYCdDdmc= +go.opentelemetry.io/otel/metric v1.44.0/go.mod h1:8O7hanEPBNgEMmybD3s2VBKcgWOCsA6tzHBPODAiquo= +go.opentelemetry.io/otel/sdk v1.44.0 h1:nHYwb9lK+fJPU/dnT6s7W7Z8itMWyqrnVfbheVYrZ58= +go.opentelemetry.io/otel/sdk v1.44.0/go.mod h1:Osuydd3Se74nqjAKxid74N5eC+jfEqfTegHRnq58oK0= +go.opentelemetry.io/otel/sdk/metric v1.44.0 h1:3LlKgI+VjbVsjNRFZJZAJ30WjXC5VkNRks6si09iEfI= +go.opentelemetry.io/otel/sdk/metric v1.44.0/go.mod h1:5B5pMARnXxKhltooO4xUuCBorl65a4EpnTalObqOigA= +go.opentelemetry.io/otel/trace v1.44.0 h1:jxF5CsGYCe74MCRx2X4g7WsY/VBKRqqpNvXlX/6gtIk= +go.opentelemetry.io/otel/trace v1.44.0/go.mod h1:oLl1jrMQAVo6v3GAggN+1VH9VIz9iUSvW53sW1Q8PIE= +golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w= +golang.org/x/crypto v0.0.0-20210921155107-089bfa567519/go.mod h1:GvvjBRRGRdwPK5ydBHafDWAxML/pGHZbMvKqRZ5+Abc= +golang.org/x/crypto v0.6.0/go.mod h1:OFC/31mSvZgRz0V1QTNCzfAI1aIRzbiufJtkMIlEp58= golang.org/x/crypto v0.57.0 h1:3ZVCjf8Ggz7zneR/EHRVx68Ctf+2pmIMP2UFhh9cC6M= golang.org/x/crypto v0.57.0/go.mod h1:Fdz0i5U6CoizGwLda9DttjSk6qlZo25zYNtR+ycvuZA= +golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4/go.mod h1:jJ57K6gSWd91VN4djpZkiMVwK6gcyfeH4XE8wZrZaV4= +golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s= +golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg= +golang.org/x/net v0.0.0-20220722155237-a158d28d115b/go.mod h1:XRhObCWvk6IyKnWLug+ECip1KBveYUHfp+8e9klMJ9c= +golang.org/x/net v0.6.0/go.mod h1:2Tu9+aMcznHK/AK1HMvgo6xiTLG5rD5rZLDS+rp2Bjs= +golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM= +golang.org/x/sync v0.0.0-20220722155255-886fb9371eb4/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM= +golang.org/x/sync v0.1.0/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM= golang.org/x/sync v0.23.0 h1:KameEIfc1IkluZyXWLn39Wd4tURc6GbCiISGiZm2bQk= golang.org/x/sync v0.23.0/go.mod h1:sUUOizhqBxiL6pEWpqNLUiaJn1ShEbZ6BBqskPbjZm0= +golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY= +golang.org/x/sys v0.0.0-20190916202348-b4ddaad3f8a3/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= +golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= +golang.org/x/sys v0.0.0-20201204225414-ed752295db88/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= +golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= +golang.org/x/sys v0.0.0-20210616094352-59db8d763f22/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= +golang.org/x/sys v0.0.0-20220520151302-bc2c85ada10a/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= +golang.org/x/sys v0.0.0-20220722155257-8c9f86f7a55f/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= +golang.org/x/sys v0.1.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= +golang.org/x/sys v0.5.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= golang.org/x/sys v0.48.0 h1:bbX/i/6MgT9BVLM9RT1thmxL04yeTAhbEz4SyadbXoo= golang.org/x/sys v0.48.0/go.mod h1:hNLxWAXmnKAxqDtdwIYC4bM9oQPEecfsnNMuSxOs3og= +golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo= +golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8= +golang.org/x/term v0.5.0/go.mod h1:jMB1sMXY+tzblOD4FWmEbocvup2/aLOaQEp7JmGp78k= +golang.org/x/term v0.46.0 h1:3+OXuTbaKDgwk8jTi3aSLHRlmWqHEUDUtxnbFigO4YE= +golang.org/x/term v0.46.0/go.mod h1:+K02xbkittuwc0Am4abfA3Fc+XRGXkvBXNO88NCXPoc= +golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ= +golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ= +golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ= +golang.org/x/text v0.7.0/go.mod h1:mrYo+phRRbMaCq/xk9113O4dZlRixOauAjOtrjsXDZ8= golang.org/x/text v0.42.0 h1:JbOZXgfeCPU9gacVtYliJqOhD+zhrEqK4LfdpmlUZqI= golang.org/x/text v0.42.0/go.mod h1:ojzP1Z+2QtioaF8DTtO8K5q7JWVVYwZKenzujK0Zd0E= +golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ= +golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo= +golang.org/x/tools v0.1.12/go.mod h1:hNGJHUnrk76NpqgfD5Aqm5Crs+Hm0VOH/i9J2+nxYbc= +golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0= gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk= gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q= gopkg.in/errgo.v2 v2.1.0/go.mod h1:hNsd1EY+bozCKY1Ytp96fpM3vjJbqLJn88ws8XvfDNI= +gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA= gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= gorm.io/datatypes v1.2.7 h1:ww9GAhF1aGXZY3EB3cJPJ7//JiuQo7DlQA7NNlVaTdk= @@ -91,6 +249,11 @@ gorm.io/driver/sqlite v1.6.0 h1:WHRRrIiulaPiPFmDcod6prc4l2VGVWHz80KspNsxSfQ= gorm.io/driver/sqlite v1.6.0/go.mod h1:AO9V1qIQddBESngQUKWL9yoH93HIeA1X6V633rBwyT8= gorm.io/driver/sqlserver v1.6.0 h1:VZOBQVsVhkHU/NzNhRJKoANt5pZGQAS1Bwc6m6dgfnc= gorm.io/driver/sqlserver v1.6.0/go.mod h1:WQzt4IJo/WHKnckU9jXBLMJIVNMVeTu25dnOzehntWw= +gorm.io/gorm v1.24.7-0.20230306060331-85eaf9eeda11/go.mod h1:L4uxeKpfBml98NYqVqwAdmV1a2nBtAec/cf3fpucW/k= gorm.io/gorm v1.25.7/go.mod h1:hbnx/Oo0ChWMn1BIhpy1oYozzpM15i4YPuHDmfYtwg8= gorm.io/gorm v1.31.1 h1:7CA8FTFz/gRfgqgpeKIBcervUn3xSyPUmr6B2WXJ7kg= gorm.io/gorm v1.31.1/go.mod h1:XyQVbO2k6YkOis7C2437jSit3SsDK72s7n7rsSHd+Gs= +gotest.tools/v3 v3.5.2 h1:7koQfIKdy+I8UTetycgUqXWSDwpgv193Ka+qRsmBY8Q= +gotest.tools/v3 v3.5.2/go.mod h1:LtdLGcnqToBH83WByAAi/wiwSFCArdFIUV/xxN4pcjA= +pgregory.net/rapid v1.2.0 h1:keKAYRcjm+e1F0oAuU5F5+YPAWcyxNNRK2wud503Gnk= +pgregory.net/rapid v1.2.0/go.mod h1:PY5XlDGj0+V1FCq0o192FdRhpKHGTRIWBgqjDBTrq04= diff --git a/gorm.go b/gorm.go index 2372b97..a5eed9d 100644 --- a/gorm.go +++ b/gorm.go @@ -48,9 +48,9 @@ type cacheEntry struct { } // GORMCacheConfig holds configuration for GORMCache. Keys are case-sensitive: -// give the key column a byte-exact collation (MySQL: *_bin). Otherwise keys -// that the column considers equal share one row, served only to the key that -// wrote it last. +// the key column should compare byte-exactly (Migrate creates MySQL tables with +// utf8mb4_bin). Otherwise keys that the column considers equal share one row, +// served only to the key that wrote it last. type GORMCacheConfig struct { // DB is the GORM database connection DB *gorm.DB @@ -84,8 +84,13 @@ func (g *GORMCache[T]) prefixedKey(key string) string { // Migrate creates or updates the cache table schema func (g *GORMCache[T]) Migrate(ctx context.Context) error { - tx := cmp.Or(GetGORMTx(ctx), g.db) - if err := tx.WithContext(ctx).Table(g.tableName).AutoMigrate(&cacheEntry{}); err != nil { + tx := cmp.Or(GetGORMTx(ctx), g.db).WithContext(ctx).Table(g.tableName) + if tx.Name() == "mysql" { + // keys are case-sensitive, MySQL's default collations are not; applies + // only when the table is created, an existing one is left as it is + tx = tx.Set("gorm:table_options", "CHARSET=utf8mb4 COLLATE=utf8mb4_bin") + } + if err := tx.AutoMigrate(&cacheEntry{}); err != nil { return errors.Wrapf(err, "failed to migrate cache table for table: %s", g.tableName) } return nil diff --git a/gorm_container_test.go b/gorm_container_test.go new file mode 100644 index 0000000..0739e60 --- /dev/null +++ b/gorm_container_test.go @@ -0,0 +1,120 @@ +package cachex + +import ( + "context" + "fmt" + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + "github.com/testcontainers/testcontainers-go" + tcmysql "github.com/testcontainers/testcontainers-go/modules/mysql" + tcpostgres "github.com/testcontainers/testcontainers-go/modules/postgres" + "gorm.io/driver/mysql" + "gorm.io/driver/postgres" + "gorm.io/gorm" +) + +// TestGORMCacheOnRealDatabases runs GORMCache against MySQL and PostgreSQL in +// containers (skipped without Docker): SQLite accepts things they do not, such +// as the bare reserved word "key", and compares keys byte-exactly by default. +func TestGORMCacheOnRealDatabases(t *testing.T) { + testcontainers.SkipIfProviderIsNotHealthy(t) + ctx := context.Background() + + dbs := map[string]func(t *testing.T) gorm.Dialector{ + "mysql": func(t *testing.T) gorm.Dialector { + c, err := tcmysql.Run(ctx, "mysql:8.4") + testcontainers.CleanupContainer(t, c) + require.NoError(t, err) + dsn, err := c.ConnectionString(ctx, "parseTime=true") + require.NoError(t, err) + return mysql.Open(dsn) + }, + "postgres": func(t *testing.T) gorm.Dialector { + c, err := tcpostgres.Run(ctx, "postgres:16", tcpostgres.BasicWaitStrategies()) + testcontainers.CleanupContainer(t, c) + require.NoError(t, err) + dsn, err := c.ConnectionString(ctx, "sslmode=disable") + require.NoError(t, err) + return postgres.Open(dsn) + }, + } + for name, open := range dbs { + t.Run(name, func(t *testing.T) { + t.Parallel() + db, err := gorm.Open(open(t), &gorm.Config{}) + require.NoError(t, err) + newCache := func(t *testing.T) *GORMCache[string] { + c := NewGORMCache[string](&GORMCacheConfig{DB: db, TableName: "cache_" + t.Name()[len(name)+1+len("TestGORMCacheOnRealDatabases/"):], KeyPrefix: "p:"}) + require.NoError(t, c.Migrate(ctx)) + return c + } + + t.Run("contract", func(t *testing.T) { testBatchCache(t, newCache(t)) }) + + t.Run("batch larger than one statement", func(t *testing.T) { + c := newCache(t) + values, keys := map[string]string{}, []string{} + for i := range 2500 { + k := fmt.Sprintf("k%04d", i) + values[k], keys = "v"+k, append(keys, k) + } + require.NoError(t, c.SetMany(ctx, values)) + got, err := c.GetMany(ctx, keys) + require.NoError(t, err) + assert.Equal(t, values, got) + require.NoError(t, c.DelMany(ctx, keys)) + got, err = c.GetMany(ctx, keys) + require.NoError(t, err) + assert.Empty(t, got) + }) + + t.Run("keys are case-sensitive", func(t *testing.T) { + c := newCache(t) + require.NoError(t, c.Set(ctx, "ABC", "upper")) + require.NoError(t, c.Set(ctx, "abc", "lower")) + got, err := c.GetMany(ctx, []string{"ABC", "abc", "Abc"}) + require.NoError(t, err) + assert.Equal(t, map[string]string{"ABC": "upper", "abc": "lower"}, got, "a table Migrate created keeps them apart") + v, err := c.Get(ctx, "ABC") + require.NoError(t, err) + assert.Equal(t, "upper", v) + }) + + if name == "mysql" { + t.Run("an existing case-insensitive table never serves another key's value", func(t *testing.T) { + table := "cache_legacy_ci" + require.NoError(t, db.Exec("CREATE TABLE "+table+" (`key` varchar(255) NOT NULL PRIMARY KEY, `value` json NOT NULL, `updated_at` datetime(3) NOT NULL) COLLATE=utf8mb4_0900_ai_ci").Error) + c := NewGORMCache[string](&GORMCacheConfig{DB: db, TableName: table}) + require.NoError(t, c.Migrate(ctx), "an existing table is left as it is") + + require.NoError(t, c.Set(ctx, "ABC", "upper")) + _, err := c.Get(ctx, "abc") + assert.True(t, IsErrKeyNotFound(err), "abc does not get ABC's row: %v", err) + require.NoError(t, c.Set(ctx, "abc", "lower")) // takes the shared row over + got, err := c.GetMany(ctx, []string{"ABC", "abc"}) + require.NoError(t, err) + assert.Equal(t, map[string]string{"abc": "lower"}, got) + }) + } + + t.Run("Client over it", func(t *testing.T) { + c := newCache(t) + up := &batchUpstream{data: map[string]string{"a": "1", "b": "2"}} + cli := NewClient[string](c, up) + got, err := cli.GetMany(ctx, []string{"a", "b", "x"}) + require.NoError(t, err) + assert.Equal(t, map[string]string{"a": "1", "b": "2"}, got) + l1 := NewClient[string](NewSyncMap[string](), c) + require.NoError(t, l1.Set(ctx, "k", "v1")) + v, err := c.Get(ctx, "k") + require.NoError(t, err) + assert.Equal(t, "v1", v, "Set writes down to the database layer") + require.NoError(t, l1.Del(ctx, "k")) + _, err = l1.Get(ctx, "k") + assert.True(t, IsErrKeyNotFound(err)) + }) + }) + } +} diff --git a/write_order_test.go b/write_order_test.go index adca0d1..d5875fd 100644 --- a/write_order_test.go +++ b/write_order_test.go @@ -554,7 +554,10 @@ func TestWriteWaitingForTheStripeRespectsCtx(t *testing.T) { assert.Equal(t, "first", v, "the cancelled Set wrote nothing") s := cli.stripe("k") - require.Eventually(t, func() bool { // the given-up Set hands the lock back once it gets it + // the given-up Set's lock is taken in the background once the first Set + // releases it; it bumps the generation (the first Set did too) and unlocks + require.Eventually(t, func() bool { return s.gen.Load() == 2 }, time.Second, time.Millisecond) + require.Eventually(t, func() bool { if !s.mu.TryLock() { return false } From c34d8a87041bff1c4e50de2c3515bc3b428f0af6 Mon Sep 17 00:00:00 2001 From: molon <3739161+molon@users.noreply.github.com> Date: Thu, 8 Oct 2026 20:14:38 +0800 Subject: [PATCH 23/40] fix: don't bound a batch over a lower Client as one fetch, and let GORMCache.SetMany keep the values that encode - Over a lower Client, a GetMany's batch call is no longer cut off by one fetch timeout: the lower Client bounds each of its own fetches, and keys still queued there failed with the upper deadline instead. - GORMCache.SetMany writes the values that encode and reports the others, as RedisCache does; one bad value no longer drops the whole write-back. - Docs: the keys of one batch call are answered together; a large GetMany write-back holds its stripes while the backend writes; and utf8mb4_bin ignores trailing spaces. --- README.md | 6 +++--- README_ZH.md | 6 +++--- batch.go | 9 +++++++-- batch_test.go | 15 +++++++++++++++ gorm.go | 14 ++++++++++---- gorm_test.go | 13 +++++++++++++ 6 files changed, 51 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 1b82565..9bc3d66 100644 --- a/README.md +++ b/README.md @@ -215,7 +215,7 @@ if err := cache.Migrate(ctx); err != nil { } ``` -Cache keys are case-sensitive, so the `key` column should compare byte for byte. PostgreSQL and SQLite do by default, and on MySQL `Migrate` creates the table with `utf8mb4_bin`. A table created before that (or by hand) keeps its collation, usually case- and accent-insensitive (`*_ci`); convert it with `ALTER TABLE cache_products CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_bin`. Even without it nothing wrong is ever served: `GORMCache` only returns the row stored under exactly the requested key, so keys differing only in case just take the row over from each other (extra misses). +Cache keys are case-sensitive, so the `key` column should compare them exactly. PostgreSQL and SQLite do by default, and on MySQL `Migrate` creates the table with `utf8mb4_bin` (case-sensitive; like any PAD SPACE collation it ignores trailing spaces, so `"a"` and `"a "` share a row — use `utf8mb4_0900_bin` on MySQL 8.0.17+ if such keys matter). A table created before that (or by hand) keeps its collation, usually case- and accent-insensitive (`*_ci`); convert it with `ALTER TABLE cache_products CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_bin`. Even without it nothing wrong is ever served: `GORMCache` only returns the row stored under exactly the requested key, so keys differing only in case just take the row over from each other (extra misses). ### Custom Cache @@ -335,7 +335,7 @@ The key insight: **cache writes propagate through `Cache[T]` chains but stop whe - If the upstream write fails, its state is unknown (it may have been applied with only the reply lost), so this layer **drops** its entry for the key (and any cached Not-Found) and returns the error; the next read goes down. A failed `Del` likewise drops this layer's entry but caches no Not-Found. - If the upstream write succeeds but this layer's own write fails, `Set`/`Del` still return the error, yet the change below is **kept** (nothing is rolled back): an error does not mean nothing was written. This layer drops its entry and cached Not-Found for the key, so the next read goes down and sees the change. - Concurrent `Set`/`Del` of one key through the same `Client` are applied one at a time, in the same order on every layer. A `Set`/`Del` that has to wait (for another write to its stripe, or a read writing back to this layer) gives up when its ctx is done and returns the ctx error: it writes nothing upstream, and, like any failed write, drops this layer's entry for the key as soon as the stripe is free. One that does not have to wait is applied even if its ctx is already done. So an invalidating `Del` after the request was canceled always clears this layer, at worst a moment after it returns. Once a write has started, the cleanup after a failure (dropping this layer's entry) runs even if ctx is done, for at most `WithFetchTimeout`. -- A read that fetched a value **before** a concurrent `Set`/`Del` still returns what it fetched, but never writes it back over the newer value: each `Client` hashes keys into 1,024 stripes, each with a write lock and a write generation, and `Get`, `GetMany` and the serve-stale refresh check the key's stripe generation while holding its lock for reading, so a backfill either lands before a `Set`/`Del` (which then overwrites it) or is skipped. A backfill is also skipped while a write to the stripe is in progress, so reads never wait on writes. Keys that share a stripe share this state: their writes run one at a time, and a write to one key can skip a backfill of another. The cost is at most an extra cache miss, or a write waiting on a write to an unrelated key. +- A read that fetched a value **before** a concurrent `Set`/`Del` still returns what it fetched, but never writes it back over the newer value: each `Client` hashes keys into 1,024 stripes, each with a write lock and a write generation, and `Get`, `GetMany` and the serve-stale refresh check the key's stripe generation while holding its lock for reading, so a backfill either lands before a `Set`/`Del` (which then overwrites it) or is skipped. A backfill is also skipped while a write to the stripe is in progress, so reads never wait on writes. Keys that share a stripe share this state: their writes run one at a time, and a write to one key can skip a backfill of another. The cost is at most an extra cache miss, or a write waiting on a write to an unrelated key, or on a read writing back to this layer: a large `GetMany` holds the stripes of all its keys (about 60% of them for 1,000 keys) while the backend writes them back, so a `Set`/`Del` of any key in those stripes waits that long, and gives up if its ctx ends first. - These guarantees hold within one process; separate processes sharing a lower layer (e.g. Redis) can still briefly disagree in their memory layers. ### Not-Found Caching @@ -417,7 +417,7 @@ How `GetMany` works: 2. **Not-Found cache**: misses are checked against it, exactly like `Get`. 3. **Singleflight**: every key that needs the upstream is claimed in the **same** singleflight `Get` uses. Keys already being fetched by a `Get` or another `GetMany` are waited for, not fetched again; so a `Get` and a `GetMany` (or two overlapping `GetMany`s) fetch a shared key only once. `WithFetchConcurrency` applies per key as usual. 4. **DoubleCheck**: the claimed keys are re-checked against the backend and Not-Found cache, by the same rules as `Get`. -5. **Upstream**: if the upstream implements `BatchUpstream[T]`, the remaining keys are fetched with **one** `GetMany` call (one `WithFetchTimeout` for the whole call). Otherwise each key is fetched exactly as `Get` would (its own double-check, fetch timeout and write-back, and handed to its waiters as soon as it arrives), at most `WithGetManyConcurrency` (default 16) at a time; a key is claimed only when its turn comes, so a concurrent `Get` of a key still queued here does not wait for the queue, and a canceled `GetMany` starts no more keys. +5. **Upstream**: if the upstream implements `BatchUpstream[T]`, the remaining keys are fetched with **one** `GetMany` call (one `WithFetchTimeout` for the whole call, except over a lower `Client`, which bounds each of its own fetches). The keys of one call are answered together: a concurrent `Get` of one of them joins the call and waits for all of it. Otherwise each key is fetched exactly as `Get` would (its own double-check, fetch timeout and write-back, and handed to its waiters as soon as it arrives), at most `WithGetManyConcurrency` (default 16) at a time; a key is claimed only when its turn comes, so a concurrent `Get` of a key still queued here does not wait for the queue, and a canceled `GetMany` starts no more keys. 6. **Write back**: found values go to the backend, missing keys to the Not-Found cache. With a `BatchUpstream` this is one `SetMany`/`DelMany` per batch (when the backend supports it); without one, each key is written back on its own, like `Get`. Either way this only touches this layer, never the upstream. `Client` implements `BatchUpstream[T]` itself, so in a layered setup a batch travels down as one call per layer: `l1Client.GetMany` → L1 batch read → `l2Client.GetMany` → L2 batch read → one database query. diff --git a/README_ZH.md b/README_ZH.md index 69e598f..3c0db3f 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -215,7 +215,7 @@ if err := cache.Migrate(ctx); err != nil { } ``` -缓存 key 区分大小写,所以 `key` 列应当逐字节比较。PostgreSQL 和 SQLite 默认如此;MySQL 上 `Migrate` 建表时会用 `utf8mb4_bin`。在这之前建的表(或手工建的表)保留原来的排序规则,通常不区分大小写和重音(`*_ci`),可以用 `ALTER TABLE cache_products CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_bin` 转换。即使不转换也不会读到错的值:`GORMCache` 只返回 key 完全相等的那一行,只差大小写的几个 key 只会互相挤占这一行(多几次未命中)。 +缓存 key 区分大小写,所以 `key` 列应当精确比较。PostgreSQL 和 SQLite 默认如此;MySQL 上 `Migrate` 建表时会用 `utf8mb4_bin`(区分大小写;和所有 PAD SPACE 排序规则一样会忽略末尾空格,`"a"` 和 `"a "` 共用一行。如果这类 key 有影响,MySQL 8.0.17 以上可改用 `utf8mb4_0900_bin`)。在这之前建的表(或手工建的表)保留原来的排序规则,通常不区分大小写和重音(`*_ci`),可以用 `ALTER TABLE cache_products CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_bin` 转换。即使不转换也不会读到错的值:`GORMCache` 只返回 key 完全相等的那一行,只差大小写的几个 key 只会互相挤占这一行(多几次未命中)。 ### 自定义缓存 @@ -335,7 +335,7 @@ L1 缓存 → L2 缓存 → L3 缓存 → 数据库 - upstream 写失败时,它的状态不明(可能已经写进去了,只是回复丢了),所以本层会**删掉**这个 key 的条目(连同缓存的 Not-Found),并返回错误;下次读会回源到下层。`Del` 失败时同样删掉本层条目,但不记 Not-Found。 - upstream 写成功、本层自己的写入失败时,`Set`/`Del` 仍返回错误,但下层的改动**保留**(不回滚):返回错误不代表什么都没写进去。本层会删掉这个 key 的条目和缓存的 Not-Found,下次读会回源到下层,读到改动后的结果。 - 通过同一个 `Client` 并发 `Set`/`Del` 同一个 key 时,逐个执行,各层的写入顺序一致。需要等待的 `Set`/`Del`(等同一分片的其他写入,或者等正在回填本层的读),在 ctx 结束时放弃并返回 ctx 错误:它不写 upstream,并且和其他失败的写入一样,等分片空出来就删掉本层这个 key 的条目。不需要等待的照常执行,即使 ctx 已经结束。所以请求取消后再调 `Del` 做失效,本层总会被清掉,最多是在它返回后稍晚一点。写入一旦开始,失败后的清理(删掉本层条目)即使 ctx 已结束也会执行,最长 `WithFetchTimeout`。 -- 回源读到值**之后**、写回本层**之前**如果发生了 `Set`/`Del`,这次读仍然返回它读到的值,但绝不会用它覆盖更新的值:每个 `Client` 把 key 按哈希分到 1,024 个分片,每个分片有一把写锁和一个写入代数,`Get`、`GetMany` 和 serve-stale 的后台刷新在持有 key 所在分片的读锁时核对分片的写入代数,所以回填要么在 `Set`/`Del` 之前落下(随后被覆盖),要么被跳过。分片正在写入时回填也直接跳过,所以读永远不等写。落在同一分片的 key 共用这份状态:它们的写入逐个执行,写一个 key 可能让另一个 key 的回填被跳过。代价最多是多一次缓存未命中,或者一次写入要等另一个不相干 key 的写入。 +- 回源读到值**之后**、写回本层**之前**如果发生了 `Set`/`Del`,这次读仍然返回它读到的值,但绝不会用它覆盖更新的值:每个 `Client` 把 key 按哈希分到 1,024 个分片,每个分片有一把写锁和一个写入代数,`Get`、`GetMany` 和 serve-stale 的后台刷新在持有 key 所在分片的读锁时核对分片的写入代数,所以回填要么在 `Set`/`Del` 之前落下(随后被覆盖),要么被跳过。分片正在写入时回填也直接跳过,所以读永远不等写。落在同一分片的 key 共用这份状态:它们的写入逐个执行,写一个 key 可能让另一个 key 的回填被跳过。代价最多是多一次缓存未命中,或者一次写入要等另一个不相干 key 的写入、或等正在回填本层的读:一次大的 `GetMany` 在后端写回期间会占着它所有 key 的分片(1,000 个 key 约占六成),这些分片上任何 key 的 `Set`/`Del` 都要等这么久,ctx 先结束就放弃。 - 这些保证在单个进程内成立;多个进程共用同一个下层(例如 Redis)时,各自的内存层仍可能短暂不一致。 ### Not-Found 缓存 @@ -416,7 +416,7 @@ client := cachex.NewClient(cache, productSource{db: db} /* , options as in Quick 2. **Not-Found 缓存**:未命中的先查它,和 `Get` 一样。 3. **Singleflight**:每个要回源的 key 都在和 `Get` **同一个** singleflight 里认领。已经有 `Get` 或别的 `GetMany` 在取的 key,等那次的结果,不再取一遍;所以 `Get` 和 `GetMany`(或两个有交集的 `GetMany`)同时要同一个 key,只回源一次。`WithFetchConcurrency` 照旧按 key 生效。 4. **DoubleCheck**:认领到的 key 按和 `Get` 相同的规则再查一次后端和 Not-Found 缓存。 -5. **上游**:上游实现了 `BatchUpstream[T]`,剩下的 key 就调**一次** `GetMany`(整次调用共用一个 `WithFetchTimeout`)。否则每个 key 都和 `Get` 完全一样地拉取(各自 double check、各自超时、各自回填,拉到就交给等它的调用方),同时最多 `WithGetManyConcurrency` 个(默认 16);每个 key 轮到时才认领,所以并发的 `Get` 碰上还在这里排队的 key 不用等整个队列,`GetMany` 被取消后也不再开始新的 key。 +5. **上游**:上游实现了 `BatchUpstream[T]`,剩下的 key 就调**一次** `GetMany`(整次调用共用一个 `WithFetchTimeout`;下层是 `Client` 时不加这个总超时,由下层给自己的每次拉取各自限时)。同一次调用里的 key 一起返回:并发 `Get` 其中某个 key 会加入这次调用,等它整个结束。否则每个 key 都和 `Get` 完全一样地拉取(各自 double check、各自超时、各自回填,拉到就交给等它的调用方),同时最多 `WithGetManyConcurrency` 个(默认 16);每个 key 轮到时才认领,所以并发的 `Get` 碰上还在这里排队的 key 不用等整个队列,`GetMany` 被取消后也不再开始新的 key。 6. **回填**:取到的值写回后端,不存在的 key 写进 Not-Found 缓存。上游实现了 `BatchUpstream` 时,一批只调一次 `SetMany`/`DelMany`(后端支持的话);否则每个 key 各自回填,和 `Get` 一样。两种情况都只写本层,不写上游。 `Client` 自己也实现了 `BatchUpstream[T]`,所以多层缓存时一批 key 每层只走一次调用:`l1Client.GetMany` → L1 批量读 → `l2Client.GetMany` → L2 批量读 → 一次数据库查询。 diff --git a/batch.go b/batch.go index ae9eb74..4b4a98c 100644 --- a/batch.go +++ b/batch.go @@ -380,8 +380,13 @@ func (c *Client[T]) fetchClaimedMany(ctx context.Context, keys, sfKeys []string, for j, i := range pending { pendingKeys[j] = keys[i] } - // like Get, the fetch timeout starts after the double-check - fetchCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), c.fetchTimeout) + // like Get, the fetch timeout starts after the double-check. A Client below + // bounds each of its own fetches, so its batch is not bounded as one fetch: + // keys still queued there would fail with this deadline, not their own. + fetchCtx, cancel := context.WithCancel(context.WithoutCancel(ctx)) + if _, layered := c.upstream.(*Client[T]); !layered { + fetchCtx, cancel = context.WithTimeout(fetchCtx, c.fetchTimeout) + } defer cancel() for j, r := range c.doFetchMany(fetchCtx, pendingKeys) { results[pending[j]] = r diff --git a/batch_test.go b/batch_test.go index 680a7af..c80e6c4 100644 --- a/batch_test.go +++ b/batch_test.go @@ -1150,6 +1150,21 @@ func TestClientGetManyBatchRefreshThatTimesOutIsLogged(t *testing.T) { 2*time.Second, 5*time.Millisecond, "a refresh that never finishes in time is not silent") } +func TestClientGetManyOverAClientIsNotBoundedAsOneFetch(t *testing.T) { + // L2 fetches its source key by key, each well within its own timeout; L1 + // hands L2 the whole batch, which takes longer than one fetch timeout + src := UpstreamFunc[string](func(_ context.Context, key string) (string, error) { + time.Sleep(30 * time.Millisecond) + return "v-" + key, nil + }) + l2 := NewClient[string](NewSyncMap[string](), src, WithGetManyConcurrency[string](1)) + l1 := NewClient[string](NewSyncMap[string](), l2, WithFetchTimeout[string](100*time.Millisecond)) + keys := []string{"k0", "k1", "k2", "k3", "k4", "k5", "k6", "k7"} + got, err := l1.GetMany(context.Background(), keys) + require.NoError(t, err, "no key fails just because the batch as a whole outlasted one fetch timeout") + assert.Len(t, got, len(keys)) +} + func TestRedisCacheGetManyPerKeyErrors(t *testing.T) { ctx := context.Background() cache, mr := newRedisCache[string](t) diff --git a/gorm.go b/gorm.go index a5eed9d..bc27db3 100644 --- a/gorm.go +++ b/gorm.go @@ -4,6 +4,7 @@ import ( "cmp" "context" "encoding/json" + stderrors "errors" "slices" "time" @@ -48,8 +49,8 @@ type cacheEntry struct { } // GORMCacheConfig holds configuration for GORMCache. Keys are case-sensitive: -// the key column should compare byte-exactly (Migrate creates MySQL tables with -// utf8mb4_bin). Otherwise keys that the column considers equal share one row, +// the key column should compare them exactly (Migrate creates MySQL tables with +// utf8mb4_bin, which still ignores trailing spaces). Otherwise keys that the column considers equal share one row, // served only to the key that wrote it last. type GORMCacheConfig struct { // DB is the GORM database connection @@ -244,13 +245,18 @@ func (g *GORMCache[T]) SetMany(ctx context.Context, values map[string]T) error { } entries := make([]cacheEntry, 0, len(values)) + var encodeErrs []error // like RedisCache, a value that cannot be encoded does not stop the others for key, value := range values { data, err := json.Marshal(value) if err != nil { - return errors.Wrapf(err, "failed to marshal value for key: %s", key) + encodeErrs = append(encodeErrs, errors.Wrapf(err, "failed to marshal value for key: %s", key)) + continue } entries = append(entries, cacheEntry{Key: g.prefixedKey(key), Value: data}) } + if len(entries) == 0 { + return stderrors.Join(encodeErrs...) + } tx := cmp.Or(GetGORMTx(ctx), g.db) if err := tx.WithContext(ctx). @@ -259,7 +265,7 @@ func (g *GORMCache[T]) SetMany(ctx context.Context, values map[string]T) error { CreateInBatches(&entries, gormBatchSize).Error; err != nil { return errors.Wrap(err, "failed to set cache entries") } - return nil + return stderrors.Join(encodeErrs...) } // DelMany removes many keys with `WHERE key IN (...)` deletes of up to gormBatchSize keys each diff --git a/gorm_test.go b/gorm_test.go index 6d47937..6e30e4d 100644 --- a/gorm_test.go +++ b/gorm_test.go @@ -2,6 +2,7 @@ package cachex import ( "context" + "math" "regexp" "strings" "testing" @@ -296,3 +297,15 @@ func TestGORMCacheQuotesTheKeyColumn(t *testing.T) { assert.NotRegexp(t, bare, sql, "the key column must be quoted") } } + +func TestGORMCacheSetManyKeepsTheValuesThatEncode(t *testing.T) { + type num struct{ V float64 } + cache, _ := newGORMCache[num](t, "encode") + ctx := context.Background() + err := cache.SetMany(ctx, map[string]num{"ok": {1}, "bad": {math.NaN()}}) + require.Error(t, err, "the value that cannot be encoded is reported") + assert.Contains(t, err.Error(), "bad") + v, err := cache.Get(ctx, "ok") + require.NoError(t, err, "like RedisCache, the others are still written") + assert.Equal(t, num{1}, v) +} From 0e3a3524aaff3ca56f6c0f33bfd19fd1f5f994cb Mon Sep 17 00:00:00 2001 From: molon <3739161+molon@users.noreply.github.com> Date: Thu, 8 Oct 2026 21:42:28 +0800 Subject: [PATCH 24/40] feat: create MySQL cache tables with utf8mb4_0900_bin utf8mb4_bin pads, so "a" and "a " were one row. utf8mb4_0900_bin compares trailing spaces too; it needs MySQL 8.0.17 or later, which is now what GORMCache supports on MySQL. --- README.md | 2 +- README_ZH.md | 2 +- gorm.go | 6 +++--- gorm_container_test.go | 9 +++++++++ 4 files changed, 14 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 9bc3d66..d64c5c0 100644 --- a/README.md +++ b/README.md @@ -215,7 +215,7 @@ if err := cache.Migrate(ctx); err != nil { } ``` -Cache keys are case-sensitive, so the `key` column should compare them exactly. PostgreSQL and SQLite do by default, and on MySQL `Migrate` creates the table with `utf8mb4_bin` (case-sensitive; like any PAD SPACE collation it ignores trailing spaces, so `"a"` and `"a "` share a row — use `utf8mb4_0900_bin` on MySQL 8.0.17+ if such keys matter). A table created before that (or by hand) keeps its collation, usually case- and accent-insensitive (`*_ci`); convert it with `ALTER TABLE cache_products CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_bin`. Even without it nothing wrong is ever served: `GORMCache` only returns the row stored under exactly the requested key, so keys differing only in case just take the row over from each other (extra misses). +Cache keys are case-sensitive, so the `key` column should compare them exactly. PostgreSQL and SQLite do by default, and on MySQL (8.0.17 or later) `Migrate` creates the table with `utf8mb4_0900_bin`, which compares case and trailing spaces exactly. A table created before that (or by hand) keeps its collation, usually case- and accent-insensitive (`*_ci`); convert it with `ALTER TABLE cache_products CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_bin`. Even without it nothing wrong is ever served: `GORMCache` only returns the row stored under exactly the requested key, so keys differing only in case just take the row over from each other (extra misses). ### Custom Cache diff --git a/README_ZH.md b/README_ZH.md index 3c0db3f..caa927b 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -215,7 +215,7 @@ if err := cache.Migrate(ctx); err != nil { } ``` -缓存 key 区分大小写,所以 `key` 列应当精确比较。PostgreSQL 和 SQLite 默认如此;MySQL 上 `Migrate` 建表时会用 `utf8mb4_bin`(区分大小写;和所有 PAD SPACE 排序规则一样会忽略末尾空格,`"a"` 和 `"a "` 共用一行。如果这类 key 有影响,MySQL 8.0.17 以上可改用 `utf8mb4_0900_bin`)。在这之前建的表(或手工建的表)保留原来的排序规则,通常不区分大小写和重音(`*_ci`),可以用 `ALTER TABLE cache_products CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_bin` 转换。即使不转换也不会读到错的值:`GORMCache` 只返回 key 完全相等的那一行,只差大小写的几个 key 只会互相挤占这一行(多几次未命中)。 +缓存 key 区分大小写,所以 `key` 列应当精确比较。PostgreSQL 和 SQLite 默认如此;MySQL(需 8.0.17 及以上)上 `Migrate` 建表时会用 `utf8mb4_0900_bin`,大小写和末尾空格都精确比较。在这之前建的表(或手工建的表)保留原来的排序规则,通常不区分大小写和重音(`*_ci`),可以用 `ALTER TABLE cache_products CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_bin` 转换。即使不转换也不会读到错的值:`GORMCache` 只返回 key 完全相等的那一行,只差大小写的几个 key 只会互相挤占这一行(多几次未命中)。 ### 自定义缓存 diff --git a/gorm.go b/gorm.go index bc27db3..a56084a 100644 --- a/gorm.go +++ b/gorm.go @@ -50,7 +50,7 @@ type cacheEntry struct { // GORMCacheConfig holds configuration for GORMCache. Keys are case-sensitive: // the key column should compare them exactly (Migrate creates MySQL tables with -// utf8mb4_bin, which still ignores trailing spaces). Otherwise keys that the column considers equal share one row, +// utf8mb4_0900_bin, so MySQL 8.0.17 or later is required). Otherwise keys that the column considers equal share one row, // served only to the key that wrote it last. type GORMCacheConfig struct { // DB is the GORM database connection @@ -87,9 +87,9 @@ func (g *GORMCache[T]) prefixedKey(key string) string { func (g *GORMCache[T]) Migrate(ctx context.Context) error { tx := cmp.Or(GetGORMTx(ctx), g.db).WithContext(ctx).Table(g.tableName) if tx.Name() == "mysql" { - // keys are case-sensitive, MySQL's default collations are not; applies + // keys compare exactly (case, trailing spaces), MySQL's defaults do not; applies // only when the table is created, an existing one is left as it is - tx = tx.Set("gorm:table_options", "CHARSET=utf8mb4 COLLATE=utf8mb4_bin") + tx = tx.Set("gorm:table_options", "CHARSET=utf8mb4 COLLATE=utf8mb4_0900_bin") // MySQL 8.0.17+ } if err := tx.AutoMigrate(&cacheEntry{}); err != nil { return errors.Wrapf(err, "failed to migrate cache table for table: %s", g.tableName) diff --git a/gorm_container_test.go b/gorm_container_test.go index 0739e60..65dfcf2 100644 --- a/gorm_container_test.go +++ b/gorm_container_test.go @@ -82,6 +82,15 @@ func TestGORMCacheOnRealDatabases(t *testing.T) { assert.Equal(t, "upper", v) }) + t.Run("keys differing only in trailing spaces are distinct", func(t *testing.T) { + c := newCache(t) + require.NoError(t, c.Set(ctx, "a", "plain")) + require.NoError(t, c.Set(ctx, "a ", "space")) + got, err := c.GetMany(ctx, []string{"a", "a "}) + require.NoError(t, err) + assert.Equal(t, map[string]string{"a": "plain", "a ": "space"}, got) + }) + if name == "mysql" { t.Run("an existing case-insensitive table never serves another key's value", func(t *testing.T) { table := "cache_legacy_ci" From 9364893338b58ab6e87c2b3bc8f2d72691df6f1b Mon Sep 17 00:00:00 2001 From: molon <3739161+molon@users.noreply.github.com> Date: Thu, 8 Oct 2026 21:56:08 +0800 Subject: [PATCH 25/40] fix: sort GORMCache.SetMany rows so overlapping batches don't deadlock, and bound a batch over a lower Client by its own budget - SetMany inserted rows in Go map order, so two concurrent SetMany calls with overlapping keys locked rows in opposite orders and deadlocked on MySQL and PostgreSQL (the aborted write-back left its keys uncached). Rows are now sorted by key; a concurrent test runs on both databases. - A GetMany over a lower Client was not bounded at all, so a lower backend that hung kept the keys claimed in this layer. It is now bounded by what the lower Client's own fetches may take (a queue of per-key fetch timeouts, a batch, or a deeper Client's budget), plus a fetch timeout for this layer's reads and write-back. --- README.md | 2 +- README_ZH.md | 2 +- batch.go | 23 ++++++++++++++++++++--- batch_test.go | 29 +++++++++++++++++++++++++++++ gorm.go | 3 +++ gorm_container_test.go | 18 ++++++++++++++++++ 6 files changed, 72 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index d64c5c0..5cbab32 100644 --- a/README.md +++ b/README.md @@ -417,7 +417,7 @@ How `GetMany` works: 2. **Not-Found cache**: misses are checked against it, exactly like `Get`. 3. **Singleflight**: every key that needs the upstream is claimed in the **same** singleflight `Get` uses. Keys already being fetched by a `Get` or another `GetMany` are waited for, not fetched again; so a `Get` and a `GetMany` (or two overlapping `GetMany`s) fetch a shared key only once. `WithFetchConcurrency` applies per key as usual. 4. **DoubleCheck**: the claimed keys are re-checked against the backend and Not-Found cache, by the same rules as `Get`. -5. **Upstream**: if the upstream implements `BatchUpstream[T]`, the remaining keys are fetched with **one** `GetMany` call (one `WithFetchTimeout` for the whole call, except over a lower `Client`, which bounds each of its own fetches). The keys of one call are answered together: a concurrent `Get` of one of them joins the call and waits for all of it. Otherwise each key is fetched exactly as `Get` would (its own double-check, fetch timeout and write-back, and handed to its waiters as soon as it arrives), at most `WithGetManyConcurrency` (default 16) at a time; a key is claimed only when its turn comes, so a concurrent `Get` of a key still queued here does not wait for the queue, and a canceled `GetMany` starts no more keys. +5. **Upstream**: if the upstream implements `BatchUpstream[T]`, the remaining keys are fetched with **one** `GetMany` call (one `WithFetchTimeout` for the whole call; over a lower `Client`, as long as that `Client`'s own fetches may take, e.g. a queue of per-key fetch timeouts). The keys of one call are answered together: a concurrent `Get` of one of them joins the call and waits for all of it. Otherwise each key is fetched exactly as `Get` would (its own double-check, fetch timeout and write-back, and handed to its waiters as soon as it arrives), at most `WithGetManyConcurrency` (default 16) at a time; a key is claimed only when its turn comes, so a concurrent `Get` of a key still queued here does not wait for the queue, and a canceled `GetMany` starts no more keys. 6. **Write back**: found values go to the backend, missing keys to the Not-Found cache. With a `BatchUpstream` this is one `SetMany`/`DelMany` per batch (when the backend supports it); without one, each key is written back on its own, like `Get`. Either way this only touches this layer, never the upstream. `Client` implements `BatchUpstream[T]` itself, so in a layered setup a batch travels down as one call per layer: `l1Client.GetMany` → L1 batch read → `l2Client.GetMany` → L2 batch read → one database query. diff --git a/README_ZH.md b/README_ZH.md index caa927b..950886f 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -416,7 +416,7 @@ client := cachex.NewClient(cache, productSource{db: db} /* , options as in Quick 2. **Not-Found 缓存**:未命中的先查它,和 `Get` 一样。 3. **Singleflight**:每个要回源的 key 都在和 `Get` **同一个** singleflight 里认领。已经有 `Get` 或别的 `GetMany` 在取的 key,等那次的结果,不再取一遍;所以 `Get` 和 `GetMany`(或两个有交集的 `GetMany`)同时要同一个 key,只回源一次。`WithFetchConcurrency` 照旧按 key 生效。 4. **DoubleCheck**:认领到的 key 按和 `Get` 相同的规则再查一次后端和 Not-Found 缓存。 -5. **上游**:上游实现了 `BatchUpstream[T]`,剩下的 key 就调**一次** `GetMany`(整次调用共用一个 `WithFetchTimeout`;下层是 `Client` 时不加这个总超时,由下层给自己的每次拉取各自限时)。同一次调用里的 key 一起返回:并发 `Get` 其中某个 key 会加入这次调用,等它整个结束。否则每个 key 都和 `Get` 完全一样地拉取(各自 double check、各自超时、各自回填,拉到就交给等它的调用方),同时最多 `WithGetManyConcurrency` 个(默认 16);每个 key 轮到时才认领,所以并发的 `Get` 碰上还在这里排队的 key 不用等整个队列,`GetMany` 被取消后也不再开始新的 key。 +5. **上游**:上游实现了 `BatchUpstream[T]`,剩下的 key 就调**一次** `GetMany`(整次调用共用一个 `WithFetchTimeout`;下层是 `Client` 时,上限放宽到下层自己的拉取最多可能用的时间,比如逐 key 排队时按轮数累加的超时)。同一次调用里的 key 一起返回:并发 `Get` 其中某个 key 会加入这次调用,等它整个结束。否则每个 key 都和 `Get` 完全一样地拉取(各自 double check、各自超时、各自回填,拉到就交给等它的调用方),同时最多 `WithGetManyConcurrency` 个(默认 16);每个 key 轮到时才认领,所以并发的 `Get` 碰上还在这里排队的 key 不用等整个队列,`GetMany` 被取消后也不再开始新的 key。 6. **回填**:取到的值写回后端,不存在的 key 写进 Not-Found 缓存。上游实现了 `BatchUpstream` 时,一批只调一次 `SetMany`/`DelMany`(后端支持的话);否则每个 key 各自回填,和 `Get` 一样。两种情况都只写本层,不写上游。 `Client` 自己也实现了 `BatchUpstream[T]`,所以多层缓存时一批 key 每层只走一次调用:`l1Client.GetMany` → L1 批量读 → `l2Client.GetMany` → L2 批量读 → 一次数据库查询。 diff --git a/batch.go b/batch.go index 4b4a98c..f9eb701 100644 --- a/batch.go +++ b/batch.go @@ -383,10 +383,11 @@ func (c *Client[T]) fetchClaimedMany(ctx context.Context, keys, sfKeys []string, // like Get, the fetch timeout starts after the double-check. A Client below // bounds each of its own fetches, so its batch is not bounded as one fetch: // keys still queued there would fail with this deadline, not their own. - fetchCtx, cancel := context.WithCancel(context.WithoutCancel(ctx)) - if _, layered := c.upstream.(*Client[T]); !layered { - fetchCtx, cancel = context.WithTimeout(fetchCtx, c.fetchTimeout) + timeout := c.fetchTimeout + if lower, layered := c.upstream.(*Client[T]); layered { + timeout += lower.batchTimeout(len(pendingKeys)) } + fetchCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), timeout) defer cancel() for j, r := range c.doFetchMany(fetchCtx, pendingKeys) { results[pending[j]] = r @@ -394,6 +395,22 @@ func (c *Client[T]) fetchClaimedMany(ctx context.Context, keys, sfKeys []string, returned = true } +// batchTimeout is how long a GetMany of n keys sent to this Client as an +// upstream may legitimately take: a fetch timeout for its own reads and +// write-back, plus its fetches (one batch, a lower Client's own budget, or a +// queue of per-key fetches, getManyConc at a time). +func (c *Client[T]) batchTimeout(n int) time.Duration { + switch up := c.upstream.(type) { + case *Client[T]: + return c.fetchTimeout + up.batchTimeout(n) + case BatchUpstream[T]: + return 2 * c.fetchTimeout + default: + rounds := (n + c.getManyConc - 1) / c.getManyConc + return c.fetchTimeout * time.Duration(1+rounds) + } +} + // doFetchMany is the batch form of doFetch: fetch from the batch upstream, // then write the results to this layer only. func (c *Client[T]) doFetchMany(ctx context.Context, keys []string) []result[T] { diff --git a/batch_test.go b/batch_test.go index c80e6c4..990c829 100644 --- a/batch_test.go +++ b/batch_test.go @@ -1165,6 +1165,35 @@ func TestClientGetManyOverAClientIsNotBoundedAsOneFetch(t *testing.T) { assert.Len(t, got, len(keys)) } +// hangingBatchCache is a BatchCache whose reads block until ctx is done. +type hangingBatchCache struct{ *SyncMap[string] } + +func (hangingBatchCache) Get(ctx context.Context, _ string) (string, error) { + <-ctx.Done() + return "", ctx.Err() +} + +func (hangingBatchCache) GetMany(ctx context.Context, _ []string) (map[string]string, error) { + <-ctx.Done() + return nil, ctx.Err() +} + +func TestClientGetManyOverAClientIsStillBounded(t *testing.T) { + src := UpstreamFunc[string](func(_ context.Context, key string) (string, error) { return "v-" + key, nil }) + l2 := NewClient[string](hangingBatchCache{NewSyncMap[string]()}, src, WithFetchTimeout[string](50*time.Millisecond)) + l1 := NewClient[string](NewSyncMap[string](), l2, WithFetchTimeout[string](50*time.Millisecond)) + + ctx, cancel := context.WithTimeout(context.Background(), 20*time.Millisecond) + defer cancel() + _, err := l1.GetMany(ctx, []string{"k"}) + require.Error(t, err) + require.Eventually(t, func() bool { + l1.flights.mu.Lock() + defer l1.flights.mu.Unlock() + return len(l1.flights.flights) == 0 + }, 2*time.Second, 5*time.Millisecond, "a lower layer that hangs does not keep the key claimed forever") +} + func TestRedisCacheGetManyPerKeyErrors(t *testing.T) { ctx := context.Background() cache, mr := newRedisCache[string](t) diff --git a/gorm.go b/gorm.go index a56084a..8ec3975 100644 --- a/gorm.go +++ b/gorm.go @@ -257,6 +257,9 @@ func (g *GORMCache[T]) SetMany(ctx context.Context, values map[string]T) error { if len(entries) == 0 { return stderrors.Join(encodeErrs...) } + // one row order for every caller, or overlapping batches lock rows in + // opposite orders and deadlock (MySQL, PostgreSQL) + slices.SortFunc(entries, func(a, b cacheEntry) int { return cmp.Compare(a.Key, b.Key) }) tx := cmp.Or(GetGORMTx(ctx), g.db) if err := tx.WithContext(ctx). diff --git a/gorm_container_test.go b/gorm_container_test.go index 65dfcf2..cab1d4b 100644 --- a/gorm_container_test.go +++ b/gorm_container_test.go @@ -3,6 +3,7 @@ package cachex import ( "context" "fmt" + "sync" "testing" "github.com/stretchr/testify/assert" @@ -108,6 +109,23 @@ func TestGORMCacheOnRealDatabases(t *testing.T) { }) } + t.Run("concurrent overlapping SetMany do not deadlock", func(t *testing.T) { + c := newCache(t) + values := map[string]string{} + for i := range 200 { + values[fmt.Sprintf("k%03d", i)] = "v" + } + var wg sync.WaitGroup + for range 8 { + wg.Go(func() { + for range 5 { + assert.NoError(t, c.SetMany(ctx, values)) + } + }) + } + wg.Wait() + }) + t.Run("Client over it", func(t *testing.T) { c := newCache(t) up := &batchUpstream{data: map[string]string{"a": "1", "b": "2"}} From d84b7e4380e6d99f767e3f0d85b93a8db3c96784 Mon Sep 17 00:00:00 2001 From: molon <3739161+molon@users.noreply.github.com> Date: Fri, 9 Oct 2026 00:00:56 +0800 Subject: [PATCH 26/40] fix: GORMCache writes no longer deadlock each other on PostgreSQL, and are retried as deadlock victims Measured with 16 workers mixing SetMany and DelMany over shared keys: - PostgreSQL: DELETE locked rows in index order, which follows the column's collation (en_US.utf8 in the official image), while SetMany locks in byte order; about half the operations deadlocked, each stalling for deadlock_timeout. DelMany now locks its rows in byte order first (SELECT ... ORDER BY key COLLATE "C" FOR UPDATE). - MySQL: with one lock order a few writes (3 in 1280) were still picked as deadlock victims through gap locks, which InnoDB expects callers to retry. GORMCache writes are now retried up to 5 times on a deadlock, except inside a caller's transaction, which the deadlock rolled back. Both gave 0 deadlocks; serializing writes per table (a table lock) also did, at 32% (MySQL) and 46% (PostgreSQL) lower throughput. --- README.md | 2 + README_ZH.md | 2 + gorm.go | 84 ++++++++++++++++++++++++++++++++---------- gorm_container_test.go | 34 +++++++++++++++++ gorm_test.go | 41 +++++++++++++++++++++ 5 files changed, 143 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 5cbab32..3d970bd 100644 --- a/README.md +++ b/README.md @@ -217,6 +217,8 @@ if err := cache.Migrate(ctx); err != nil { Cache keys are case-sensitive, so the `key` column should compare them exactly. PostgreSQL and SQLite do by default, and on MySQL (8.0.17 or later) `Migrate` creates the table with `utf8mb4_0900_bin`, which compares case and trailing spaces exactly. A table created before that (or by hand) keeps its collation, usually case- and accent-insensitive (`*_ci`); convert it with `ALTER TABLE cache_products CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_bin`. Even without it nothing wrong is ever served: `GORMCache` only returns the row stored under exactly the requested key, so keys differing only in case just take the row over from each other (extra misses). +Concurrent batch writes (from several instances' `GetMany` write-backs) lock rows in one order, so they do not deadlock each other; a write the database still aborts as a deadlock victim (MySQL's gap locks can) is retried a few times. Inside a transaction passed with `WithGORMTx` it is not retried, since the deadlock has rolled that whole transaction back; the error is returned. + ### Custom Cache Implement the `Cache[T]` interface: diff --git a/README_ZH.md b/README_ZH.md index 950886f..f97018d 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -217,6 +217,8 @@ if err := cache.Migrate(ctx); err != nil { 缓存 key 区分大小写,所以 `key` 列应当精确比较。PostgreSQL 和 SQLite 默认如此;MySQL(需 8.0.17 及以上)上 `Migrate` 建表时会用 `utf8mb4_0900_bin`,大小写和末尾空格都精确比较。在这之前建的表(或手工建的表)保留原来的排序规则,通常不区分大小写和重音(`*_ci`),可以用 `ALTER TABLE cache_products CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_bin` 转换。即使不转换也不会读到错的值:`GORMCache` 只返回 key 完全相等的那一行,只差大小写的几个 key 只会互相挤占这一行(多几次未命中)。 +并发的批量写入(多个实例的 `GetMany` 回填)按同一顺序锁行,彼此不会死锁;数据库仍判为死锁牺牲者的写入(MySQL 的间隙锁可能导致)会重试几次。通过 `WithGORMTx` 传入的事务里不重试,因为死锁已经回滚了整个事务,直接返回错误。 + ### 自定义缓存 实现 `Cache[T]` 接口: diff --git a/gorm.go b/gorm.go index 8ec3975..4352082 100644 --- a/gorm.go +++ b/gorm.go @@ -5,7 +5,9 @@ import ( "context" "encoding/json" stderrors "errors" + "math/rand/v2" "slices" + "strings" "time" "github.com/pkg/errors" @@ -14,6 +16,45 @@ import ( "gorm.io/gorm/clause" ) +// gormDeadlockRetries is how many times a write chosen as a deadlock victim is +// run in all. Writes take row locks in one order (sorted keys), but MySQL's gap +// locks can still deadlock now and then, and InnoDB expects a retry. +const gormDeadlockRetries = 5 + +// write runs a write to the cache table, retrying it if the database aborts +// it as a deadlock victim, unless it runs in the caller's transaction, which +// the deadlock has already rolled back as a whole. +func (g *GORMCache[T]) write(ctx context.Context, f func(tx *gorm.DB) error) error { + if tx := GetGORMTx(ctx); tx != nil { + return f(tx.WithContext(ctx)) + } + for attempt := 1; ; attempt++ { + err := f(g.db.WithContext(ctx)) + if !isDeadlock(err) || attempt == gormDeadlockRetries { + return err + } + select { + case <-ctx.Done(): + return err + case <-time.After(time.Duration(1+rand.IntN(5*attempt)) * time.Millisecond): + } + } +} + +// isDeadlock reports whether err aborted a statement as a deadlock victim: +// SQLSTATE 40P01/40001 from PostgreSQL drivers (pgx, lib/pq), or MySQL error +// 1213, matched by text since go-sql-driver's error has no SQLState method. +func isDeadlock(err error) bool { + if err == nil { + return false + } + var pg interface{ SQLState() string } + if stderrors.As(err, &pg) { + return pg.SQLState() == "40P01" || pg.SQLState() == "40001" + } + return strings.Contains(err.Error(), "Error 1213 (40001)") +} + // keyColumn is the key column as a clause, so GORM quotes it: "key" is a // reserved word in MySQL. var keyColumn = clause.Column{Name: "key"} @@ -125,11 +166,9 @@ func (g *GORMCache[T]) Set(ctx context.Context, key string, value T) error { Value: data, } - tx := cmp.Or(GetGORMTx(ctx), g.db) - if err := tx.WithContext(ctx). - Table(g.tableName). - Clauses(upsertEntry). - Create(&entry).Error; err != nil { + if err := g.write(ctx, func(tx *gorm.DB) error { + return tx.Table(g.tableName).Clauses(upsertEntry).Create(&entry).Error + }); err != nil { return errors.Wrapf(err, "failed to set cache entry for key: %s", key) } @@ -167,11 +206,9 @@ func (g *GORMCache[T]) Get(ctx context.Context, key string) (T, error) { // Del removes a value from the cache func (g *GORMCache[T]) Del(ctx context.Context, key string) error { - tx := cmp.Or(GetGORMTx(ctx), g.db) - if err := tx.WithContext(ctx). - Table(g.tableName). - Where(clause.Eq{Column: keyColumn, Value: g.prefixedKey(key)}). - Delete(nil).Error; err != nil { + if err := g.write(ctx, func(tx *gorm.DB) error { + return tx.Table(g.tableName).Where(clause.Eq{Column: keyColumn, Value: g.prefixedKey(key)}).Delete(nil).Error + }); err != nil { return errors.Wrapf(err, "failed to delete cache entry for key: %s", key) } return nil @@ -261,11 +298,9 @@ func (g *GORMCache[T]) SetMany(ctx context.Context, values map[string]T) error { // opposite orders and deadlock (MySQL, PostgreSQL) slices.SortFunc(entries, func(a, b cacheEntry) int { return cmp.Compare(a.Key, b.Key) }) - tx := cmp.Or(GetGORMTx(ctx), g.db) - if err := tx.WithContext(ctx). - Table(g.tableName). - Clauses(upsertEntry). - CreateInBatches(&entries, gormBatchSize).Error; err != nil { + if err := g.write(ctx, func(tx *gorm.DB) error { + return tx.Table(g.tableName).Clauses(upsertEntry).CreateInBatches(&entries, gormBatchSize).Error + }); err != nil { return errors.Wrap(err, "failed to set cache entries") } return stderrors.Join(encodeErrs...) @@ -282,12 +317,21 @@ func (g *GORMCache[T]) DelMany(ctx context.Context, keys []string) error { prefixed[i] = g.prefixedKey(key) } - tx := cmp.Or(GetGORMTx(ctx), g.db) for chunk := range slices.Chunk(prefixed, gormBatchSize) { - if err := tx.WithContext(ctx). - Table(g.tableName). - Where(clause.IN{Column: keyColumn, Values: anys(chunk)}). - Delete(nil).Error; err != nil { + if err := g.write(ctx, func(tx *gorm.DB) error { + in := clause.IN{Column: keyColumn, Values: anys(chunk)} + if tx.Name() != "postgres" { + return tx.Table(g.tableName).Where(in).Delete(nil).Error + } + // DELETE locks rows in scan order, which follows the column's + // collation (often en_US), not SetMany's byte order: lock them in + // byte order first, or the two deadlock each other + locked := tx.Session(&gorm.Session{NewDB: true}).Table(g.tableName). + Select("?", keyColumn).Where(in). + Order(clause.OrderBy{Expression: clause.Expr{SQL: `? COLLATE "C"`, Vars: []any{keyColumn}, WithoutParentheses: true}}). + Clauses(clause.Locking{Strength: clause.LockingStrengthUpdate}) + return tx.Table(g.tableName).Where("? IN (?)", keyColumn, locked).Delete(nil).Error + }); err != nil { return errors.Wrap(err, "failed to delete cache entries") } } diff --git a/gorm_container_test.go b/gorm_container_test.go index cab1d4b..51b8773 100644 --- a/gorm_container_test.go +++ b/gorm_container_test.go @@ -3,6 +3,7 @@ package cachex import ( "context" "fmt" + "math/rand/v2" "sync" "testing" @@ -126,6 +127,39 @@ func TestGORMCacheOnRealDatabases(t *testing.T) { wg.Wait() }) + t.Run("concurrent SetMany and DelMany do not deadlock", func(t *testing.T) { + // mixed case: byte order differs from PostgreSQL's default en_US + // collation, which once made DELETE lock rows in another order + c := newCache(t) + keys := make([]string, 400) + for i := range keys { + keys[i] = fmt.Sprintf("%c%03d", "aBcD"[i%4], i) + } + var wg sync.WaitGroup + for w := range 8 { + wg.Go(func() { + for round := range 20 { + r := rand.New(rand.NewPCG(uint64(w), uint64(round))) + pick := r.Perm(len(keys))[:100] + if round%3 == 0 { + sub := make([]string, len(pick)) + for i, j := range pick { + sub[i] = keys[j] + } + assert.NoError(t, c.DelMany(ctx, sub)) + continue + } + values := map[string]string{} + for _, j := range pick { + values[keys[j]] = "v" + } + assert.NoError(t, c.SetMany(ctx, values)) + } + }) + } + wg.Wait() + }) + t.Run("Client over it", func(t *testing.T) { c := newCache(t) up := &batchUpstream{data: map[string]string{"a": "1", "b": "2"}} diff --git a/gorm_test.go b/gorm_test.go index 6e30e4d..31873ae 100644 --- a/gorm_test.go +++ b/gorm_test.go @@ -5,8 +5,10 @@ import ( "math" "regexp" "strings" + "sync/atomic" "testing" + "github.com/pkg/errors" "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" "gorm.io/driver/sqlite" @@ -309,3 +311,42 @@ func TestGORMCacheSetManyKeepsTheValuesThatEncode(t *testing.T) { require.NoError(t, err, "like RedisCache, the others are still written") assert.Equal(t, num{1}, v) } + +// sqlStateError mimics a pgx/lib/pq error. +type sqlStateError string + +func (e sqlStateError) Error() string { return "ERROR: (SQLSTATE " + string(e) + ")" } +func (e sqlStateError) SQLState() string { return string(e) } + +func TestIsDeadlock(t *testing.T) { + assert.True(t, isDeadlock(errors.Wrap(sqlStateError("40P01"), "x")), "PostgreSQL deadlock") + assert.True(t, isDeadlock(sqlStateError("40001")), "serialization failure") + assert.True(t, isDeadlock(errors.New("Error 1213 (40001): Deadlock found when trying to get lock; try restarting transaction")), "MySQL deadlock") + assert.False(t, isDeadlock(sqlStateError("23505"))) + assert.False(t, isDeadlock(errors.New("Error 1205 (HY000): Lock wait timeout exceeded"))) + assert.False(t, isDeadlock(nil)) +} + +func TestGORMCacheRetriesDeadlockVictims(t *testing.T) { + cache, db := newGORMCache[string](t, "retry") + ctx := context.Background() + var fails atomic.Int32 + require.NoError(t, db.Callback().Create().Before("gorm:create").Register("test:deadlock", func(tx *gorm.DB) { + if fails.Add(-1) >= 0 { + _ = tx.AddError(sqlStateError("40P01")) + } + })) + + fails.Store(2) + require.NoError(t, cache.Set(ctx, "k", "v"), "a deadlock victim is retried") + v, err := cache.Get(ctx, "k") + require.NoError(t, err) + assert.Equal(t, "v", v) + + fails.Store(100) + assert.True(t, isDeadlock(cache.SetMany(ctx, map[string]string{"k": "v2"})), "retries are bounded") + + fails.Store(1) + err = db.Transaction(func(tx *gorm.DB) error { return cache.Set(WithGORMTx(ctx, tx), "k", "v3") }) + assert.True(t, isDeadlock(err), "inside the caller's transaction, which the deadlock rolled back, nothing is retried") +} From d3f87318a4e0494ac20f78189227961014af039f Mon Sep 17 00:00:00 2001 From: molon <3739161+molon@users.noreply.github.com> Date: Sat, 10 Oct 2026 02:59:14 +0800 Subject: [PATCH 27/40] fix: RedisCache reads replies without copying them again The encode/decode refactor read GET replies with Result() and converted the string to []byte, copying every JSON, binary and []byte value once more. Read them with StringCmd.Bytes(), which shares the reply's memory, as Get on main did. --- redis.go | 27 +++++++++++++++------------ redis_test.go | 12 ++++++++++++ 2 files changed, 27 insertions(+), 12 deletions(-) diff --git a/redis.go b/redis.go index ef26af9..df72629 100644 --- a/redis.go +++ b/redis.go @@ -92,20 +92,23 @@ func (r *RedisCache[T]) encode(key string, value T) (any, error) { } } -func (r *RedisCache[T]) decode(key string, data string) (T, error) { +// decode reads a GET reply. cmd.Bytes() shares the reply's memory instead of +// copying it; the cmd is discarded afterwards, so nothing else holds it. +func (r *RedisCache[T]) decode(key string, cmd *redis.StringCmd) (T, error) { var zero T - switch any(zero).(type) { - case string: + if _, ok := any(zero).(string); ok { + return any(cmd.Val()).(T), nil + } + data, _ := cmd.Bytes() + if _, ok := any(zero).([]byte); ok { return any(data).(T), nil - case []byte: - return any([]byte(data)).(T), nil } var value T if r.useBinary { if unmarshaler, ok := any(&value).(encoding.BinaryUnmarshaler); ok { - if err := unmarshaler.UnmarshalBinary([]byte(data)); err != nil { + if err := unmarshaler.UnmarshalBinary(data); err != nil { return zero, errors.Wrapf(err, "failed to unmarshal binary for key: %s", key) } } @@ -113,7 +116,7 @@ func (r *RedisCache[T]) decode(key string, data string) (T, error) { } // For other types: unmarshal from JSON - if err := json.Unmarshal([]byte(data), &value); err != nil { + if err := json.Unmarshal(data, &value); err != nil { return zero, errors.Wrapf(err, "failed to unmarshal value for key: %s", key) } return value, nil @@ -143,11 +146,11 @@ func (r *RedisCache[T]) handleRedisError(err error, key string) error { // Get retrieves a value from the cache func (r *RedisCache[T]) Get(ctx context.Context, key string) (T, error) { var zero T - data, err := r.client.Get(ctx, r.prefixedKey(key)).Result() - if err != nil { + cmd := r.client.Get(ctx, r.prefixedKey(key)) + if err := cmd.Err(); err != nil { return zero, r.handleRedisError(err, key) } - return r.decode(key, data) + return r.decode(key, cmd) } // Del removes a value from the cache @@ -179,13 +182,13 @@ func (r *RedisCache[T]) GetMany(ctx context.Context, keys []string) (map[string] var keyErrs map[string]error for i, key := range keys { - data, err := cmds[i].Result() + err := cmds[i].Err() if errors.Is(err, redis.Nil) { continue } var value T if err == nil { - value, err = r.decode(key, data) + value, err = r.decode(key, cmds[i]) } else { err = r.handleRedisError(err, key) } diff --git a/redis_test.go b/redis_test.go index 6c75ea2..f3a49a3 100644 --- a/redis_test.go +++ b/redis_test.go @@ -340,3 +340,15 @@ func TestRedisCacheWithStandardBinaryMarshaler(t *testing.T) { assert.NotContains(t, rawValue, `"X"`, "Should be stored in binary format, not JSON") }) } + +func TestRedisCacheDecodeSharesTheReply(t *testing.T) { + cache := NewRedisCache[[]byte](&RedisCacheConfig{Client: redis.NewClient(&redis.Options{})}) + cmd := redis.NewStringResult("payload", nil) + allocs := testing.AllocsPerRun(100, func() { + v, err := cache.decode("k", cmd) + if err != nil || string(v) != "payload" { + t.Fatal(v, err) + } + }) + assert.Zero(t, allocs, "[]byte values reuse the reply's memory, as Get on main did via cmd.Bytes()") +} From a91af7f5b122ca729928f7a3f2941e777a4c1a76 Mon Sep 17 00:00:00 2001 From: molon <3739161+molon@users.noreply.github.com> Date: Sat, 10 Oct 2026 03:06:07 +0800 Subject: [PATCH 28/40] fix: RedisCache.GetMany read an unreachable Redis as empty values; batch writes are best effort and report failed keys - When the connection could not be made, go-redis's pipeline Exec returned the error but left the commands it never sent without one, and GetMany read them as empty values: an outage served "" (or a decode error) as a hit. Pipeline errors that Redis did not reply to a command are now set on every command without an error. - SetMany and DelMany are best effort on every built-in backend, as the BatchCache contract now states: each key is tried, and the keys that failed are reported in a *BatchError. GORMCache runs one statement per chunk instead of one transaction for the whole call, and goes on after a failed chunk (in GetMany too). The per-key fallback for a plain Cache reports by key as well. - RedisCacheConfig.ChunkSize and GORMCacheConfig.ChunkSize (default DefaultChunkSize, 1000) split large calls into pipelines or statements sent one after another; GORMCache caps it at 10000. --- README.md | 5 +- README_ZH.md | 4 +- batch.go | 27 +++++++-- batch_test.go | 121 +++++++++++++++++++++++++++++++++++++ error.go | 8 +++ gorm.go | 121 ++++++++++++++++++++----------------- gorm_test.go | 5 ++ redis.go | 163 +++++++++++++++++++++++++++++--------------------- types.go | 3 + 9 files changed, 327 insertions(+), 130 deletions(-) diff --git a/README.md b/README.md index 3d970bd..5c3d2f0 100644 --- a/README.md +++ b/README.md @@ -244,6 +244,9 @@ type BatchCache[T any] interface { // Errors follow BatchUpstream below: any error other than an unwrapped // *cachex.BatchError fails every key (it is not read as all misses). GetMany(ctx context.Context, keys []string) (map[string]T, error) + // Best effort: apply every key you can and list the keys that failed in a + // *cachex.BatchError returned as is; any other error means it is unknown + // which keys were applied. SetMany(ctx context.Context, values map[string]T) error DelMany(ctx context.Context, keys []string) error } @@ -437,7 +440,7 @@ if errors.As(err, &batchErr) { // products is usable either way ``` -These built-in backends implement `BatchCache[T]`: `RistrettoCache`, `SyncMap`, `RedisCache` (one pipeline of `GET`/`SET`/`DEL`, which also works on Redis Cluster) and `GORMCache` (`WHERE key IN (...)` and multi-row upserts, 1000 keys per statement to stay under the bound parameter limits). `BigCache` and the `Transform` wrappers do not, so `GetMany` reads and writes them key by key (wrapping a `RedisCache` in `Transform` means one round trip per key). +These built-in backends implement `BatchCache[T]`: `RistrettoCache`, `SyncMap`, `RedisCache` (pipelines of `GET`/`SET`/`DEL`, which also work on Redis Cluster) and `GORMCache` (`WHERE key IN (...)` and multi-row upserts). Both split a large call into pipelines or statements of `ChunkSize` keys (default 1000, set in their config; `GORMCache` caps it at 10000 to stay under the bound parameter limits), sent one after another, and write best effort: a failed chunk is reported by key and the others are still written. `BigCache` and the `Transform` wrappers do not, so `GetMany` reads and writes them key by key (wrapping a `RedisCache` in `Transform` means one round trip per key). Fetching 100 missing keys through an upstream that costs 1ms per call (`BenchmarkGetManyVsGet`): diff --git a/README_ZH.md b/README_ZH.md index f97018d..96a0e86 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -244,6 +244,8 @@ type BatchCache[T any] interface { // 错误约定同下文的 BatchUpstream:除了原样返回的 *cachex.BatchError, // 其他 error 都算所有 key 失败(不会当成全部未命中)。 GetMany(ctx context.Context, keys []string) (map[string]T, error) + // 尽力而为:能写的 key 都写,失败的 key 列在原样返回的 *cachex.BatchError 里; + // 其他 error 表示不知道哪些 key 写成功了。 SetMany(ctx context.Context, values map[string]T) error DelMany(ctx context.Context, keys []string) error } @@ -436,7 +438,7 @@ if errors.As(err, &batchErr) { // 不管有没有 err,products 都能用 ``` -以下内置后端实现了 `BatchCache[T]`:`RistrettoCache`、`SyncMap`、`RedisCache`(一个 `GET`/`SET`/`DEL` 的 pipeline,Redis Cluster 下也能用)和 `GORMCache`(`WHERE key IN (...)` 和多行 upsert,每条语句 1000 个 key,不会超出数据库的绑定参数上限)。`BigCache` 和 `Transform` 包装没有实现,`GetMany` 对它们逐个 key 读写(用 `Transform` 包一层 `RedisCache`,就是每个 key 一次往返)。 +以下内置后端实现了 `BatchCache[T]`:`RistrettoCache`、`SyncMap`、`RedisCache`(`GET`/`SET`/`DEL` 的 pipeline,Redis Cluster 下也能用)和 `GORMCache`(`WHERE key IN (...)` 和多行 upsert)。两者都会把大调用按 `ChunkSize` 个 key 切成多个 pipeline 或语句(默认 1000,在各自的配置里设置;`GORMCache` 最多 10000,不会超出数据库的绑定参数上限),依次发送;写入尽力而为:某一段失败会按 key 报告,其他段照常写入。`BigCache` 和 `Transform` 包装没有实现,`GetMany` 对它们逐个 key 读写(用 `Transform` 包一层 `RedisCache`,就是每个 key 一次往返)。 上游每次调用耗时 1ms,取 100 个全未命中的 key(`BenchmarkGetManyVsGet`): diff --git a/batch.go b/batch.go index f9eb701..777ee76 100644 --- a/batch.go +++ b/batch.go @@ -583,17 +583,30 @@ func getMany[T any](ctx context.Context, from Upstream[T], keys []string) (map[s return out, nil } +// DefaultChunkSize is how many keys one pipeline or statement of the built-in +// batch backends carries unless configured otherwise. +const DefaultChunkSize = 1000 + +func chunkSizeOr(size, def int) int { + if size <= 0 { + return def + } + return size +} + // setMany writes many keys, in one call when cache implements BatchCache, // otherwise key by key; like Get, one key failing does not stop the others. func setMany[T any](ctx context.Context, cache Cache[T], values map[string]T) error { if batch, ok := cache.(BatchCache[T]); ok { return batch.SetMany(ctx, values) } - var errs []error + errs := map[string]error{} for key, value := range values { - errs = append(errs, cache.Set(ctx, key, value)) + if err := cache.Set(ctx, key, value); err != nil { + errs[key] = err + } } - return stderrors.Join(errs...) + return batchError(errs) } // delMany is the delete counterpart of setMany. @@ -601,11 +614,13 @@ func delMany[T any](ctx context.Context, cache Cache[T], keys []string) error { if batch, ok := cache.(BatchCache[T]); ok { return batch.DelMany(ctx, keys) } - var errs []error + errs := map[string]error{} for _, key := range keys { - errs = append(errs, cache.Del(ctx, key)) + if err := cache.Del(ctx, key); err != nil { + errs[key] = err + } } - return stderrors.Join(errs...) + return batchError(errs) } // errForKey returns the error a batch call reported for key: the key's own diff --git a/batch_test.go b/batch_test.go index 990c829..5dd2764 100644 --- a/batch_test.go +++ b/batch_test.go @@ -7,6 +7,7 @@ import ( "fmt" "log/slog" "maps" + "math" "runtime" "slices" "strings" @@ -15,9 +16,12 @@ import ( "testing" "time" + "github.com/alicebob/miniredis/v2" "github.com/pkg/errors" + "github.com/redis/go-redis/v9" "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" + "gorm.io/gorm" ) // testBatchCache checks the BatchCache contract against one implementation. @@ -1440,3 +1444,120 @@ func (b *syncBuffer) String() string { defer b.mu.Unlock() return b.buf.String() } + +func TestBatchWritesAreBestEffortAndReportFailedKeys(t *testing.T) { + ctx := context.Background() + + t.Run("RedisCache reports every key of a failed pipeline", func(t *testing.T) { + cache, mr := newRedisCache[string](t) + mr.Close() + var be *BatchError + require.ErrorAs(t, cache.SetMany(ctx, map[string]string{"a": "1", "b": "2"}), &be) + assert.ElementsMatch(t, []string{"a", "b"}, slices.Collect(maps.Keys(be.Errors))) + require.ErrorAs(t, cache.DelMany(ctx, []string{"a", "b"}), &be) + assert.ElementsMatch(t, []string{"a", "b"}, slices.Collect(maps.Keys(be.Errors))) + }) + + t.Run("RedisCache reports a value that cannot be encoded by key", func(t *testing.T) { + cache, _ := newRedisCache[float64](t) + err := cache.SetMany(ctx, map[string]float64{"ok": 1, "bad": math.NaN()}) + var be *BatchError + require.ErrorAs(t, err, &be) + assert.Equal(t, []string{"bad"}, slices.Collect(maps.Keys(be.Errors))) + v, err := cache.Get(ctx, "ok") + require.NoError(t, err) + assert.Equal(t, 1.0, v) + }) + + t.Run("GORMCache keeps writing the chunks after a failed one", func(t *testing.T) { + cache, db := newGORMCacheWith[string](t, "besteffort", 2) + var creates atomic.Int32 + require.NoError(t, db.Callback().Create().Before("gorm:create").Register("test:fail-first", func(tx *gorm.DB) { + if creates.Add(1) == 1 { + _ = tx.AddError(errors.New("boom")) + } + })) + values := map[string]string{"a": "1", "b": "2", "c": "3", "d": "4"} // sorted: chunks [a b] [c d] + err := cache.SetMany(ctx, values) + var be *BatchError + require.ErrorAs(t, err, &be) + assert.ElementsMatch(t, []string{"a", "b"}, slices.Collect(maps.Keys(be.Errors)), "the keys of the failed chunk") + got, err := cache.GetMany(ctx, []string{"a", "b", "c", "d"}) + require.NoError(t, err) + assert.Equal(t, map[string]string{"c": "3", "d": "4"}, got, "the next chunk is still written") + assert.Equal(t, int32(2), creates.Load(), "one statement per chunk") + + var deletes atomic.Int32 + require.NoError(t, db.Callback().Delete().Before("gorm:delete").Register("test:fail-first", func(tx *gorm.DB) { + if deletes.Add(1) == 1 { + _ = tx.AddError(errors.New("boom")) + } + })) + err = cache.DelMany(ctx, []string{"c", "d", "x", "y"}) + require.ErrorAs(t, err, &be) + assert.ElementsMatch(t, []string{"c", "d"}, slices.Collect(maps.Keys(be.Errors))) + assert.Equal(t, int32(2), deletes.Load(), "DelMany goes on after a failed chunk") + }) + + t.Run("the per-key fallback for a plain Cache reports by key too", func(t *testing.T) { + c := keyFailingCache[string]{m: NewSyncMap[string](), bad: "bad"} + var be *BatchError + require.ErrorAs(t, setMany[string](ctx, c, map[string]string{"ok": "1", "bad": "2"}), &be) + assert.Equal(t, []string{"bad"}, slices.Collect(maps.Keys(be.Errors))) + require.ErrorAs(t, delMany[string](ctx, c, []string{"ok", "bad"}), &be) + assert.Equal(t, []string{"bad"}, slices.Collect(maps.Keys(be.Errors))) + }) +} + +func TestBatchBackendsSplitLargeCallsIntoChunks(t *testing.T) { + ctx := context.Background() + t.Run("RedisCache", func(t *testing.T) { + mr := miniredis.RunT(t) + client := redis.NewClient(&redis.Options{Addr: mr.Addr()}) + t.Cleanup(func() { _ = client.Close() }) + require.NoError(t, client.Ping(ctx).Err()) // the connection handshake is a pipeline too + var pipelines atomic.Int32 + client.AddHook(pipelineCounter{&pipelines}) + cache := NewRedisCache[string](&RedisCacheConfig{Client: client, ChunkSize: 2}) + require.NoError(t, cache.SetMany(ctx, map[string]string{"a": "1", "b": "2", "c": "3"})) + got, err := cache.GetMany(ctx, []string{"a", "b", "c"}) + require.NoError(t, err) + assert.Len(t, got, 3) + require.NoError(t, cache.DelMany(ctx, []string{"a", "b", "c"})) + assert.Equal(t, int32(6), pipelines.Load(), "3 keys in chunks of 2: two pipelines per call") + }) + t.Run("GORMCache", func(t *testing.T) { + cache, db := newGORMCacheWith[string](t, "chunks", 2) + var queries atomic.Int32 + require.NoError(t, db.Callback().Query().Before("gorm:query").Register("test:count", func(*gorm.DB) { queries.Add(1) })) + require.NoError(t, cache.SetMany(ctx, map[string]string{"a": "1", "b": "2", "c": "3"})) + got, err := cache.GetMany(ctx, []string{"a", "b", "c"}) + require.NoError(t, err) + assert.Len(t, got, 3) + assert.Equal(t, int32(2), queries.Load()) + }) +} + +// pipelineCounter counts the pipelines a go-redis client sends. +type pipelineCounter struct{ n *atomic.Int32 } + +func (pipelineCounter) DialHook(next redis.DialHook) redis.DialHook { return next } +func (pipelineCounter) ProcessHook(next redis.ProcessHook) redis.ProcessHook { return next } +func (p pipelineCounter) ProcessPipelineHook(next redis.ProcessPipelineHook) redis.ProcessPipelineHook { + return func(ctx context.Context, cmds []redis.Cmder) error { + p.n.Add(1) + return next(ctx, cmds) + } +} + +func TestRedisCacheGetManyWhenRedisIsDown(t *testing.T) { + ctx := context.Background() + cache, mr := newRedisCache[string](t) + require.NoError(t, cache.Set(ctx, "a", "1")) + mr.Close() + got, err := cache.GetMany(ctx, []string{"a", "b"}) + assert.Empty(t, got, "nothing was read, so nothing is returned as found") + var be *BatchError + require.ErrorAs(t, err, &be) + assert.ElementsMatch(t, []string{"a", "b"}, slices.Collect(maps.Keys(be.Errors))) +} diff --git a/error.go b/error.go index 7d7de57..f2c7a48 100644 --- a/error.go +++ b/error.go @@ -63,6 +63,14 @@ func (e *BatchError) Error() string { return fmt.Sprintf("%d keys failed: %s", len(keys), strings.Join(parts, "; ")) } +// batchError returns errs as a *BatchError, or nil if no key failed. +func batchError(errs map[string]error) error { + if len(errs) == 0 { + return nil + } + return &BatchError{Errors: errs} +} + // Unwrap returns the per-key errors, in sorted key order func (e *BatchError) Unwrap() []error { keys := slices.Sorted(maps.Keys(e.Errors)) diff --git a/gorm.go b/gorm.go index 4352082..efa35e9 100644 --- a/gorm.go +++ b/gorm.go @@ -79,6 +79,7 @@ type GORMCache[T any] struct { db *gorm.DB tableName string keyPrefix string + chunkSize int } var _ BatchCache[any] = &GORMCache[any]{} @@ -102,6 +103,11 @@ type GORMCacheConfig struct { // KeyPrefix is the prefix for all keys (optional) KeyPrefix string + + // ChunkSize is how many keys one statement of GetMany, SetMany or DelMany + // carries; a larger call runs several statements, one after another. Zero + // means DefaultChunkSize; values above gormMaxChunkSize are capped to it. + ChunkSize int } // NewGORMCache creates a new GORM-based cache with configuration @@ -117,6 +123,7 @@ func NewGORMCache[T any](config *GORMCacheConfig) *GORMCache[T] { db: config.DB, tableName: config.TableName, keyPrefix: config.KeyPrefix, + chunkSize: min(chunkSizeOr(config.ChunkSize, DefaultChunkSize), gormMaxChunkSize), } } @@ -214,15 +221,14 @@ func (g *GORMCache[T]) Del(ctx context.Context, key string) error { return nil } -// gormBatchSize bounds the keys per statement, keeping every batch statement -// well under the databases' bound parameter limits (32766 on SQLite, 65535 on -// PostgreSQL, 65535 on MySQL). -const gormBatchSize = 1000 +// gormMaxChunkSize keeps every statement under the databases' bound parameter +// limits: an upsert binds 3 parameters per row, and SQLite allows 32766. +const gormMaxChunkSize = 10000 // GetMany retrieves many values with `WHERE key IN (...)` queries of up to -// gormBatchSize keys each. -// Missing keys are absent from the result; a value that fails to unmarshal is -// reported in a *BatchError without hiding the others. +// ChunkSize keys each. +// Missing keys are absent from the result; a key that fails (its chunk's query, +// or unmarshaling its value) is reported in a *BatchError without hiding the others. func (g *GORMCache[T]) GetMany(ctx context.Context, keys []string) (map[string]T, error) { out := make(map[string]T, len(keys)) if len(keys) == 0 { @@ -234,24 +240,26 @@ func (g *GORMCache[T]) GetMany(ctx context.Context, keys []string) (map[string]T prefixed[i] = g.prefixedKey(key) } - var entries []cacheEntry + stored := make(map[string]cacheEntry, len(keys)) + keyErrs := map[string]error{} tx := cmp.Or(GetGORMTx(ctx), g.db) - for chunk := range slices.Chunk(prefixed, gormBatchSize) { + for start := 0; start < len(keys); start += g.chunkSize { + chunk := prefixed[start:min(start+g.chunkSize, len(keys))] var found []cacheEntry if err := tx.WithContext(ctx). Table(g.tableName). Where(clause.IN{Column: keyColumn, Values: anys(chunk)}). Find(&found).Error; err != nil { - return nil, errors.Wrap(err, "failed to get cache entries") + for _, key := range keys[start : start+len(chunk)] { + keyErrs[key] = errors.Wrapf(err, "failed to get cache entry for key: %s", key) + } + continue + } + for _, entry := range found { + stored[entry.Key] = entry } - entries = append(entries, found...) } - stored := make(map[string]cacheEntry, len(entries)) - for _, entry := range entries { - stored[entry.Key] = entry - } - var keyErrs map[string]error for i, key := range keys { // exact lookup: a key column that is not byte-exact (e.g. MySQL's _ci // collations) can return another key's row, which is not this key's value @@ -259,67 +267,70 @@ func (g *GORMCache[T]) GetMany(ctx context.Context, keys []string) (map[string]T if !ok { continue } + if _, failed := keyErrs[key]; failed { + continue + } var value T if err := json.Unmarshal(entry.Value, &value); err != nil { - if keyErrs == nil { - keyErrs = map[string]error{} - } keyErrs[key] = errors.Wrapf(err, "failed to unmarshal value for key: %s", key) continue } out[key] = value } - if keyErrs != nil { - return out, &BatchError{Errors: keyErrs} - } - return out, nil + return out, batchError(keyErrs) } -// SetMany stores many values with multi-row upserts of up to gormBatchSize rows each +// SetMany stores many values with multi-row upserts of up to ChunkSize rows +// each, every statement on its own. It is best effort: every key is tried, and +// the keys that failed (to be encoded, or their chunk's statement) are reported +// in a *BatchError. func (g *GORMCache[T]) SetMany(ctx context.Context, values map[string]T) error { - if len(values) == 0 { - return nil + keyErrs := map[string]error{} + type row struct { + key string + entry cacheEntry } - - entries := make([]cacheEntry, 0, len(values)) - var encodeErrs []error // like RedisCache, a value that cannot be encoded does not stop the others + rows := make([]row, 0, len(values)) for key, value := range values { data, err := json.Marshal(value) if err != nil { - encodeErrs = append(encodeErrs, errors.Wrapf(err, "failed to marshal value for key: %s", key)) + keyErrs[key] = errors.Wrapf(err, "failed to marshal value for key: %s", key) continue } - entries = append(entries, cacheEntry{Key: g.prefixedKey(key), Value: data}) - } - if len(entries) == 0 { - return stderrors.Join(encodeErrs...) + rows = append(rows, row{key: key, entry: cacheEntry{Key: g.prefixedKey(key), Value: data}}) } // one row order for every caller, or overlapping batches lock rows in // opposite orders and deadlock (MySQL, PostgreSQL) - slices.SortFunc(entries, func(a, b cacheEntry) int { return cmp.Compare(a.Key, b.Key) }) + slices.SortFunc(rows, func(a, b row) int { return cmp.Compare(a.entry.Key, b.entry.Key) }) - if err := g.write(ctx, func(tx *gorm.DB) error { - return tx.Table(g.tableName).Clauses(upsertEntry).CreateInBatches(&entries, gormBatchSize).Error - }); err != nil { - return errors.Wrap(err, "failed to set cache entries") + for chunk := range slices.Chunk(rows, g.chunkSize) { + entries := make([]cacheEntry, len(chunk)) + for i, r := range chunk { + entries[i] = r.entry + } + if err := g.write(ctx, func(tx *gorm.DB) error { + return tx.Table(g.tableName).Clauses(upsertEntry).Create(&entries).Error + }); err != nil { + for _, r := range chunk { + keyErrs[r.key] = errors.Wrapf(err, "failed to set cache entry for key: %s", r.key) + } + } } - return stderrors.Join(encodeErrs...) + return batchError(keyErrs) } -// DelMany removes many keys with `WHERE key IN (...)` deletes of up to gormBatchSize keys each +// DelMany removes many keys with `WHERE key IN (...)` deletes of up to +// ChunkSize keys each, every statement on its own. It is best effort: every key +// is tried, and the keys of a failed statement are reported in a *BatchError. func (g *GORMCache[T]) DelMany(ctx context.Context, keys []string) error { - if len(keys) == 0 { - return nil - } - - prefixed := make([]string, len(keys)) - for i, key := range keys { - prefixed[i] = g.prefixedKey(key) - } - - for chunk := range slices.Chunk(prefixed, gormBatchSize) { + keyErrs := map[string]error{} + for chunk := range slices.Chunk(keys, g.chunkSize) { + prefixed := make([]string, len(chunk)) + for i, key := range chunk { + prefixed[i] = g.prefixedKey(key) + } if err := g.write(ctx, func(tx *gorm.DB) error { - in := clause.IN{Column: keyColumn, Values: anys(chunk)} + in := clause.IN{Column: keyColumn, Values: anys(prefixed)} if tx.Name() != "postgres" { return tx.Table(g.tableName).Where(in).Delete(nil).Error } @@ -332,8 +343,10 @@ func (g *GORMCache[T]) DelMany(ctx context.Context, keys []string) error { Clauses(clause.Locking{Strength: clause.LockingStrengthUpdate}) return tx.Table(g.tableName).Where("? IN (?)", keyColumn, locked).Delete(nil).Error }); err != nil { - return errors.Wrap(err, "failed to delete cache entries") + for _, key := range chunk { + keyErrs[key] = errors.Wrapf(err, "failed to delete cache entry for key: %s", key) + } } } - return nil + return batchError(keyErrs) } diff --git a/gorm_test.go b/gorm_test.go index 31873ae..702a8e2 100644 --- a/gorm_test.go +++ b/gorm_test.go @@ -16,11 +16,16 @@ import ( ) func newGORMCache[T any](tb testing.TB, tableName string) (*GORMCache[T], *gorm.DB) { + return newGORMCacheWith[T](tb, tableName, 0) +} + +func newGORMCacheWith[T any](tb testing.TB, tableName string, chunkSize int) (*GORMCache[T], *gorm.DB) { db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{}) require.NoError(tb, err) cache := NewGORMCache[T](&GORMCacheConfig{ DB: db, TableName: tableName, + ChunkSize: chunkSize, }) require.NoError(tb, cache.Migrate(context.Background())) return cache, db diff --git a/redis.go b/redis.go index df72629..2698cca 100644 --- a/redis.go +++ b/redis.go @@ -4,7 +4,8 @@ import ( "context" "encoding" "encoding/json" - stderrors "errors" + "maps" + "slices" "time" "github.com/pkg/errors" @@ -17,6 +18,7 @@ type RedisCache[T any] struct { keyPrefix string ttl time.Duration useBinary bool // true if T implements encoding.BinaryMarshaler and encoding.BinaryUnmarshaler + chunkSize int } var _ BatchCache[any] = &RedisCache[any]{} @@ -32,6 +34,11 @@ type RedisCacheConfig struct { // TTL is the time-to-live for cache entries // Zero means no expiration TTL time.Duration + + // ChunkSize is how many commands one pipeline of GetMany, SetMany or + // DelMany carries; a larger call is sent as several pipelines, one after + // another. Zero means DefaultChunkSize. + ChunkSize int } // NewRedisCache creates a new Redis-based cache with configuration @@ -58,6 +65,7 @@ func NewRedisCache[T any](config *RedisCacheConfig) *RedisCache[T] { keyPrefix: config.KeyPrefix, ttl: config.TTL, useBinary: useBinary, + chunkSize: chunkSizeOr(config.ChunkSize, DefaultChunkSize), } } @@ -161,89 +169,108 @@ func (r *RedisCache[T]) Del(ctx context.Context, key string) error { return nil } -// GetMany retrieves many values in one round trip (a pipeline of GETs, which, -// unlike MGET, also works across slots on Redis Cluster). -// Missing keys are absent from the result; a value that fails to decode is -// reported in a *BatchError without hiding the others. -func (r *RedisCache[T]) GetMany(ctx context.Context, keys []string) (map[string]T, error) { - out := make(map[string]T, len(keys)) - if len(keys) == 0 { - return out, nil +// execPipe runs a pipeline so that every command carries its own outcome. +// Exec returns only the first failed command's error. Errors replied by Redis +// are already set on their commands, but commands never sent (e.g. the +// connection could not be made) carry no error, and a GET would read as an +// empty value: set the pipeline's error on them. +func execPipe(ctx context.Context, pipe redis.Pipeliner) { + cmds, err := pipe.Exec(ctx) + var replied redis.Error + if err == nil || errors.As(err, &replied) { + return } - - pipe := r.client.Pipeline() - cmds := make([]*redis.StringCmd, len(keys)) - for i, key := range keys { - cmds[i] = pipe.Get(ctx, r.prefixedKey(key)) + for _, cmd := range cmds { + if cmd.Err() == nil { + cmd.SetErr(err) + } } - // Exec reports only the first failed command; every command carries its own - // error (a connection failure is set on all of them), so read them per key. - _, _ = pipe.Exec(ctx) +} - var keyErrs map[string]error - for i, key := range keys { - err := cmds[i].Err() - if errors.Is(err, redis.Nil) { - continue - } - var value T - if err == nil { - value, err = r.decode(key, cmds[i]) - } else { - err = r.handleRedisError(err, key) +// GetMany retrieves many values with pipelines of GETs (which, unlike MGET, +// also work across slots on Redis Cluster), ChunkSize keys each. +// Missing keys are absent from the result; a key that fails (to be read or +// decoded) is reported in a *BatchError without hiding the others. +func (r *RedisCache[T]) GetMany(ctx context.Context, keys []string) (map[string]T, error) { + out := make(map[string]T, len(keys)) + keyErrs := map[string]error{} + for chunk := range slices.Chunk(keys, r.chunkSize) { + pipe := r.client.Pipeline() + cmds := make([]*redis.StringCmd, len(chunk)) + for i, key := range chunk { + cmds[i] = pipe.Get(ctx, r.prefixedKey(key)) } - if err != nil { - if keyErrs == nil { - keyErrs = map[string]error{} + execPipe(ctx, pipe) + + for i, key := range chunk { + err := cmds[i].Err() + if errors.Is(err, redis.Nil) { + continue } - keyErrs[key] = err - continue + var value T + if err == nil { + value, err = r.decode(key, cmds[i]) + } else { + err = r.handleRedisError(err, key) + } + if err != nil { + keyErrs[key] = err + continue + } + out[key] = value } - out[key] = value } - if keyErrs != nil { - return out, &BatchError{Errors: keyErrs} - } - return out, nil + return out, batchError(keyErrs) } -// SetMany stores many values in one round trip (a pipeline of SETs with the configured TTL) +// SetMany stores many values with pipelines of SETs (with the configured TTL), +// ChunkSize keys each. It is best effort: every key is tried, and the keys that +// failed (to be encoded or written) are reported in a *BatchError. func (r *RedisCache[T]) SetMany(ctx context.Context, values map[string]T) error { - if len(values) == 0 { - return nil - } - - // A value that fails to encode is reported without holding back the others. - var encodeErrs []error - pipe := r.client.Pipeline() - for key, value := range values { - data, err := r.encode(key, value) - if err != nil { - encodeErrs = append(encodeErrs, err) + keyErrs := map[string]error{} + for chunk := range slices.Chunk(slices.Collect(maps.Keys(values)), r.chunkSize) { + pipe := r.client.Pipeline() + sent := make([]string, 0, len(chunk)) + cmds := make([]*redis.StatusCmd, 0, len(chunk)) + for _, key := range chunk { + data, err := r.encode(key, values[key]) + if err != nil { + keyErrs[key] = err + continue + } + sent = append(sent, key) + cmds = append(cmds, pipe.Set(ctx, r.prefixedKey(key), data, r.ttl)) + } + if len(cmds) == 0 { continue } - pipe.Set(ctx, r.prefixedKey(key), data, r.ttl) - } - if pipe.Len() > 0 { - if _, err := pipe.Exec(ctx); err != nil { - return errors.Wrap(err, "failed to set cache entries") + execPipe(ctx, pipe) + for i, cmd := range cmds { + if err := cmd.Err(); err != nil { + keyErrs[sent[i]] = errors.Wrapf(err, "failed to set cache entry for key: %s", sent[i]) + } } } - return stderrors.Join(encodeErrs...) + return batchError(keyErrs) } -// DelMany removes many keys in one round trip +// DelMany removes many keys with pipelines of DELs, ChunkSize keys each. It is +// best effort: every key is tried, and the keys that failed are reported in a +// *BatchError. func (r *RedisCache[T]) DelMany(ctx context.Context, keys []string) error { - if len(keys) == 0 { - return nil - } - - pipe := r.client.Pipeline() - for _, key := range keys { - pipe.Del(ctx, r.prefixedKey(key)) - } - if _, err := pipe.Exec(ctx); err != nil { - return errors.Wrap(err, "failed to delete cache entries") + keyErrs := map[string]error{} + for chunk := range slices.Chunk(keys, r.chunkSize) { + pipe := r.client.Pipeline() + cmds := make([]*redis.IntCmd, len(chunk)) + for i, key := range chunk { + cmds[i] = pipe.Del(ctx, r.prefixedKey(key)) + } + execPipe(ctx, pipe) + for i, cmd := range cmds { + if err := cmd.Err(); err != nil { + keyErrs[chunk[i]] = errors.Wrapf(err, "failed to delete cache entry for key: %s", chunk[i]) + } + } } - return nil + return batchError(keyErrs) } diff --git a/types.go b/types.go index 9961e1e..526c8d4 100644 --- a/types.go +++ b/types.go @@ -51,6 +51,9 @@ type BatchUpstream[T any] interface { // cache when available, and falls back to Get/Set/Del per key otherwise. // Its GetMany follows the BatchUpstream contract: missing keys are absent, and // a whole-batch error is a failure of every key, not a batch of misses. +// SetMany and DelMany are best effort: they apply every key they can, and +// report the keys that failed in a *BatchError returned as is; any other error +// means it is unknown which keys were applied. type BatchCache[T any] interface { Cache[T] BatchUpstream[T] From 97c294a32e02e98a7167cc73ebda88f29d2b1812 Mon Sep 17 00:00:00 2001 From: molon <3739161+molon@users.noreply.github.com> Date: Sat, 10 Oct 2026 03:14:09 +0800 Subject: [PATCH 29/40] fix: answer every waiter when the upstream exits, and detach a claimed fetch from its leader's cancellation - A fetch whose upstream calls runtime.Goexit now publishes an error to every waiter, single-key or batch, as a panic already did. Before, waiters (like x/sync's DoChan, golang/go#52557) waited for their own ctx, forever without a deadline. One helper publishes each claimed flight exactly once, for Get and GetMany alike. - The batch serve-stale refresh no longer bounds its wait: every fetch now answers its waiters. - A claimed fetch serves every waiter of the key, so it runs on the leader's ctx without its cancellation (values kept) and without its GORM transaction. Before, a leader that gave up failed the double-check and fetched again although the cache had the value, and a GORM write-back ran inside the leader's transaction. The double-check is bounded by the fetch timeout. --- batch.go | 194 +++++++++++++++++++++++++-------------------- batch_test.go | 16 ++-- client.go | 46 +++++------ client_test.go | 47 +++++++++++ get_compat_test.go | 9 +-- gorm.go | 9 +++ 6 files changed, 191 insertions(+), 130 deletions(-) diff --git a/batch.go b/batch.go index 777ee76..9c5e4e8 100644 --- a/batch.go +++ b/batch.go @@ -3,6 +3,7 @@ package cachex import ( "context" stderrors "errors" + "log/slog" "runtime/debug" "sync" "time" @@ -70,6 +71,66 @@ func (g *flightGroup[T]) forget(sfKey string, f *flight[T]) { } } +// claimed are flights one request has claimed. Each gets exactly one result, +// published as soon as it is known; run makes sure an upstream that panics or +// calls runtime.Goexit still answers every waiter, with an error. +type claimed[T any] struct { + c *Client[T] + keys []string + sfKeys []string + flights []*flight[T] + mu sync.Mutex + done []bool +} + +func (c *Client[T]) claimedFlights(keys, sfKeys []string, flights []*flight[T]) *claimed[T] { + return &claimed[T]{c: c, keys: keys, sfKeys: sfKeys, flights: flights, done: make([]bool, len(keys))} +} + +// publish answers the waiters of flight i, once. +func (p *claimed[T]) publish(i int, r result[T]) { + p.mu.Lock() + defer p.mu.Unlock() + if p.done[i] { + return + } + p.done[i] = true + p.c.flights.finish(p.sfKeys[i], p.flights[i], r.value, r.err) +} + +// run runs body, which fetches flights idxs, and publishes an error for each +// of them still unanswered if body panics or calls runtime.Goexit. +func (p *claimed[T]) run(ctx context.Context, idxs []int, body func()) { + returned := false + defer func() { + var err error + if r := recover(); r != nil { + keys := make([]string, len(idxs)) + for j, i := range idxs { + keys[j] = p.keys[i] + } + attr := slog.Any("keys", keys) + if len(keys) == 1 { + attr = slog.String("key", keys[0]) + } + p.c.logger.ErrorContext(ctx, "panic during upstream fetch", + attr, + "panic", r, + "stack", string(debug.Stack())) + err = errors.Errorf("panic during upstream fetch: %v", r) + } else if !returned { + err = errors.New("upstream fetch exited without returning (runtime.Goexit)") + } + if err != nil { + for _, i := range idxs { + p.publish(i, result[T]{err: err}) + } + } + }() + body() + returned = true +} + type result[T any] struct { value T err error @@ -266,7 +327,7 @@ func (c *Client[T]) fetchMany(ctx context.Context, keys, sfKeys []string) []resu } } if len(ownKeys) > 0 { - go c.fetchClaimedMany(ctx, ownKeys, ownSFKeys, ownFlights) + go c.fetchClaimedMany(flightCtx(ctx), ownKeys, ownSFKeys, ownFlights) } results := make([]result[T], len(keys)) @@ -313,86 +374,55 @@ func (c *Client[T]) fetchEach(ctx context.Context, keys, sfKeys []string) []resu } // fetchClaimedMany is the batch form of fetchClaimed for a BatchUpstream: -// double-check, then fetch what is still missing, then finish every flight. +// double-check, then fetch what is still missing; every flight is answered as +// soon as its result is known. func (c *Client[T]) fetchClaimedMany(ctx context.Context, keys, sfKeys []string, flights []*flight[T]) { - results := make([]result[T], len(keys)) - var pending []int // keys still to fetch after the double-check; nil until it ran - returned := false - defer func() { - r := recover() - if r == nil && !returned { - // runtime.Goexit in the upstream: release the keys without - // publishing, like Get; waiters wait for their ctx. - for i, f := range flights { - c.flights.forget(sfKeys[i], f) - } - return - } - if r != nil { - c.logger.ErrorContext(ctx, "panic during upstream fetch", - "keys", keys, - "panic", r, - "stack", string(debug.Stack())) - err := errors.Errorf("panic during upstream fetch: %v", r) - failed := pending - if failed == nil { - failed = make([]int, len(keys)) - for i := range failed { - failed[i] = i + p := c.claimedFlights(keys, sfKeys, flights) + all := make([]int, len(keys)) + for i := range all { + all[i] = i + } + p.run(ctx, all, func() { + pending := all + if c.enableDoubleCheck { + pending = nil + checkCtx, cancel := context.WithTimeout(ctx, c.fetchTimeout) + lookups := c.lookupMany(checkCtx, keys, true) + cancel() + for i, r := range lookups { + switch { + case r.fetch: + pending = append(pending, i) + case r.err == nil: + p.publish(i, result[T]{value: r.value}) + case isCachedFreshNotFound(r.err): + p.publish(i, result[T]{err: r.err}) + default: + pending = append(pending, i) // like Get: a failed double-check falls through to upstream } } - for _, i := range failed { - results[i] = result[T]{err: err} - } } - for i, f := range flights { - c.flights.finish(sfKeys[i], f, results[i].value, results[i].err) + if len(pending) == 0 { + return } - }() - checked := make([]int, 0, len(keys)) - if c.enableDoubleCheck { - // like Get, the double-check reads with the request ctx - for i, r := range c.lookupMany(ctx, keys, true) { - switch { - case r.fetch: - checked = append(checked, i) - case r.err == nil: - results[i].value = r.value - case isCachedFreshNotFound(r.err): - results[i].err = r.err - default: - checked = append(checked, i) // like Get: a failed double-check falls through to upstream - } + pendingKeys := make([]string, len(pending)) + for j, i := range pending { + pendingKeys[j] = keys[i] } - } else { - for i := range keys { - checked = append(checked, i) + // like Get, the fetch timeout starts after the double-check. A Client below + // bounds each of its own fetches, so its batch is not bounded as one fetch: + // keys still queued there would fail with this deadline, not their own. + timeout := c.fetchTimeout + if lower, layered := c.upstream.(*Client[T]); layered { + timeout += lower.batchTimeout(len(pendingKeys)) } - } - pending = checked - if len(pending) == 0 { - returned = true - return - } - - pendingKeys := make([]string, len(pending)) - for j, i := range pending { - pendingKeys[j] = keys[i] - } - // like Get, the fetch timeout starts after the double-check. A Client below - // bounds each of its own fetches, so its batch is not bounded as one fetch: - // keys still queued there would fail with this deadline, not their own. - timeout := c.fetchTimeout - if lower, layered := c.upstream.(*Client[T]); layered { - timeout += lower.batchTimeout(len(pendingKeys)) - } - fetchCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), timeout) - defer cancel() - for j, r := range c.doFetchMany(fetchCtx, pendingKeys) { - results[pending[j]] = r - } - returned = true + fetchCtx, cancel := context.WithTimeout(ctx, timeout) + defer cancel() + for j, r := range c.doFetchMany(fetchCtx, pendingKeys) { + p.publish(pending[j], r) + } + }) } // batchTimeout is how long a GetMany of n keys sent to this Client as an @@ -538,22 +568,10 @@ func (c *Client[T]) asyncRefreshMany(ctx context.Context, keys []string) { c.asyncRefreshing.Delete(sfKey) } }() - if _, ok := c.upstream.(BatchUpstream[T]); ok { - // Bound the wait: some keys may be fetched by other callers, and a - // fetch that never finishes (runtime.Goexit) must not pin the whole - // batch. Keys key by key need no bound: each has its own fetch - // timeout, as in Get's refresh. - var cancel context.CancelFunc - ctx, cancel = context.WithTimeout(ctx, c.fetchTimeout) - defer cancel() - } + // every fetch answers its waiters (bounded by its fetch timeout, and with + // an error if it panics or exits), so this wait needs no bound of its own for i, r := range c.fetchMany(ctx, refreshKeys, sfKeys) { - switch { - case r.err == nil || IsErrKeyNotFound(r.err): - case ctx.Err() != nil && stderrors.Is(r.err, ctx.Err()): - // no longer waited for; it may still finish (or fail) on its own - c.logger.WarnContext(ctx, "async refresh not finished within the fetch timeout", "key", refreshKeys[i]) - default: + if r.err != nil && !IsErrKeyNotFound(r.err) { c.logger.ErrorContext(ctx, "async refresh failed", "key", refreshKeys[i], "error", r.err) } } diff --git a/batch_test.go b/batch_test.go index 5dd2764..dbe3635 100644 --- a/batch_test.go +++ b/batch_test.go @@ -615,7 +615,7 @@ func BenchmarkGetManyVsGet(b *testing.B) { } func TestClientGetManyUpstreamGoexit(t *testing.T) { - t.Run("batch upstream: the claims are released like Get", func(t *testing.T) { + t.Run("batch upstream: every claimed key gets the failure, like Get", func(t *testing.T) { var calls atomic.Int64 up := batchUpstreamFunc[string](func(_ context.Context, keys []string) (map[string]string, error) { if calls.Add(1) == 1 { @@ -625,10 +625,10 @@ func TestClientGetManyUpstreamGoexit(t *testing.T) { }) cli := NewClient(NewSyncMap[string](), up) - ctx, cancel := context.WithTimeout(context.Background(), 50*time.Millisecond) - defer cancel() - _, err := cli.GetMany(ctx, []string{"a"}) - assert.ErrorIs(t, err, context.DeadlineExceeded) + _, err := cli.GetMany(context.Background(), []string{"a"}) // no deadline: must not hang + var be *BatchError + require.ErrorAs(t, err, &be) + assert.Equal(t, "upstream fetch exited without returning (runtime.Goexit)", be.Errors["a"].Error()) ctx2, cancel2 := context.WithTimeout(context.Background(), time.Second) defer cancel2() @@ -646,13 +646,11 @@ func TestClientGetManyUpstreamGoexit(t *testing.T) { return "v-" + key, nil })) - ctx, cancel := context.WithTimeout(context.Background(), 50*time.Millisecond) - defer cancel() - got, err := cli.GetMany(ctx, []string{"a", "bad"}) + got, err := cli.GetMany(context.Background(), []string{"a", "bad"}) assert.Equal(t, map[string]string{"a": "v-a"}, got) var be *BatchError require.ErrorAs(t, err, &be) - assert.ErrorIs(t, be.Errors["bad"], context.DeadlineExceeded, "waiters wait for their ctx, like Get") + assert.Equal(t, "upstream fetch exited without returning (runtime.Goexit)", be.Errors["bad"].Error()) _, err = backend.Get(context.Background(), "bad") assert.True(t, IsErrKeyNotFound(err), "nothing is written for the key") }) diff --git a/client.go b/client.go index 6e57407..3a9d46c 100644 --- a/client.go +++ b/client.go @@ -7,7 +7,6 @@ import ( "hash/maphash" "log/slog" "math/rand/v2" - "runtime/debug" "sync" "sync/atomic" "time" @@ -433,7 +432,7 @@ func (c *Client[T]) fetchFromUpstreamWithSFKey(ctx context.Context, key string, f, leader := c.flights.claim(sfKey) if leader { - go c.runClaimed(ctx, key, sfKey, f) + go c.runClaimed(flightCtx(ctx), key, sfKey, f) } select { @@ -450,39 +449,28 @@ func (c *Client[T]) fetchFromUpstreamWithSFKey(ctx context.Context, key string, } } +// flightCtx is the ctx of a fetch claimed by one request but awaited by every +// request of the key: it keeps ctx's values (tracing, etc.) but not its +// cancellation, which belongs to that one request, nor its GORM transaction. +func flightCtx(ctx context.Context) context.Context { + return withoutGORMTx(context.WithoutCancel(ctx)) +} + // runClaimed fetches a key this request has claimed and publishes the result. func (c *Client[T]) runClaimed(ctx context.Context, key, sfKey string, f *flight[T]) { - returned := false - defer func() { - if !returned { - // runtime.Goexit in the upstream: release the key without - // publishing, like x/sync/singleflight; waiters wait for their ctx. - c.flights.forget(sfKey, f) - } - }() - value, err := c.fetchClaimed(ctx, key) - returned = true - c.flights.finish(sfKey, f, value, err) + p := c.claimedFlights([]string{key}, []string{sfKey}, []*flight[T]{f}) + p.run(ctx, []int{0}, func() { + value, err := c.fetchClaimed(ctx, key) + p.publish(0, result[T]{value: value, err: err}) + }) } // fetchClaimed fetches a key this request has claimed in the flight group. -func (c *Client[T]) fetchClaimed(ctx context.Context, key string) (result T, resultErr error) { +func (c *Client[T]) fetchClaimed(ctx context.Context, key string) (T, error) { if c.testHooks != nil && c.testHooks.afterSingleflightStart != nil { c.testHooks.afterSingleflightStart(ctx, key) } - defer func() { - if r := recover(); r != nil { - c.logger.ErrorContext(ctx, "panic during upstream fetch", - "key", key, - "panic", r, - "stack", string(debug.Stack())) - var zero T - result = zero - resultErr = errors.Errorf("panic during upstream fetch: %v", r) - } - }() - // Double-check optimization: check cache again before fetching from upstream // This handles the narrow window after a write completes but before singleflight releases // @@ -491,7 +479,9 @@ func (c *Client[T]) fetchClaimed(ctx context.Context, key string) (result T, res // 2. Once ANY slot completes, ALL slots should converge to reuse that result (convergence phase) // 3. Using key ensures cross-slot visibility, maximizing result reuse after first completion if c.enableDoubleCheck { - cachedValue, err := c.get(ctx, key, true) + checkCtx, cancel := context.WithTimeout(ctx, c.fetchTimeout) + cachedValue, err := c.get(checkCtx, key, true) + cancel() if err == nil { return cachedValue, nil @@ -503,7 +493,7 @@ func (c *Client[T]) fetchClaimed(ctx context.Context, key string) (result T, res // otherwise, fetch from upstream } - fetchCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), c.fetchTimeout) + fetchCtx, cancel := context.WithTimeout(ctx, c.fetchTimeout) defer cancel() return c.doFetch(fetchCtx, key) } diff --git a/client_test.go b/client_test.go index 03f9162..91d1d08 100644 --- a/client_test.go +++ b/client_test.go @@ -12,6 +12,7 @@ import ( "github.com/pkg/errors" "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" + "gorm.io/gorm" ) func TestClientBasics(t *testing.T) { @@ -875,3 +876,49 @@ func waitAsyncRefreshDone[T any](t *testing.T, cli *Client[T]) { return idle }, time.Second, time.Millisecond, "background refresh should finish") } + +func TestFetchIsDetachedFromTheLeader(t *testing.T) { + t.Run("a leader that gives up does not fail the double-check for the others", func(t *testing.T) { + backend := ctxCache{NewSyncMap[string]()} // refuses a done ctx, like Redis or GORM + var calls atomic.Int32 + cli := NewClient[string](ctxGetCache{backend}, UpstreamFunc[string](func(context.Context, string) (string, error) { + calls.Add(1) + return "from-upstream", nil + }), WithDoubleCheck[string](DoubleCheckEnabled)) + leaderCtx, cancel := context.WithCancel(context.Background()) + cli.testHooks = &testHooks{afterSingleflightStart: func(context.Context, string) { + // between the leader's miss and its double-check: another request + // filled the cache, and the leader's caller gave up + _ = backend.Set(context.Background(), "k", "filled-meanwhile") + cancel() + }} + _, _ = cli.Get(leaderCtx, "k") + require.Eventually(t, func() bool { + v, err := backend.Get(context.Background(), "k") + return err == nil && v == "filled-meanwhile" + }, time.Second, time.Millisecond) + time.Sleep(20 * time.Millisecond) // let a wrongly started fetch show up + assert.Zero(t, calls.Load(), "the double-check ran with the flight's ctx, found the value, and skipped the upstream") + }) + + t.Run("the fetch does not run in the leader's GORM transaction", func(t *testing.T) { + var sawTx atomic.Bool + cli := NewClient[string](NewSyncMap[string](), UpstreamFunc[string](func(ctx context.Context, _ string) (string, error) { + sawTx.Store(GetGORMTx(ctx) != nil) + return "v", nil + })) + _, err := cli.Get(WithGORMTx(context.Background(), &gorm.DB{}), "k") + require.NoError(t, err) + assert.False(t, sawTx.Load(), "the fetch serves every waiter, so it must not write inside one caller's transaction") + }) +} + +// ctxGetCache is a cache whose Get refuses a done ctx, like Redis or GORM. +type ctxGetCache struct{ ctxCache } + +func (c ctxGetCache) Get(ctx context.Context, key string) (string, error) { + if err := ctx.Err(); err != nil { + return "", err + } + return c.SyncMap.Get(ctx, key) +} diff --git a/get_compat_test.go b/get_compat_test.go index 1fa79de..7b97cc9 100644 --- a/get_compat_test.go +++ b/get_compat_test.go @@ -185,12 +185,11 @@ func TestGetCompatUpstreamGoexit(t *testing.T) { return "ok", nil })) - ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond) - defer cancel() - _, err := cli.Get(ctx, "k") + // unlike main (x/sync's DoChan never answered its waiters then), the fetch + // publishes an error, so a waiter without a deadline does not hang + _, err := cli.Get(context.Background(), "k") require.Error(t, err) - assert.ErrorIs(t, err, context.DeadlineExceeded, "a fetch that exits without returning publishes nothing; waiters wait for their ctx") - assert.Equal(t, "context cancelled during fetch for key: k: context deadline exceeded", err.Error()) + assert.Equal(t, "upstream fetch exited without returning (runtime.Goexit)", err.Error()) ctx2, cancel2 := context.WithTimeout(context.Background(), time.Second) defer cancel2() diff --git a/gorm.go b/gorm.go index efa35e9..7f23b0c 100644 --- a/gorm.go +++ b/gorm.go @@ -154,6 +154,15 @@ func WithGORMTx(ctx context.Context, tx *gorm.DB) context.Context { return context.WithValue(ctx, ctxKeyGORMTx{}, tx) } +// withoutGORMTx hides ctx's GORM transaction: a fetch shared by every waiter +// must not write inside one caller's transaction. +func withoutGORMTx(ctx context.Context) context.Context { + if GetGORMTx(ctx) == nil { + return ctx + } + return context.WithValue(ctx, ctxKeyGORMTx{}, (*gorm.DB)(nil)) +} + // GetGORMTx retrieves the GORM transaction from the context. // Returns nil if no transaction is attached to the context. func GetGORMTx(ctx context.Context) *gorm.DB { From bf787dea6646f81d2c2afe1f9b85d0c8fbff1f2d Mon Sep 17 00:00:00 2001 From: molon <3739161+molon@users.noreply.github.com> Date: Sat, 10 Oct 2026 03:18:34 +0800 Subject: [PATCH 30/40] feat: WithGetManyChunkSize splits BatchUpstream calls, and WithGetManyFetchConcurrency bounds one GetMany's upstream requests - WithGetManyChunkSize(n) sends the keys one GetMany fetches from a BatchUpstream in calls of at most n keys, run concurrently; each call's keys are answered as soon as it returns, and a panic or exit fails only that call's keys. Zero (default) keeps one call. - WithGetManyConcurrency is renamed WithGetManyFetchConcurrency (and its default DefaultGetManyFetchConcurrency): it bounds the upstream requests one GetMany has in flight, per-key Gets or chunk calls alike, as opposed to WithFetchConcurrency, which bounds the fetches of one key. - A lower Client's budget accounts for its chunking. --- README.md | 2 +- README_ZH.md | 2 +- batch.go | 70 ++++++++++++++++++++++++++++----------------- batch_test.go | 78 +++++++++++++++++++++++++++++++++++++++++++++------ client.go | 38 +++++++++++++++++-------- 5 files changed, 143 insertions(+), 47 deletions(-) diff --git a/README.md b/README.md index 5c3d2f0..596bbe4 100644 --- a/README.md +++ b/README.md @@ -422,7 +422,7 @@ How `GetMany` works: 2. **Not-Found cache**: misses are checked against it, exactly like `Get`. 3. **Singleflight**: every key that needs the upstream is claimed in the **same** singleflight `Get` uses. Keys already being fetched by a `Get` or another `GetMany` are waited for, not fetched again; so a `Get` and a `GetMany` (or two overlapping `GetMany`s) fetch a shared key only once. `WithFetchConcurrency` applies per key as usual. 4. **DoubleCheck**: the claimed keys are re-checked against the backend and Not-Found cache, by the same rules as `Get`. -5. **Upstream**: if the upstream implements `BatchUpstream[T]`, the remaining keys are fetched with **one** `GetMany` call (one `WithFetchTimeout` for the whole call; over a lower `Client`, as long as that `Client`'s own fetches may take, e.g. a queue of per-key fetch timeouts). The keys of one call are answered together: a concurrent `Get` of one of them joins the call and waits for all of it. Otherwise each key is fetched exactly as `Get` would (its own double-check, fetch timeout and write-back, and handed to its waiters as soon as it arrives), at most `WithGetManyConcurrency` (default 16) at a time; a key is claimed only when its turn comes, so a concurrent `Get` of a key still queued here does not wait for the queue, and a canceled `GetMany` starts no more keys. +5. **Upstream**: if the upstream implements `BatchUpstream[T]`, the remaining keys are fetched with **one** `GetMany` call, or, with `WithGetManyChunkSize(n)`, with calls of at most `n` keys run concurrently (useful when the upstream limits its batch size). Each call has one `WithFetchTimeout` (over a lower `Client`, as long as that `Client`'s own fetches may take, e.g. a queue of per-key fetch timeouts). The keys of one call are answered together, as soon as it returns: a concurrent `Get` of one of them joins the call and waits for it. Otherwise each key is fetched exactly as `Get` would (its own double-check, fetch timeout and write-back, and handed to its waiters as soon as it arrives), at most `WithGetManyFetchConcurrency` (default 16) at a time. The same option bounds the concurrent chunk calls above, so it reads as "upstream requests one `GetMany` has in flight" (`WithFetchConcurrency`, by contrast, bounds the fetches of one key). A key is claimed only when its turn comes, so a concurrent `Get` of a key still queued here does not wait for the queue, and a canceled `GetMany` starts no more keys. 6. **Write back**: found values go to the backend, missing keys to the Not-Found cache. With a `BatchUpstream` this is one `SetMany`/`DelMany` per batch (when the backend supports it); without one, each key is written back on its own, like `Get`. Either way this only touches this layer, never the upstream. `Client` implements `BatchUpstream[T]` itself, so in a layered setup a batch travels down as one call per layer: `l1Client.GetMany` → L1 batch read → `l2Client.GetMany` → L2 batch read → one database query. diff --git a/README_ZH.md b/README_ZH.md index 96a0e86..708d3dd 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -420,7 +420,7 @@ client := cachex.NewClient(cache, productSource{db: db} /* , options as in Quick 2. **Not-Found 缓存**:未命中的先查它,和 `Get` 一样。 3. **Singleflight**:每个要回源的 key 都在和 `Get` **同一个** singleflight 里认领。已经有 `Get` 或别的 `GetMany` 在取的 key,等那次的结果,不再取一遍;所以 `Get` 和 `GetMany`(或两个有交集的 `GetMany`)同时要同一个 key,只回源一次。`WithFetchConcurrency` 照旧按 key 生效。 4. **DoubleCheck**:认领到的 key 按和 `Get` 相同的规则再查一次后端和 Not-Found 缓存。 -5. **上游**:上游实现了 `BatchUpstream[T]`,剩下的 key 就调**一次** `GetMany`(整次调用共用一个 `WithFetchTimeout`;下层是 `Client` 时,上限放宽到下层自己的拉取最多可能用的时间,比如逐 key 排队时按轮数累加的超时)。同一次调用里的 key 一起返回:并发 `Get` 其中某个 key 会加入这次调用,等它整个结束。否则每个 key 都和 `Get` 完全一样地拉取(各自 double check、各自超时、各自回填,拉到就交给等它的调用方),同时最多 `WithGetManyConcurrency` 个(默认 16);每个 key 轮到时才认领,所以并发的 `Get` 碰上还在这里排队的 key 不用等整个队列,`GetMany` 被取消后也不再开始新的 key。 +5. **上游**:上游实现了 `BatchUpstream[T]`,剩下的 key 就调**一次** `GetMany`;设了 `WithGetManyChunkSize(n)` 时,切成每次最多 `n` 个 key 的多次调用并发执行(适合上游限制了批量大小的情况)。每次调用共用一个 `WithFetchTimeout`(下层是 `Client` 时,上限放宽到下层自己的拉取最多可能用的时间,比如逐 key 排队时按轮数累加的超时)。同一次调用里的 key 在这次调用返回时一起返回:并发 `Get` 其中某个 key 会加入这次调用,等它结束。否则每个 key 都和 `Get` 完全一样地拉取(各自 double check、各自超时、各自回填,拉到就交给等它的调用方),同时最多 `WithGetManyFetchConcurrency` 个(默认 16)。上面分批调用的并发数也由它限制,所以它的含义是「一次 `GetMany` 同时向上游发出的请求数」(相比之下,`WithFetchConcurrency` 限制的是同一个 key 的并发回源数);每个 key 轮到时才认领,所以并发的 `Get` 碰上还在这里排队的 key 不用等整个队列,`GetMany` 被取消后也不再开始新的 key。 6. **回填**:取到的值写回后端,不存在的 key 写进 Not-Found 缓存。上游实现了 `BatchUpstream` 时,一批只调一次 `SetMany`/`DelMany`(后端支持的话);否则每个 key 各自回填,和 `Get` 一样。两种情况都只写本层,不写上游。 `Client` 自己也实现了 `BatchUpstream[T]`,所以多层缓存时一批 key 每层只走一次调用:`l1Client.GetMany` → L1 批量读 → `l2Client.GetMany` → L2 批量读 → 一次数据库查询。 diff --git a/batch.go b/batch.go index 9c5e4e8..a21627f 100644 --- a/batch.go +++ b/batch.go @@ -1,10 +1,12 @@ package cachex import ( + "cmp" "context" stderrors "errors" "log/slog" "runtime/debug" + "slices" "sync" "time" @@ -150,7 +152,7 @@ type result[T any] struct { // BatchUpstream, the keys this call claims are double-checked // (WithDoubleCheck) and fetched together with one upstream.GetMany under // one fetch timeout. Otherwise each key is fetched exactly as Get would -// (claimed only when its turn comes), at most WithGetManyConcurrency at a +// (claimed only when its turn comes), at most WithGetManyFetchConcurrency at a // time, and a canceled GetMany starts no more keys. // - Fetched values are written to the backend and not-found keys to the // not-found cache, without touching the upstream, exactly like Get: in @@ -406,39 +408,55 @@ func (c *Client[T]) fetchClaimedMany(ctx context.Context, keys, sfKeys []string, return } - pendingKeys := make([]string, len(pending)) - for j, i := range pending { - pendingKeys[j] = keys[i] - } - // like Get, the fetch timeout starts after the double-check. A Client below - // bounds each of its own fetches, so its batch is not bounded as one fetch: - // keys still queued there would fail with this deadline, not their own. - timeout := c.fetchTimeout - if lower, layered := c.upstream.(*Client[T]); layered { - timeout += lower.batchTimeout(len(pendingKeys)) - } - fetchCtx, cancel := context.WithTimeout(ctx, timeout) - defer cancel() - for j, r := range c.doFetchMany(fetchCtx, pendingKeys) { - p.publish(pending[j], r) + // one call per chunk, getManyConc at a time; each answers its keys + var wg sync.WaitGroup + sem := make(chan struct{}, c.getManyConc) + for chunk := range slices.Chunk(pending, cmp.Or(c.getManyChunk, len(pending))) { + sem <- struct{}{} + wg.Go(func() { + defer func() { <-sem }() + p.run(ctx, chunk, func() { c.fetchChunk(ctx, p, chunk) }) + }) } + wg.Wait() }) } +// fetchChunk fetches the claimed flights idxs with one upstream.GetMany. +func (c *Client[T]) fetchChunk(ctx context.Context, p *claimed[T], idxs []int) { + keys := make([]string, len(idxs)) + for j, i := range idxs { + keys[j] = p.keys[i] + } + // like Get, the fetch timeout starts after the double-check. A Client below + // bounds each of its own fetches, so its call is not bounded as one fetch: + // keys still queued there would fail with this deadline, not their own. + timeout := c.fetchTimeout + if lower, layered := c.upstream.(*Client[T]); layered { + timeout += lower.batchTimeout(len(keys)) + } + fetchCtx, cancel := context.WithTimeout(ctx, timeout) + defer cancel() + for j, r := range c.doFetchMany(fetchCtx, keys) { + p.publish(idxs[j], r) + } +} + // batchTimeout is how long a GetMany of n keys sent to this Client as an // upstream may legitimately take: a fetch timeout for its own reads and -// write-back, plus its fetches (one batch, a lower Client's own budget, or a -// queue of per-key fetches, getManyConc at a time). +// write-back, plus its fetches: rounds of getManyConc calls at a time, each a +// fetch timeout (a lower Client's own budget per call), or per-key fetches. func (c *Client[T]) batchTimeout(n int) time.Duration { - switch up := c.upstream.(type) { - case *Client[T]: - return c.fetchTimeout + up.batchTimeout(n) - case BatchUpstream[T]: - return 2 * c.fetchTimeout - default: - rounds := (n + c.getManyConc - 1) / c.getManyConc - return c.fetchTimeout * time.Duration(1+rounds) + ceil := func(a, b int) int { return (a + b - 1) / b } + if _, ok := c.upstream.(BatchUpstream[T]); !ok { + return c.fetchTimeout * time.Duration(1+ceil(n, c.getManyConc)) + } + size := max(1, min(n, cmp.Or(c.getManyChunk, n))) + rounds := time.Duration(ceil(ceil(n, size), c.getManyConc)) + if lower, layered := c.upstream.(*Client[T]); layered { + return c.fetchTimeout + rounds*lower.batchTimeout(size) } + return c.fetchTimeout + rounds*c.fetchTimeout } // doFetchMany is the batch form of doFetch: fetch from the batch upstream, diff --git a/batch_test.go b/batch_test.go index dbe3635..08d7278 100644 --- a/batch_test.go +++ b/batch_test.go @@ -838,7 +838,7 @@ func TestClientGetManyPerKeyFallbackIsPerKey(t *testing.T) { } }) cli := NewClient[string](NewSyncMap[string](), up, - WithFetchTimeout[string](100*time.Millisecond), WithGetManyConcurrency[string](1)) + WithFetchTimeout[string](100*time.Millisecond), WithGetManyFetchConcurrency[string](1)) keys := make([]string, 10) for i := range keys { keys[i] = fmt.Sprintf("k%d", i) @@ -857,7 +857,7 @@ func TestClientGetManyPerKeyFallbackIsPerKey(t *testing.T) { } return "v-" + key, nil }) - cli := NewClient[string](NewSyncMap[string](), up, WithGetManyConcurrency[string](2)) + cli := NewClient[string](NewSyncMap[string](), up, WithGetManyFetchConcurrency[string](2)) done := make(chan struct{}) go func() { @@ -1013,7 +1013,7 @@ func TestClientGetManyPerKeyFallbackDoesNotQueueOthers(t *testing.T) { calls.Add(1) return "v-" + key, nil }) - cli := NewClient[string](NewSyncMap[string](), up, WithGetManyConcurrency[string](1)) + cli := NewClient[string](NewSyncMap[string](), up, WithGetManyFetchConcurrency[string](1)) done := make(chan struct{}) go func() { defer close(done) @@ -1040,7 +1040,7 @@ func TestClientGetManyPerKeyFallbackDoesNotQueueOthers(t *testing.T) { } return "v-" + key, nil }) - cli := NewClient[string](NewSyncMap[string](), up, WithGetManyConcurrency[string](1)) + cli := NewClient[string](NewSyncMap[string](), up, WithGetManyFetchConcurrency[string](1)) ctx, cancel := context.WithCancel(context.Background()) errc := make(chan error, 1) go func() { @@ -1080,7 +1080,7 @@ func TestClientGetManyRefreshOfManyKeysLogsNoFalseFailures(t *testing.T) { }), WithServeStale[string](true), WithFetchTimeout[string](100*time.Millisecond), // each key fits, the six together do not - WithGetManyConcurrency[string](1), + WithGetManyFetchConcurrency[string](1), WithLogger[string](slog.New(slog.NewTextHandler(&logBuf, nil)))) _, err := cli.GetMany(ctx, keys) @@ -1159,7 +1159,7 @@ func TestClientGetManyOverAClientIsNotBoundedAsOneFetch(t *testing.T) { time.Sleep(30 * time.Millisecond) return "v-" + key, nil }) - l2 := NewClient[string](NewSyncMap[string](), src, WithGetManyConcurrency[string](1)) + l2 := NewClient[string](NewSyncMap[string](), src, WithGetManyFetchConcurrency[string](1)) l1 := NewClient[string](NewSyncMap[string](), l2, WithFetchTimeout[string](100*time.Millisecond)) keys := []string{"k0", "k1", "k2", "k3", "k4", "k5", "k6", "k7"} got, err := l1.GetMany(context.Background(), keys) @@ -1363,7 +1363,7 @@ func (m *slowSecondBatch) GetMany(ctx context.Context, keys []string) (map[strin func TestClientGetManyReviewFixes2(t *testing.T) { ctx := context.Background() - t.Run("the per-key fallback fetches at most WithGetManyConcurrency keys at once", func(t *testing.T) { + t.Run("the per-key fallback fetches at most WithGetManyFetchConcurrency keys at once", func(t *testing.T) { var cur, peak atomic.Int64 up := UpstreamFunc[string](func(_ context.Context, key string) (string, error) { n := cur.Add(1) @@ -1377,7 +1377,7 @@ func TestClientGetManyReviewFixes2(t *testing.T) { cur.Add(-1) return key, nil }) - cli := NewClient[string](NewSyncMap[string](), up, WithGetManyConcurrency[string](4)) + cli := NewClient[string](NewSyncMap[string](), up, WithGetManyFetchConcurrency[string](4)) keys := make([]string, 50) for i := range keys { keys[i] = fmt.Sprintf("k%d", i) @@ -1559,3 +1559,65 @@ func TestRedisCacheGetManyWhenRedisIsDown(t *testing.T) { require.ErrorAs(t, err, &be) assert.ElementsMatch(t, []string{"a", "b"}, slices.Collect(maps.Keys(be.Errors))) } + +func TestClientGetManyChunksBatchUpstreamCalls(t *testing.T) { + ctx := context.Background() + keys := []string{"k0", "k1", "k2", "k3", "k4"} + + t.Run("calls carry at most the chunk size, at most the fetch concurrency at once", func(t *testing.T) { + var mu sync.Mutex + var sizes []int + var inFlight, peak atomic.Int32 + up := batchUpstreamFunc[string](func(_ context.Context, ks []string) (map[string]string, error) { + n := inFlight.Add(1) + for p := peak.Load(); n > p && !peak.CompareAndSwap(p, n); p = peak.Load() { + } + defer inFlight.Add(-1) + mu.Lock() + sizes = append(sizes, len(ks)) + mu.Unlock() + time.Sleep(20 * time.Millisecond) + out := map[string]string{} + for _, k := range ks { + out[k] = "v-" + k + } + return out, nil + }) + cli := NewClient[string](NewSyncMap[string](), up, + WithGetManyChunkSize[string](2), WithGetManyFetchConcurrency[string](2)) + got, err := cli.GetMany(ctx, keys) + require.NoError(t, err) + assert.Len(t, got, 5) + assert.ElementsMatch(t, []int{2, 2, 1}, sizes) + assert.Equal(t, int32(2), peak.Load()) + }) + + t.Run("a chunk's keys are answered as soon as the chunk is done", func(t *testing.T) { + release := make(chan struct{}) + up := batchUpstreamFunc[string](func(_ context.Context, ks []string) (map[string]string, error) { + if slices.Contains(ks, "k4") { + <-release // the last chunk hangs + } + out := map[string]string{} + for _, k := range ks { + out[k] = "v-" + k + } + return out, nil + }) + cli := NewClient[string](NewSyncMap[string](), up, + WithGetManyChunkSize[string](2), WithGetManyFetchConcurrency[string](3)) + done := make(chan struct{}) + go func() { + defer close(done) + _, _ = cli.GetMany(ctx, keys) + }() + getCtx, cancel := context.WithTimeout(ctx, time.Second) + defer cancel() + require.Eventually(t, func() bool { // k0 is claimed by the GetMany, then answered by its chunk + v, err := cli.Get(getCtx, "k0") + return err == nil && v == "v-k0" + }, time.Second, 5*time.Millisecond) + close(release) + <-done + }) +} diff --git a/client.go b/client.go index 3a9d46c..bebc35e 100644 --- a/client.go +++ b/client.go @@ -17,10 +17,10 @@ import ( var ( DefaultFetchTimeout = 60 * time.Second DefaultFetchConcurrency = 1 - // DefaultGetManyConcurrency bounds the concurrent upstream.Get calls of one - // GetMany when the upstream does not implement BatchUpstream. - DefaultGetManyConcurrency = 16 - NowFunc = time.Now + // DefaultGetManyFetchConcurrency bounds the upstream requests one GetMany + // has in flight at once (see WithGetManyFetchConcurrency). + DefaultGetManyFetchConcurrency = 16 + NowFunc = time.Now ) // Client manages cache operations with automatic upstream fetching @@ -36,6 +36,7 @@ type Client[T any] struct { fetchTimeout time.Duration fetchConcurrency int getManyConc int + getManyChunk int // keys per BatchUpstream call; 0 means all in one logger *slog.Logger flights flightGroup[T] @@ -73,7 +74,7 @@ func NewClient[T any](backend Cache[T], upstream Upstream[T], opts ...ClientOpti upstream: upstream, fetchTimeout: DefaultFetchTimeout, fetchConcurrency: DefaultFetchConcurrency, - getManyConc: DefaultGetManyConcurrency, + getManyConc: DefaultGetManyFetchConcurrency, logger: slog.Default(), doubleCheckMode: DoubleCheckAuto, // Default: auto (smart heuristic) writeSeed: maphash.MakeSeed(), @@ -93,8 +94,11 @@ func NewClient[T any](backend Cache[T], upstream Upstream[T], opts ...ClientOpti if c.fetchConcurrency <= 0 { panic("fetchConcurrency must be positive") } + if c.getManyChunk < 0 { + panic("getManyChunkSize must not be negative") + } if c.getManyConc <= 0 { - panic("getManyConcurrency must be positive") + panic("getManyFetchConcurrency must be positive") } return c @@ -628,16 +632,28 @@ func WithFetchConcurrency[T any](concurrency int) ClientOption[T] { } } -// WithGetManyConcurrency sets the maximum number of keys one GetMany fetches -// at a time when the upstream does not implement BatchUpstream (default -// DefaultGetManyConcurrency); each is fetched as Get would, with its own fetch -// timeout. It does not apply to a BatchUpstream, which gets one GetMany call. -func WithGetManyConcurrency[T any](concurrency int) ClientOption[T] { +// WithGetManyFetchConcurrency sets how many upstream requests one GetMany has +// in flight at once (default DefaultGetManyFetchConcurrency): upstream.Get +// calls when the upstream does not implement BatchUpstream (each key fetched as +// Get would), or chunks of a BatchUpstream call (see WithGetManyChunkSize). +// Unlike WithFetchConcurrency, which bounds the fetches of one key, this bounds +// the different keys (or chunks) of one GetMany. +func WithGetManyFetchConcurrency[T any](concurrency int) ClientOption[T] { return func(c *Client[T]) { c.getManyConc = concurrency } } +// WithGetManyChunkSize splits the keys one GetMany sends to a BatchUpstream into +// calls of at most size keys, run concurrently up to WithGetManyFetchConcurrency; +// the keys of a call are answered as soon as it returns. Zero (the default) +// sends them in one call. Use it when the upstream limits its batch size. +func WithGetManyChunkSize[T any](size int) ClientOption[T] { + return func(c *Client[T]) { + c.getManyChunk = size + } +} + // WithLogger sets the logger for the client. // If not set, slog.Default() is used. func WithLogger[T any](logger *slog.Logger) ClientOption[T] { From ce776c137a1b4cb74599211e526180ffa1fce534 Mon Sep 17 00:00:00 2001 From: molon <3739161+molon@users.noreply.github.com> Date: Sat, 10 Oct 2026 03:27:59 +0800 Subject: [PATCH 31/40] feat: DoubleCheckAuto re-reads only when this Client wrote the key's stripe since the lookup; 4096 write stripes - DoubleCheckAuto used to turn the double-check on only when a not-found cache was configured, which has little to do with when it pays off. Each stripe now also counts this Client's backfills; a request notes the count (with the write generation) before reading the layer, and a claimed fetch re-reads only if it changed. Measured with a hot key over a 1 ms cache: 19 upstream calls (Enabled 18, Disabled 30); over 8000 cold keys: 1.004 cache reads per Get (Enabled 2.0, Disabled 1.0). DoubleCheckEnabled and DoubleCheckDisabled keep their meaning. - writeStripeCount goes from 1024 to 4096: a quarter of the cross-key write waits, skipped backfills and needless re-reads, for 160 KB per Client. - Docs: what the double-check saves, measured, instead of "eliminates the race window". --- README.md | 11 +++---- README_ZH.md | 11 +++---- batch.go | 66 ++++++++++++++++++++++++++++++------------ client.go | 59 ++++++++++++++++++++----------------- double_check.go | 69 +++++++++++++++----------------------------- double_check_test.go | 57 ++++++++++++++++++++++++++---------- get_compat_test.go | 1 + 7 files changed, 158 insertions(+), 116 deletions(-) diff --git a/README.md b/README.md index 596bbe4..220184e 100644 --- a/README.md +++ b/README.md @@ -172,7 +172,7 @@ sequenceDiagram - **NotFoundCache** - Dedicated cache for non-existent keys to prevent cache penetration - **Upstream** - Data source (database, API, another Client, or custom) - **Singleflight** - Deduplicates concurrent requests for the same key (primary defense against cache stampede) -- **DoubleCheck** - Re-checks backend and notFoundCache before upstream fetch to catch concurrent writes (eliminates race window) +- **DoubleCheck** - After claiming a fetch, re-checks backend and notFoundCache to catch a value another request just wrote, instead of fetching it again - **Entry** - Wrapper with timestamp for time-based staleness checks ## Cache Backends @@ -421,7 +421,7 @@ How `GetMany` works: 1. **Backend**: one batch read (`BatchCache[T]`, otherwise key by key). Each value is classified by staleness: fresh values are returned, stale values are returned and refreshed in the background together (with `WithServeStale`), rotten values and misses go on. 2. **Not-Found cache**: misses are checked against it, exactly like `Get`. 3. **Singleflight**: every key that needs the upstream is claimed in the **same** singleflight `Get` uses. Keys already being fetched by a `Get` or another `GetMany` are waited for, not fetched again; so a `Get` and a `GetMany` (or two overlapping `GetMany`s) fetch a shared key only once. `WithFetchConcurrency` applies per key as usual. -4. **DoubleCheck**: the claimed keys are re-checked against the backend and Not-Found cache, by the same rules as `Get`. +4. **DoubleCheck**: the claimed keys are re-checked against the backend and Not-Found cache, by the same rules as `Get` (in the default `DoubleCheckAuto`, only the keys whose stripe this `Client` wrote since the lookup). 5. **Upstream**: if the upstream implements `BatchUpstream[T]`, the remaining keys are fetched with **one** `GetMany` call, or, with `WithGetManyChunkSize(n)`, with calls of at most `n` keys run concurrently (useful when the upstream limits its batch size). Each call has one `WithFetchTimeout` (over a lower `Client`, as long as that `Client`'s own fetches may take, e.g. a queue of per-key fetch timeouts). The keys of one call are answered together, as soon as it returns: a concurrent `Get` of one of them joins the call and waits for it. Otherwise each key is fetched exactly as `Get` would (its own double-check, fetch timeout and write-back, and handed to its waiters as soon as it arrives), at most `WithGetManyFetchConcurrency` (default 16) at a time. The same option bounds the concurrent chunk calls above, so it reads as "upstream requests one `GetMany` has in flight" (`WithFetchConcurrency`, by contrast, bounds the fetches of one key). A key is claimed only when its turn comes, so a concurrent `Get` of a key still queued here does not wait for the queue, and a canceled `GetMany` starts no more keys. 6. **Write back**: found values go to the backend, missing keys to the Not-Found cache. With a `BatchUpstream` this is one `SetMany`/`DelMany` per batch (when the backend supports it); without one, each key is written back on its own, like `Get`. Either way this only touches this layer, never the upstream. @@ -526,10 +526,11 @@ user, err := userCache.Get(ctx, "user:123") - **N > 1**: Moderate redundancy - requests distributed across N slots for higher throughput 2. **DoubleCheck** (Supplementary): - - Handles the narrow race window where Request B checks the cache (miss) before Request A completes its write + - Handles the window where Request B reads the cache (miss) just before Request A's fetch writes it, but claims the key only after A's fetch finished: B re-reads instead of fetching again - Works **across all singleflight slots**, enabling fast convergence after first successful fetch - - Auto-enabled by default when notFoundCache is configured (smart detection) - - Configure with `WithDoubleCheck(DoubleCheckEnabled/Disabled/Auto)` based on your scenario + - The saving grows with how long a cache read takes to come back and how hot the key is. Measured with a key requested 20 times per ms, expiring every 20 ms, a 5 ms upstream and a cache answering in 1 ms: 18 upstream calls with it, 30 without; with an in-memory cache, no difference + - Default `DoubleCheckAuto` re-checks only when this `Client` wrote the key's stripe since the request read the cache, so cold keys and keys that do not exist skip the useless re-read (measured over 8000 cold keys: 1.004 cache reads per `Get`, against 2 with `DoubleCheckEnabled`) + - Configure with `WithDoubleCheck(DoubleCheckEnabled/Disabled/Auto)`; `DoubleCheckEnabled` also catches values other processes wrote to a shared cache ### Q: What's the difference between fresh and stale TTL? diff --git a/README_ZH.md b/README_ZH.md index 708d3dd..9b94011 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -172,7 +172,7 @@ sequenceDiagram - **NotFoundCache** - 专门缓存不存在的 key,防止缓存穿透 - **Upstream** - 数据源(数据库、API、另一个 Client 或自定义) - **Singleflight** - 对相同 key 的并发请求去重(防御缓存击穿的主要机制) -- **DoubleCheck** - 在查询 upstream 前重新检查 backend 和 notFoundCache 以捕获并发写入(消除竞态窗口) +- **DoubleCheck** - 认领回源之后,再查一次 backend 和 notFoundCache,如果别的请求刚把值写进去,就直接用它,不再回源 - **Entry** - 带时间戳的包装器,用于基于时间的陈旧检查 ## 缓存后端 @@ -419,7 +419,7 @@ client := cachex.NewClient(cache, productSource{db: db} /* , options as in Quick 1. **后端**:一次批量读(实现了 `BatchCache[T]` 就批量,否则逐个)。每个值按新鲜度分类:新鲜的直接返回;陈旧的先返回,再在后台合成一批刷新(开了 `WithServeStale` 时);腐烂的和未命中的往下走。 2. **Not-Found 缓存**:未命中的先查它,和 `Get` 一样。 3. **Singleflight**:每个要回源的 key 都在和 `Get` **同一个** singleflight 里认领。已经有 `Get` 或别的 `GetMany` 在取的 key,等那次的结果,不再取一遍;所以 `Get` 和 `GetMany`(或两个有交集的 `GetMany`)同时要同一个 key,只回源一次。`WithFetchConcurrency` 照旧按 key 生效。 -4. **DoubleCheck**:认领到的 key 按和 `Get` 相同的规则再查一次后端和 Not-Found 缓存。 +4. **DoubleCheck**:认领到的 key 按和 `Get` 相同的规则再查一次后端和 Not-Found 缓存(默认的 `DoubleCheckAuto` 下,只查查找之后本 `Client` 写过其分片的那些 key)。 5. **上游**:上游实现了 `BatchUpstream[T]`,剩下的 key 就调**一次** `GetMany`;设了 `WithGetManyChunkSize(n)` 时,切成每次最多 `n` 个 key 的多次调用并发执行(适合上游限制了批量大小的情况)。每次调用共用一个 `WithFetchTimeout`(下层是 `Client` 时,上限放宽到下层自己的拉取最多可能用的时间,比如逐 key 排队时按轮数累加的超时)。同一次调用里的 key 在这次调用返回时一起返回:并发 `Get` 其中某个 key 会加入这次调用,等它结束。否则每个 key 都和 `Get` 完全一样地拉取(各自 double check、各自超时、各自回填,拉到就交给等它的调用方),同时最多 `WithGetManyFetchConcurrency` 个(默认 16)。上面分批调用的并发数也由它限制,所以它的含义是「一次 `GetMany` 同时向上游发出的请求数」(相比之下,`WithFetchConcurrency` 限制的是同一个 key 的并发回源数);每个 key 轮到时才认领,所以并发的 `Get` 碰上还在这里排队的 key 不用等整个队列,`GetMany` 被取消后也不再开始新的 key。 6. **回填**:取到的值写回后端,不存在的 key 写进 Not-Found 缓存。上游实现了 `BatchUpstream` 时,一批只调一次 `SetMany`/`DelMany`(后端支持的话);否则每个 key 各自回填,和 `Get` 一样。两种情况都只写本层,不写上游。 @@ -524,10 +524,11 @@ user, err := userCache.Get(ctx, "user:123") - **N > 1**:适度冗余 - 请求分布在 N 个 slot 中,提升吞吐量 2. **DoubleCheck**(辅助): - - 处理窄竞态窗口,即请求 B 在请求 A 完成写入之前检查缓存(miss) + - 处理这样的窗口:请求 B 在请求 A 的回源写入缓存之前读到未命中,却在 A 的回源结束之后才认领这个 key;B 改为再读一次缓存,而不是再回源一次 - **跨所有 singleflight slot 工作**,确保首次成功 fetch 后快速收敛 - - 默认情况下当配置了 notFoundCache 时自动启用(智能检测) - - 可通过 `WithDoubleCheck(DoubleCheckEnabled/Disabled/Auto)` 根据场景配置 + - 收益随缓存读的响应时间和 key 的热度增长。实测:一个 key 每毫秒 20 次请求、每 20ms 过期一次、上游 5ms、缓存 1ms 响应时,开启时上游调用 18 次,关闭时 30 次;内存缓存则没有区别 + - 默认的 `DoubleCheckAuto` 只在请求读缓存之后、本 `Client` 写过这个 key 所在分片时才再读,冷 key 和不存在的 key 就不会白读一次(实测 8000 个冷 key:每次 `Get` 读缓存 1.004 次,`DoubleCheckEnabled` 是 2 次) + - 用 `WithDoubleCheck(DoubleCheckEnabled/Disabled/Auto)` 配置;`DoubleCheckEnabled` 还能抓到其他进程写进共享缓存的值 ### Q: 新鲜 TTL 和过期 TTL 有什么区别? diff --git a/batch.go b/batch.go index a21627f..90a679d 100644 --- a/batch.go +++ b/batch.go @@ -175,11 +175,13 @@ func (c *Client[T]) GetMany(ctx context.Context, keys []string) (map[string]T, e errs := map[string]error{} var fetchKeys, refreshKeys []string + var fetchSeen, refreshSeen []uint64 for i, r := range c.lookupMany(ctx, keys, false) { key := keys[i] switch { case r.fetch: fetchKeys = append(fetchKeys, key) + fetchSeen = append(fetchSeen, r.seen) case r.err == nil: out[key] = r.value case !IsErrKeyNotFound(r.err): @@ -187,11 +189,12 @@ func (c *Client[T]) GetMany(ctx context.Context, keys []string) (map[string]T, e } if r.refresh { refreshKeys = append(refreshKeys, key) + refreshSeen = append(refreshSeen, r.seen) } } if len(refreshKeys) > 0 { - c.asyncRefreshMany(context.WithoutCancel(ctx), refreshKeys) + c.asyncRefreshMany(context.WithoutCancel(ctx), refreshKeys, refreshSeen) } if len(fetchKeys) > 0 { @@ -199,7 +202,7 @@ func (c *Client[T]) GetMany(ctx context.Context, keys []string) (map[string]T, e for i, key := range fetchKeys { sfKeys[i] = c.makeSFKey(key) } - for i, r := range c.fetchMany(ctx, fetchKeys, sfKeys) { + for i, r := range c.fetchMany(ctx, fetchKeys, sfKeys, fetchSeen) { key := fetchKeys[i] switch { case r.err == nil: @@ -219,9 +222,10 @@ func (c *Client[T]) GetMany(ctx context.Context, keys []string) (map[string]T, e // lookup is what the caches say about one key. type lookup[T any] struct { value T - err error // final error (ErrKeyNotFound for a cached not-found), unless fetch - fetch bool // must be fetched from upstream - refresh bool // served stale, refresh in the background + err error // final error (ErrKeyNotFound for a cached not-found), unless fetch + fetch bool // must be fetched from upstream + refresh bool // served stale, refresh in the background + seen uint64 // the key's stripe epoch before reading, see shouldDoubleCheck } // lookupMany is the batch form of the cache part of get: it reads the backend @@ -234,6 +238,9 @@ func (c *Client[T]) lookupMany(ctx context.Context, keys []string, doubleCheck b checkDataStale = alwaysFresh[T] } + for i, key := range keys { + res[i].seen = c.stripe(key).epoch() + } values, err := getMany(ctx, c.backend, keys) var missing []int for i, key := range keys { @@ -312,13 +319,14 @@ func (c *Client[T]) lookupMany(ctx context.Context, keys []string, doubleCheck b // fetchMany fetches keys through the flight group. For a BatchUpstream it // claims every key, fetches the claimed ones as one batch, and waits for all // of them (including those claimed by others); otherwise see fetchEach. -func (c *Client[T]) fetchMany(ctx context.Context, keys, sfKeys []string) []result[T] { +func (c *Client[T]) fetchMany(ctx context.Context, keys, sfKeys []string, seen []uint64) []result[T] { if _, ok := c.upstream.(BatchUpstream[T]); !ok { - return c.fetchEach(ctx, keys, sfKeys) + return c.fetchEach(ctx, keys, sfKeys, seen) } flights := make([]*flight[T], len(keys)) var ownKeys, ownSFKeys []string var ownFlights []*flight[T] + var ownSeen []uint64 for i, sfKey := range sfKeys { f, leader := c.flights.claim(sfKey) flights[i] = f @@ -326,10 +334,11 @@ func (c *Client[T]) fetchMany(ctx context.Context, keys, sfKeys []string) []resu ownKeys = append(ownKeys, keys[i]) ownSFKeys = append(ownSFKeys, sfKey) ownFlights = append(ownFlights, f) + ownSeen = append(ownSeen, seen[i]) } } if len(ownKeys) > 0 { - go c.fetchClaimedMany(flightCtx(ctx), ownKeys, ownSFKeys, ownFlights) + go c.fetchClaimedMany(flightCtx(ctx), ownKeys, ownSFKeys, ownFlights, ownSeen) } results := make([]result[T], len(keys)) @@ -352,7 +361,7 @@ func (c *Client[T]) fetchMany(ctx context.Context, keys, sfKeys []string) []resu // as Get would, at most getManyConc at a time. A key is claimed only when its // turn comes, so a Get of a key still queued here does not wait for the queue, // and once ctx is done no more keys are started. -func (c *Client[T]) fetchEach(ctx context.Context, keys, sfKeys []string) []result[T] { +func (c *Client[T]) fetchEach(ctx context.Context, keys, sfKeys []string, seen []uint64) []result[T] { results := make([]result[T], len(keys)) sem := make(chan struct{}, c.getManyConc) var wg sync.WaitGroup @@ -362,7 +371,7 @@ func (c *Client[T]) fetchEach(ctx context.Context, keys, sfKeys []string) []resu case sem <- struct{}{}: wg.Go(func() { defer func() { <-sem }() - value, err := c.fetchFromUpstreamWithSFKey(ctx, key, sfKeys[i]) + value, err := c.fetchFromUpstreamWithSFKey(ctx, key, sfKeys[i], seen[i]) results[i] = result[T]{value: value, err: err} }) continue @@ -378,20 +387,31 @@ func (c *Client[T]) fetchEach(ctx context.Context, keys, sfKeys []string) []resu // fetchClaimedMany is the batch form of fetchClaimed for a BatchUpstream: // double-check, then fetch what is still missing; every flight is answered as // soon as its result is known. -func (c *Client[T]) fetchClaimedMany(ctx context.Context, keys, sfKeys []string, flights []*flight[T]) { +func (c *Client[T]) fetchClaimedMany(ctx context.Context, keys, sfKeys []string, flights []*flight[T], seen []uint64) { p := c.claimedFlights(keys, sfKeys, flights) all := make([]int, len(keys)) for i := range all { all[i] = i } p.run(ctx, all, func() { - pending := all - if c.enableDoubleCheck { - pending = nil + var pending, check []int + for i, key := range keys { + if c.shouldDoubleCheck(key, seen[i]) { + check = append(check, i) + } else { + pending = append(pending, i) + } + } + if len(check) > 0 { + checkKeys := make([]string, len(check)) + for j, i := range check { + checkKeys[j] = keys[i] + } checkCtx, cancel := context.WithTimeout(ctx, c.fetchTimeout) - lookups := c.lookupMany(checkCtx, keys, true) + lookups := c.lookupMany(checkCtx, checkKeys, true) cancel() - for i, r := range lookups { + for j, r := range lookups { + i := check[j] switch { case r.fetch: pending = append(pending, i) @@ -492,6 +512,7 @@ func (c *Client[T]) doFetchMany(ctx context.Context, keys []string) []result[T] }() found := map[string]T{} var notFound []string + filled := map[*writeStripe]bool{} for i, key := range keys { s := c.stripe(key) ok, seen := held[s] @@ -505,8 +526,10 @@ func (c *Client[T]) doFetchMany(ctx context.Context, keys []string) []result[T] switch { case results[i].err == nil: found[key] = results[i].value + filled[s] = true case IsErrKeyNotFound(results[i].err): notFound = append(notFound, key) + filled[s] = true } } if err := c.setManyWithoutUpstream(ctx, found); err != nil { @@ -515,6 +538,9 @@ func (c *Client[T]) doFetchMany(ctx context.Context, keys []string) []result[T] if err := c.delManyWithoutUpstream(ctx, notFound); err != nil { c.logger.WarnContext(ctx, "failed to delete cache entries", "error", err) } + for s := range filled { // see writeStripe.epoch + s.fills.Add(1) + } return results } @@ -567,13 +593,15 @@ func (c *Client[T]) delManyWithoutUpstream(ctx context.Context, keys []string) e // asyncRefreshMany is the batch form of asyncRefresh: the stale keys of one // GetMany are refreshed together in the background. -func (c *Client[T]) asyncRefreshMany(ctx context.Context, keys []string) { +func (c *Client[T]) asyncRefreshMany(ctx context.Context, keys []string, seen []uint64) { var refreshKeys, sfKeys []string - for _, key := range keys { + var refreshSeen []uint64 + for i, key := range keys { sfKey := c.makeSFKey(key) if _, loaded := c.asyncRefreshing.LoadOrStore(sfKey, struct{}{}); !loaded { refreshKeys = append(refreshKeys, key) sfKeys = append(sfKeys, sfKey) + refreshSeen = append(refreshSeen, seen[i]) } } if len(refreshKeys) == 0 { @@ -588,7 +616,7 @@ func (c *Client[T]) asyncRefreshMany(ctx context.Context, keys []string) { }() // every fetch answers its waiters (bounded by its fetch timeout, and with // an error if it panics or exits), so this wait needs no bound of its own - for i, r := range c.fetchMany(ctx, refreshKeys, sfKeys) { + for i, r := range c.fetchMany(ctx, refreshKeys, sfKeys, refreshSeen) { if r.err != nil && !IsErrKeyNotFound(r.err) { c.logger.ErrorContext(ctx, "async refresh failed", "key", refreshKeys[i], "error", r.err) } diff --git a/client.go b/client.go index bebc35e..bcf08b3 100644 --- a/client.go +++ b/client.go @@ -47,8 +47,7 @@ type Client[T any] struct { writes [writeStripeCount]writeStripe // Double-check optimization - doubleCheckMode DoubleCheckMode // User configuration (immutable) - enableDoubleCheck bool // Resolved execution decision + doubleCheckMode DoubleCheckMode // User configuration (immutable) // Test hooks for simulating race conditions testHooks *testHooks @@ -86,7 +85,6 @@ func NewClient[T any](backend Cache[T], upstream Upstream[T], opts ...ClientOpti } // Resolve double-check mode to boolean flag - c.enableDoubleCheck = c.resolveDoubleCheckMode() if c.fetchTimeout <= 0 { panic("fetchTimeout must be positive") @@ -112,6 +110,7 @@ func (c *Client[T]) Get(ctx context.Context, key string) (T, error) { func (c *Client[T]) get(ctx context.Context, key string, doubleCheck bool) (T, error) { var zero T + seen := c.stripe(key).epoch() // before reading, see shouldDoubleCheck // Check backend cache first value, err := c.backend.Get(ctx, key) @@ -128,7 +127,7 @@ func (c *Client[T]) get(ctx context.Context, key string, doubleCheck bool) (T, e case StateStale: if c.serveStale && !doubleCheck { - c.asyncRefresh(context.WithoutCancel(ctx), key) + c.asyncRefresh(context.WithoutCancel(ctx), key, seen) return value, nil } @@ -158,7 +157,7 @@ func (c *Client[T]) get(ctx context.Context, key string, doubleCheck bool) (T, e case StateStale: if c.serveStale && !doubleCheck { - c.asyncRefresh(context.WithoutCancel(ctx), key) + c.asyncRefresh(context.WithoutCancel(ctx), key, seen) return zero, errors.Wrapf(&ErrKeyNotFound{ Cached: true, CacheState: StateStale, @@ -177,7 +176,7 @@ func (c *Client[T]) get(ctx context.Context, key string, doubleCheck bool) (T, e return zero, errors.Wrapf(&ErrKeyNotFound{}, "key not found in cache for key: %s", key) } - return c.fetchFromUpstream(ctx, key) + return c.fetchFromUpstreamWithSFKey(ctx, key, c.makeSFKey(key), seen) } // Del removes a value from the cache and propagates deletion through cache layers. @@ -283,14 +282,21 @@ func (c *Client[T]) Set(ctx context.Context, key string, value T) error { // Keys share stripes by hash, so two keys in one stripe serialize // their writes and a write to one can skip the other's backfill (a spare // cache miss, never a stale value); raise it if that shows up. -const writeStripeCount = 1024 +// 4096 stripes of 40 bytes cost 160 KB per Client, embedded, no allocation. +const writeStripeCount = 4096 // writeStripe orders writes and backfills of the keys that hash to it. type writeStripe struct { - mu sync.RWMutex // Set/Del hold it, so all layers apply them in one order; backfills hold it for reading - gen atomic.Uint64 // bumped by every Set/Del, checked by backfills + mu sync.RWMutex // Set/Del hold it, so all layers apply them in one order; backfills hold it for reading + gen atomic.Uint64 // bumped by every Set/Del, checked by backfills + fills atomic.Uint64 // bumped by every backfill that wrote this layer } +// epoch changes whenever this Client writes this layer for a key of the +// stripe (a Set/Del or a backfill). If it has not changed since a request read +// the layer, re-reading it (the double-check) would find the same miss. +func (s *writeStripe) epoch() uint64 { return s.gen.Load() + s.fills.Load() } + // lock takes the stripe for writing. Waiting for another write or a backfill // gives up when ctx is done; a free stripe is taken even with a done ctx. A // lock given up on is still taken in the background, runs late while holding @@ -406,6 +412,7 @@ func (c *Client[T]) backfill(ctx context.Context, key string, gen uint64, fill f if err := fill(); err != nil { c.logger.WarnContext(ctx, failMsg, "key", key, "error", err) } + s.fills.Add(1) } // setWithoutUpstream clears a cached not-found and writes the backend; a failed @@ -423,11 +430,9 @@ func (c *Client[T]) setWithoutUpstream(ctx context.Context, key string, value T) return stderrors.Join(errs...) } -func (c *Client[T]) fetchFromUpstream(ctx context.Context, key string) (T, error) { - return c.fetchFromUpstreamWithSFKey(ctx, key, c.makeSFKey(key)) -} - -func (c *Client[T]) fetchFromUpstreamWithSFKey(ctx context.Context, key string, sfKey string) (T, error) { +// fetchFromUpstreamWithSFKey fetches key through the flight group; seen is the +// key's stripe epoch from before the caller read this layer. +func (c *Client[T]) fetchFromUpstreamWithSFKey(ctx context.Context, key string, sfKey string, seen uint64) (T, error) { var zero T if c.testHooks != nil && c.testHooks.beforeSingleflightStart != nil { @@ -436,7 +441,7 @@ func (c *Client[T]) fetchFromUpstreamWithSFKey(ctx context.Context, key string, f, leader := c.flights.claim(sfKey) if leader { - go c.runClaimed(flightCtx(ctx), key, sfKey, f) + go c.runClaimed(flightCtx(ctx), key, sfKey, f, seen) } select { @@ -461,16 +466,16 @@ func flightCtx(ctx context.Context) context.Context { } // runClaimed fetches a key this request has claimed and publishes the result. -func (c *Client[T]) runClaimed(ctx context.Context, key, sfKey string, f *flight[T]) { +func (c *Client[T]) runClaimed(ctx context.Context, key, sfKey string, f *flight[T], seen uint64) { p := c.claimedFlights([]string{key}, []string{sfKey}, []*flight[T]{f}) p.run(ctx, []int{0}, func() { - value, err := c.fetchClaimed(ctx, key) + value, err := c.fetchClaimed(ctx, key, seen) p.publish(0, result[T]{value: value, err: err}) }) } // fetchClaimed fetches a key this request has claimed in the flight group. -func (c *Client[T]) fetchClaimed(ctx context.Context, key string) (T, error) { +func (c *Client[T]) fetchClaimed(ctx context.Context, key string, seen uint64) (T, error) { if c.testHooks != nil && c.testHooks.afterSingleflightStart != nil { c.testHooks.afterSingleflightStart(ctx, key) } @@ -482,7 +487,7 @@ func (c *Client[T]) fetchClaimed(ctx context.Context, key string) (T, error) { // 1. fetchConcurrency allows multiple slots to fetch concurrently (exploration phase) // 2. Once ANY slot completes, ALL slots should converge to reuse that result (convergence phase) // 3. Using key ensures cross-slot visibility, maximizing result reuse after first completion - if c.enableDoubleCheck { + if c.shouldDoubleCheck(key, seen) { checkCtx, cancel := context.WithTimeout(ctx, c.fetchTimeout) cachedValue, err := c.get(checkCtx, key, true) cancel() @@ -515,7 +520,7 @@ func (c *Client[T]) makeSFKey(key string) string { return key } -func (c *Client[T]) asyncRefresh(ctx context.Context, key string) { +func (c *Client[T]) asyncRefresh(ctx context.Context, key string, seen uint64) { sfKey := c.makeSFKey(key) if _, loaded := c.asyncRefreshing.LoadOrStore(sfKey, struct{}{}); loaded { @@ -525,7 +530,7 @@ func (c *Client[T]) asyncRefresh(ctx context.Context, key string) { go func() { defer c.asyncRefreshing.Delete(sfKey) - if _, err := c.fetchFromUpstreamWithSFKey(ctx, key, sfKey); err != nil { + if _, err := c.fetchFromUpstreamWithSFKey(ctx, key, sfKey, seen); err != nil { c.logger.ErrorContext(ctx, "async refresh failed", "key", key, "error", err) } }() @@ -547,18 +552,18 @@ func (c *Client[T]) doFetch(ctx context.Context, key string) (T, error) { return value, nil } -// resolveDoubleCheckMode converts the mode to a boolean decision -func (c *Client[T]) resolveDoubleCheckMode() bool { +// shouldDoubleCheck reports whether a claimed fetch re-reads this layer first. +// In DoubleCheckAuto it does only if this Client wrote the key's stripe since +// the request read the layer (seen): otherwise the re-read would find the same +// miss. A write to another key of the stripe makes it re-read for nothing. +func (c *Client[T]) shouldDoubleCheck(key string, seen uint64) bool { switch c.doubleCheckMode { case DoubleCheckEnabled: return true case DoubleCheckDisabled: return false - case DoubleCheckAuto: - // Auto mode: enable when notFoundCache exists (can leverage it in double-check) - return c.notFoundCache != nil default: - return false + return c.stripe(key).epoch() != seen } } diff --git a/double_check.go b/double_check.go index dba52b8..50e4849 100644 --- a/double_check.go +++ b/double_check.go @@ -10,60 +10,39 @@ const ( // DoubleCheckEnabled always performs double-check before upstream fetch DoubleCheckEnabled - // DoubleCheckAuto enables double-check based on configuration (default): - // - Enabled when notFoundCache exists (can leverage it to catch not-found in race window) - // - Disabled when no notFoundCache (cost limited to backend only) + // DoubleCheckAuto (default) double-checks only when it can find something: + // when this Client wrote this layer for a key of the same stripe (a Set, + // Del or backfill) since the request read it. Otherwise the re-read would + // find the same miss, so it is skipped. DoubleCheckAuto ) // WithDoubleCheck configures the double-check optimization mode. // -// Default: DoubleCheckAuto (smart detection based on notFoundCache configuration) +// Default: DoubleCheckAuto. // -// Background: Double-check works together with singleflight to reduce redundant upstream calls: -// - Singleflight: Deduplicates concurrent requests for the same key (same moment) -// - Double-check: Handles slightly staggered requests in race window (near-miss timing) +// Singleflight merges the requests that miss a key at the same moment. A +// request that read the layer (a miss) just before another request's fetch +// wrote it, but claims the key only after that fetch has finished, would +// start a fetch of its own. The double-check re-reads this layer (and the +// not-found cache) after claiming the key and returns what it finds instead. // -// Double-check queries backend (and notFoundCache if configured) one more time -// before going to upstream. This addresses the race window where: -// 1. Request A writes to cache -// 2. Request B misses cache (A's write not yet visible or in-flight) -// 3. Request B enters fetch path and would normally query upstream -// 4. Double-check catches A's write, avoiding redundant upstream query -// -// Effectiveness (see TestDoubleCheckRaceWindowProbability for controlled test): -// - Test simulates worst-case scenario: two-wave concurrent pattern with precise timing -// - Test results: ~40% redundant fetches without double-check, 0% with double-check -// - Real-world impact: typically much lower race window probability, actual benefit varies -// -// Effectiveness depends on: -// - Concurrent access patterns (higher concurrency = more benefit) -// - Race window duration (network latency, cache propagation delay) -// - Cost ratio between double-check and upstream query +// How much it saves depends on that window: roughly how long a read of this +// layer takes to come back, times how many requests the key gets. Measured +// with a key requested 20 times per ms that expires every 20 ms, a 5 ms +// upstream and a layer that answers in 1 ms: 18 upstream calls with the +// double-check, 30 without; with a layer that answers at once (memory), no +// difference. Its cost is one more read of this layer per fetch. // // Modes: -// - DoubleCheckDisabled: Skip double-check -// Use when: backend query cost >= upstream cost, or backend is unreliable/slow, -// or without notFoundCache in scenarios where upstream frequently returns not-found -// (double-check cannot catch not-found without notFoundCache, reducing effectiveness) -// - DoubleCheckEnabled: Always double-check (adds query cost, reduces upstream calls) -// Use when: upstream is significantly more expensive than backend queries -// - DoubleCheckAuto: Smart detection based on notFoundCache (default) -// Enables when notFoundCache exists (double-check covers both found and not-found scenarios), -// disables otherwise (double-check only covers found scenario, limited effectiveness) -// -// Cost-benefit analysis: -// -// Cost = backend_query [+ notFoundCache_query if configured] -// Benefit = Avoid upstream_query when hitting race window -// -// Worth enabling when: upstream_cost >> (backend_cost + notFoundCache_cost) -// -// Recommendations by scenario: -// - Memory cache -> DB: DoubleCheckEnabled (DB ≫ memory, ~10000x difference) -// - Redis -> DB: DoubleCheckEnabled (DB ≫ Redis, ~10-50x difference) -// - Redis (+ notFoundCache) -> Redis: DoubleCheckDisabled (cost ≈ benefit) -// - Default/Uncertain: DoubleCheckAuto (smart heuristic) +// - DoubleCheckAuto: re-reads only when this Client wrote the key's stripe +// since the request read the layer. Hot keys get the saving above; keys +// fetched with nothing written in between (a long tail of cold keys, keys +// that do not exist) skip the useless re-read. Writes made by other +// processes to a shared layer are not seen. +// - DoubleCheckEnabled: always re-reads, also catching writes by other +// processes to a shared layer, at one more read per fetch. +// - DoubleCheckDisabled: never re-reads. func WithDoubleCheck[T any](mode DoubleCheckMode) ClientOption[T] { return func(c *Client[T]) { c.doubleCheckMode = mode diff --git a/double_check_test.go b/double_check_test.go index 2399e53..ce9b0c6 100644 --- a/double_check_test.go +++ b/double_check_test.go @@ -4,6 +4,7 @@ import ( "context" "fmt" "sync" + "sync/atomic" "testing" "time" @@ -21,7 +22,6 @@ func TestWithDoubleCheckValidation(t *testing.T) { t.Run("default auto mode", func(t *testing.T) { client := NewClient(backend, upstream) assert.Equal(t, DoubleCheckAuto, client.doubleCheckMode) - assert.False(t, client.enableDoubleCheck, "should be disabled when no notFoundCache") }) t.Run("explicitly disabled", func(t *testing.T) { @@ -29,7 +29,6 @@ func TestWithDoubleCheckValidation(t *testing.T) { WithDoubleCheck[string](DoubleCheckDisabled), ) assert.Equal(t, DoubleCheckDisabled, client.doubleCheckMode) - assert.False(t, client.enableDoubleCheck) }) t.Run("explicitly enabled", func(t *testing.T) { @@ -37,25 +36,13 @@ func TestWithDoubleCheckValidation(t *testing.T) { WithDoubleCheck[string](DoubleCheckEnabled), ) assert.Equal(t, DoubleCheckEnabled, client.doubleCheckMode) - assert.True(t, client.enableDoubleCheck) }) - t.Run("auto mode without notFoundCache", func(t *testing.T) { + t.Run("explicit auto mode", func(t *testing.T) { client := NewClient(backend, upstream, WithDoubleCheck[string](DoubleCheckAuto), ) assert.Equal(t, DoubleCheckAuto, client.doubleCheckMode, "should preserve original config") - assert.False(t, client.enableDoubleCheck, "should be disabled when no notFoundCache") - }) - - t.Run("auto mode with notFoundCache", func(t *testing.T) { - notFoundCache := newRistrettoCache[time.Time](t) - client := NewClient(backend, upstream, - NotFoundWithTTL[string](notFoundCache, 1*time.Second, 0), - WithDoubleCheck[string](DoubleCheckAuto), - ) - assert.Equal(t, DoubleCheckAuto, client.doubleCheckMode, "should preserve original config") - assert.True(t, client.enableDoubleCheck, "should be enabled when notFoundCache exists") }) } @@ -340,3 +327,43 @@ func TestDoubleCheckRaceWindowProbability(t *testing.T) { t.Logf(" 5. Two-wave pattern simulates real-world traffic bursts") }) } + +// readCounter counts backend reads, single and batch. +type readCounter struct { + *SyncMap[string] + gets, getManys atomic.Int32 +} + +func (r *readCounter) Get(ctx context.Context, key string) (string, error) { + r.gets.Add(1) + return r.SyncMap.Get(ctx, key) +} + +func (r *readCounter) GetMany(ctx context.Context, keys []string) (map[string]string, error) { + r.getManys.Add(1) + return r.SyncMap.GetMany(ctx, keys) +} + +func TestDoubleCheckAutoSkipsWhenNothingWasWritten(t *testing.T) { + ctx := context.Background() + up := UpstreamFunc[string](func(_ context.Context, key string) (string, error) { return "v-" + key, nil }) + for _, tc := range []struct { + mode DoubleCheckMode + reads int32 + }{ + {DoubleCheckAuto, 1}, // nothing written since the miss: re-reading is useless + {DoubleCheckEnabled, 2}, // always re-reads + } { + backend := &readCounter{SyncMap: NewSyncMap[string]()} + cli := NewClient[string](backend, up, WithDoubleCheck[string](tc.mode)) + _, err := cli.Get(ctx, "cold") + require.NoError(t, err) + assert.Equal(t, tc.reads, backend.gets.Load(), "Get, mode %d", tc.mode) + + batchBackend := &readCounter{SyncMap: NewSyncMap[string]()} + batchCli := NewClient[string](batchBackend, &batchUpstream{data: map[string]string{"a": "1"}}, WithDoubleCheck[string](tc.mode)) + _, err = batchCli.GetMany(ctx, []string{"a", "b"}) + require.NoError(t, err) + assert.Equal(t, tc.reads, batchBackend.getManys.Load(), "GetMany, mode %d", tc.mode) + } +} diff --git a/get_compat_test.go b/get_compat_test.go index 7b97cc9..bb806f2 100644 --- a/get_compat_test.go +++ b/get_compat_test.go @@ -288,6 +288,7 @@ func TestGetCompatDoubleCheckRaceWindow(t *testing.T) { }{ {"enabled: the late request reuses the value just written", DoubleCheckEnabled, 1}, {"disabled: the late request fetches again", DoubleCheckDisabled, 2}, + {"auto: the early request's write-back is seen, so the late one double-checks", DoubleCheckAuto, 1}, } { t.Run(tc.name, func(t *testing.T) { ctx := context.Background() From e598135d28e6865cd6ddb6392698be917f01ee1d Mon Sep 17 00:00:00 2001 From: molon <3739161+molon@users.noreply.github.com> Date: Sat, 10 Oct 2026 03:28:45 +0800 Subject: [PATCH 32/40] feat: GORMCache.Migrate checks the MySQL version before creating its table utf8mb4_0900_bin needs MySQL 8.0.17 or later and MariaDB lacks it, so creating the table there failed with an opaque "Unknown collation". When the table does not exist yet, Migrate now reads VERSION() and returns an error naming the version; an existing table is left alone, as before. --- README.md | 2 +- README_ZH.md | 2 +- gorm.go | 28 ++++++++++++++++++++++++++++ gorm_test.go | 21 +++++++++++++++++++++ 4 files changed, 51 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 220184e..f974130 100644 --- a/README.md +++ b/README.md @@ -215,7 +215,7 @@ if err := cache.Migrate(ctx); err != nil { } ``` -Cache keys are case-sensitive, so the `key` column should compare them exactly. PostgreSQL and SQLite do by default, and on MySQL (8.0.17 or later) `Migrate` creates the table with `utf8mb4_0900_bin`, which compares case and trailing spaces exactly. A table created before that (or by hand) keeps its collation, usually case- and accent-insensitive (`*_ci`); convert it with `ALTER TABLE cache_products CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_bin`. Even without it nothing wrong is ever served: `GORMCache` only returns the row stored under exactly the requested key, so keys differing only in case just take the row over from each other (extra misses). +Cache keys are case-sensitive, so the `key` column should compare them exactly. PostgreSQL and SQLite do by default, and on MySQL (8.0.17 or later) `Migrate` creates the table with `utf8mb4_0900_bin`, which compares case and trailing spaces exactly. Before creating it, `Migrate` checks the server version and returns an error naming it on an older MySQL or on MariaDB, which lack that collation. A table created before that (or by hand) keeps its collation, usually case- and accent-insensitive (`*_ci`); convert it with `ALTER TABLE cache_products CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_bin`. Even without it nothing wrong is ever served: `GORMCache` only returns the row stored under exactly the requested key, so keys differing only in case just take the row over from each other (extra misses). Concurrent batch writes (from several instances' `GetMany` write-backs) lock rows in one order, so they do not deadlock each other; a write the database still aborts as a deadlock victim (MySQL's gap locks can) is retried a few times. Inside a transaction passed with `WithGORMTx` it is not retried, since the deadlock has rolled that whole transaction back; the error is returned. diff --git a/README_ZH.md b/README_ZH.md index 9b94011..890215d 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -215,7 +215,7 @@ if err := cache.Migrate(ctx); err != nil { } ``` -缓存 key 区分大小写,所以 `key` 列应当精确比较。PostgreSQL 和 SQLite 默认如此;MySQL(需 8.0.17 及以上)上 `Migrate` 建表时会用 `utf8mb4_0900_bin`,大小写和末尾空格都精确比较。在这之前建的表(或手工建的表)保留原来的排序规则,通常不区分大小写和重音(`*_ci`),可以用 `ALTER TABLE cache_products CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_bin` 转换。即使不转换也不会读到错的值:`GORMCache` 只返回 key 完全相等的那一行,只差大小写的几个 key 只会互相挤占这一行(多几次未命中)。 +缓存 key 区分大小写,所以 `key` 列应当精确比较。PostgreSQL 和 SQLite 默认如此;MySQL(需 8.0.17 及以上)上 `Migrate` 建表时会用 `utf8mb4_0900_bin`,大小写和末尾空格都精确比较。建表前 `Migrate` 会检查服务端版本:低于 8.0.17 的 MySQL 或 MariaDB 都没有这个排序规则,会返回写明版本号的错误。在这之前建的表(或手工建的表)保留原来的排序规则,通常不区分大小写和重音(`*_ci`),可以用 `ALTER TABLE cache_products CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_bin` 转换。即使不转换也不会读到错的值:`GORMCache` 只返回 key 完全相等的那一行,只差大小写的几个 key 只会互相挤占这一行(多几次未命中)。 并发的批量写入(多个实例的 `GetMany` 回填)按同一顺序锁行,彼此不会死锁;数据库仍判为死锁牺牲者的写入(MySQL 的间隙锁可能导致)会重试几次。通过 `WithGORMTx` 传入的事务里不重试,因为死锁已经回滚了整个事务,直接返回错误。 diff --git a/gorm.go b/gorm.go index 7f23b0c..fdc2884 100644 --- a/gorm.go +++ b/gorm.go @@ -5,6 +5,7 @@ import ( "context" "encoding/json" stderrors "errors" + "fmt" "math/rand/v2" "slices" "strings" @@ -55,6 +56,24 @@ func isDeadlock(err error) bool { return strings.Contains(err.Error(), "Error 1213 (40001)") } +// checkMySQLVersion fails unless version (SELECT VERSION()) is MySQL 8.0.17 +// or later, the first with the utf8mb4_0900_bin collation Migrate creates +// tables with. MariaDB has no such collation. +func checkMySQLVersion(version string) error { + fail := errors.Errorf("GORMCache needs MySQL 8.0.17 or later to create its table (utf8mb4_0900_bin collation), found %q", version) + if strings.Contains(version, "MariaDB") { + return fail + } + var major, minor, patch int + if _, err := fmt.Sscanf(version, "%d.%d.%d", &major, &minor, &patch); err != nil { + return fail + } + if cmp.Or(cmp.Compare(major, 8), cmp.Compare(minor, 0), cmp.Compare(patch, 17)) < 0 { + return fail + } + return nil +} + // keyColumn is the key column as a clause, so GORM quotes it: "key" is a // reserved word in MySQL. var keyColumn = clause.Column{Name: "key"} @@ -135,6 +154,15 @@ func (g *GORMCache[T]) prefixedKey(key string) string { func (g *GORMCache[T]) Migrate(ctx context.Context) error { tx := cmp.Or(GetGORMTx(ctx), g.db).WithContext(ctx).Table(g.tableName) if tx.Name() == "mysql" { + if !tx.Migrator().HasTable(g.tableName) { + var version string + if err := tx.Raw("SELECT VERSION()").Scan(&version).Error; err != nil { + return errors.Wrap(err, "failed to read the MySQL version") + } + if err := checkMySQLVersion(version); err != nil { + return err + } + } // keys compare exactly (case, trailing spaces), MySQL's defaults do not; applies // only when the table is created, an existing one is left as it is tx = tx.Set("gorm:table_options", "CHARSET=utf8mb4 COLLATE=utf8mb4_0900_bin") // MySQL 8.0.17+ diff --git a/gorm_test.go b/gorm_test.go index 702a8e2..e605d9c 100644 --- a/gorm_test.go +++ b/gorm_test.go @@ -355,3 +355,24 @@ func TestGORMCacheRetriesDeadlockVictims(t *testing.T) { err = db.Transaction(func(tx *gorm.DB) error { return cache.Set(WithGORMTx(ctx, tx), "k", "v3") }) assert.True(t, isDeadlock(err), "inside the caller's transaction, which the deadlock rolled back, nothing is retried") } + +func TestCheckMySQLVersion(t *testing.T) { + for version, ok := range map[string]bool{ + "8.0.17": true, + "8.0.36-0ubuntu0.22.04.1": true, + "8.4.2": true, + "9.1.0": true, + "8.0.16": false, + "5.7.44-log": false, + "10.11.6-MariaDB": false, + "11.4.2-MariaDB-ubu2404": false, + "garbage": false, + } { + err := checkMySQLVersion(version) + if ok { + assert.NoError(t, err, version) + } else { + assert.ErrorContains(t, err, "MySQL 8.0.17 or later", version) + } + } +} From 146c6c88a41fe255d5291f46c75584e645393563 Mon Sep 17 00:00:00 2001 From: molon <3739161+molon@users.noreply.github.com> Date: Sat, 10 Oct 2026 03:29:34 +0800 Subject: [PATCH 33/40] docs: Get and GetMany outcomes side by side, what GetMany returns when, multi-instance limits, and the follow-ups - README: a table of the three outcomes (found, possibly nil; does not exist; failed) for Get and GetMany, and testing presence with v, ok. - README: GetMany returns its whole result at once; the backend step says how each value read is handled, without "returned first". - README: the write order guarantees hold within one process; with several instances, memory layers and a shared layer rely on TTLs, and why. - TODO: Redis leases against stale backfills into a shared cache, and invalidation broadcast over Redis Pub/Sub. --- README.md | 16 ++++++++++++++-- README_ZH.md | 16 ++++++++++++++-- TODO.md | 23 +++++++++++++++++++++++ TODO_ZH.md | 23 +++++++++++++++++++++++ 4 files changed, 74 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index f974130..c8ecdae 100644 --- a/README.md +++ b/README.md @@ -341,7 +341,9 @@ The key insight: **cache writes propagate through `Cache[T]` chains but stop whe - If the upstream write succeeds but this layer's own write fails, `Set`/`Del` still return the error, yet the change below is **kept** (nothing is rolled back): an error does not mean nothing was written. This layer drops its entry and cached Not-Found for the key, so the next read goes down and sees the change. - Concurrent `Set`/`Del` of one key through the same `Client` are applied one at a time, in the same order on every layer. A `Set`/`Del` that has to wait (for another write to its stripe, or a read writing back to this layer) gives up when its ctx is done and returns the ctx error: it writes nothing upstream, and, like any failed write, drops this layer's entry for the key as soon as the stripe is free. One that does not have to wait is applied even if its ctx is already done. So an invalidating `Del` after the request was canceled always clears this layer, at worst a moment after it returns. Once a write has started, the cleanup after a failure (dropping this layer's entry) runs even if ctx is done, for at most `WithFetchTimeout`. - A read that fetched a value **before** a concurrent `Set`/`Del` still returns what it fetched, but never writes it back over the newer value: each `Client` hashes keys into 1,024 stripes, each with a write lock and a write generation, and `Get`, `GetMany` and the serve-stale refresh check the key's stripe generation while holding its lock for reading, so a backfill either lands before a `Set`/`Del` (which then overwrites it) or is skipped. A backfill is also skipped while a write to the stripe is in progress, so reads never wait on writes. Keys that share a stripe share this state: their writes run one at a time, and a write to one key can skip a backfill of another. The cost is at most an extra cache miss, or a write waiting on a write to an unrelated key, or on a read writing back to this layer: a large `GetMany` holds the stripes of all its keys (about 60% of them for 1,000 keys) while the backend writes them back, so a `Set`/`Del` of any key in those stripes waits that long, and gives up if its ctx ends first. -- These guarantees hold within one process; separate processes sharing a lower layer (e.g. Redis) can still briefly disagree in their memory layers. +- These guarantees hold **within one process**: the stripes live in one `Client`'s memory and know nothing of other instances. With several instances sharing a lower layer (e.g. Redis): + - a write made on one instance does not reach the memory layers of the others, which keep their old value until it expires. Give memory layers a TTL no longer than the staleness you can accept; to invalidate them sooner, broadcast the change from your own code (e.g. Redis Pub/Sub); + - an instance that read the old value from the source just before another instance wrote it can still put that old value into the shared layer after the write, where it stays until it expires. This race is rare (the read and the write must overlap within milliseconds) but the stale value lives as long as the shared layer's TTL, so give that layer a TTL you can live with too. ### Not-Found Caching @@ -418,7 +420,7 @@ client := cachex.NewClient(cache, productSource{db: db} /* , options as in Quick How `GetMany` works: -1. **Backend**: one batch read (`BatchCache[T]`, otherwise key by key). Each value is classified by staleness: fresh values are returned, stale values are returned and refreshed in the background together (with `WithServeStale`), rotten values and misses go on. +1. **Backend**: one batch read (`BatchCache[T]`, otherwise key by key). Each value read is handled by staleness: a fresh value goes into the result; a stale one goes into the result too (with `WithServeStale`), and those keys are refreshed together in the background; rotten values and misses go on to the next steps, and what those find goes into the same result. The whole result is returned at once. 2. **Not-Found cache**: misses are checked against it, exactly like `Get`. 3. **Singleflight**: every key that needs the upstream is claimed in the **same** singleflight `Get` uses. Keys already being fetched by a `Get` or another `GetMany` are waited for, not fetched again; so a `Get` and a `GetMany` (or two overlapping `GetMany`s) fetch a shared key only once. `WithFetchConcurrency` applies per key as usual. 4. **DoubleCheck**: the claimed keys are re-checked against the backend and Not-Found cache, by the same rules as `Get` (in the default `DoubleCheckAuto`, only the keys whose stripe this `Client` wrote since the lookup). @@ -429,6 +431,16 @@ How `GetMany` works: **Errors**: the returned map always holds every key that succeeded. If some keys failed (backend, upstream or context errors), the error is a `*cachex.BatchError` whose `Errors` map lists them by key; `errors.Is`/`errors.As` see through it to the per-key errors. A per-key error is always a real failure, never a not-found: keys that do not exist are just absent from the map. +`Get` and `GetMany` report the same three outcomes, each in the shape its return allows: + +| Outcome | `Get` | `GetMany` | +|---|---|---| +| found (the value may itself be `nil`) | `(value, nil)` | in the map | +| does not exist | `cachex.IsErrKeyNotFound(err)` | absent from the map and from the `BatchError` | +| failed | any other error | listed in the `BatchError` | + +A cached value can be `nil` (a nil pointer, for example) and is still a hit, so test presence with `v, ok := products[id]`, not with `products[id] == nil`. + ```go products, err := client.GetMany(ctx, ids) var batchErr *cachex.BatchError diff --git a/README_ZH.md b/README_ZH.md index 890215d..44ad11f 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -340,7 +340,9 @@ L1 缓存 → L2 缓存 → L3 缓存 → 数据库 - upstream 写成功、本层自己的写入失败时,`Set`/`Del` 仍返回错误,但下层的改动**保留**(不回滚):返回错误不代表什么都没写进去。本层会删掉这个 key 的条目和缓存的 Not-Found,下次读会回源到下层,读到改动后的结果。 - 通过同一个 `Client` 并发 `Set`/`Del` 同一个 key 时,逐个执行,各层的写入顺序一致。需要等待的 `Set`/`Del`(等同一分片的其他写入,或者等正在回填本层的读),在 ctx 结束时放弃并返回 ctx 错误:它不写 upstream,并且和其他失败的写入一样,等分片空出来就删掉本层这个 key 的条目。不需要等待的照常执行,即使 ctx 已经结束。所以请求取消后再调 `Del` 做失效,本层总会被清掉,最多是在它返回后稍晚一点。写入一旦开始,失败后的清理(删掉本层条目)即使 ctx 已结束也会执行,最长 `WithFetchTimeout`。 - 回源读到值**之后**、写回本层**之前**如果发生了 `Set`/`Del`,这次读仍然返回它读到的值,但绝不会用它覆盖更新的值:每个 `Client` 把 key 按哈希分到 1,024 个分片,每个分片有一把写锁和一个写入代数,`Get`、`GetMany` 和 serve-stale 的后台刷新在持有 key 所在分片的读锁时核对分片的写入代数,所以回填要么在 `Set`/`Del` 之前落下(随后被覆盖),要么被跳过。分片正在写入时回填也直接跳过,所以读永远不等写。落在同一分片的 key 共用这份状态:它们的写入逐个执行,写一个 key 可能让另一个 key 的回填被跳过。代价最多是多一次缓存未命中,或者一次写入要等另一个不相干 key 的写入、或等正在回填本层的读:一次大的 `GetMany` 在后端写回期间会占着它所有 key 的分片(1,000 个 key 约占六成),这些分片上任何 key 的 `Set`/`Del` 都要等这么久,ctx 先结束就放弃。 -- 这些保证在单个进程内成立;多个进程共用同一个下层(例如 Redis)时,各自的内存层仍可能短暂不一致。 +- 这些保证**只在单个进程内**成立:分片在一个 `Client` 的内存里,不知道其他实例的存在。多个实例共用同一个下层(例如 Redis)时: + - 一个实例上的写入到达不了其他实例的内存层,它们会继续返回旧值,直到过期。内存层的 TTL 不要超过你能接受的旧数据时长;要更快失效,请在业务代码里广播变更(例如 Redis Pub/Sub); + - 一个实例刚从数据源读到旧值、另一个实例随即完成写入,前者仍可能在写入之后把旧值回填进共享的下层,并一直留到过期。这种竞态很少见(读和写要在几毫秒内交错),但旧值会存活整个共享层的 TTL,所以共享层的 TTL 也要设成你能接受的长度。 ### Not-Found 缓存 @@ -416,7 +418,7 @@ client := cachex.NewClient(cache, productSource{db: db} /* , options as in Quick `GetMany` 的流程: -1. **后端**:一次批量读(实现了 `BatchCache[T]` 就批量,否则逐个)。每个值按新鲜度分类:新鲜的直接返回;陈旧的先返回,再在后台合成一批刷新(开了 `WithServeStale` 时);腐烂的和未命中的往下走。 +1. **后端**:一次批量读(实现了 `BatchCache[T]` 就批量,否则逐个)。读到的值按新鲜度处理:新鲜的放进结果;陈旧的也放进结果(开了 `WithServeStale` 时),同时这些 key 在后台合成一批刷新;腐烂的和未命中的继续走后面的步骤,查到的也放进同一份结果。整份结果一次返回。 2. **Not-Found 缓存**:未命中的先查它,和 `Get` 一样。 3. **Singleflight**:每个要回源的 key 都在和 `Get` **同一个** singleflight 里认领。已经有 `Get` 或别的 `GetMany` 在取的 key,等那次的结果,不再取一遍;所以 `Get` 和 `GetMany`(或两个有交集的 `GetMany`)同时要同一个 key,只回源一次。`WithFetchConcurrency` 照旧按 key 生效。 4. **DoubleCheck**:认领到的 key 按和 `Get` 相同的规则再查一次后端和 Not-Found 缓存(默认的 `DoubleCheckAuto` 下,只查查找之后本 `Client` 写过其分片的那些 key)。 @@ -427,6 +429,16 @@ client := cachex.NewClient(cache, productSource{db: db} /* , options as in Quick **错误**:返回的 map 总是包含所有成功的 key。有 key 失败(后端、上游或 context 出错)时,error 是 `*cachex.BatchError`,它的 `Errors` 按 key 列出各自的错误;`errors.Is`/`errors.As` 能穿透到每个 key 的错误。每个 key 的错误都是真正的失败,不会是「不存在」:不存在的 key 只是不出现在 map 里。 +`Get` 和 `GetMany` 表达的是同样的三种结果,只是各自用了适合自己返回形式的方式: + +| 结果 | `Get` | `GetMany` | +|---|---|---| +| 找到了(值本身可能是 `nil`) | `(value, nil)` | 在 map 里 | +| 不存在 | `cachex.IsErrKeyNotFound(err)` | 既不在 map 里,也不在 `BatchError` 里 | +| 失败了 | 其他 error | 列在 `BatchError` 里 | + +缓存的值可以是 `nil`(比如空指针),它依然算命中。所以判断 key 在不在要用 `v, ok := products[id]`,不要用 `products[id] == nil`。 + ```go products, err := client.GetMany(ctx, ids) var batchErr *cachex.BatchError diff --git a/TODO.md b/TODO.md index bb5c2f2..11895b6 100644 --- a/TODO.md +++ b/TODO.md @@ -122,3 +122,26 @@ type TrafficShapingConfig struct { - Maintain backward compatibility with existing API - Add comprehensive benchmarks to measure overhead - Document performance characteristics and trade-offs + +## Consistency Across Instances + +The write stripes order writes only within one `Client` process. With several instances sharing a lower layer such as Redis, the two points below rely on TTLs for now (see "Write order and consistency" in the README). + +### Keep stale backfills out of a shared cache with Redis leases + +- **Problem:** instance A misses and reads an old value from the source; instance B then writes the source and updates or deletes the shared cache; A writes the old value back into the shared cache, where it stays until its TTL. +- **Approach (leases, from Facebook's memcache paper):** + - On a miss, a Lua script atomically runs `GET k` and, if empty, sets `lease:k = random token` and returns the token (the read and the lease must be one atomic step) + - Every write (Set/Del) also deletes `lease:k`, voiding all outstanding tokens (it can share the write's pipeline) + - A backfill runs another Lua script that writes the value only if `lease:k` still holds its token +- **Cost:** no extra round trips; a miss writes one lease key, a backfill uses `EVALSHA`, a write adds one `DEL`. The data source needs no version numbers. +- **Implementation considerations:** + - A new optional interface (e.g. `LeaseCache`), used by the Client only when the backend implements it; batch reads need batch leases + - `RedisCache` first; `GORMCache` if needed (a lease column or table with conditional updates) + - Delayed double delete only narrows the window and is lost when the process exits; not worth building in + +### Broadcast invalidations with Redis Pub/Sub (optional) + +- **Problem:** a write made on one instance does not reach the memory layers of the others, which serve the old value until it expires. +- **Approach:** after a write, publish the changed keys on a channel; subscribed instances delete them from their memory layer. +- **Note:** messages are lost while disconnected, so TTLs remain the backstop; make it opt-in, off by default. diff --git a/TODO_ZH.md b/TODO_ZH.md index 11ade77..955bd91 100644 --- a/TODO_ZH.md +++ b/TODO_ZH.md @@ -121,3 +121,26 @@ type TrafficShapingConfig struct { - 保持与现有 API 的向后兼容性 - 添加全面的基准测试以衡量开销 - 记录性能特征和权衡取舍 + +## 多实例一致性 + +分片锁只在单个 `Client` 进程内保证顺序。多个实例共用 Redis 等下层时,以下两点目前只靠 TTL 兜底(README「写入顺序与一致性」一节有说明)。 + +### 用 Redis lease 防止旧值回填进共享缓存 + +- **问题:** 实例 A 未命中,从数据源读到旧值;实例 B 随即写入数据源并更新或删除共享缓存;A 再把旧值回填进共享缓存,旧值一直留到 TTL 到期。 +- **做法(Facebook memcache 论文中的 lease):** + - 读未命中时,用一段 Lua 原子地 `GET k`,若为空就写入 `lease:k = 随机令牌` 并返回令牌(读和领租约必须在同一原子操作里) + - 任何写入(Set/Del)同时删除 `lease:k`,让在途令牌全部作废(可放进同一个 pipeline) + - 回填用另一段 Lua:只有 `lease:k` 仍等于自己的令牌才写入值 +- **代价:** 往返次数不变;未命中多写一个租约 key,回填改用 `EVALSHA`,写入多一个 `DEL`。不需要数据源提供版本号。 +- **实现考虑:** + - 新增可选接口(例如 `LeaseCache`),后端支持时 Client 才走这条路;批量读要支持批量领租约 + - 先做 `RedisCache`;`GORMCache` 视需要跟进(租约列或租约表 + 条件更新) + - 延迟双删只能缩小窗口、进程退出即失效,不做进库里 + +### 用 Redis Pub/Sub 广播失效(可选) + +- **问题:** 一个实例上的写入到达不了其他实例的内存层,它们会返回旧值直到过期。 +- **做法:** 写入后在一个频道上发布被改动的 key,订阅的实例删除自己内存层里的这些 key。 +- **注意:** 断线期间的消息会丢,最终仍要靠 TTL 兜底;做成可选功能,默认关闭。 From 21e574becb8294e9d50712b5b07c944e35d131e7 Mon Sep 17 00:00:00 2001 From: molon <3739161+molon@users.noreply.github.com> Date: Sat, 10 Oct 2026 11:07:14 +0800 Subject: [PATCH 34/40] docs: stripe figures for 4096 stripes, and WithGetManyChunkSize as the way to hold fewer stripes during a large write-back --- README.md | 2 +- README_ZH.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index c8ecdae..219e4d4 100644 --- a/README.md +++ b/README.md @@ -340,7 +340,7 @@ The key insight: **cache writes propagate through `Cache[T]` chains but stop whe - If the upstream write fails, its state is unknown (it may have been applied with only the reply lost), so this layer **drops** its entry for the key (and any cached Not-Found) and returns the error; the next read goes down. A failed `Del` likewise drops this layer's entry but caches no Not-Found. - If the upstream write succeeds but this layer's own write fails, `Set`/`Del` still return the error, yet the change below is **kept** (nothing is rolled back): an error does not mean nothing was written. This layer drops its entry and cached Not-Found for the key, so the next read goes down and sees the change. - Concurrent `Set`/`Del` of one key through the same `Client` are applied one at a time, in the same order on every layer. A `Set`/`Del` that has to wait (for another write to its stripe, or a read writing back to this layer) gives up when its ctx is done and returns the ctx error: it writes nothing upstream, and, like any failed write, drops this layer's entry for the key as soon as the stripe is free. One that does not have to wait is applied even if its ctx is already done. So an invalidating `Del` after the request was canceled always clears this layer, at worst a moment after it returns. Once a write has started, the cleanup after a failure (dropping this layer's entry) runs even if ctx is done, for at most `WithFetchTimeout`. -- A read that fetched a value **before** a concurrent `Set`/`Del` still returns what it fetched, but never writes it back over the newer value: each `Client` hashes keys into 1,024 stripes, each with a write lock and a write generation, and `Get`, `GetMany` and the serve-stale refresh check the key's stripe generation while holding its lock for reading, so a backfill either lands before a `Set`/`Del` (which then overwrites it) or is skipped. A backfill is also skipped while a write to the stripe is in progress, so reads never wait on writes. Keys that share a stripe share this state: their writes run one at a time, and a write to one key can skip a backfill of another. The cost is at most an extra cache miss, or a write waiting on a write to an unrelated key, or on a read writing back to this layer: a large `GetMany` holds the stripes of all its keys (about 60% of them for 1,000 keys) while the backend writes them back, so a `Set`/`Del` of any key in those stripes waits that long, and gives up if its ctx ends first. +- A read that fetched a value **before** a concurrent `Set`/`Del` still returns what it fetched, but never writes it back over the newer value: each `Client` hashes keys into 1,024 stripes, each with a write lock and a write generation, and `Get`, `GetMany` and the serve-stale refresh check the key's stripe generation while holding its lock for reading, so a backfill either lands before a `Set`/`Del` (which then overwrites it) or is skipped. A backfill is also skipped while a write to the stripe is in progress, so reads never wait on writes. Keys that share a stripe share this state: their writes run one at a time, and a write to one key can skip a backfill of another. The cost is at most an extra cache miss, or a write waiting on a write to an unrelated key, or on a read writing back to this layer: a large `GetMany` holds the stripes of all its keys (about 22% of them for 1,000 keys, 91% for 10,000) while the backend writes them back, so a `Set`/`Del` of any key in those stripes waits that long, and gives up if its ctx ends first. With `WithGetManyChunkSize(n)`, each chunk writes back on its own and holds only its keys' stripes; a smaller backend `ChunkSize` does not help, as the stripes are held for the whole `SetMany`. - These guarantees hold **within one process**: the stripes live in one `Client`'s memory and know nothing of other instances. With several instances sharing a lower layer (e.g. Redis): - a write made on one instance does not reach the memory layers of the others, which keep their old value until it expires. Give memory layers a TTL no longer than the staleness you can accept; to invalidate them sooner, broadcast the change from your own code (e.g. Redis Pub/Sub); - an instance that read the old value from the source just before another instance wrote it can still put that old value into the shared layer after the write, where it stays until it expires. This race is rare (the read and the write must overlap within milliseconds) but the stale value lives as long as the shared layer's TTL, so give that layer a TTL you can live with too. diff --git a/README_ZH.md b/README_ZH.md index 44ad11f..440cffb 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -339,7 +339,7 @@ L1 缓存 → L2 缓存 → L3 缓存 → 数据库 - upstream 写失败时,它的状态不明(可能已经写进去了,只是回复丢了),所以本层会**删掉**这个 key 的条目(连同缓存的 Not-Found),并返回错误;下次读会回源到下层。`Del` 失败时同样删掉本层条目,但不记 Not-Found。 - upstream 写成功、本层自己的写入失败时,`Set`/`Del` 仍返回错误,但下层的改动**保留**(不回滚):返回错误不代表什么都没写进去。本层会删掉这个 key 的条目和缓存的 Not-Found,下次读会回源到下层,读到改动后的结果。 - 通过同一个 `Client` 并发 `Set`/`Del` 同一个 key 时,逐个执行,各层的写入顺序一致。需要等待的 `Set`/`Del`(等同一分片的其他写入,或者等正在回填本层的读),在 ctx 结束时放弃并返回 ctx 错误:它不写 upstream,并且和其他失败的写入一样,等分片空出来就删掉本层这个 key 的条目。不需要等待的照常执行,即使 ctx 已经结束。所以请求取消后再调 `Del` 做失效,本层总会被清掉,最多是在它返回后稍晚一点。写入一旦开始,失败后的清理(删掉本层条目)即使 ctx 已结束也会执行,最长 `WithFetchTimeout`。 -- 回源读到值**之后**、写回本层**之前**如果发生了 `Set`/`Del`,这次读仍然返回它读到的值,但绝不会用它覆盖更新的值:每个 `Client` 把 key 按哈希分到 1,024 个分片,每个分片有一把写锁和一个写入代数,`Get`、`GetMany` 和 serve-stale 的后台刷新在持有 key 所在分片的读锁时核对分片的写入代数,所以回填要么在 `Set`/`Del` 之前落下(随后被覆盖),要么被跳过。分片正在写入时回填也直接跳过,所以读永远不等写。落在同一分片的 key 共用这份状态:它们的写入逐个执行,写一个 key 可能让另一个 key 的回填被跳过。代价最多是多一次缓存未命中,或者一次写入要等另一个不相干 key 的写入、或等正在回填本层的读:一次大的 `GetMany` 在后端写回期间会占着它所有 key 的分片(1,000 个 key 约占六成),这些分片上任何 key 的 `Set`/`Del` 都要等这么久,ctx 先结束就放弃。 +- 回源读到值**之后**、写回本层**之前**如果发生了 `Set`/`Del`,这次读仍然返回它读到的值,但绝不会用它覆盖更新的值:每个 `Client` 把 key 按哈希分到 1,024 个分片,每个分片有一把写锁和一个写入代数,`Get`、`GetMany` 和 serve-stale 的后台刷新在持有 key 所在分片的读锁时核对分片的写入代数,所以回填要么在 `Set`/`Del` 之前落下(随后被覆盖),要么被跳过。分片正在写入时回填也直接跳过,所以读永远不等写。落在同一分片的 key 共用这份状态:它们的写入逐个执行,写一个 key 可能让另一个 key 的回填被跳过。代价最多是多一次缓存未命中,或者一次写入要等另一个不相干 key 的写入、或等正在回填本层的读:一次大的 `GetMany` 在后端写回期间会占着它所有 key 的分片(1,000 个 key 约占 22%,10,000 个约占 91%),这些分片上任何 key 的 `Set`/`Del` 都要等这么久,ctx 先结束就放弃。设置 `WithGetManyChunkSize(n)` 后,每一批各自写回,只占这一批 key 的分片;调小后端的 `ChunkSize` 没有这个效果,因为分片在整个 `SetMany` 期间一直被占着。 - 这些保证**只在单个进程内**成立:分片在一个 `Client` 的内存里,不知道其他实例的存在。多个实例共用同一个下层(例如 Redis)时: - 一个实例上的写入到达不了其他实例的内存层,它们会继续返回旧值,直到过期。内存层的 TTL 不要超过你能接受的旧数据时长;要更快失效,请在业务代码里广播变更(例如 Redis Pub/Sub); - 一个实例刚从数据源读到旧值、另一个实例随即完成写入,前者仍可能在写入之后把旧值回填进共享的下层,并一直留到过期。这种竞态很少见(读和写要在几毫秒内交错),但旧值会存活整个共享层的 TTL,所以共享层的 TTL 也要设成你能接受的长度。 From ab4e59295332f075bd5102ad7fc5bad49fe956c4 Mon Sep 17 00:00:00 2001 From: molon <3739161+molon@users.noreply.github.com> Date: Sat, 10 Oct 2026 12:06:41 +0800 Subject: [PATCH 35/40] test: re-runnable scripts for the GORM deadlock, double-check and batch result shape measurements Behind the bench build tag, so go test ./... skips them. The deadlock script runs MySQL 8.4 and PostgreSQL 16 in testcontainers and compares unordered writes, one lock order, GORMCache (one lock order + retry) and a table lock. --- .../2026-10-batch-result-shape/shape_test.go | 71 ++++++ .../2026-10-double-check/doublecheck_test.go | 98 ++++++++ .../2026-10-gorm-deadlock/deadlock_test.go | 225 ++++++++++++++++++ 3 files changed, 394 insertions(+) create mode 100644 tools/bench/2026-10-batch-result-shape/shape_test.go create mode 100644 tools/bench/2026-10-double-check/doublecheck_test.go create mode 100644 tools/bench/2026-10-gorm-deadlock/deadlock_test.go diff --git a/tools/bench/2026-10-batch-result-shape/shape_test.go b/tools/bench/2026-10-batch-result-shape/shape_test.go new file mode 100644 index 0000000..6cdf730 --- /dev/null +++ b/tools/bench/2026-10-batch-result-shape/shape_test.go @@ -0,0 +1,71 @@ +//go:build bench + +// Compares the cost of three shapes a batch read could return, with half the +// keys missing as in a cache. See docs/research/2026-10-batch-result-shape.md. +// +// go test -tags bench -bench . ./tools/bench/2026-10-batch-result-shape/ +package bench + +import ( + "errors" + "fmt" + "testing" +) + +type result struct { + Value string + Err error +} + +var errNotFound = errors.New("key not found") // one shared instance: no allocation per miss + +func keys(n int) []string { + k := make([]string, n) + for i := range k { + k[i] = fmt.Sprintf("key:%06d", i) + } + return k +} + +func BenchmarkShape(b *testing.B) { + for _, n := range []int{100, 10000} { + ks := keys(n) + b.Run(fmt.Sprintf("map_values/n=%d", n), func(b *testing.B) { // map[string]T, misses absent + b.ReportAllocs() + for b.Loop() { + m := make(map[string]string, n/2) + for i, k := range ks { + if i%2 == 0 { + m[k] = "v" + } + } + } + }) + b.Run(fmt.Sprintf("map_results/n=%d", n), func(b *testing.B) { // map[string]Result, misses as errors + b.ReportAllocs() + for b.Loop() { + m := make(map[string]result, n) + for i, k := range ks { + if i%2 == 0 { + m[k] = result{Value: "v"} + } else { + m[k] = result{Err: errNotFound} + } + } + } + }) + b.Run(fmt.Sprintf("slice_results/n=%d", n), func(b *testing.B) { // []Result aligned with keys + b.ReportAllocs() + for b.Loop() { + s := make([]result, n) + for i := range ks { + if i%2 == 0 { + s[i] = result{Value: "v"} + } else { + s[i].Err = errNotFound + } + } + } + }) + } +} diff --git a/tools/bench/2026-10-double-check/doublecheck_test.go b/tools/bench/2026-10-double-check/doublecheck_test.go new file mode 100644 index 0000000..c6f32f5 --- /dev/null +++ b/tools/bench/2026-10-double-check/doublecheck_test.go @@ -0,0 +1,98 @@ +//go:build bench + +// Measures what the double-check saves and costs, under open-loop load (new +// requests arrive at their own pace, as real traffic does). See +// docs/research/2026-10-double-check.md. +// +// go test -tags bench -run TestDoubleCheckValue -v ./tools/bench/2026-10-double-check/ +package bench + +import ( + "context" + "fmt" + "sync" + "sync/atomic" + "testing" + "time" + + "github.com/theplant/cachex" +) + +// slowBackend answers like a remote cache: it reads, then the reply takes +// delay to come back (the window the double-check is about). +type slowBackend struct { + *cachex.SyncMap[*cachex.Entry[string]] + delay time.Duration + reads atomic.Int64 +} + +func (s *slowBackend) Get(ctx context.Context, key string) (*cachex.Entry[string], error) { + s.reads.Add(1) + v, err := s.SyncMap.Get(ctx, key) + time.Sleep(s.delay) + return v, err +} + +// run sends 20 requests per ms for 400 ms; hot uses one key that expires +// every 20 ms, otherwise every request asks for a new (cold) key. +func run(mode cachex.DoubleCheckMode, delay time.Duration, hot bool) (upstreamCalls int64, readsPerGet float64) { + ctx := context.Background() + backend := &slowBackend{SyncMap: cachex.NewSyncMap[*cachex.Entry[string]](), delay: delay} + var calls atomic.Int64 + up := cachex.UpstreamFunc[*cachex.Entry[string]](func(context.Context, string) (*cachex.Entry[string], error) { + calls.Add(1) + time.Sleep(5 * time.Millisecond) + return &cachex.Entry[string]{Data: "v", CachedAt: cachex.NowFunc()}, nil + }) + cli := cachex.NewClient[*cachex.Entry[string]](backend, up, + cachex.EntryWithTTL[string](20*time.Millisecond, 0), + cachex.WithDoubleCheck[*cachex.Entry[string]](mode)) + + var n atomic.Int64 + var wg sync.WaitGroup + for ms := range 400 { + for j := range 20 { + key := "hot" + if !hot { + key = fmt.Sprintf("cold-%d-%d", ms, j) + } + wg.Go(func() { + _, _ = cli.Get(ctx, key) + n.Add(1) + }) + } + time.Sleep(time.Millisecond) + } + wg.Wait() + return calls.Load(), float64(backend.reads.Load()) / float64(n.Load()) +} + +func TestDoubleCheckValue(t *testing.T) { + modes := []struct { + name string + mode cachex.DoubleCheckMode + }{{"enabled", cachex.DoubleCheckEnabled}, {"auto", cachex.DoubleCheckAuto}, {"disabled", cachex.DoubleCheckDisabled}} + for _, hot := range []bool{true, false} { + for _, delay := range []time.Duration{0, 200 * time.Microsecond, time.Millisecond} { + if !hot && delay != time.Millisecond { + continue // cold keys: only the cost matters, one latency is enough + } + for _, m := range modes { + const rounds = 3 + var calls int64 + var reads float64 + for range rounds { + c, r := run(m.mode, delay, hot) + calls += c + reads += r + } + scenario := "hot key, expires every 20ms" + if !hot { + scenario = "8000 cold keys" + } + t.Logf("%-28s backend=%-6v %-9s upstream calls %5d backend reads per Get %.3f", + scenario, delay, m.name, calls/rounds, reads/rounds) + } + } + } +} diff --git a/tools/bench/2026-10-gorm-deadlock/deadlock_test.go b/tools/bench/2026-10-gorm-deadlock/deadlock_test.go new file mode 100644 index 0000000..5af5e1b --- /dev/null +++ b/tools/bench/2026-10-gorm-deadlock/deadlock_test.go @@ -0,0 +1,225 @@ +//go:build bench + +// Compares ways to keep concurrent GORMCache batch writes from deadlocking, on +// MySQL 8.4 and PostgreSQL 16 in testcontainers (Docker required). See +// docs/research/2026-10-gorm-deadlock.md. +// +// go test -tags bench -run TestDeadlockStrategies -v -timeout 60m ./tools/bench/2026-10-gorm-deadlock/ +// +// WORKERS and ROUNDS (env) scale the load; defaults 16 and 80. The "unordered" +// strategy is slow on PostgreSQL: every deadlock waits out deadlock_timeout. +package bench + +import ( + "cmp" + "context" + "encoding/json" + "fmt" + "math/rand/v2" + "os" + "slices" + "strconv" + "strings" + "sync" + "sync/atomic" + "testing" + "time" + + "github.com/stretchr/testify/require" + "github.com/testcontainers/testcontainers-go" + tcmysql "github.com/testcontainers/testcontainers-go/modules/mysql" + tcpostgres "github.com/testcontainers/testcontainers-go/modules/postgres" + "github.com/theplant/cachex" + "gorm.io/datatypes" + "gorm.io/driver/mysql" + "gorm.io/driver/postgres" + "gorm.io/gorm" + "gorm.io/gorm/clause" + "gorm.io/gorm/logger" +) + +// row matches the table GORMCache.Migrate creates, for the strategies that +// write it with raw GORM (what GORMCache did before the fix). +type row struct { + Key string `gorm:"primaryKey"` + Value datatypes.JSON + UpdatedAt time.Time +} + +func isDeadlock(err error) bool { + if err == nil { + return false + } + s := strings.ToLower(err.Error()) + return strings.Contains(s, "deadlock") || strings.Contains(s, "40p01") || strings.Contains(s, "(40001)") +} + +type strategy struct { + name string + set func(ctx context.Context, db *gorm.DB, c *cachex.GORMCache[string], table string, values map[string]string) error + del func(ctx context.Context, db *gorm.DB, c *cachex.GORMCache[string], table string, keys []string) error +} + +var keyCol = clause.Column{Name: "key"} + +func rawSet(sorted bool) func(context.Context, *gorm.DB, *cachex.GORMCache[string], string, map[string]string) error { + return func(ctx context.Context, db *gorm.DB, _ *cachex.GORMCache[string], table string, values map[string]string) error { + rows := make([]row, 0, len(values)) + for k, v := range values { // Go map order: random + data, _ := json.Marshal(v) + rows = append(rows, row{Key: k, Value: data, UpdatedAt: time.Now()}) + } + if sorted { + slices.SortFunc(rows, func(a, b row) int { return cmp.Compare(a.Key, b.Key) }) + } + return db.WithContext(ctx).Table(table).Clauses(clause.OnConflict{ + Columns: []clause.Column{keyCol}, + DoUpdates: clause.AssignmentColumns([]string{"key", "value", "updated_at"}), + }).Create(&rows).Error + } +} + +func rawDel(ordered bool) func(context.Context, *gorm.DB, *cachex.GORMCache[string], string, []string) error { + return func(ctx context.Context, db *gorm.DB, _ *cachex.GORMCache[string], table string, keys []string) error { + in := clause.IN{Column: keyCol, Values: anys(keys)} + if !ordered || db.Name() != "postgres" { + return db.WithContext(ctx).Table(table).Where(in).Delete(nil).Error + } + locked := db.Session(&gorm.Session{NewDB: true}).Table(table).Select("?", keyCol).Where(in). + Order(clause.OrderBy{Expression: clause.Expr{SQL: `? COLLATE "C"`, Vars: []any{keyCol}, WithoutParentheses: true}}). + Clauses(clause.Locking{Strength: clause.LockingStrengthUpdate}) + return db.WithContext(ctx).Table(table).Where("? IN (?)", keyCol, locked).Delete(nil).Error + } +} + +func anys(keys []string) []any { + out := make([]any, len(keys)) + for i, k := range keys { + out[i] = k + } + return out +} + +// tableLocked serializes every write to the table: a named lock on MySQL, held +// on one connection around the whole transaction (taken before BEGIN, released +// after COMMIT); an advisory transaction lock on PostgreSQL. Either has the +// effect of a table lock. +func tableLocked(ctx context.Context, db *gorm.DB, table string, f func(ctx context.Context) error) error { + if db.Name() != "mysql" { + return db.WithContext(ctx).Transaction(func(tx *gorm.DB) error { + if err := tx.Exec("SELECT pg_advisory_xact_lock(hashtext(?))", "bench:"+table).Error; err != nil { + return err + } + return f(cachex.WithGORMTx(ctx, tx)) + }) + } + return db.WithContext(ctx).Connection(func(conn *gorm.DB) error { + if err := conn.Exec("SELECT GET_LOCK(?, 30)", "bench:"+table).Error; err != nil { + return err + } + defer conn.Exec("SELECT RELEASE_LOCK(?)", "bench:"+table) + return conn.Transaction(func(tx *gorm.DB) error { return f(cachex.WithGORMTx(ctx, tx)) }) + }) +} + +var strategies = []strategy{ + {name: "unordered", set: rawSet(false), del: rawDel(false)}, + {name: "ordered", set: rawSet(true), del: rawDel(true)}, + {name: "ordered+retry (GORMCache)", + set: func(ctx context.Context, _ *gorm.DB, c *cachex.GORMCache[string], _ string, v map[string]string) error { + return c.SetMany(ctx, v) + }, + del: func(ctx context.Context, _ *gorm.DB, c *cachex.GORMCache[string], _ string, k []string) error { + return c.DelMany(ctx, k) + }}, + {name: "table lock", + set: func(ctx context.Context, db *gorm.DB, c *cachex.GORMCache[string], table string, v map[string]string) error { + return tableLocked(ctx, db, table, func(ctx context.Context) error { return c.SetMany(ctx, v) }) + }, + del: func(ctx context.Context, db *gorm.DB, c *cachex.GORMCache[string], table string, k []string) error { + return tableLocked(ctx, db, table, func(ctx context.Context) error { return c.DelMany(ctx, k) }) + }}, +} + +func envInt(name string, def int) int { + if v, err := strconv.Atoi(os.Getenv(name)); err == nil && v > 0 { + return v + } + return def +} + +func TestDeadlockStrategies(t *testing.T) { + testcontainers.SkipIfProviderIsNotHealthy(t) + ctx := context.Background() + workers, rounds := envInt("WORKERS", 16), envInt("ROUNDS", 80) + + mc, err := tcmysql.Run(ctx, "mysql:8.4") + testcontainers.CleanupContainer(t, mc) + require.NoError(t, err) + mdsn, err := mc.ConnectionString(ctx, "parseTime=true") + require.NoError(t, err) + pc, err := tcpostgres.Run(ctx, "postgres:16", tcpostgres.BasicWaitStrategies()) + testcontainers.CleanupContainer(t, pc) + require.NoError(t, err) + pdsn, err := pc.ConnectionString(ctx, "sslmode=disable") + require.NoError(t, err) + + // mixed case: byte order differs from PostgreSQL's default en_US collation + keys := make([]string, 2000) + for i := range keys { + keys[i] = fmt.Sprintf("%c%04d", "aBcD"[i%4], i) + } + + for _, d := range []struct { + name string + dial gorm.Dialector + }{{"mysql", mysql.Open(mdsn)}, {"postgres", postgres.Open(pdsn)}} { + db, err := gorm.Open(d.dial, &gorm.Config{Logger: logger.Discard}) + require.NoError(t, err) + sqlDB, err := db.DB() + require.NoError(t, err) + sqlDB.SetMaxOpenConns(32) + + for i, st := range strategies { + table := fmt.Sprintf("bench_deadlock_%d", i) + require.NoError(t, db.Exec("DROP TABLE IF EXISTS "+table).Error) + c := cachex.NewGORMCache[string](&cachex.GORMCacheConfig{DB: db, TableName: table}) + require.NoError(t, c.Migrate(ctx)) + + var deadlocks, ops atomic.Int64 + start := time.Now() + var wg sync.WaitGroup + for range workers { + wg.Go(func() { + for range rounds { + pick := rand.Perm(len(keys))[:100] + var err error + if rand.IntN(10) < 6 { + values := map[string]string{} + for _, j := range pick { + values[keys[j]] = "v" + } + err = st.set(ctx, db, c, table, values) + } else { + sub := make([]string, len(pick)) + for n, j := range pick { + sub[n] = keys[j] + } + err = st.del(ctx, db, c, table, sub) + } + ops.Add(1) + if isDeadlock(err) { + deadlocks.Add(1) + } else if err != nil { + t.Errorf("%s/%s: %v", d.name, st.name, err) + } + } + }) + } + wg.Wait() + elapsed := time.Since(start) + t.Logf("%-8s %-26s deadlocks %4d / %d %7.2fs %6.0f ops/s", + d.name, st.name, deadlocks.Load(), ops.Load(), elapsed.Seconds(), float64(ops.Load())/elapsed.Seconds()) + } + } +} From 083a66425aa65a783e0492ce47e1eafb5687f65c Mon Sep 17 00:00:00 2001 From: molon <3739161+molon@users.noreply.github.com> Date: Sat, 10 Oct 2026 12:06:41 +0800 Subject: [PATCH 36/40] docs: design notes, glossary, ADRs, FAQ and measurements, in Chinese - GLOSSARY.md: the project's terms, each with the English term used in code. - docs/design.md and docs/design/: the read path, singleflight, write order and striped locks, batch reads, backends, and consistency across instances, with sequence and data flow diagrams. - docs/adr/: eleven decisions, including where cachex deliberately departs from x/sync/singleflight. - docs/faq.md replaces the README FAQ; docs/todo.md replaces TODO.md and TODO_ZH.md, with TTL jitter first; docs/research/ holds the measurements behind the decisions. - README.md and README_ZH.md link to the docs; CLAUDE.md lists what to read first, the conventions and the invariants. --- CLAUDE.md | 54 +++ GLOSSARY.md | 157 +++++++++ README.md | 40 +-- README_ZH.md | 40 +-- TODO.md | 147 --------- TODO_ZH.md | 146 --------- docs/adr/0001-own-flight-group.md | 14 + docs/adr/0002-upstream-first-writes.md | 15 + docs/adr/0003-striped-backfill-guard.md | 18 + docs/adr/0004-batch-result-shape.md | 18 + docs/adr/0005-best-effort-batch-writes.md | 14 + docs/adr/0006-goexit-publishes-an-error.md | 16 + docs/adr/0007-detached-fetch-context.md | 18 + docs/adr/0008-on-demand-double-check.md | 24 ++ .../adr/0009-gorm-exact-keys-and-collation.md | 20 ++ .../0010-gorm-deadlock-ordering-and-retry.md | 25 ++ ...0011-cross-instance-consistency-via-ttl.md | 15 + docs/design.md | 125 +++++++ docs/design/backends.md | 106 ++++++ docs/design/batch.md | 132 ++++++++ docs/design/consistency.md | 97 ++++++ docs/design/read-path.md | 177 ++++++++++ docs/design/singleflight.md | 145 ++++++++ docs/design/write-order.md | 310 ++++++++++++++++++ docs/faq.md | 132 ++++++++ docs/research/2026-10-batch-result-shape.md | 37 +++ docs/research/2026-10-double-check.md | 47 +++ docs/research/2026-10-gorm-deadlock.md | 70 ++++ docs/research/README.md | 9 + docs/todo.md | 162 +++++++++ 30 files changed, 1973 insertions(+), 357 deletions(-) create mode 100644 CLAUDE.md create mode 100644 GLOSSARY.md delete mode 100644 TODO.md delete mode 100644 TODO_ZH.md create mode 100644 docs/adr/0001-own-flight-group.md create mode 100644 docs/adr/0002-upstream-first-writes.md create mode 100644 docs/adr/0003-striped-backfill-guard.md create mode 100644 docs/adr/0004-batch-result-shape.md create mode 100644 docs/adr/0005-best-effort-batch-writes.md create mode 100644 docs/adr/0006-goexit-publishes-an-error.md create mode 100644 docs/adr/0007-detached-fetch-context.md create mode 100644 docs/adr/0008-on-demand-double-check.md create mode 100644 docs/adr/0009-gorm-exact-keys-and-collation.md create mode 100644 docs/adr/0010-gorm-deadlock-ordering-and-retry.md create mode 100644 docs/adr/0011-cross-instance-consistency-via-ttl.md create mode 100644 docs/design.md create mode 100644 docs/design/backends.md create mode 100644 docs/design/batch.md create mode 100644 docs/design/consistency.md create mode 100644 docs/design/read-path.md create mode 100644 docs/design/singleflight.md create mode 100644 docs/design/write-order.md create mode 100644 docs/faq.md create mode 100644 docs/research/2026-10-batch-result-shape.md create mode 100644 docs/research/2026-10-double-check.md create mode 100644 docs/research/2026-10-gorm-deadlock.md create mode 100644 docs/research/README.md create mode 100644 docs/todo.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..f6155c1 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,54 @@ +# cachex + +Go 泛型多层缓存客户端:合并回源、二次检查、不存在缓存、返回陈旧值、批量读、写入顺序保证;后端有 Ristretto、SyncMap、BigCache、Redis、GORM。 + +## 先读什么 + +| 文档 | 什么时候读 | +|---|---| +| [docs/design.md](docs/design.md) | 动任何机制之前:现行设计总览和各分篇的链接 | +| [GLOSSARY.md](GLOSSARY.md) | 写文档、写注释、和用户讨论时,用这里的叫法 | +| [docs/adr/](docs/adr/) | 想改一个「看起来很奇怪」的做法之前,先看有没有对应的决策 | +| [docs/todo.md](docs/todo.md) | 发现了但这次不解决的问题都在这里 | +| [docs/faq.md](docs/faq.md) | 用户问过的问题 | +| [docs/research/](docs/research/README.md) | 实测数据;复跑脚本在 `tools/bench/` | + +## 仓库布局 + +- 根目录就是 `cachex` 包:`client.go`(单 key 读取、写入、分片锁)、`batch.go`(批量读、合并回源的 `flightGroup`)、`double_check.go`、`entry.go`、各后端(`ristretto.go`、`syncmap.go`、`bigcache.go`、`redis.go`、`gorm.go`、`transform.go`)。 +- 测试和代码放在一起。`get_compat_test.go` 固定了单 key `Get` 和 main 一致的可观察行为,改它要有对应的 ADR。`gorm_container_test.go` 用 testcontainers 在 MySQL 和 PostgreSQL 上跑,没有 Docker 时自动跳过。 +- `tools/bench/<日期-主题>/`:实测的复跑脚本,带 `bench` build tag,平时的 `go test ./...` 不会运行。 + +## 常用命令 + +```sh +go test -race ./... # 全量,约 3 分钟 +go test -short -p=1 -count=1 ./... # CI 的跑法 +golangci-lint run ./... # 用 CI 锁定的 v2.13.2;本机旧版本跑不了 go1.26 的代码 +go test -tags bench -v -run ./tools/bench/<目录>/ # 复跑实测 +``` + +并发相关的测试要用钩子或 channel 控制时序,不靠 `sleep` 碰运气;新加的时序测试用 `-race -count=20` 以上跑几遍确认稳定。修 bug 时先写能复现的测试,确认它在旧代码上失败。 + +## 协作约定 + +- **文档语言**:`README.md`/`README_ZH.md` 和 `BENCHMARK.md`/`BENCHMARK_ZH.md` 是中英双语,**两份必须逐段一一对应**,改一份就同步改另一份。其余文档(`GLOSSARY.md`、`docs/` 下的全部、本文件)只写中文;术语表里保留每个术语对应的英文。 +- **设计结论写回 design**:只写现在成立的设计,被推翻的直接删,理由写进 ADR。专题写进 `docs/design/` 的对应分篇,`docs/design.md` 跟着同步。 +- **ADR**:只给难回退、没有背景会让人意外、确实有过取舍的决定写,编号递增。 +- **不解决的问题记 todo**:当场记进 `docs/todo.md`,解决了就删。 +- **用户问过的问题记 faq**:先给结论,再给依据。 +- **实测存档**:报告写进 `docs/research/` 并更新索引,脚本放进 `tools/bench/<日期-主题>/`。 +- **文档里不引用其他缓存库或同类项目**。依赖的库(例如 `golang.org/x/sync`)和 Go 官方的 issue 可以引用。 +- **提交和 PR**:提交信息、PR 描述用英文,照仓库现有的风格写,不加任何 AI 署名。行为变了就更新 PR 描述里的行为变化表。 + +## 底线 + +这些地方最容易被「顺手优化」改坏: + +- **先写上游,再写本层;任何失败都删掉本层条目。** 不要改回「先写本层」。见 [ADR 0002](docs/adr/0002-upstream-first-writes.md)。 +- **回填必须持分片读锁、核对写入代数,写入之后还要摘除在途回源。** 少任何一步,旧值都可能盖过写入。见 [ADR 0003](docs/adr/0003-striped-backfill-guard.md)。 +- **每个在途回源恰好发布一次结果**,panic 和 Goexit 也不例外。不要让等待方去等一个永远不会来的结果。见 [ADR 0006](docs/adr/0006-goexit-publishes-an-error.md)。 +- **回源用的 ctx 不带领头请求的取消,也不带它的 GORM 事务。** 见 [ADR 0007](docs/adr/0007-detached-fetch-context.md)。 +- **批量读里,不存在不是错误**,缺席的 key 就是不存在;整批失败的错误不能被当成「全部不存在」。见 [ADR 0004](docs/adr/0004-batch-result-shape.md)。 +- **GORMCache 的 key 列条件要用 clause 构造**(`key` 是 MySQL 的保留字),**只返回 key 完全相等的行**,**批量写按字节序加锁**。见 [ADR 0009](docs/adr/0009-gorm-exact-keys-and-collation.md)、[ADR 0010](docs/adr/0010-gorm-deadlock-ordering-and-retry.md)。 +- **Redis pipeline 的错误要逐条命令判断**,连接层面的失败要设到没发出去的命令上,否则 `GET` 会把故障读成空值。见 [design/backends.md](docs/design/backends.md#批量pipeline)。 diff --git a/GLOSSARY.md b/GLOSSARY.md new file mode 100644 index 0000000..b424bf9 --- /dev/null +++ b/GLOSSARY.md @@ -0,0 +1,157 @@ +# cachex 术语表 + +cachex 是一个多层缓存客户端:一层缓存未命中时向下一层取值,并负责合并并发请求、处理过期和不存在的 key、保证写入在各层的先后顺序。本表统一这些概念的叫法,括号里是代码和英文文档中对应的术语。 + +## 层与数据 + +**层(layer)**: +一个 Client 连同它自己的存储,构成缓存链路上的一级,例如内存层、Redis 层。 +_避免_:级、tier + +**后端(backend)**: +一层用来存值的存储,例如 Ristretto、Redis、数据库表。 +_避免_:store、存储层 + +**上游(upstream)**: +一层未命中时去取值的地方,可以是下一层,也可以是数据源。 +_避免_:下游、loader + +**数据源(source)**: +链路最底层、保存真实数据的地方,通常是数据库或其他服务;它不是缓存。 +_避免_:origin、源站 + +**条目(entry)**: +后端里为一个 key 存的一份值。 +_避免_:item + +**不存在记录(not-found entry)**: +不存在缓存里为一个 key 记下的「它在上游不存在」,带有记录的时间,同样分新鲜、陈旧、腐烂。 + +## 新鲜度 + +**新鲜(fresh)**: +条目还在可信期内,直接作为结果返回。 + +**陈旧(stale)**: +条目已过可信期、但仍在可用期内:开启返回陈旧值时先返回它,同时在后台刷新。 +_避免_:过期(容易和「腐烂」混淆) + +**腐烂(rotten)**: +条目已过可用期,不能再返回,必须回源。 +_避免_:过期、失效 + +**新鲜期 / 陈旧期(fresh TTL / stale TTL)**: +条目保持新鲜的时长,以及新鲜期之后还能作为陈旧值返回的额外时长。 + +## 读取 + +**命中 / 未命中(hit / miss)**: +一层在后端里找到 / 没找到可用条目。 + +**回源(fetch)**: +一层因为未命中或条目腐烂,向上游取值。 +_避免_:load、加载、拉取 + +**回填(backfill)**: +回源拿到结果后,把它写进本层(值写进后端,「不存在」写进不存在缓存)。 +_避免_:write-back、写回、回写 + +**刷新(refresh)**: +为了更新陈旧条目而在后台发起的回源,调用方不等它。 +_避免_:重新加载 + +**返回陈旧值(serve-stale)**: +读到陈旧条目时先把它返回、再在后台刷新的读取方式。 +_避免_:stale-while-revalidate(意思相同,但本项目不用这个叫法) + +**不存在缓存(not-found cache)**: +专门记录「这个 key 在上游不存在」的缓存,有自己的新鲜期和陈旧期。 +_避免_:空值缓存、negative cache + +**二次检查(double-check)**: +认领回源之后、真正去上游之前,再读一次本层,看是否有别的请求刚把结果写进来。 +_避免_:双重检查锁 + +## 合并回源 + +**在途回源(flight)**: +一个 key 正在进行、尚未发布结果的回源;同一个 key 的并发请求共用它。 + +**认领(claim)**: +请求为一个 key 登记在途回源;登记成功即成为领头请求,否则成为等待方。 + +**领头请求(leader)**: +认领成功、由它发起这次回源的请求;它和等待方一样等待结果。 +_避免_:owner、主请求 + +**等待方(waiter)**: +发现 key 已有在途回源、等待它的结果的请求。 + +**发布(publish)**: +在途回源把结果(值或错误)交给所有等待方,并结束这次在途回源。 + +**摘除(drop)**: +在不打断的前提下,把一个在途回源从登记中移除:已在等的请求照样拿到结果,之后来的请求重新回源。 + +**回源槽位(fetch slot)**: +同一个 key 允许同时存在的在途回源份数;默认 1 份,即完全合并。 + +## 写入 + +**写入(write)**: +调用方主动发起的 `Set` 或 `Del`,从本层一路写到不再是缓存的那一层为止。 +_避免_:更新(容易和回填混淆) + +**失效(invalidate)**: +删掉一层里某个 key 的条目和不存在记录,让下次读取回源。 + +**写入顺序(write order)**: +先写上游、再写本层;同一个 key 的写入在各层按同一顺序生效。 + +**分片锁(striped lock)**: +把 key 按哈希分进固定数量的分片、每个分片一把锁的做法,用来给同一个 key 的写入和回填排序,而不用为每个 key 单独建锁。 + +**分片(stripe)**: +key 按哈希分成的固定若干组之一;同一组的 key 共用一份写入协调状态。 +_避免_:分段(分段指 chunk)、桶、segment + +**写入代数(write generation)**: +一个分片上已发生的写入次数,用来判断「回源期间有没有发生写入」。 + +**分片纪元(stripe epoch)**: +一个分片上写入与回填的总次数,用来判断「读取之后本层有没有被写过」。 + +## 批量 + +**批量读(batch read)**: +一次调用读取多个 key(`GetMany`),语义与逐个读取相同。 + +**批量上游(batch upstream)**: +能一次回答多个 key 的上游。 + +**分段(chunk)**: +大批量被切成的一部分,每一段单独发出一次调用或一条语句。 +_避免_:批(单独说「批」时指整个批量读)、分片(分片指 stripe) + +**整批失败(whole-batch failure)**: +一次批量调用整体出错,无法知道哪些 key 成功;所有 key 都按失败处理。 + +**部分失败(partial failure)**: +一次批量调用里只有部分 key 出错,其余 key 正常返回。 + +**三种结果(outcome)**: +每个 key 读取后必然是三者之一:找到(值可以是 nil)、不存在、失败。 + +## 一致性 + +**旧值回填(stale backfill)**: +回源读到旧值后,在一次写入完成之后才把旧值回填进去,导致这次写入被悄悄撤销。 + +**实例(instance)**: +运行 cachex 的一个进程;多个实例可能共用 Redis 或数据库这样的下层。 + +**租约(lease)**: +(尚未实现)由共享层发给领头请求的令牌;写入会让令牌作废,持有作废令牌的回填被拒绝。 + +**失效广播(invalidation broadcast)**: +(尚未实现)一个实例写入后通知其他实例失效各自内存层的做法。 diff --git a/README.md b/README.md index 219e4d4..df2fb37 100644 --- a/README.md +++ b/README.md @@ -521,40 +521,16 @@ user, err := userCache.Get(ctx, "user:123") > > 📊 **Throughput Amplification** = Application QPS / Theoretical DB Capacity, where Theoretical DB Capacity = Conn Pool / (Latency / 1000ms). -## FAQ +## Documentation -### Q: When should I use `Entry[T]` vs custom staleness? +Design notes for maintainers and readers who want the details, in Chinese only: -**A:** Use `Entry[T]` with `EntryWithTTL` for simple time-based expiration. Use custom staleness checkers when you need domain-specific logic (e.g., checking a `version` field). - -### Q: How does cache stampede protection work? - -**A:** Cachex uses a two-layer defense based on the philosophy of **concurrent exploration + result convergence**: - -1. **Singleflight with Concurrency Control** (Primary): - - - **Exploration phase**: When cache misses, `WithFetchConcurrency` allows N concurrent fetches to maximize throughput - - **Default (N=1)**: Full deduplication - only one fetch, others wait (99%+ redundancy elimination) - - **N > 1**: Moderate redundancy - requests distributed across N slots for higher throughput - -2. **DoubleCheck** (Supplementary): - - Handles the window where Request B reads the cache (miss) just before Request A's fetch writes it, but claims the key only after A's fetch finished: B re-reads instead of fetching again - - Works **across all singleflight slots**, enabling fast convergence after first successful fetch - - The saving grows with how long a cache read takes to come back and how hot the key is. Measured with a key requested 20 times per ms, expiring every 20 ms, a 5 ms upstream and a cache answering in 1 ms: 18 upstream calls with it, 30 without; with an in-memory cache, no difference - - Default `DoubleCheckAuto` re-checks only when this `Client` wrote the key's stripe since the request read the cache, so cold keys and keys that do not exist skip the useless re-read (measured over 8000 cold keys: 1.004 cache reads per `Get`, against 2 with `DoubleCheckEnabled`) - - Configure with `WithDoubleCheck(DoubleCheckEnabled/Disabled/Auto)`; `DoubleCheckEnabled` also catches values other processes wrote to a shared cache - -### Q: What's the difference between fresh and stale TTL? - -**A:** Fresh TTL defines how long data is considered fresh. Stale TTL defines an **additional** period during which data can be served as stale (with async refresh). Total lifetime = `freshTTL + staleTTL`. - -### Q: Should I cache all database queries? - -**A:** No. Cache frequently accessed, relatively static data. Avoid caching: - -- Data that changes frequently (< 1s freshness requirement) -- User-specific data with high cardinality -- Large objects that don't fit in memory efficiently +- [Design overview](docs/design.md) (Chinese): the model, the architecture, and one page per mechanism: read path, singleflight, write order and striped locks, batch reads, backends, consistency across instances +- [FAQ](docs/faq.md) (Chinese) +- [Glossary](GLOSSARY.md) (Chinese, with the English terms used in code) +- [Architecture decision records](docs/adr/) (Chinese) +- [Measurements](docs/research/README.md) (Chinese) and their re-runnable scripts in `tools/bench/` +- [To do](docs/todo.md) (Chinese) ## License diff --git a/README_ZH.md b/README_ZH.md index 440cffb..b5e3de9 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -519,40 +519,16 @@ user, err := userCache.Get(ctx, "user:123") > > 📊 **吞吐量放大** = 应用层 QPS / 理论 DB 吞吐量,其中理论 DB 吞吐量 = 连接池大小 / (延迟 / 1000ms)。 -## 常见问题 +## 文档 -### Q: 何时应该使用 `Entry[T]` 而不是自定义陈旧检查? +面向维护者和想深入了解的读者的设计文档,只有中文版: -**A:** 对于简单的基于时间的过期,使用 `Entry[T]` 配合 `EntryWithTTL`。当需要领域特定逻辑(如检查 `version` 字段)时,使用自定义陈旧检查器。 - -### Q: 缓存击穿防护如何工作? - -**A:** Cachex 使用基于**并发探索 + 结果收敛**哲学的双层防御机制: - -1. **Singleflight 并发控制**(主要): - - - **探索阶段**:缓存 miss 时,`WithFetchConcurrency` 允许 N 个并发 fetch 以最大化吞吐量 - - **默认 (N=1)**:完全去重 - 仅一次 fetch,其他等待(消除 99%+ 冗余) - - **N > 1**:适度冗余 - 请求分布在 N 个 slot 中,提升吞吐量 - -2. **DoubleCheck**(辅助): - - 处理这样的窗口:请求 B 在请求 A 的回源写入缓存之前读到未命中,却在 A 的回源结束之后才认领这个 key;B 改为再读一次缓存,而不是再回源一次 - - **跨所有 singleflight slot 工作**,确保首次成功 fetch 后快速收敛 - - 收益随缓存读的响应时间和 key 的热度增长。实测:一个 key 每毫秒 20 次请求、每 20ms 过期一次、上游 5ms、缓存 1ms 响应时,开启时上游调用 18 次,关闭时 30 次;内存缓存则没有区别 - - 默认的 `DoubleCheckAuto` 只在请求读缓存之后、本 `Client` 写过这个 key 所在分片时才再读,冷 key 和不存在的 key 就不会白读一次(实测 8000 个冷 key:每次 `Get` 读缓存 1.004 次,`DoubleCheckEnabled` 是 2 次) - - 用 `WithDoubleCheck(DoubleCheckEnabled/Disabled/Auto)` 配置;`DoubleCheckEnabled` 还能抓到其他进程写进共享缓存的值 - -### Q: 新鲜 TTL 和过期 TTL 有什么区别? - -**A:** 新鲜 TTL 定义数据被视为新鲜的时长。过期 TTL 定义在新鲜期后的**额外**时长,在此期间数据可作为陈旧数据提供(并异步刷新)。总生命周期 = `新鲜TTL + 过期TTL`。 - -### Q: 是否应该缓存所有数据库查询? - -**A:** 不应该。缓存频繁访问、相对静态的数据。避免缓存: - -- 频繁变化的数据(< 1s 新鲜度要求) -- 高基数的用户特定数据 -- 不适合在内存中高效存储的大对象 +- [设计总览](docs/design.md):核心模型、架构,以及每个机制的分篇(读取路径、合并回源、写入顺序与分片锁、批量读、后端、多实例一致性) +- [常见问题](docs/faq.md) +- [术语表](GLOSSARY.md):附代码中使用的英文术语 +- [架构决策记录](docs/adr/) +- [实测与调研](docs/research/README.md),复跑脚本在 `tools/bench/` +- [待办](docs/todo.md) ## 许可证 diff --git a/TODO.md b/TODO.md deleted file mode 100644 index 11895b6..0000000 --- a/TODO.md +++ /dev/null @@ -1,147 +0,0 @@ -# TODO - -## GORM Cache Improvements - -### Cleanup Worker - -Implement a background cleanup worker for `GORMCache` to remove stale entries: - -- **Requirements:** - - - Must operate with fine-grained batches (avoid large bulk deletions) - - Should run continuously with a configurable interval - - Delete strategy: small batches over time (e.g., 100 entries per batch) - - Should respect database load and implement backpressure - - Consider adding metrics for monitoring cleanup operations - -- **Implementation considerations:** - - Use `updated_at` timestamp for identifying stale entries - - Configurable staleness threshold (e.g., delete entries older than 7 days) - - Graceful shutdown support (stop worker when cache is closed) - - Optional: adaptive batch sizing based on database performance - -## Hotness Statistics - -### Core Hotness Tracking Feature - -Implement a hotness statistics mechanism to track cache key access patterns: - -- **Requirements:** - - - Track access frequency for each key - - Track last access timestamp - - Decay mechanism to reduce weight of old accesses - - Efficient data structure (e.g., concurrent map or time-windowed counter) - - Configurable retention period for statistics - -- **Metrics to track:** - - Hit count per key - - Last access time - - Access rate (hits per time window) - - Optional: distinguish between cache hits and cache misses - -### CacheWrapper for Hot Key Recording - -Implement a `CacheWrapper` that wraps existing `Cache` implementations to record hot keys: - -- **Requirements:** - - - Wraps any `Cache[T]` implementation - - Records top N hottest keys based on access patterns - - Export hot keys list on `Close()` for persistence - - Support loading hot keys on startup for cache warming - -- **Use cases:** - - - Identify which keys should be warmed up on application restart - - Analyze cache access patterns - - Optimize cache allocation strategies - -- **API design considerations:** - -```go -type HotKeyRecorder[T any] struct { - backend Cache[T] - stats *HotnessStats - topN int -} - -// Export hot keys when closing -func (h *HotKeyRecorder[T]) Close() (hotKeys []string, err error) - -// Load hot keys for warming -// Note: For batch warming with RistrettoCache, Wait() can be called once -// at the end after all Set operations to improve performance -func (h *HotKeyRecorder[T]) WarmUp(ctx context.Context, keys []string) error -``` - -### Traffic Shaping Based on Hotness - -Implement a traffic shaping mechanism to protect upstream services and databases: - -- **Requirements:** - - - Differentiate fetch concurrency based on key hotness - - Hot keys: higher concurrency (faster response for majority users) - - Cold keys: lower concurrency (protect database stability) - - Gradual throttling to avoid sudden traffic spikes - -- **Implementation strategy:** - - - Maintain separate fetch concurrency limits for hot/cold keys - - Hot key threshold: configurable percentile (e.g., top 20% by access rate) - - Cold keys: use smaller concurrency or rate limiting - - Dynamic adjustment based on real-time access patterns - -- **Configuration example:** - -```go -type TrafficShapingConfig struct { - HotKeyConcurrency int // e.g., 10 - ColdKeyConcurrency int // e.g., 2 - HotKeyPercentile float64 // e.g., 0.8 (top 20%) -} -``` - -- **Benefits:** - - Protect database from cold key storms - - Ensure good performance for majority of users (hot keys) - - Prevent slow queries on cold keys from affecting hot key performance - - Better resource allocation under high load - -## Implementation Priority - -1. **Phase 1:** Hotness Statistics (foundation for other features) -2. **Phase 2:** CacheWrapper for Hot Key Recording (enables cache warming) -3. **Phase 3:** GORM Cleanup Worker (operational stability) -4. **Phase 4:** Traffic Shaping (advanced optimization) - -## Additional Considerations - -- All features should be optional and configurable -- Maintain backward compatibility with existing API -- Add comprehensive benchmarks to measure overhead -- Document performance characteristics and trade-offs - -## Consistency Across Instances - -The write stripes order writes only within one `Client` process. With several instances sharing a lower layer such as Redis, the two points below rely on TTLs for now (see "Write order and consistency" in the README). - -### Keep stale backfills out of a shared cache with Redis leases - -- **Problem:** instance A misses and reads an old value from the source; instance B then writes the source and updates or deletes the shared cache; A writes the old value back into the shared cache, where it stays until its TTL. -- **Approach (leases, from Facebook's memcache paper):** - - On a miss, a Lua script atomically runs `GET k` and, if empty, sets `lease:k = random token` and returns the token (the read and the lease must be one atomic step) - - Every write (Set/Del) also deletes `lease:k`, voiding all outstanding tokens (it can share the write's pipeline) - - A backfill runs another Lua script that writes the value only if `lease:k` still holds its token -- **Cost:** no extra round trips; a miss writes one lease key, a backfill uses `EVALSHA`, a write adds one `DEL`. The data source needs no version numbers. -- **Implementation considerations:** - - A new optional interface (e.g. `LeaseCache`), used by the Client only when the backend implements it; batch reads need batch leases - - `RedisCache` first; `GORMCache` if needed (a lease column or table with conditional updates) - - Delayed double delete only narrows the window and is lost when the process exits; not worth building in - -### Broadcast invalidations with Redis Pub/Sub (optional) - -- **Problem:** a write made on one instance does not reach the memory layers of the others, which serve the old value until it expires. -- **Approach:** after a write, publish the changed keys on a channel; subscribed instances delete them from their memory layer. -- **Note:** messages are lost while disconnected, so TTLs remain the backstop; make it opt-in, off by default. diff --git a/TODO_ZH.md b/TODO_ZH.md deleted file mode 100644 index 955bd91..0000000 --- a/TODO_ZH.md +++ /dev/null @@ -1,146 +0,0 @@ -# 待办事项 - -## GORM 缓存改进 - -### 清理 Worker - -为 `GORMCache` 实现后台清理 worker,用于删除过期条目: - -- **需求:** - - - 必须使用细粒度批次操作(避免大批量删除) - - 应持续运行,具有可配置的间隔时间 - - 删除策略:细水长流(例如每批 100 条记录) - - 应考虑数据库负载并实现背压机制 - - 考虑添加监控指标以观察清理操作 - -- **实现考虑:** - - 使用 `updated_at` 时间戳识别过期条目 - - 可配置的过期阈值(例如删除 7 天前的条目) - - 支持优雅关闭(缓存关闭时停止 worker) - - 可选:基于数据库性能的自适应批次大小 - -## 热度统计 - -### 核心热度追踪功能 - -实现热度统计机制以跟踪缓存键的访问模式: - -- **需求:** - - - 跟踪每个键的访问频率 - - 跟踪最后访问时间戳 - - 衰减机制以降低旧访问的权重 - - 高效的数据结构(例如并发 map 或时间窗口计数器) - - 可配置的统计数据保留期限 - -- **需要追踪的指标:** - - 每个键的命中次数 - - 最后访问时间 - - 访问速率(每时间窗口的命中次数) - - 可选:区分缓存命中和缓存未命中 - -### 用于热点 Key 记录的 CacheWrapper - -实现一个 `CacheWrapper`,包装现有的 `Cache` 实现以记录热点键: - -- **需求:** - - - 包装任何 `Cache[T]` 实现 - - 基于访问模式记录最热的 N 个键 - - 在 `Close()` 时导出热点键列表以供持久化 - - 支持启动时加载热点键进行缓存预热 - -- **使用场景:** - - - 识别应用重启时应预热哪些键 - - 分析缓存访问模式 - - 优化缓存分配策略 - -- **API 设计考虑:** - -```go -type HotKeyRecorder[T any] struct { - backend Cache[T] - stats *HotnessStats - topN int -} - -// 关闭时导出热点键 -func (h *HotKeyRecorder[T]) Close() (hotKeys []string, err error) - -// 加载热点键进行预热 -// 注意:批量预热时(如使用 RistrettoCache),可以在所有 Set 操作完成后 -// 最后统一调用一次 Wait() 来提升性能 -func (h *HotKeyRecorder[T]) WarmUp(ctx context.Context, keys []string) error -``` - -### 基于热度的流量整形 - -实现流量整形机制以保护上游服务和数据库: - -- **需求:** - - - 根据键的热度区分 fetch 并发度 - - 热点键:更高并发度(为大多数用户提供更快响应) -冷门键:较低并发度(保护数据库稳定性) - - 渐进式限流以避免突发流量峰值 - -- **实现策略:** - - - 为热点/冷门键维护独立的 fetch 并发限制 - - 热点键阈值:可配置的百分位数(例如按访问率排名前 20%) - - 冷门键:使用较小的并发度或速率限制 - - 基于实时访问模式的动态调整 - -- **配置示例:** - -```go -type TrafficShapingConfig struct { - HotKeyConcurrency int // 例如 10 - ColdKeyConcurrency int // 例如 2 - HotKeyPercentile float64 // 例如 0.8(前 20%) -} -``` - -- **优势:** - - 保护数据库免受冷门键风暴的影响 - - 确保大多数用户(热点键)的良好性能 - - 防止冷门键的慢查询影响热点键性能 - - 高负载下更好的资源分配 - -## 实现优先级 - -1. **阶段 1:** 热度统计(其他功能的基础) -2. **阶段 2:** 用于热点键记录的 CacheWrapper(启用缓存预热) -3. **阶段 3:** GORM 清理 Worker(运维稳定性) -4. **阶段 4:** 流量整形(高级优化) - -## 其他考虑 - -- 所有功能应该是可选的且可配置的 -- 保持与现有 API 的向后兼容性 -- 添加全面的基准测试以衡量开销 -- 记录性能特征和权衡取舍 - -## 多实例一致性 - -分片锁只在单个 `Client` 进程内保证顺序。多个实例共用 Redis 等下层时,以下两点目前只靠 TTL 兜底(README「写入顺序与一致性」一节有说明)。 - -### 用 Redis lease 防止旧值回填进共享缓存 - -- **问题:** 实例 A 未命中,从数据源读到旧值;实例 B 随即写入数据源并更新或删除共享缓存;A 再把旧值回填进共享缓存,旧值一直留到 TTL 到期。 -- **做法(Facebook memcache 论文中的 lease):** - - 读未命中时,用一段 Lua 原子地 `GET k`,若为空就写入 `lease:k = 随机令牌` 并返回令牌(读和领租约必须在同一原子操作里) - - 任何写入(Set/Del)同时删除 `lease:k`,让在途令牌全部作废(可放进同一个 pipeline) - - 回填用另一段 Lua:只有 `lease:k` 仍等于自己的令牌才写入值 -- **代价:** 往返次数不变;未命中多写一个租约 key,回填改用 `EVALSHA`,写入多一个 `DEL`。不需要数据源提供版本号。 -- **实现考虑:** - - 新增可选接口(例如 `LeaseCache`),后端支持时 Client 才走这条路;批量读要支持批量领租约 - - 先做 `RedisCache`;`GORMCache` 视需要跟进(租约列或租约表 + 条件更新) - - 延迟双删只能缩小窗口、进程退出即失效,不做进库里 - -### 用 Redis Pub/Sub 广播失效(可选) - -- **问题:** 一个实例上的写入到达不了其他实例的内存层,它们会返回旧值直到过期。 -- **做法:** 写入后在一个频道上发布被改动的 key,订阅的实例删除自己内存层里的这些 key。 -- **注意:** 断线期间的消息会丢,最终仍要靠 TTL 兜底;做成可选功能,默认关闭。 diff --git a/docs/adr/0001-own-flight-group.md b/docs/adr/0001-own-flight-group.md new file mode 100644 index 0000000..1d12ea9 --- /dev/null +++ b/docs/adr/0001-own-flight-group.md @@ -0,0 +1,14 @@ +# 用自己的 flightGroup 替换 x/sync/singleflight + +`GetMany` 要在同一套合并回源里**逐个认领**多个 key,然后把自己领头的那些 key 合成一次批量调用。认领时必须**当场**知道自己是不是领头请求。`golang.org/x/sync/singleflight` 的 `DoChan` 做不到:它在锁内决定谁是领头,但把回源函数放进另一个 goroutine 执行,不把结果告诉调用方。如果为了得到答案而等待,两个互相重叠的批量读会各自等对方手里的 key,从而死锁。所以我们写了 `flightGroup`:`claim` 立即返回(在途回源,是否领头),`finish` 负责发布。`Get` 和 `GetMany` 共用它,因此一个 `Get` 和一个包含同一 key 的 `GetMany` 也只回源一次。 + +## 考虑过的方案 + +- **继续用 x/sync,`GetMany` 自己维护一张登记表**:`Get` 和 `GetMany` 之间就不能合并回源,同一个 key 会被回源两次。 +- **整批作为一个 singleflight key**:同一批 key 才能合并,只要有一个 key 不同就要重新回源,也无法和 `Get` 合并。 + +## 后果 + +- 单 key 的行为逐项对照过 main:合并方式、回源槽位、panic 的错误信息和日志、调用方取消、超时、测试钩子都保持一致。有一个**有意的偏离**:Goexit 时会给等待方发布错误,见 [ADR 0006](0006-goexit-publishes-an-error.md)。`get_compat_test.go` 固定了单 key 的这些可观察行为。 +- `finish` 先移除登记、再发布结果,和 x/sync 的顺序相同。现有的二次检查依赖这个顺序。 +- `x/sync` 仍然留在 `go.mod` 里,基准测试用到了它的 semaphore。 diff --git a/docs/adr/0002-upstream-first-writes.md b/docs/adr/0002-upstream-first-writes.md new file mode 100644 index 0000000..3bcd617 --- /dev/null +++ b/docs/adr/0002-upstream-first-writes.md @@ -0,0 +1,15 @@ +# Set/Del 先写上游,任何失败都删掉本层条目 + +`Set`/`Del` 先写上游、成功后再写本层;任何一步失败,都删掉本层这个 key 的条目和不存在记录,然后返回错误。理由是:上层不能出现下层没有的值。如果先写本层、上游却写失败了,本层就会一直挂着一个「从未真正发生过」的值,直到 TTL 到期。上游写失败时,它的状态是未知的(可能已经写进去了,只是回复丢了),所以本层不能猜,只能删掉,让下次读取回源取真实状态。 + +## 考虑过的方案 + +- **先写本层(main 的做法)**:写入一返回,本层马上可见;但上游失败时会留下本层有、下层没有的值。 +- **只删本层、不写本层(cache-aside 的经典做法)**:删除总是安全的;但 `Set` 之后的第一次读必须回源。在「上游不是 Cache」的用法里(先改数据库、再 `Set`),`Set` 就退化成了 `Del`,失去了意义。分片锁已经保证了写入顺序([ADR 0003](0003-striped-backfill-guard.md)),写本层是安全的,所以保留写入。 + +## 后果 + +- 写入过程中有一个短暂窗口:本层自己的写入落下之前,并发读本层仍会读到旧值。`Set`/`Del` 返回后窗口关闭。 +- 上游写成功、本层写失败时,返回错误,但上游的改动**不回滚**。返回错误不代表什么都没写进去。 +- `Del` 失败时不会记下不存在,因为上游可能还留着这个 key。 +- 这是相对 main 的行为变化,已写进 PR 描述的行为变化表。 diff --git a/docs/adr/0003-striped-backfill-guard.md b/docs/adr/0003-striped-backfill-guard.md new file mode 100644 index 0000000..234c800 --- /dev/null +++ b/docs/adr/0003-striped-backfill-guard.md @@ -0,0 +1,18 @@ +# 用分片锁和写入代数防止旧值回填 + +一次回源读到旧值后,可能在一次 `Set`/`Del` 完成之后才回填,悄悄撤销这次写入。我们把 key 按哈希分进固定 4096 个分片,每个分片有一把读写锁和一个写入代数:`Set`/`Del` 持写锁,写完上游后把写入代数加 1;回填用 `TryRLock` 拿读锁,并且只在写入代数和回源前记下的一样时才写。所以回填要么在写入之前落下(随后被覆盖),要么被跳过,永远不会在 `Set`/`Del` 返回之后落下;读也永远不会等写。 + +## 考虑过的方案 + +- **每个 key 一把锁**:锁的数量随 key 数无限增长;要安全删除,就得加引用计数和一把全局锁。 +- **回填后发现期间有写入,再删掉本层条目(撤销式)**:这是本 PR 的第一个版本。缺点是在「回填落下」和「被删掉」之间,读者能看到旧值。 +- **带版本的条件写**:值要带上数据源的版本号,写入时只在版本更新时才覆盖。对数据源的要求太高,通用库做不到。 +- **只做摘除在途回源**:能挡住「加入更早的回源」,但挡不住已经开始的回源在写入后回填。cachex 两者都做,见 [write-order.md](../design/write-order.md#摘除在途回源)。 +- **分片数 1024 还是 4096**:4096 让跨 key 的写入排队、被跳过的回填、多余的二次检查都减少到四分之一,代价是每个 Client 的内存从 32KB 增加到 160KB。这个数字很容易调整,不单独成篇。 + +## 后果 + +- 落在同一个分片的不同 key 会互相影响:写入排队,或者回填被跳过(多一次未命中),但永远不会读到错的值。 +- 一次大批量回填会在回填期间占住它所有 key 的分片(1000 个 key 约 22%);用 `WithGetManyChunkSize` 可以让每段各自回填、只占自己的分片。 +- 等写锁时要能被 ctx 取消,所以加锁用了「`TryLock`,拿不到就开 goroutine 去 `Lock` 并同时等 ctx」的写法;放弃等待的写入,会在分片空出来后删掉本层条目。 +- 只在单个进程内成立,见 [ADR 0011](0011-cross-instance-consistency-via-ttl.md)。 diff --git a/docs/adr/0004-batch-result-shape.md b/docs/adr/0004-batch-result-shape.md new file mode 100644 index 0000000..223fb39 --- /dev/null +++ b/docs/adr/0004-batch-result-shape.md @@ -0,0 +1,18 @@ +# 批量读返回 (map, error),缺席即不存在 + +`GetMany` 和 `BatchUpstream.GetMany` 都返回 `(map[string]T, error)`:在 map 里表示找到,不在 map 里表示不存在,失败的 key 列在原样返回的 `*BatchError` 里;其他 error 表示整批失败。不存在**不算错误**,也不放进 `BatchError`。理由是:缓存的批量读几乎每次都有未命中,如果把不存在算作错误,`err` 就几乎总是非 nil,调用方每次都得过滤;而实现批量上游的人最自然的产出就是「查到的那些行」,比如 SQL 的 `WHERE id IN` 只返回存在的行。 + +## 考虑过的方案 + +| 方案 | 不选的原因 | +|---|---| +| `[]Result[T]`,按请求 key 的顺序一一对应 | 实现方必须保证第 i 个结果对应第 i 个 key。SQL 查回来的行是无序的,一旦排错,调用方会拿到**别的 key 的值**,而且没有任何报错。map 以 key 为索引,从结构上就排除了这种错误 | +| `map[string]Result[T]`,不存在用 `Err = ErrKeyNotFound` 表示 | 实现方必须对照请求逐个补上不存在的 key;每个未命中都要占一项。实测耗时和内存都约为方案 A 的 3 倍,见 [research/2026-10-batch-result-shape.md](../research/2026-10-batch-result-shape.md) | +| 一个 `BatchResult{Values, Errors}` 结构体 | 本质和现在一样,只是丢掉了 error 接口,不能写 `if err != nil` | + +## 后果 + +- `Get` 和 `GetMany` 用各自的方式表达同一套三种结果(找到、不存在、失败),README 里有对照表。 +- 值可以是 nil,判断 key 在不在必须用 `v, ok := m[k]`。 +- 整批失败的 error,即使在错误链里包着 `ErrKeyNotFound`,也不算不存在:每个 key 的错误都会包一层内部标记,`IsErrKeyNotFound` 对它返回 false,但 `errors.Is`/`errors.As` 仍然能找到原来的错误。 +- 命名:方法用 `GetMany`(这次操作多个 key),类型用 `Batch*`(这个东西支持批量)。这个决定容易修改,不单独成篇;没有用 `BatchGet` 的一个原因是,Google API 规范(AIP-231)规定 `BatchGet` 必须是原子的,而这里允许部分成功。 diff --git a/docs/adr/0005-best-effort-batch-writes.md b/docs/adr/0005-best-effort-batch-writes.md new file mode 100644 index 0000000..b0570ad --- /dev/null +++ b/docs/adr/0005-best-effort-batch-writes.md @@ -0,0 +1,14 @@ +# 批量写尽力而为 + +`BatchCache.SetMany`/`DelMany` 对每个 key 都尝试写,失败的 key 列在原样返回的 `*BatchError` 里,其余照常写入;返回其他 error 表示不知道哪些写成功了。所有内置后端都照此实现:Redis 逐条命令判断错误;GORM 每段一条语句、独立提交,某段失败就继续写后面的段。理由是:Client 只在回填时使用它们,多缓存一个 key 就少一次回源;而整批回滚(GORM 的默认事务)只会让本来能写进去的 key 也一起失败。 + +## 考虑过的方案 + +- **全有或全无**:需要事务,Redis 则要改用 MULTI/EXEC;某一段失败会连累整批,对缓存没有好处。 +- **各后端各行其是,只在文档里写清楚**:调用方无法写出通用的错误处理。 + +## 后果 + +- 错误规则和 `GetMany` 一致:原样返回的 `*BatchError` 表示部分失败,其他 error 表示整批失败。 +- GORM 不再把一次 `SetMany` 包在一个事务里,所以一次大的回填不再是原子的。对缓存来说这没有问题。 +- 在调用方自己的事务里(`WithGORMTx`),某条语句失败后,PostgreSQL 会让整个事务失效,后面的段也会失败。它们会被如实报告在 `BatchError` 里。 diff --git a/docs/adr/0006-goexit-publishes-an-error.md b/docs/adr/0006-goexit-publishes-an-error.md new file mode 100644 index 0000000..9040399 --- /dev/null +++ b/docs/adr/0006-goexit-publishes-an-error.md @@ -0,0 +1,16 @@ +# 上游 Goexit 时给所有等待方发布错误(有意偏离 x/sync) + +上游调用 `runtime.Goexit`(现实中基本只来自测试里在上游函数中调用 `t.FailNow`)时,cachex 给这次回源的所有等待方发布错误 `upstream fetch exited without returning (runtime.Goexit)`,和 panic 时的处理方式一致。这**有意偏离**了 main 上 `x/sync/singleflight` 的行为。 + +## x/sync 是怎么做的,为什么不照搬 + +x/sync 的设计原则是「同一个 key 的所有调用方,得到和自己亲自调用一样的结局」:用 `Do` 时,回源 panic,等待方也 panic;回源 Goexit,等待方也 Goexit。但 `DoChan` 的回源跑在另一个 goroutine 里,没法把结局复制给等待方:panic 时它故意让整个进程崩溃;Goexit 时它**什么都不发送**,等待方要一直等到自己的 ctx 结束,没有截止时间就永远挂着。2022 年有人报过这个泄漏([golang/go#52557](https://github.com/golang/go/issues/52557)),最终没修就关了,所以这不是刻意设计。main 上的 cachex 用的就是 `DoChan`,继承了这个泄漏。 + +main 对 panic 的处理是在回源函数里 recover、转成错误发给所有等待方,从来没有走到 x/sync 的崩溃路径。把 Goexit 也转成错误,和 main 对 panic 的处理正好一致。 + +## 后果 + +- 等待方不会再因为 Goexit 永远挂着。这类测试会很快失败,而不是挂到超时。 +- 每个在途回源恰好发布一次结果。单 key 和批量共用同一个小结构 `claimed` 来保证这一点:批量回源中途 panic 或 Goexit 时,只有还没拿到结果的 key 收到错误。 +- 后台批量刷新原来要给等待加一个超时,防止某个回源永远不发布结果、导致这些 key 永远不再刷新。有了这个保证,那个超时就删掉了。 +- `get_compat_test.go` 里对应的用例按新行为修改了,测试里注明了这是和 main 的有意差异。 diff --git a/docs/adr/0007-detached-fetch-context.md b/docs/adr/0007-detached-fetch-context.md new file mode 100644 index 0000000..cfc3949 --- /dev/null +++ b/docs/adr/0007-detached-fetch-context.md @@ -0,0 +1,18 @@ +# 回源在认领后脱离领头请求的取消,并去掉它的 GORM 事务 + +一次回源服务的是这个 key 的**所有**等待方,但认领它的只是其中一个请求。所以认领成功后,整个回源(包括二次检查)用的 ctx 是:保留领头请求 ctx 里的值(trace 等),去掉它的取消和截止时间,并去掉 `WithGORMTx` 放进去的事务。二次检查和向上游取值各自受 `WithFetchTimeout` 限制。 + +## 以前的问题(main 也是如此) + +- 二次检查用的是领头请求的原始 ctx。领头请求一放弃,二次检查就因为 ctx 已取消而失败,然后照样去上游取值:缓存里明明已经有值,还是多打了一次上游。 +- 回填时如果后端是 GORMCache,会用到领头请求放进 ctx 的业务事务。这个事务一旦已经结束,回填就会失败;如果事务还在进行,回填会跟着它一起提交或回滚。 + +## 考虑过的方案 + +- **只去掉事务,取消的时机不变**:解决不了领头请求放弃导致的多余回源。 +- **连 ctx 里的值也全部去掉**:trace 就断开了,而且没有通用的办法只保留一部分值。 + +## 后果 + +- 领头请求的 ctx 结束时,它自己立即返回,回源继续为其他等待方服务。这一点和以前相同。 +- 二次检查有了独立的超时,不会无限期挂在一个卡住的后端上。 diff --git a/docs/adr/0008-on-demand-double-check.md b/docs/adr/0008-on-demand-double-check.md new file mode 100644 index 0000000..36d012b --- /dev/null +++ b/docs/adr/0008-on-demand-double-check.md @@ -0,0 +1,24 @@ +# 默认的二次检查改为按需:只在读取之后本层被写过时才再读 + +`DoubleCheckAuto`(默认)以前的规则是「配置了不存在缓存就开启」。这个规则和二次检查什么时候有收益关系不大:收益取决于后端读的响应时间和 key 的热度。现在的规则是:请求在读后端之前记下 key 所在分片的分片纪元(写入次数加回填次数);认领回源时,只有分片纪元变了(说明读取之后本 Client 往这个分片写过东西),才再读一次。没人写过,再读一次也只会读到同样的未命中。 + +## 实测 + +见 [research/2026-10-double-check.md](../research/2026-10-double-check.md)。后端读延迟 1ms、上游 5ms、一个热点 key 每毫秒 20 次请求: + +| | Enabled | 新的 Auto | Disabled | +|---|---|---|---| +| 热点 key:上游调用次数 | 18 | 19 | 30 | +| 8000 个冷 key:每次 Get 读后端的次数 | 2.000 | 1.005 | 1.000 | + +## 考虑过的方案 + +- **总是开启**:热点 key 的收益最大,但冷 key 和不存在的 key 每次未命中都要多一次后端往返,对远程 Redis 约多 0.5ms 延迟,而且永远没有收益。 +- **按后端类型判断**(内存后端关闭,其他开启):要维护一份后端类型清单,用户自定义的后端也判断不了。 +- **删掉二次检查**:远程后端上的热点 key,上游调用会多出约 60%(30 次对比 18 次)。 + +## 后果 + +- 和其他 key 共用一个分片、并且被写过时,会多读一次(实测 0.5%),但永远不会漏掉一次该做的检查。 +- 看不到**其他进程**写进共享层的值;需要这一点时用 `DoubleCheckEnabled`。 +- 这是相对 main 的默认行为变化:配置了不存在缓存的用户,冷 key 上不再二次检查;没配置的用户,热点 key 开始二次检查。 diff --git a/docs/adr/0009-gorm-exact-keys-and-collation.md b/docs/adr/0009-gorm-exact-keys-and-collation.md new file mode 100644 index 0000000..a2ad435 --- /dev/null +++ b/docs/adr/0009-gorm-exact-keys-and-collation.md @@ -0,0 +1,20 @@ +# GORMCache 只认完全相等的 key,MySQL 建表用 utf8mb4_0900_bin + +缓存 key 区分大小写和末尾空格,但 MySQL 默认的排序规则(`utf8mb4_0900_ai_ci`)既不区分大小写、也不区分重音。在 main 上,`Set("ABC")` 之后 `Get("abc")` 会读到 `ABC` 的值,而 upsert 又不改写主键列,于是 `Set("abc", x)` 会把 x 写进 `ABC` 的那一行。我们做了三件事: + +1. `Get`/`GetMany` 只返回存储的 key 和请求的 key 完全相等的行; +2. upsert 时连同 key 列一起改写,一行共享的数据只属于最后写入它的 key; +3. `Migrate` 在 MySQL 上建表时使用 `utf8mb4_0900_bin`,大小写和末尾空格都精确比较。这要求 MySQL 8.0.17 及以上(MariaDB 没有这个排序规则),所以建表前会先检查版本。 + +前两点保证不管表用什么排序规则,**都不会读到别的 key 的值**;第三点让新表从根上避免冲突。 + +## 考虑过的方案 + +- **大小写不敏感地匹配,和 `Get` 保持一致**:这是本 PR 的一个中间版本。它只是让 `GetMany` 和 `Get` 错得一样,读到别的 key 的值这个问题依然存在。 +- **`utf8mb4_bin`**:支持更老的 MySQL,但它是 PAD SPACE 排序规则,会忽略末尾空格,`"a"` 和 `"a "` 仍会共用一行。我们选择只支持 MySQL 8.0.17 及以上。 +- **改写已有表的排序规则**:会对老用户的表执行 ALTER,风险不应由库来承担。已有的表保持不动,README 给出了手动转换的语句。 + +## 后果 + +- 老表上只差大小写的几个 key 会互相挤占同一行,表现为多几次未命中,但不会串值。 +- 不再支持在 MySQL 8.0.17 以下的版本和 MariaDB 上**新建**表;已经存在的表照常可以使用。 diff --git a/docs/adr/0010-gorm-deadlock-ordering-and-retry.md b/docs/adr/0010-gorm-deadlock-ordering-and-retry.md new file mode 100644 index 0000000..d9c0143 --- /dev/null +++ b/docs/adr/0010-gorm-deadlock-ordering-and-retry.md @@ -0,0 +1,25 @@ +# GORM 并发写的死锁:统一加锁顺序加有限重试,不锁表 + +多个实例同时回填有重叠的 key 时,`SetMany` 按 Go map 的随机顺序插入行,两条语句会以相反的顺序锁行,造成死锁。PostgreSQL 上还有第二个来源:`DELETE` 按索引顺序加锁,而索引顺序跟着列的排序规则走(官方镜像默认是 `en_US.utf8`),和字节序不一致。我们的做法是:`SetMany` 插入前按 key 的字节序排序;PostgreSQL 的 `DelMany` 先用 `ORDER BY key COLLATE "C" FOR UPDATE` 按字节序锁好行,再删除;剩下的少量死锁(MySQL 的间隙锁,InnoDB 要求应用重试)会重试,最多执行 5 次(即重试 4 次),在调用方自己的事务里则不重试。 + +## 实测 + +并发混合执行 `SetMany` 和 `DelMany`([research/2026-10-gorm-deadlock.md](../research/2026-10-gorm-deadlock.md))。第一行来自第一轮(8 个 worker,共 320 次操作),其余来自第二轮(16 个 worker,共 1280 次操作): + +| 方案 | MySQL 8.4 | PostgreSQL 16 | +|---|---|---| +| 只给 `SetMany` 排序(修复前,第一轮) | 2 / 320 次死锁 | 149 / 320 次死锁,每次卡 1 秒 | +| 统一加锁顺序 | 3 次死锁,949 ops/s | 0,1922 ops/s | +| **统一顺序 + 重试(采用)** | **0,840 ops/s** | **0,1936 ops/s** | +| 锁表(整表串行写) | 0,647 ops/s(-32%) | 0,1045 ops/s(-46%) | + +## 考虑过的方案 + +- **锁表**:死锁也能降到 0,但吞吐损失随并发上升(8 个 worker 时约 -20%,16 个时 -32% 到 -46%)。缓存层正是高并发的地方,代价太大。 +- **只重试、不统一顺序**:PostgreSQL 上反而更糟,重来一遍还会撞上;第一轮的 320 次操作跑了 460 秒。 +- **改用 READ COMMITTED 隔离级别以减少间隙锁**:MySQL 上的死锁反而更多。 + +## 后果 + +- 死锁的识别要区分驱动:PostgreSQL 用 SQLSTATE;MySQL 只能匹配错误文本 `Error 1213 (40001)`,因为 go-sql-driver 的错误类型没有 SQLState 方法。驱动如果改了错误格式,MySQL 这边的重试就会失效。 +- 老的 MySQL `*_ci` 表的索引顺序不是字节序,那里只能靠重试兜底。 diff --git a/docs/adr/0011-cross-instance-consistency-via-ttl.md b/docs/adr/0011-cross-instance-consistency-via-ttl.md new file mode 100644 index 0000000..4323796 --- /dev/null +++ b/docs/adr/0011-cross-instance-consistency-via-ttl.md @@ -0,0 +1,15 @@ +# 跨实例一致性暂时靠 TTL 兜底 + +分片锁和在途回源的登记都只在一个 Client 的内存里,因此只能在一个进程内保证写入顺序。多个实例共用 Redis 或数据库时,有两件事不保证:其他实例的内存层看不到你的写入;一个实例可能在另一个实例写入之后,把旧值回填进共享层。这个 PR **不处理**它们,交给 TTL 兜底,并在文档里写清边界和 TTL 的设置建议。 + +## 考虑过的方案 + +- **带版本的条件写**:值要带上数据源的版本号,删除还要留墓碑。对数据源的要求太高,通用库做不到。 +- **延迟双删**:写完后过一段时间再删一次。只能缩小窗口;回填比延迟还慢,或者进程在第二次删除前退出,就失效了;库里还要为每次写入挂一个定时任务。不建议做进库里。 +- **Redis 租约(lease)**:能彻底解决旧值回填,还能顺带做跨实例的回源去重,而且不要求数据源提供版本号。但它需要新的可选接口、Lua 脚本、批量领租约,是一个独立的功能,放进待办。 +- **失效广播(Redis Pub/Sub)**:解决其他实例的内存层看不到写入的问题,但断线时会丢消息,仍要靠 TTL 兜底。作为可选功能放进待办。 + +## 后果 + +- 多实例部署时,内存层和共享层的 TTL 都要按「能接受旧数据存活多久」来设,见 [consistency.md](../design/consistency.md)。 +- 两项后续工作都记在 [todo.md](../todo.md) 里。 diff --git a/docs/design.md b/docs/design.md new file mode 100644 index 0000000..67c9026 --- /dev/null +++ b/docs/design.md @@ -0,0 +1,125 @@ +# cachex 设计总览 + +这里只写**现在成立**的设计。被推翻的做法直接删掉,理由放进 [ADR](adr/)。术语以 [GLOSSARY.md](../GLOSSARY.md) 为准。 + +## 一句话 + +cachex 是一个泛型的多层缓存客户端:每一层未命中时向上游取值,把同一个 key 的并发请求合并成一次回源,用新鲜/陈旧/腐烂三态和不存在缓存处理过期与不存在的 key,并保证写入在各层按同一顺序生效、回源不会把旧值回填到写入之后。 + +## 为什么需要它 + +直接「查缓存,没有就查数据库再回填」会遇到几类问题,cachex 分别用一个机制处理: + +| 问题 | 现象 | 机制 | +|---|---|---| +| 缓存击穿 | 热点 key 过期的瞬间,大量请求同时打到数据源 | [合并回源](design/singleflight.md)(singleflight)+ [二次检查](design/read-path.md#二次检查) | +| 缓存穿透 | 查询根本不存在的 key,每次都打到数据源 | [不存在缓存](design/read-path.md#不存在缓存) | +| 过期时的等待 | 条目一过期,读请求就要同步等回源 | [返回陈旧值](design/read-path.md#返回陈旧值) | +| 旧值回填 | 写入刚完成,一个更早开始的回源把旧值写了回去 | [写入顺序与分片锁](design/write-order.md) | +| 多次往返 | 一次要读几百个 key,逐个回源太慢 | [批量读](design/batch.md) | + +缓存雪崩(大量 key 同时过期)目前没有专门机制,见 [todo](todo.md) 第一条。 + +## 核心模型 + +```go +type Upstream[T any] interface { Get(ctx, key) (T, error) } // 能取值的东西 +type Cache[T any] interface { Upstream[T]; Set(...); Del(...) } // 能存值的东西 +type BatchUpstream[T any] interface { GetMany(ctx, keys) (map[string]T, error) } // 可选:能一次取多个 +type BatchCache[T any] interface { Cache[T]; BatchUpstream[T]; SetMany(...); DelMany(...) } // 可选 +``` + +- **一层 = 一个 `Client` + 它的后端(`Cache`)+ 它的上游(`Upstream`)**。 +- `Client` 自己实现了 `Cache` 和 `BatchUpstream`,所以一个 `Client` 可以做另一个 `Client` 的上游,层就这样串起来。 +- 上游如果也是 `Cache`,写入会继续往下传;到了不是 `Cache` 的上游(数据源)就停止。 + +## 架构总览 + +下面两张图都以「内存层 → Redis 层 → 数据库」这条三段链路为例。 + +**读取的数据流**:每条边都是双向的,去程是请求,回程是值、「不存在」或回填。 + +```mermaid +flowchart LR + caller([调用方]) + L1[内存层 Client] + B1[(内存层后端
Ristretto)] + N1[(内存层
不存在缓存)] + L2[Redis 层 Client] + B2[(Redis 层后端
Redis)] + N2[(Redis 层
不存在缓存)] + SRC[(数据源
数据库)] + + caller <-->|"Get / GetMany"| L1 + L1 <-->|"读 / 回填"| B1 + L1 <-->|"读 / 回填"| N1 + L1 <-->|"回源:调用 Redis 层的 Get / GetMany"| L2 + L2 <-->|"读 / 回填"| B2 + L2 <-->|"读 / 回填"| N2 + L2 <-->|"回源"| SRC +``` + +**写入的数据流**:编号就是先后顺序。 + +```mermaid +flowchart LR + caller([调用方]) + L1[内存层 Client] + B1[(内存层后端)] + L2[Redis 层 Client] + B2[(Redis 层后端)] + SRC[(数据源)] + + caller -->|"1 Set / Del"| L1 + L1 -->|"2 先写上游"| L2 + L2 -->|"3 写本层"| B2 + L2 -.-x|"数据源不是 Cache,不写"| SRC + L1 -->|"4 再写本层"| B1 +``` + +每一层内部的处理顺序都相同: + +1. **查后端**,按新鲜度决定直接返回、返回陈旧值并后台刷新,还是继续往下走([读取路径](design/read-path.md))。 +2. **未命中时查不存在缓存**,确认「已知不存在」就直接返回。 +3. **合并回源**:同一个 key 只让一个请求去上游,其他请求等它的结果([合并回源](design/singleflight.md))。 +4. **二次检查**之后**回源**,再**回填**本层;回填受分片锁保护,不会落在写入之后([写入顺序](design/write-order.md))。 + +## 配置项 + +`NewClient(backend, upstream, opts...)` 的选项: + +| 选项 | 默认 | 作用 | 详见 | +|---|---|---|---| +| `WithStale(fn)` / `EntryWithTTL(fresh, stale)` | 一律新鲜(过期交给后端自己的 TTL) | 判断一个值是新鲜、陈旧还是腐烂 | [read-path.md](design/read-path.md#新鲜度) | +| `WithNotFound(cache, fn)` / `NotFoundWithTTL(cache, fresh, stale)` | 不启用 | 不存在缓存 | [read-path.md](design/read-path.md#不存在缓存) | +| `WithServeStale(bool)` | 关闭 | 返回陈旧值,并在后台刷新 | [read-path.md](design/read-path.md#返回陈旧值) | +| `WithDoubleCheck(mode)` | `DoubleCheckAuto` | 二次检查 | [read-path.md](design/read-path.md#二次检查) | +| `WithFetchTimeout(d)` | `DefaultFetchTimeout` = 60 秒 | 一次回源的超时;二次检查、写入失败后的清理也用它限时 | [singleflight.md](design/singleflight.md#回源用的-ctx) | +| `WithFetchConcurrency(n)` | `DefaultFetchConcurrency` = 1 | 同一个 key 的回源槽位数 | [singleflight.md](design/singleflight.md#回源槽位) | +| `WithGetManyFetchConcurrency(n)` | `DefaultGetManyFetchConcurrency` = 16 | 一次 `GetMany` 同时向上游发出的请求数 | [batch.md](design/batch.md#回源怎么发) | +| `WithGetManyChunkSize(n)` | 0(不分段) | 发往批量上游的每次调用最多多少个 key | [batch.md](design/batch.md#回源怎么发) | +| `WithLogger(l)` | `slog.Default()` | 日志 | — | + +`WithFetchTimeout`、`WithFetchConcurrency`、`WithGetManyFetchConcurrency` 必须大于 0,`WithGetManyChunkSize` 不能为负,否则 `NewClient` 会 panic。后端自己的配置(TTL、`ChunkSize`、`KeyPrefix` 等)见 [backends.md](design/backends.md)。 + +## 分篇 + +| 文档 | 内容 | +|---|---| +| [design/read-path.md](design/read-path.md) | 一次 `Get` 的完整流程:新鲜度三态、不存在缓存、返回陈旧值、二次检查 | +| [design/singleflight.md](design/singleflight.md) | 合并回源:认领与发布、回源 ctx、panic 与 Goexit、回源槽位 | +| [design/write-order.md](design/write-order.md) | 写入顺序:先写上游、分片锁、写入代数、回填保护、摘除在途回源 | +| [design/batch.md](design/batch.md) | 批量读:流程、分段与并发、错误模型和三种结果 | +| [design/backends.md](design/backends.md) | 各后端的实现要点:Ristretto、SyncMap、Redis、GORM、BigCache、Transform | +| [design/consistency.md](design/consistency.md) | 一致性:单进程内保证什么、多实例的边界、TTL 的作用 | + +## 其他文档 + +| 文档 | 内容 | +|---|---| +| [GLOSSARY.md](../GLOSSARY.md) | 术语表 | +| [adr/](adr/) | 架构决策记录 | +| [todo.md](todo.md) | 发现了但还没做的事 | +| [faq.md](faq.md) | 常见问题 | +| [research/](research/README.md) | 实测与调研报告 | +| [../BENCHMARK.md](../BENCHMARK.md) | 性能基准(中英双语) | diff --git a/docs/design/backends.md b/docs/design/backends.md new file mode 100644 index 0000000..3ec79d9 --- /dev/null +++ b/docs/design/backends.md @@ -0,0 +1,106 @@ +# 后端 + +各个内置后端的实现要点和已知限制。所有后端都实现了 `Cache[T]`:未命中时 `Get` 返回 `*ErrKeyNotFound`(可以再包一层)。实现了 `BatchCache[T]` 的后端,`GetMany`/`SetMany`/`DelMany` 遵守 [batch.md](batch.md#批量上游要遵守的约定) 里的约定。 + +| 后端 | 存在哪 | 批量 | 自己的 TTL | 适合 | +|---|---|---|---|---| +| `RistrettoCache` | 进程内存(dgraph-io/ristretto) | ✅ | ✅ | 内存层 | +| `SyncMap` | 进程内存(`sync.Map`) | ✅ | ❌ | 测试、小数据量 | +| `BigCache` | 进程内存(allegro/bigcache),只存 `[]byte` | ❌ | 由 bigcache 配置 | 大量小值、在意 GC | +| `RedisCache` | Redis(单机或 Cluster) | ✅ | ✅ | 共享层 | +| `GORMCache` | 数据库表(MySQL 8.0.17+、PostgreSQL、SQLite) | ✅ | ❌(清理见 [todo](../todo.md)) | 持久化的共享层 | +| `Transform` | 包装另一个后端,做类型转换 | ❌ | 取决于被包装的后端 | 在不同值类型之间复用同一个后端 | + +没有实现批量接口的后端(`BigCache`、`Transform`、自定义后端),`GetMany` 会逐个 key 读写。注意:用 `Transform` 包一层 `RedisCache`,`GetMany` 就会变成每个 key 一次往返。 + +## RistrettoCache + +- `Set` 之后调用 `Wait()`,等缓冲区里的写入真正生效,保证 `Set` 返回后立即 `Get` 能读到。`SetMany`/`DelMany` 写完全部 key 后只 `Wait()` 一次。 +- Ristretto 的准入策略(W-TinyLFU)可能**静默丢弃**一次写入,被丢弃时不算错误:这本来就是它防止低价值条目污染缓存的手段,丢了也只是下次未命中。 +- 每个条目的代价(cost)固定为 1,容量上限就是条目数。 + +## SyncMap + +`sync.Map` 的简单包装,没有过期、没有容量限制。主要用于测试,或者作为确定不会无限增长的小数据量内存层。 + +## RedisCache + +### 编码 + +| 值的类型 | 怎么存 | +|---|---| +| `string`、`[]byte` | 原样存 | +| 实现了 `encoding.BinaryMarshaler`(且 `*T` 实现了 `BinaryUnmarshaler`) | 二进制 | +| 其他 | JSON | + +读取时用 `StringCmd.Bytes()` 拿回复。它和回复共用内存,不再复制一次。`T = []byte` 时,返回的切片也直接共用这块内存;这个命令对象用完就丢弃,没有别人持有它,所以是安全的。 + +### 批量:pipeline + +- `GetMany`/`SetMany`/`DelMany` 用 `GET`/`SET`/`DEL` 的 pipeline,而不是 `MGET`。这样在 Redis Cluster 上,一批 key 即使分布在不同的 slot 也能用。 +- 大批量按 `RedisCacheConfig.ChunkSize`(默认 1000)切成多个 pipeline,**依次**发送。Redis 服务端是单线程的,并发发送多个 pipeline 收益很小。 +- **每条命令的错误各自判断**:pipeline 的 `Exec` 只返回第一个失败命令的错误。Redis 回复的错误(例如对一个 list 执行 `GET` 返回 `WRONGTYPE`)已经记在各自的命令上;但**连接层面的失败**(连不上、连接中断)发生时,没发出去的命令自身是没有错误的。所以 `Exec` 返回的错误如果不是 Redis 的回复错误,就把它设到每一条还没有错误的命令上。否则 `GET` 会被当成读到了空值,Redis 故障时所有 key 都会被当成「命中空字符串」。 +- 写入尽力而为:失败的 key(编码失败、命令失败)列在 `*BatchError` 里,其余照常写入。 + +## GORMCache + +### 表结构 + +```go +type cacheEntry struct { + Key string `gorm:"not null;primaryKey;size:255"` + Value datatypes.JSON `gorm:"not null;type:json"` + UpdatedAt time.Time `gorm:"not null;index"` +} +``` + +值以 JSON 存储。`KeyPrefix` 会拼在 key 前面,同一张表可以给多个用途使用。 + +### key 必须精确比较 + +缓存 key 区分大小写,也区分末尾空格。不同数据库的默认行为不同: + +| 数据库 | key 列默认怎么比较 | cachex 的处理 | +|---|---|---| +| PostgreSQL、SQLite | 逐字节 | 不需要额外处理 | +| MySQL | 默认排序规则(`utf8mb4_0900_ai_ci`)**不区分大小写和重音** | `Migrate` 建表时使用 `utf8mb4_0900_bin`。建表前检查版本:低于 8.0.17 的 MySQL 和 MariaDB 都没有这个排序规则,会返回写明版本号的错误。已经存在的表不会改动 | + +即使 key 列不能精确比较(比如升级前建的老表),也**不会读到别的 key 的值**: + +- `Get`/`GetMany` 只返回存储的 key 和请求的 key **完全相等**的那一行; +- upsert 时连同 key 列一起改写,所以一行共享的数据只属于最后写入它的那个 key。 + +代价是只差大小写的几个 key 会互相挤占同一行,表现为多几次未命中。把老表转成精确比较:`ALTER TABLE <表> CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_bin`。决策过程见 [ADR 0009](../adr/0009-gorm-exact-keys-and-collation.md)。 + +### `key` 是 MySQL 的保留字 + +所有条件都用 GORM 的 `clause.Eq`、`clause.IN` 构造,由 GORM 给列名加引号。不能写成 `Where("key = ?")` 这样的原始 SQL 片段:SQLite 能接受,MySQL 会报语法错误。有一个单元测试会截获实际执行的 SQL,检查列名有没有加引号。 + +### 批量与死锁 + +- `GetMany`/`SetMany`/`DelMany` 按 `GORMCacheConfig.ChunkSize`(默认 1000,最大 10000,以免超出 SQLite 的 32766 个绑定参数上限)切成多条语句,依次执行,**每条语句独立提交**(在 `WithGORMTx` 传入的事务里时除外,那时都在调用方的事务里)。某一段失败时,这一段的 key 记进 `*BatchError`,然后继续执行后面的段。 +- **统一加锁顺序**: + - `SetMany` 插入前按 key 的字节序排序。否则多个实例同时回填有重叠的 key 时,会以相反的顺序锁行而死锁。 + - PostgreSQL 的 `DelMany` 先用 `SELECT … ORDER BY key COLLATE "C" FOR UPDATE` 按字节序锁好行,再删除。`DELETE` 是按索引顺序加锁的,而索引顺序跟着列的排序规则走(官方镜像默认是 `en_US.utf8`),和 `SetMany` 的字节序不一致。 + - MySQL 新表的 `utf8mb4_0900_bin` 按码点排序,和 UTF-8 的字节序一致,所以不需要额外处理。 +- **死锁重试**:MySQL 的间隙锁仍可能偶发死锁,InnoDB 要求应用自行重试。所以 `Set`/`Del`/`SetMany`/`DelMany` 被数据库判为死锁牺牲者时会重试,最多执行 5 次(即重试 4 次),每次退避的时间带随机抖动,并尊重 ctx。识别方式:PostgreSQL 看 SQLSTATE `40P01`/`40001`;MySQL 匹配驱动的错误文本 `Error 1213 (40001)`,因为 go-sql-driver 的错误类型没有提供 SQLState 方法。 +- **调用方自己的事务里不重试**:用 `WithGORMTx` 把事务放进 ctx 时,死锁已经让数据库回滚了整个事务,只重试一条语句是错的,所以直接把错误返回给调用方。 + +这几种做法的实测对比(包括锁表)见 [research/2026-10-gorm-deadlock.md](../research/2026-10-gorm-deadlock.md),决策见 [ADR 0010](../adr/0010-gorm-deadlock-ordering-and-retry.md)。 + +### 事务 + +`WithGORMTx(ctx, tx)` 让 GORMCache 在调用方的事务里读写。但**回源时**,cachex 会把这个事务从 ctx 中去掉(见 [singleflight.md](singleflight.md#回源用的-ctx)):一次回源服务的是所有等待方,回填不能写进某一个调用方的事务里。 + +### 已知限制 + +- 没有过期清理:表只增不减,需要自己定期删除旧行。清理任务在 [todo](../todo.md) 里。 +- 值为 JSON 标量数字(例如 `T = float64`)时,SQLite 会把它存成数字类型,`datatypes.JSON` 读回来时扫描失败。结构体、字符串等类型不受影响。见 [todo](../todo.md)。 + +## BigCache + +只存 `[]byte`,适合大量小值、希望减少 GC 压力的场景。要存其他类型,用 `Transform` 包一层。 + +## Transform + +`Transform(cache, encode, decode)` 把一个 `Cache[A]` 包装成 `Cache[B]`,比如把 `RedisCache[[]byte]` 包成 `Cache[*Product]`。它没有实现批量接口。 diff --git a/docs/design/batch.md b/docs/design/batch.md new file mode 100644 index 0000000..b388bb9 --- /dev/null +++ b/docs/design/batch.md @@ -0,0 +1,132 @@ +# 批量读 + +`Client.GetMany(ctx, keys)` 一次读多个 key。它的语义和**逐个调用 `Get`** 完全相同(新鲜度、不存在缓存、返回陈旧值、合并回源、二次检查、回填都照常生效),只是读后端、回源、回填都尽量合成批量调用。代码在 `batch.go`。 + +## 接口 + +```go +// 可选:能一次回答多个 key 的上游 +type BatchUpstream[T any] interface { + GetMany(ctx context.Context, keys []string) (map[string]T, error) +} + +// 可选:能批量读写的后端 +type BatchCache[T any] interface { + Cache[T] + BatchUpstream[T] + SetMany(ctx context.Context, values map[string]T) error + DelMany(ctx context.Context, keys []string) error +} + +func (c *Client[T]) GetMany(ctx context.Context, keys []string) (map[string]T, error) +``` + +- 上游或后端没有实现批量接口时,自动退回逐个 key 调用,语义不变。 +- `Client` 自己实现了 `BatchUpstream`,所以在 L1 → L2 → 数据源的链路里,一批 key 会以每层一次调用的方式一路传下去。 + +## 流程 + +```mermaid +sequenceDiagram + participant C as 调用方 + participant L as Client + participant B as 后端 + participant N as 不存在缓存 + participant G as flightGroup + participant U as 批量上游 + C->>L: GetMany(k1..k5) + L->>L: 去重;记下每个 key 的分片纪元 + L->>B: GetMany(k1..k5)(一次批量读) + B-->>L: k1 新鲜、k2 陈旧、k3 腐烂;k4、k5 未命中 + L->>N: GetMany(k4, k5) + N-->>L: k4 有新鲜的不存在记录;k5 没有 + L-)L: 后台刷新 k2(返回陈旧值时) + L->>G: 认领 k3、k5 + L->>L: 二次检查(只查需要的 key) + L->>U: GetMany(k3, k5)(一次,或分段) + U-->>L: k3 = v,k5 不在 map 里 + L->>N: 回填:删除 k3 的不存在记录 + L->>B: 回填:SetMany(k3) + L->>N: 回填:记下 k5 不存在 + L->>B: 回填:DelMany(k5)(回填受分片锁保护) + L->>G: 发布 k3、k5 + L-->>C: {k1, k2, k3}(k4、k5 不存在,所以不在 map 里) +``` + +逐步说明: + +1. **去重**:重复的 key 只处理一次。 +2. **读后端**:一次批量读。读到的每个值按新鲜度处理:新鲜的放进结果;陈旧的也放进结果(开启返回陈旧值时),同时这些 key 在后台合成一批刷新;腐烂的和未命中的继续往下走,后面查到的也放进同一份结果。**整份结果最后一次性返回。** +3. **查不存在缓存**:后端未命中的 key 一起查一次,规则同 `Get`。 +4. **合并回源**:需要回源的 key 逐个在同一个 flightGroup 里认领。别人正在回源的 key 直接等结果,自己领头的 key 由自己回源。见 [singleflight.md](singleflight.md#批量认领)。 +5. **二次检查**:只对需要的 key 再读一次本层(默认的 `DoubleCheckAuto` 下,只检查读取之后本 Client 写过其分片的 key)。 +6. **回源**:见下一节。 +7. **回填**:找到的值写进后端,不存在的 key 写进不存在缓存,并删掉后端的旧值。只写本层。 + +## 回源怎么发 + +| 上游 | 怎么发 | 每个请求的超时 | key 什么时候拿到结果 | +|---|---|---|---| +| 实现了 `BatchUpstream` | **一次** `GetMany`;设置了 `WithGetManyChunkSize(n)` 时,切成每段最多 n 个 key、并发执行 | 每段一个 `WithFetchTimeout`;上游是 `Client` 时为 `WithFetchTimeout` 加上下层的预算(见下文) | 这一段返回时,一起拿到 | +| 没有实现 | 每个 key 按单个 `Get` 的完整流程回源 | 每个 key 一个 `WithFetchTimeout` | 自己那个 key 回源完成时 | + +两种情况的并发上限都是 `WithGetManyFetchConcurrency`(默认 16),它的含义是「一次 `GetMany` 同时向上游发出的请求数」。不要和 `WithFetchConcurrency` 混淆,后者是同一个 key 的回源槽位数。 + +**上游不支持批量时,key 轮到它才认领**。如果一开始就认领全部 key、再慢慢排队回源,一个普通 `Get` 碰上排在队尾的 key,就要等整个队列。逐个认领可以避免这种情况。另外,`GetMany` 的 ctx 一结束,就不再开始新的 key。 + +**分段的好处**: +- 上游限制了单次批量大小时(比如某个 RPC 一次最多接受 100 个 id),由库负责切分; +- 每一段返回时立即发布结果、立即回填,并且只锁这一段 key 的分片(见 [write-order.md](write-order.md#慢操作会拖慢多大范围)); +- 某一段 panic 或调用 Goexit,只影响这一段还没拿到结果的 key。 + +**上游是另一个 Client 时的超时**:下层 Client 会给自己的每次回源各自限时,所以上层不能只给这次批量调用一个 `WithFetchTimeout`,否则下层还在排队的 key 会被上层的超时误判为失败。上层的上限是「本层的一个 `fetchTimeout`」加上「下层最多可能用的时间」: + +``` +下层预算(n) = + 下层逐 key 回源:fetchTimeout × (1 + ⌈n / 并发⌉) + 下层批量回源: fetchTimeout + ⌈⌈n / 段大小⌉ / 并发⌉ × fetchTimeout + 下层又是 Client:fetchTimeout + ⌈⌈n / 段大小⌉ / 并发⌉ × 再下一层的预算(段大小) +``` + +这样基本不会误伤还在下层排队的 key(下层第一次读后端、二次检查的时间不在预算里),下层卡死时也不会无限期挂着。 + +## 错误模型 + +### 三种结果 + +每个 key 读完后,必然是下面三种之一。`Get` 和 `GetMany` 表达的是同一套,只是用了各自返回形式里最自然的方式: + +| 结果 | `Get` | `GetMany` | +|---|---|---| +| 找到了(值本身可能是 `nil`) | `(value, nil)` | 在 map 里 | +| 不存在 | `IsErrKeyNotFound(err)` 为真 | 既不在 map 里,也不在 `BatchError` 里 | +| 失败了 | 其他 error | 列在 `BatchError.Errors` 里 | + +- **不存在不算错误**:缓存的 `GetMany` 几乎每次都有未命中。如果把不存在也算进 `BatchError`,`err` 就几乎总是非 nil,调用方每次都得过滤一遍。这和 go-redis 的 `MGet`、`database/sql` 的 `Query`、Go map 的 `v, ok := m[k]` 是同一个思路。 +- **值可以是 `nil`**:缓存的空指针也是命中。判断 key 在不在,要用 `v, ok := m[k]`,不能用 `m[k] == nil`。 +- **返回的 map 总是包含所有成功的 key**,不管 `err` 是不是 nil。 + +### 批量上游要遵守的约定 + +实现 `BatchUpstream`(以及 `BatchCache` 的 `GetMany`)时: + +| 返回 | 含义 | +|---|---| +| map 里有 key | 找到了 | +| map 里没有 key | 不存在。**不要**用 `ErrKeyNotFound` 表示 | +| 原样返回的 `*BatchError`(不要再包一层) | 部分失败:只有它列出的 key 失败,map 里照常放其余 key | +| 其他任何 error | **整批失败**:所有 key 都按失败处理 | + +整批失败的 error,即使在错误链里包着 `ErrKeyNotFound`,也算所有 key 失败,不算不存在。实现上,cachex 会给每个 key 的错误包一层内部标记 `wholeBatchError`:`IsErrKeyNotFound` 遇到这个标记就返回 false,但 `errors.Is`/`errors.As` 仍然能找到原来的错误(比如连接错误)。只有**原样返回**的 `*BatchError` 才算部分失败,因为被包过一层或 join 过的 `BatchError`,旁边可能还有一个让整批失败的错误。 + +### 批量写 + +`BatchCache.SetMany`/`DelMany` 是**尽力而为**:每个 key 都尝试写,失败的 key 列在原样返回的 `*BatchError` 里;返回其他 error,表示不知道哪些 key 写成功了。Client 只在回填时用它们,失败只记 WARN 日志,因为多缓存一个 key,就少一次回源。见 [ADR 0005](../adr/0005-best-effort-batch-writes.md)。 + +为什么返回 `(map, error)` 而不是 `[]Result` 或 `map[string]Result`,见 [ADR 0004](../adr/0004-batch-result-shape.md)。 + +## 和单个 Get 的交互 + +- 一个 `Get` 和一个包含同一 key 的 `GetMany` 共用在途回源,只回源一次。 +- `Get` 加入的如果是批量上游的那次批量回源,它要等这一次调用(或这一段)整体返回,才能拿到结果。 +- 批量回源时,上游没有返回某个 key,那么等待这个 key 的 `Get` 拿到的是普通的 `ErrKeyNotFound`(不带 `Cached`),而不是下层不存在缓存的那种。 diff --git a/docs/design/consistency.md b/docs/design/consistency.md new file mode 100644 index 0000000..88231f8 --- /dev/null +++ b/docs/design/consistency.md @@ -0,0 +1,97 @@ +# 一致性 + +cachex 在**一个进程**内保证写入顺序;跨进程(多个实例共用 Redis 或数据库)的新鲜度,目前靠 TTL 兜底。这篇说明边界在哪里、TTL 该怎么设,以及以后可以怎么补。 + +## 单个进程内保证什么 + +前提:通过**同一个 Client** 调用 `Set`/`Del`,并且先改数据源、再调用它们(见 [write-order.md](write-order.md#使用方式改数据源时要做什么))。 + +| 保证 | 靠什么 | +|---|---| +| `Set`/`Del` 返回后,这个进程的读取不会再拿到写入前的值 | 分片锁 + 写入代数(挡住旧值回填)、摘除在途回源(挡住加入更早的回源) | +| 新值不会先于下层出现在上层 | 先写上游、再写本层 | +| 同一个 key 的并发写入,在各层以同一顺序生效 | 同一分片的写入串行执行 | +| 写入失败时,本层不会留下这个 key 的条目 | 失败后删除本层条目和不存在记录 | + +**不保证**的情况:写入**进行中**,本层自己的写入落下之前,并发的读取仍可能读到旧值。`Set`/`Del` 一返回,这个窗口就关闭了。 + +## 多个实例时不保证什么 + +分片锁和在途回源的登记都在一个 Client 的内存里,其他实例对它们一无所知。 + +### 1. 其他实例的内存层 + +```mermaid +sequenceDiagram + participant A as 实例 A 的内存层 + participant R as 共享的 Redis 层 + participant B as 实例 B + Note over A: 已缓存 v1 + B->>R: Set(k, v2)(B 自己的内存层也更新) + Note over A: 仍是 v1,直到它的 TTL 到期 +``` + +实例 B 的写入不会碰实例 A 的内存。A 会一直返回旧值,直到 A 内存层里这个条目过期。 + +**缓解**:内存层的 TTL 不要超过你能接受的旧数据时长。需要更快失效时,在业务代码里广播变更(例如 Redis Pub/Sub),收到消息的实例调用本地内存层的 `Del`。 + +### 2. 旧值回填进共享层 + +```mermaid +sequenceDiagram + participant A as 实例 A + participant R as 共享的 Redis 层 + participant DB as 数据库 + participant B as 实例 B + A->>R: 未命中 + A->>DB: 读到 v1 + Note over A: 还在返回途中 + B->>DB: 写成 v2 + B->>R: Del(k) + A->>R: 把 v1 回填 ✗ + Note over R: v1 一直留到 Redis 的 TTL 到期 +``` + +A 的分片锁不知道 B 写过,所以挡不住这次回填。这是 cache-aside 模式的经典竞态: + +- **概率低**:读和写要在几毫秒内交错; +- **后果持续久**:旧值会存活整个共享层的 TTL。 + +**缓解**:共享层的 TTL 也要设成你能接受的旧数据时长。 + +## TTL 怎么设 + +| 层 | 建议 | +|---|---| +| 内存层 | 不超过「其他实例可以容忍看到旧值多久」。通常是秒级到分钟级 | +| 共享层(Redis、数据库) | 不超过「旧值回填后可以容忍存活多久」。数据改动频繁、又在意新鲜度时,不宜设成小时级 | +| 后端自己的 TTL | 不小于 `freshTTL + staleTTL`,否则陈旧期还没到,条目就已经消失了 | + +## 以后可以怎么补 + +两项都记在 [todo](../todo.md) 里,暂不实现的理由见 [ADR 0011](../adr/0011-cross-instance-consistency-via-ttl.md)。 + +### Redis 租约(lease) + +思路和进程内的写入代数相同,只是把「写入发生过」这个事实放到所有实例共享的 Redis 里: + +```mermaid +sequenceDiagram + participant A as 实例 A + participant R as Redis + participant B as 实例 B + A->>R: Lua:GET k,为空就写 lease:k = 令牌 t1 + R-->>A: 未命中 + 令牌 t1 + A->>A: 回源,读到 v1 + B->>R: Set/Del k,并删除 lease:k + A->>R: Lua:lease:k 仍是 t1 才写入 v1 + R-->>A: 令牌已作废,拒绝 ✓ +``` + +- 读和领租约必须在同一个原子操作里,否则 B 可能恰好插在两步之间。 +- 它同时能做**跨实例的回源去重**:别的实例看到已有租约,就等待或返回陈旧值,不再回源。 +- 不需要数据源提供版本号;往返次数不变。 + +### 失效广播 + +写入后在一个频道上发布被改动的 key,其他实例收到后删除自己内存层里的这些 key。断线期间的消息会丢,所以 TTL 仍然是最后的兜底。 diff --git a/docs/design/read-path.md b/docs/design/read-path.md new file mode 100644 index 0000000..c2db5e0 --- /dev/null +++ b/docs/design/read-path.md @@ -0,0 +1,177 @@ +# 读取路径 + +一次 `Client.Get(ctx, key)` 在**一层**里怎么走。多层时,每一层都按同样的流程处理,它的回源就是调用下一层的 `Get`。批量读见 [batch.md](batch.md),合并回源的细节见 [singleflight.md](singleflight.md),回填保护见 [write-order.md](write-order.md)。 + +## 总流程 + +```mermaid +flowchart TD + start([Get key]) --> epoch[记下 key 所在分片的分片纪元] + epoch --> be{查后端} + be -- 出错(不是未命中) --> err1([返回错误,不回源]) + be -- 找到 --> st{新鲜度} + st -- 新鲜 --> ret1([返回值]) + st -- 陈旧,且开启返回陈旧值 --> refresh[后台刷新] --> ret2([返回陈旧值]) + st -- 陈旧但未开启返回陈旧值 / 腐烂 --> fetch + be -- 未命中 --> nfq{配置了不存在缓存?} + nfq -- 否 --> fetch + nfq -- 是 --> nf{查不存在缓存} + nf -- 出错 --> err2([返回错误,不回源]) + nf -- 没有记录 --> fetch + nf -- 新鲜的不存在记录 --> nf1([返回不存在]) + nf -- 陈旧,且开启返回陈旧值 --> refresh2[后台刷新] --> nf2([返回不存在]) + nf -- 陈旧但未开启 / 腐烂 --> fetch + fetch[合并回源] --> dc{需要二次检查?} + dc -- 是 --> recheck{再读一次本层} + recheck -- 找到新鲜值或新鲜的不存在记录 --> ret3([直接返回它]) + recheck -- 仍然没有 --> up + dc -- 否 --> up[向上游取值] + up -- 值 --> bf1[回填值] --> ret4([返回值]) + up -- 不存在 --> bf2[回填不存在] --> ret5([返回不存在]) + up -- 其他错误 --> ret6([返回错误,什么都不写]) +``` + +几个容易忽略的点: + +- **后端或不存在缓存读失败时,不会回源**,而是直接返回错误。理由是:这一层出了故障时把流量全部转给上游,很容易把上游也压垮。 +- **只有后端未命中时才查不存在缓存**。后端里有一个腐烂的值时,会直接回源。 +- **上游返回其他错误时,什么都不写**。错误会交给这次回源的所有等待方,但不会被缓存,下一次读取会重新回源。 + +## 新鲜度 + +每个值是新鲜、陈旧还是腐烂,由 `WithStale(func(T) State)` 判断。不配置时一律算新鲜,过期完全交给后端自己的 TTL。 + +最常用的是 `Entry[T]` 加上 `EntryWithTTL(freshTTL, staleTTL)`。`Entry` 记录了取值的时间 `CachedAt`: + +| 条目的年龄 | 状态 | +|---|---| +| `[0, freshTTL)` | 新鲜 | +| `[freshTTL, freshTTL + staleTTL)` | 陈旧 | +| `≥ freshTTL + staleTTL` | 腐烂 | + +也可以自定义判断逻辑,比如根据值里的版本字段。后端自己的 TTL(`RistrettoCacheConfig.TTL`、`RedisCacheConfig.TTL`)是硬性上限:到期后条目直接消失,相当于未命中。所以后端的 TTL 应该不小于 `freshTTL + staleTTL`,否则陈旧期还没到,条目就已经没了。 + +## 不存在缓存 + +上游明确回答「不存在」(返回 `ErrKeyNotFound`,批量时是 map 里没有这个 key)时,回填会: + +- 在不存在缓存里记下当前时间; +- 删掉后端里这个 key 的旧值。 + +不存在记录同样分新鲜、陈旧、腐烂三态,由 `NotFoundWithTTL(cache, freshTTL, staleTTL)` 或 `WithNotFound(cache, checkStale)` 配置。`staleTTL` 为 0 时没有陈旧期。 + +读到新鲜的不存在记录时,返回的 `ErrKeyNotFound` 带有 `Cached: true` 和 `CacheState`,调用方可以借此区分「刚从上游确认不存在」和「缓存里记着不存在」。 + +回填值的时候,会先删掉这个 key 的不存在记录,再写值,避免两者同时存在。 + +## 返回陈旧值 + +开启 `WithServeStale(true)` 后,读到陈旧的值或不存在记录时: + +1. 立即返回它; +2. 在后台为这个 key 发起一次**刷新**。 + +刷新按 key(准确地说是按回源槽位)去重:同一个 key 的刷新还没结束时,不会再发起第二次。刷新走的是正常的合并回源流程,所以它会和同一时刻的前台回源合并成一次。刷新用的 ctx 去掉了调用方的取消,调用方返回之后刷新仍会继续。 + +```mermaid +sequenceDiagram + participant C as 调用方 + participant L as Client + participant B as 后端 + participant U as 上游 + C->>L: Get(k) + L->>B: Get(k) + B-->>L: 陈旧的值 v1 + L-->>C: v1(立即返回) + L-)L: 后台刷新 k(同一个 k 只发起一次) + L->>U: Get(k) + U-->>L: v2 + L->>B: 回填 v2 +``` + +## 二次检查 + +### 它解决的窗口 + +合并回源只能合并**同一时刻**的请求。下面这个请求就会漏掉: + +```mermaid +sequenceDiagram + participant A as 请求 A + participant B as 请求 B + participant L as 本层后端 + participant U as 上游 + A->>L: 读,未命中 + A->>U: 认领并回源 + B->>L: 读,未命中(A 还没回填) + Note over B,L: B 的读结果还在返回途中 + U-->>A: v + A->>L: 回填 v + Note over A: A 的回源结束,在途登记被移除 + B->>B: 认领:没有在途回源,成为领头请求 + alt 不做二次检查 + B->>U: 又回源一次(多余) + else 做二次检查 + B->>L: 再读一次 + L-->>B: v(A 刚回填的) + end +``` + +窗口的大小大约是「本层一次读取的响应时间 × 这个 key 每单位时间的请求数」。后端是内存时,窗口几乎为零;后端是远程的 Redis 或数据库、key 又很热时,就很明显。实测数据见 [research/2026-10-double-check.md](../research/2026-10-double-check.md):后端读取延迟 1ms 时,开启二次检查少打了约 40% 的上游。 + +### 三种模式 + +| 模式 | 行为 | +|---|---| +| `DoubleCheckAuto`(默认) | 只有在本请求读后端之后、本 Client 往这个 key 所在的分片写过东西(写入或回填),才再读一次 | +| `DoubleCheckEnabled` | 每次回源前都再读一次 | +| `DoubleCheckDisabled` | 从不再读 | + +`Auto` 的依据是:二次检查只有在「读取之后有人往本层写了东西」时才可能读到不一样的结果;没人写过,再读也只是同样的未命中。所以请求在读后端**之前**先记下分片纪元,认领时比较一次。分片纪元变了才再读,没变就直接回源。 + +- 热点 key:前一次回源的回填会让分片纪元变化,后来的请求就会二次检查,收益和 `Enabled` 几乎一样。 +- 冷 key 和不存在的 key:期间没有任何写入,跳过二次检查,成本和 `Disabled` 几乎一样。 +- 误判:别的 key 和它落在同一个分片,并且恰好被写过,就会多读一次。这只是多一次读取,不会少读一次该读的。 +- 看不到其他进程写入共享层的值。需要这一点时用 `Enabled`。 + +决策过程见 [ADR 0008](../adr/0008-on-demand-double-check.md)。 + +### 二次检查的细节 + +- 二次检查和回源都在认领之后执行,用的是**脱离了领头请求取消**的 ctx(见 [singleflight.md](singleflight.md#回源用的-ctx)),并且受 `WithFetchTimeout` 限制。 +- 二次检查只接受**新鲜**的值或**新鲜**的不存在记录。读到陈旧的值、读失败,都照常回源。 +- 回源的超时从二次检查结束之后开始计算,二次检查花掉的时间不会挤占回源的时间。 + +## 回源与回填 + +```mermaid +sequenceDiagram + participant C1 as 请求 1(领头) + participant C2 as 请求 2(等待方) + participant L as Client + participant B as 后端 + participant N as 不存在缓存 + participant U as 上游 + C1->>L: Get(k) + L->>B: 未命中 + L->>N: 没有记录 + L->>L: 认领 k,成为领头请求 + C2->>L: Get(k) + L->>L: k 已有在途回源,等待 + L->>U: Get(k)(超时 = WithFetchTimeout) + alt 找到 + U-->>L: v + L->>N: 删除不存在记录 + L->>B: 写入 v(受分片锁保护) + else 不存在 + U-->>L: ErrKeyNotFound + L->>N: 记下不存在 + L->>B: 删除旧值 + end + L-->>C1: 结果 + L-->>C2: 同一个结果 +``` + +- 回填只写**本层**,不会写上游。上游自己的回填由上游那一层负责。 +- 回填受分片锁和写入代数保护:如果回源期间这个 key 发生过 `Set`/`Del`,或者此刻正在写,这次回填就跳过,结果照常返回。详见 [write-order.md](write-order.md)。 +- 回填时某一步失败(比如不存在缓存写不进去),另一步照样执行,失败只记 WARN 日志。删除旧值这一步尤其不能省:上游已经确认不存在了,旧值必须删掉。 diff --git a/docs/design/singleflight.md b/docs/design/singleflight.md new file mode 100644 index 0000000..57508e0 --- /dev/null +++ b/docs/design/singleflight.md @@ -0,0 +1,145 @@ +# 合并回源(singleflight) + +同一个 key 的并发未命中只回源一次:第一个请求**认领**这个 key、成为**领头请求**去回源,其他请求成为**等待方**,等它**发布**结果。`Get` 和 `GetMany` 共用同一套登记,所以一个 `Get` 和一个包含同一 key 的 `GetMany` 也只回源一次。 + +实现是 `batch.go` 里的 `flightGroup`,替代了 main 上使用的 `golang.org/x/sync/singleflight`,原因见 [ADR 0001](../adr/0001-own-flight-group.md)。 + +## 数据结构 + +```go +type flight[T any] struct { + done chan struct{} // 发布时关闭 + value T + err error +} + +type flightGroup[T any] struct { + mu sync.Mutex + flights map[string]*flight[T] // 回源槽位 key → 在途回源 +} +``` + +| 操作 | 做什么 | 谁调用 | +|---|---|---| +| `claim(sfKey)` | 有在途回源就返回它(调用方成为等待方),没有就新建并返回「你是领头请求」。**当场**给出答案,不阻塞 | 每个要回源的请求 | +| `finish(sfKey, f, value, err)` | 先从登记中移除(只在登记的仍是这个在途回源时才移除),再写入结果、关闭 `done` | 领头请求,每个在途回源恰好一次 | +| `drop(sfKey)` | 从登记中移除,但不发布结果、不打断回源 | `Set`/`Del`,见 [write-order.md](write-order.md#摘除在途回源) | + +「只在登记的仍是这个在途回源时才移除」很重要:一个被 `Set`/`Del` 摘除的回源结束时,登记里可能已经是写入之后新建的回源,不能把它删掉(见 [write-order.md](write-order.md#摘除在途回源))。 + +`finish` **先移除、再发布**:一个请求拿到结果后立刻再来读,会发现没有在途回源,于是新建一个;这时它的二次检查会读到刚回填的值。反过来,如果先发布再移除,它就可能加入一个已经结束的回源。 + +## 单个 key 的时序 + +```mermaid +sequenceDiagram + participant A as 请求 A + participant B as 请求 B + participant G as flightGroup + participant F as 回源 goroutine + participant U as 上游 + A->>G: claim(k) + G-->>A: 新建 flight,A 是领头请求 + A->>F: 启动回源(脱离 A 的取消) + B->>G: claim(k) + G-->>B: 已有 flight,B 是等待方 + par A 和 B 都等同一个 flight + A->>A: 等 done 或自己的 ctx 结束 + B->>B: 等 done 或自己的 ctx 结束 + end + F->>F: 二次检查(需要时) + F->>U: Get(k) + U-->>F: v + F->>F: 回填本层 + F->>G: finish:先移除登记,再写入 v、关闭 done + G-->>A: v + G-->>B: v +``` + +注意领头请求本身**不在自己的 goroutine 里回源**。回源由一个单独的 goroutine 执行,领头请求和其他等待方一样等结果。这样领头请求的 ctx 结束时,它可以立刻返回,回源仍然继续,为其他等待方服务。 + +## 等待方的取消 + +每个等待方只等两件事:`done` 关闭,或者**自己的** ctx 结束。 + +- ctx 先结束:返回 `context cancelled during fetch for key: …`,不影响回源本身。 +- 两者同时就绪时,Go 的 `select` 会随机选一个。`GetMany` 的等待之后还会再非阻塞地检查一次 `done`:只要结果已经在了,就用结果,不会把已经到手的结果丢掉、改报取消错误。单个 `Get` 没有这一步,和 main 一样,两者同时就绪时可能返回取消错误。 + +## 回源用的 ctx + +一次回源服务的是所有等待方,不只是领头请求。所以认领成功后,回源 goroutine 用的 ctx 是: + +- **保留**领头请求 ctx 里的值(trace、日志字段等); +- **去掉**它的取消和截止时间(`context.WithoutCancel`):领头请求放弃了,回源仍然继续; +- **去掉**它的 GORM 事务(`WithGORMTx` 放进去的那个):回填不能写进某一个调用方的事务里。 + +在这个 ctx 之上: + +- 二次检查受 `WithFetchTimeout` 限制; +- 向上游取值另外受一次 `WithFetchTimeout` 限制,计时从二次检查结束后开始。 + +决策过程见 [ADR 0007](../adr/0007-detached-fetch-context.md)。 + +## panic 与 Goexit + +上游可能 panic,也可能调用 `runtime.Goexit`(例如测试里在上游函数中调用 `t.FailNow`)。不管哪种情况,**每个在途回源都恰好发布一次结果**,等待方不会永远挂着: + +| 上游的行为 | 等待方拿到的结果 | 日志 | +|---|---|---| +| 正常返回 | 值或错误 | — | +| panic | `panic during upstream fetch: ` | ERROR,带 key 和调用栈 | +| `runtime.Goexit` | `upstream fetch exited without returning (runtime.Goexit)` | — | + +单个 key 和批量共用同一个小结构 `claimed`: + +- `publish(i, result)` 给第 i 个在途回源发布结果,重复调用无效; +- `run(ctx, idxs, body)` 执行回源,`body` panic 或调用 Goexit 时,给 `idxs` 里**还没发布的**在途回源发布错误。 + +批量时,二次检查已经找到值的 key 会先单独发布;之后某一段回源 panic,只影响这一段里还没发布的 key。 + +这一点和 `x/sync/singleflight` 不同:x/sync 在 Goexit 时,不会给 `DoChan` 的等待方发送任何结果,等待方要一直等到自己的 ctx 结束;没有截止时间的话,就永远挂着([golang/go#52557](https://github.com/golang/go/issues/52557))。cachex 有意偏离了这一点,见 [ADR 0006](../adr/0006-goexit-publishes-an-error.md)。 + +## 回源槽位 + +`WithFetchConcurrency(n)` 允许同一个 key 同时有 n 个在途回源。实现上,n 大于 1 时,回源槽位 key 是 `"i:key"`,`i` 是 `[0, n)` 里的随机数,每次请求随机落进一个槽位;n 为 1 时就是 key 本身。 + +- `n = 1`(默认):完全合并,一个 key 同一时刻只回源一次。 +- `n > 1`:请求分散到 n 个槽位,最多同时回源 n 次。代价是多打上游,好处是避免单个慢回源拖住所有请求。 +- 二次检查读的是 key 本身而不是槽位 key,所以任何一个槽位先完成回填,其他槽位之后的请求都能读到它,很快收敛。 +- `Set`/`Del` 摘除在途回源时,会摘掉这个 key 的**所有**槽位。 + +## 批量认领 + +`GetMany` 也走这套登记,但认领方式取决于上游是否支持批量: + +```mermaid +sequenceDiagram + participant M as GetMany(k1, k2, k3) + participant G as flightGroup + participant X as 另一个 Get(k2) + participant F as 批量回源 goroutine + participant U as 批量上游 + X->>G: claim(k2),成为 k2 的领头请求 + M->>G: claim(k1) → 领头 + M->>G: claim(k2) → 等待方(X 正在回源) + M->>G: claim(k3) → 领头 + M->>F: 回源自己领头的 k1、k3 + F->>U: GetMany(k1, k3) + U-->>F: 结果 + F->>G: 发布 k1、k3 + X->>G: 发布 k2 + G-->>M: k1、k2、k3 全部到齐 +``` + +- **上游支持批量**:一次性认领全部 key,把自己领头的 key 合成一次(或分段成几次)批量调用;别人正在回源的 key 就等别人的结果。认领**当场**给出答案,所以总是先发出自己的回源,再去等别人的。两个互相重叠的 `GetMany` 不会互相等待而死锁。 +- **上游不支持批量**:每个 key 在轮到它时才认领,然后按单个 `Get` 的完整流程处理。这样,一个普通 `Get` 碰上某个还在 `GetMany` 队列里排队的 key 时,不需要等整个队列。 + +详见 [batch.md](batch.md)。 + +## 后台刷新的去重 + +返回陈旧值时发起的后台刷新,用一个 `sync.Map`(`asyncRefreshing`)按回源槽位 key 去重:同一个 key 的刷新还没结束时,不会再发起新的刷新。刷新本身也走合并回源,所以它会和同一时刻的前台回源合并。 + +## 使用约束 + +上游不能在回源时**同步**回调同一个 Client 读取同一个 key:这个 key 已经被调用方认领了,回调会等待它自己的结果,形成自锁。分层的 Client 不受影响,因为每一层都有自己的 flightGroup。 diff --git a/docs/design/write-order.md b/docs/design/write-order.md new file mode 100644 index 0000000..a138934 --- /dev/null +++ b/docs/design/write-order.md @@ -0,0 +1,310 @@ +# 写入顺序与分片锁 + +这篇讲 `Set`/`Del` 怎么写、写入和回填之间怎么排序,以及支撑这一切的**分片锁**。代码在 `client.go`:`write`、`writeStripe`、`backfill`;批量回填在 `batch.go` 的 `doFetchMany`。 + +## 先说结论:对使用者意味着什么 + +TTL 是你**什么都不做时**,旧数据最多存活多久。`Set`/`Del` 是你**主动**要求「现在就让缓存变成新的」。这篇讲的机制保证:**这个主动要求不会被悄悄撤销**。在同一个进程里,`Set`/`Del` 一返回,之后的读取就不会再拿到写入之前的值。 + +没有这个保证会怎样,不是「新值早一点还是晚一点」的区别: + +- **失效等于没做**:你改了价格并调用 `Del`,`Del` 也返回成功了;但一个在改价之前就读到旧价格的请求,随后把旧价格回填进缓存。于是整个 TTL 期间(可能一小时)都显示旧价格,而且没有任何报错。 +- **数据倒退**:用户改完资料,刷新看到新资料,再刷新又变回旧的。 +- **多层之间不一致**:L1 是新值、L2 是旧值,两层过期时间不同,读到的结果会在新旧之间来回跳。 + +真正在意这一点的场景:用户改完自己的数据要立刻看到;管理员封禁账号或收回权限要马上生效;价格、库存。 + +如果从不调用 `Set`/`Del`,这套机制几乎没有成本:没有写入就不会加写锁,回填的 `TryRLock` 永远成功。分层缓存也是如此:读取过程中的回填**不走** `Set`/`Del`。L1 未命中时调用的是 L2 Client 的 `Get`;L2 回源后直接写进 L2 的后端,L1 拿到结果后直接写进 L1 的后端,两者都只拿各自分片的读锁。 + +## 使用方式:改数据源时要做什么 + +**不需要、也拿不到分片锁**,它是库内部的。只需要遵守一个顺序:**先改数据源,再通过同一个 Client 调用 `Set` 或 `Del`**。 + +```go +db.Update(&product) // ① 先改数据源 +err := client.Del(ctx, product.ID) // ② 再让缓存失效(或用 client.Set 写入新值) +``` + +在 ① 之前就读到旧值、还在回源路上的请求,不会在 ② 返回之后把旧值回填进去;在 ① 之后才开始回源的请求,读到的本来就是新值。 + +顺序反过来(先 `Del`、再改数据源)就有问题:在两步之间回源的请求会读到旧值,并且**合法地**把它回填进缓存。对库来说,这次回填发生在 `Del` 之后,它无法看出这是旧值。 + +这个保证只在**同一个进程**内成立,见 [consistency.md](consistency.md)。 + +## 写入流程 + +```mermaid +sequenceDiagram + participant C as 调用方 + participant L1 as L1 Client + participant L2 as L2 Client + participant B2 as L2 后端 + participant B1 as L1 后端 + C->>L1: Set(k, v) + L1->>L1: 拿 k 所在分片的写锁 + L1->>L2: Set(k, v)(上游是 Cache,继续往下写) + L2->>L2: 拿 L2 自己的分片写锁 + L2->>B2: 写 v(L2 的上游是数据源,不是 Cache,到此为止) + L2-->>L1: 成功 + L1->>L1: 写入代数 +1,摘除 k 的在途回源 + L1->>B1: 删不存在记录,写 v + L1->>L1: 再摘除一次在途回源,释放写锁 + L1-->>C: 成功 +``` + +- **先写上游,再写本层**:新值不会先出现在上层、而下层还没有。代价是写入过程中有一个短暂窗口:本层自己的写入落下之前,并发读本层仍会读到旧值。`Set`/`Del` 一返回,窗口就关闭了。决策过程见 [ADR 0002](../adr/0002-upstream-first-writes.md)。 +- **`Set` 写本层**:删掉不存在记录,把值写进后端。 +- **`Del` 写本层**:在不存在缓存里记下「不存在」,删掉后端的值。 +- **写到哪一层为止**:上游是 `Cache`(比如另一个 Client)就继续往下写;上游不是 `Cache`(比如 `UpstreamFunc` 包装的数据库查询)就停下。所以 cache-aside 用法(先改数据库、再 `Set`)只会写缓存层。 + +### 失败时 + +| 失败在哪一步 | 结果 | +|---|---| +| 上游写失败 | 上游的状态未知(可能已经写进去了,只是回复丢了),所以本层**删掉**这个 key 的条目和不存在记录,返回错误。下次读会回源,读到上游的真实状态 | +| 上游写成功,本层写失败 | 返回错误,但**上游的改动保留**(不回滚)。本层删掉这个 key 的条目和不存在记录,下次读回源,读到改动后的结果 | +| 等分片锁时 ctx 结束 | 返回 ctx 错误,**不写上游**。等分片空出来后,本层的这个 key 仍会被删掉(见下文) | + +一句话:**任何失败的写入,都不会在本层留下这个 key 的条目**。返回错误不代表什么都没写进去。失败后的清理用的是去掉取消的 ctx,并受 `WithFetchTimeout` 限制,因为写入失败往往正是 ctx 结束导致的。 + +## 要解决的竞态:旧值回填盖过新写入 + +读未命中时会去上游取值,取到后写进本层,这一步叫**回填**。回源需要时间,这段时间里别人可能已经 `Set` 了新值。没有任何保护时: + +```mermaid +sequenceDiagram + participant R as 读 Get(k) + participant W as 写 Set(k, v2) + participant DB as 数据源 + participant B as 本层后端 + R->>B: 未命中 + R->>DB: 读到 v1 + Note over R: 还在返回途中 + W->>DB: 写成 v2 + W->>B: 写成 v2,Set 返回 + R->>B: 把 v1 回填进去 ✗ + Note over B: 数据源是 v2,缓存却停在 v1,直到 TTL +``` + +另一个问题是两个并发的 `Set`:在 L1 → L2 的链路里,它们写 L1 和写 L2 的先后可能不同,结果 L1 留下 A 的值、L2 留下 B 的值。 + +两个问题的本质一样:**同一个 key 的写入和回填需要有先后顺序**。 + +## 为什么不是每个 key 一把锁 + +最直接的想法是 `map[string]*sync.Mutex`。问题在于锁本身的生命周期: + +- **内存没有上限**:缓存里有多少个 key,就有多少把锁。 +- **什么时候删锁**:不能用完就删,因为另一个 goroutine 可能刚拿到这把锁的指针、正准备加锁。要安全地删,就得加引用计数,再用一把全局锁保护 map,复杂度和争用都上来了。 + +**分片锁**(lock striping)换了个思路:准备**固定数量**的锁,每个 key 按哈希落到其中一把上。锁的数量和 key 的数量无关,不需要创建,也不需要删除。 + +```mermaid +flowchart LR + k1["user:42"] -- "maphash(seed, key) % 4096" --> s317["分片 317
读写锁 + 写入代数 + 回填计数"] + k2["order:9"] --> s317 + k3["sku:7"] --> s880["分片 880"] + s0["分片 0 … 4095
固定 4096 个"] +``` + +不同的 key 可能落到同一个分片(上图的 `user:42` 和 `order:9`)。这不影响正确性,只是它们会共用一把锁,代价见文末。 + +```go +const writeStripeCount = 4096 + +type writeStripe struct { + mu sync.RWMutex // Set/Del 持写锁;回填持读锁 + gen atomic.Uint64 // 写入代数:每次 Set/Del 加 1 + fills atomic.Uint64 // 每次回填写入本层加 1 +} + +func (c *Client[T]) stripe(key string) *writeStripe { + return &c.writes[maphash.String(c.writeSeed, key)%writeStripeCount] +} +``` + +哈希用标准库的 `hash/maphash`,每个 Client 在创建时随机生成种子。所以同一个 key 在不同进程、不同 Client 里落到的分片一般不同,别人也没法刻意构造一批 key 全部挤进同一个分片。 + +## 一个分片里有什么 + +| 谁 | 拿什么锁 | 拿多久 | 拿不到时 | +|---|---|---|---| +| `Set`/`Del` | 写锁(独占) | 从写上游开始,到写完本层为止 | 等待;ctx 结束就放弃 | +| 回填 | 读锁(共享),用 `TryRLock` | 只在把值写进本层的那一下 | **不等,直接跳过回填** | +| 普通的读缓存 | 不拿锁 | — | — | + +**读写锁**的规则是:写锁和任何锁互斥,读锁之间可以共存。所以多个回填可以同时进行,但回填和写入不会重叠。 + +**写入代数**(`gen`)是只增不减的计数器。每次 `Set`/`Del` 写完上游后把它加 1。回填的流程是: + +```go +gen := stripe.gen.Load() // ① 回源之前先记下写入代数 +value := upstream.Get(key) // ② 回源,可能要很久 +if !stripe.mu.TryRLock() { // ③ 有写入正在进行:不回填 + return value +} +defer stripe.mu.RUnlock() +if stripe.gen.Load() != gen { // ④ 回源期间发生过写入:不回填 + return value +} +backend.Set(key, value) // ⑤ 持着读锁写本层 +stripe.fills.Add(1) // ⑥ 记一次回填,二次检查会用到 +return value +``` + +不管回不回填,读到的值都会照常返回给调用方。不回填的唯一代价是:下一次读还是未命中,要再回源一次。 + +**回填计数**(`fills`)只用于二次检查:写入代数加回填计数,就是**分片纪元**。默认的 `DoubleCheckAuto` 用它判断「读取之后本 Client 有没有往这一层写过东西」,见 [read-path.md](read-path.md#二次检查)。 + +## 三种时序,逐一检查 + +回填和写入只有三种相对时间关系。逐个看,它们都不会留下旧值。 + +### 情况 A:写入发生在回源期间,回填时写入已经结束 + +```mermaid +sequenceDiagram + participant R as 读 + participant S as 分片(gen) + participant W as 写 Set(v2) + participant B as 本层后端 + R->>S: 记下 gen = 5 + R->>R: 回源读到 v1 + W->>S: 拿写锁 + W->>W: 写上游 + W->>S: gen = 6 + W->>B: 写 v2 + W->>S: 释放写锁 + R->>S: TryRLock 成功 + R->>S: gen 是 6 ≠ 5,跳过回填 ✓ + Note over B: 仍然是 v2 +``` + +**靠写入代数挡住。** 这正是上面那个竞态。光有锁挡不住:回填时锁是空闲的,只有写入代数能告诉回填「你读到的值已经过时了」。 + +### 情况 B:回填的时候,写入正在进行 + +```mermaid +sequenceDiagram + participant R as 读 + participant S as 分片 + participant W as 写 Set(v2) + participant B as 本层后端 + R->>S: 记下 gen + R->>R: 回源读到 v1 + W->>S: 拿到写锁,正在写上游 + R->>S: TryRLock 失败,跳过回填 ✓ + R->>R: 把 v1 返回给调用方 + W->>S: gen +1 + W->>B: 写 v2 + W->>S: 释放写锁 +``` + +**靠锁挡住。** 此时写入代数还没变(写完上游才加 1),只看代数会放行,所以锁是必需的。用 `TryRLock` 而不是 `RLock`,是为了让读**永远不等写**:写可能要等上游好几百毫秒,读不应该被它拖住。 + +### 情况 C:回填先完成,写入在后 + +```mermaid +sequenceDiagram + participant R as 读 + participant S as 分片 + participant W as 写 Set(v2) + participant B as 本层后端 + R->>S: 记下 gen,回源读到 v1 + R->>S: 拿到读锁,gen 没变 + W->>S: 想拿写锁,等读锁释放 + R->>B: 写 v1 + R->>S: 释放读锁 + W->>S: 拿到写锁 + W->>W: 写上游 + W->>B: 写 v2 ✓ +``` + +**靠先后顺序本身。** 回填完整地发生在写入之前,随后被写入覆盖。`Set` 只会等回填写本层的那一下,不会等回源。 + +三种情况的共同结论:**回填要么在某次写入之前落下(随后被覆盖),要么被跳过**,永远不会在 `Set`/`Del` 返回之后落下。 + +## 摘除在途回源 + +分片锁管住了回填,但还有一条路能读到旧值:**加入一次更早开始的回源**。比如请求 A 在 `Del` 之前就开始回源、读到了旧值;`Del` 返回之后请求 B 来读,本层未命中,B 通过合并回源加入 A 的回源,于是拿到了已删掉的值。 + +所以 `write` 在两个时间点**摘除**这个 key 的在途回源(包括所有回源槽位): + +1. **写完上游之后**:此后开始的读不会再加入之前的回源。 +2. **写完本层之后**(释放写锁之前):在「写完上游」和「写完本层」之间认领的回源,二次检查时可能读到了本层还没删掉的旧值,也要摘掉。 + +摘除**不打断**回源:已经在等的请求照样拿到结果(它们开始得比写入早,看到旧值是合理的);之后来的请求找不到登记,会重新回源。被摘掉的回源自己的回填会因为写入代数变了而跳过。 + +```mermaid +sequenceDiagram + participant A as 请求 A(写入前开始) + participant W as Del(k) + participant G as flightGroup + participant B as 请求 B(Del 返回后开始) + participant U as 上游 + A->>G: claim(k),回源中(读到旧值 v1) + W->>W: 写上游(删除) + W->>G: drop(k) + W->>W: 删本层,再 drop(k),Del 返回 + B->>G: claim(k):没有登记,新建回源 + B->>U: Get(k) + U-->>B: 不存在 ✓ + A-->>A: A 自己拿到 v1(它开始得早),但回填被跳过 +``` + +## 批量回填为什么不会死锁 + +`GetMany` 一批可能有上千个 key,落在几百个分片上。它的回填要同时持有这些分片的读锁,然后一次 `SetMany` 写进本层。 + +平常同时拿多把锁必须按固定顺序拿,否则会死锁。这里不需要排序,因为 `TryRLock` **从不等待**:拿不到就跳过那个分片的 key。死锁的前提是「拿着一把锁,再等另一把」,而回填从不等待;`Set`/`Del` 只拿一把写锁,也不会「拿着一把等另一把」。 + +## 等写锁时尊重 ctx + +`sync.RWMutex` 的 `Lock()` 没法被取消。如果前一个 `Set` 卡在上游,后面的 `Set` 就会无视自己的超时一直等下去。所以 `writeStripe.lock` 这样实现: + +```mermaid +flowchart TD + a[TryLock] -- 成功 --> ok([拿到锁,即使 ctx 已经结束]) + a -- 失败 --> b[开一个 goroutine 去 Lock] + b --> c{先到的是?} + c -- 锁 --> ok2([拿到锁]) + c -- ctx 结束 --> d([返回 ctx 错误,什么都不写上游]) + d -.-> e[后台 goroutine 之后拿到锁] + e -.-> f[收尾:写入代数 +1、摘除在途回源、删掉本层条目] + f -.-> g[释放锁] +``` + +1. **先 `TryLock`**:分片空闲就直接拿到,即使 ctx 已经结束也照常写。这样「请求取消之后才调用 `Del` 做失效」的场景仍然有效。 +2. **拿不到**,就开一个 goroutine 去 `Lock()`,自己同时等「锁到手」和「ctx 结束」。 +3. **ctx 先结束**:返回错误,不写上游。那个 goroutine 继续排队,拿到锁后执行一次收尾(写入代数加 1、摘除在途回源、删掉本层这个 key 的条目),然后释放锁。 + +收尾这一步,是为了兑现「任何失败的写入都不留下本层条目」:`Set` 返回了错误,调用方并不确定数据处于什么状态,本层就不应该继续挂着可能过时的值。 + +## 慢操作会拖慢多大范围 + +锁只在写入时才让别人等,而且读永远不等。两类慢操作的影响范围差别很大: + +| 慢的是什么 | 占着哪些分片 | 谁会被拖住 | 谁不受影响 | 最长多久 | +|---|---|---|---|---| +| **一次大 GetMany 的批量回填**(例如 1000 个 key 的 `SetMany` 写得慢) | 这批 key 涉及的**全部**分片(约 22%),读锁 | 这些分片上**任何** key 的 `Set`/`Del`,包括和这批 key 无关的 | 所有读;其他回填(读锁可以共存) | 受这批回源的超时限制 | +| 单个 key 的回填 | 1 个分片,读锁,只在写本层的那一下 | 同一分片上的 `Set`/`Del`,只等很短一下 | 其余一切 | 一次本层写入 | +| **一个慢的 `Set`/`Del`**(例如下层 Redis 卡住) | **只有 1 个分片**(1/4096),写锁 | 同一分片上其他 key 的 `Set`/`Del` 排队;同一分片上的回填被**跳过**(多一次未命中,不会等) | 所有读;其余 4095 个分片 | 受这次写入的 ctx 和下层自身的超时限制;排队的写在自己的 ctx 结束时放弃 | + +「一个慢操作拖慢一大片分片」只对**批量回填**成立。如果你的场景里有很大的 `GetMany`(远超 1000 个 key),同时又有频繁的写入,可以设置 `WithGetManyChunkSize(n)`:每一段上游调用**各自**回填,只锁这一段 key 的分片,写完就释放。一万个 key、按 1000 分段时,每段只占约 22% 的分片,持锁时间也只有原来的十分之一左右。注意各段是并发执行的(最多 `WithGetManyFetchConcurrency` 段),同时回填的段会叠加;要真正限制同时占住的分片,还要一起调小 `WithGetManyFetchConcurrency`。后端的往返次数不变,因为后端本来就按 1000 个一段发送;上游调用则从 1 次变成 10 次。 + +注意:调小后端的 `ChunkSize` **没有**这个效果。它只决定一次 `SetMany` 拆成几条语句,而分片锁在整个 `SetMany` 期间一直被持有。批量在 1000 个 key 以内时,两种做法没有区别。 + +## 代价汇总 + +| 项目 | 数值 | 说明 | +|---|---|---| +| 内存 | 160 KB / Client | 每个分片 40 字节(读写锁 24 + 两个计数器各 8)× 4096,直接内嵌在 Client 结构体里,不需要额外分配 | +| 两个指定的 key 撞进同一分片 | 1 / 4096 | 撞上后:它们的写入互相排队;一个 key 的写入可能让另一个 key 的回填被跳过(多一次未命中) | +| 一次 1000 个 key 的 GetMany 覆盖的分片 | 约 22% | 1 − (4095/4096)^1000;一万个 key 时约 91% | +| 读路径 | 无等待 | 读缓存不拿锁;回填只用 `TryRLock`,拿不到就跳过 | + +撞分片的代价只体现在延迟和偶尔多一次未命中上,**永远不会读到错的值**。分片数从最初的 1024 调到了 4096:碰撞少到四分之一,内存从 32KB 增加到 160KB。决策过程见 [ADR 0003](../adr/0003-striped-backfill-guard.md)。 + +## 使用约束 + +上游是 `Cache` 时,它的 `Set`/`Del` 不能同步回调同一个 Client、写同一个分片上的任何 key(不只是同一个 key):调用方正持有这个分片的写锁,回调会一直等到自己的 ctx 结束。分层的 Client 不受影响,因为每一层都有自己的分片。 diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 0000000..85f1e2b --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,132 @@ +# 常见问题 + +每个问题先给结论,再给依据。设计细节以 [design.md](design.md) 及其分篇为准。 + +## 使用 + +### 什么时候用 `Entry[T]`,什么时候自定义新鲜度判断? + +只按时间判断过期时,用 `Entry[T]` 配合 `EntryWithTTL(freshTTL, staleTTL)`。需要业务相关的判断时(比如检查值里的 `version` 字段),用 `WithStale` 传入自己的判断函数。见 [design/read-path.md](design/read-path.md#新鲜度)。 + +### 新鲜期和陈旧期有什么区别? + +新鲜期内直接返回;新鲜期之后的**额外**一段时间是陈旧期,开启 `WithServeStale` 时,这段时间里的读取会先拿到旧值,同时后台刷新。条目的总寿命是「新鲜期 + 陈旧期」。后端自己的 TTL 要不小于这个总寿命,否则陈旧期还没到,条目就已经没了。 + +### 是不是所有数据库查询都该缓存? + +不是。缓存访问频繁、相对稳定的数据。不适合缓存的: + +- 变化非常频繁的数据(要求不到 1 秒就更新); +- 基数很高、按用户区分的数据; +- 在内存里存不划算的大对象。 + +### 改了数据源之后要做什么?需要先拿分片锁吗? + +不需要,也拿不到,分片锁是库内部的。只要遵守一个顺序:**先改数据源,再通过同一个 Client 调用 `Set` 或 `Del`**。顺序反过来(先 `Del` 再改数据源),中间回源的请求会读到旧值,并合法地把它回填进缓存。见 [design/write-order.md](design/write-order.md#使用方式改数据源时要做什么)。 + +### 缓存的值是 nil,怎么和「不存在」区分? + +缓存一个 nil(比如空指针)也算命中: + +- `Get` 返回 `(nil, nil)`,不会返回 `ErrKeyNotFound`; +- `GetMany` 的 map 里有这个 key,值是 nil。 + +所以判断 key 在不在,要用 `v, ok := m[k]`,不能用 `m[k] == nil`。 + +### 为什么 `GetMany` 的 `BatchError` 里没有「不存在」的 key? + +批量读里,**不存在不算错误**:不存在的 key 就是不出现在 map 里,`BatchError` 只列真正失败的 key。缓存的批量读几乎每次都有未命中,如果把不存在也算作错误,`err` 就几乎总是非 nil,调用方每次都得过滤。每个 key 必然是三种结果之一: + +| 结果 | `Get` | `GetMany` | +|---|---|---| +| 找到了 | `(value, nil)` | 在 map 里 | +| 不存在 | `IsErrKeyNotFound(err)` | 既不在 map 里,也不在 `BatchError` 里 | +| 失败了 | 其他 error | 在 `BatchError` 里 | + +见 [ADR 0004](adr/0004-batch-result-shape.md)。 + +### `Get` 为什么还要返回 `ErrKeyNotFound`,和 `GetMany` 不一致? + +两者表达的是同一套三种结果,只是方式不同。`Get` 只返回一个值,没法用「缺席」表示不存在:值本身可能就是合法的 nil;`T` 是 int 时,零值更无法表示缺席。这和 `database/sql` 一样:`QueryRow` 查不到时返回 `ErrNoRows`,`Query` 查不到时只是没有行。 + +## 合并回源与二次检查 + +### 缓存击穿是怎么防的? + +两层: + +1. **合并回源**(主要):同一个 key 的并发未命中只回源一次,其他请求等它的结果。`WithFetchConcurrency(n)` 允许同一个 key 同时有 n 个回源(默认 1,即完全合并),用一些冗余换取更高的吞吐。见 [design/singleflight.md](design/singleflight.md)。 +2. **二次检查**(补充):请求 B 在请求 A 回填之前读到未命中,却在 A 的回源结束之后才认领,B 会再读一次缓存,而不是再回源一次。 + +### 二次检查值得开吗?默认开吗? + +默认按需开启(`DoubleCheckAuto`):只有在请求读缓存之后、本 Client 往这个 key 所在的分片写过东西时,才再读一次。实测: + +- 后端读取 1ms、热点 key 时,上游调用从 30 次降到 19 次(总是开启是 18 次); +- 冷 key 上几乎没有额外读取(每次 `Get` 读 1.005 次,总是开启是 2 次); +- 后端是内存时,开不开没有区别。 + +需要看到其他进程写进共享缓存的值时,用 `DoubleCheckEnabled`。见 [ADR 0008](adr/0008-on-demand-double-check.md) 和 [research/2026-10-double-check.md](research/2026-10-double-check.md)。 + +### 上游 panic 或调用 `runtime.Goexit` 时会怎样? + +这次回源的所有等待方都会收到错误,不会挂住: + +- panic 时是 `panic during upstream fetch: …`,并记一条带调用栈的 ERROR 日志; +- Goexit 时是 `upstream fetch exited without returning (runtime.Goexit)`。 + +后者和 `x/sync/singleflight` 不同(x/sync 会让等待方一直等到自己的 ctx 结束),是有意的,见 [ADR 0006](adr/0006-goexit-publishes-an-error.md)。 + +## 写入顺序与分片锁 + +### 保证写入顺序有什么用?反正都要承受 TTL。 + +TTL 是**不主动写入**时旧数据的存活上限。`Set`/`Del` 是你主动要求「现在就变成新的」。顺序保证的是,这个要求不会被一个更早开始的回源悄悄撤销。没有它,`Del` 返回成功后,旧值仍可能被回填进去,并存活整个 TTL;用户还可能看到数据先变新、再变回旧的。见 [design/write-order.md](design/write-order.md#先说结论对使用者意味着什么)。 + +### 分层缓存里,读取会不会通过 `Set`/`Del` 去写下一层、从而加写锁? + +不会。读取时的回填直接写本层的后端,只拿读锁;L1 未命中时调用的是 L2 的 `Get`。只有业务代码主动调用 `Set`/`Del` 时才会加写锁。 + +### 一个慢操作会拖慢多大范围? + +- 慢的 `Set`/`Del` 只占它自己的 1 个分片(共 4096 个); +- 一次大批量回填会在回填期间占住它所有 key 的分片(1000 个 key 约 22%),这些分片上的写入要排队; +- 读永远不等。 + +批量远超 1000 个 key 时,用 `WithGetManyChunkSize` 让每段各自回填、只占自己的分片。调小后端的 `ChunkSize` 没有这个效果。见 [design/write-order.md](design/write-order.md#慢操作会拖慢多大范围)。 + +### 多个实例部署时,还保证写入顺序吗? + +不保证。分片锁只在一个进程内有效: + +- 其他实例的内存层看不到你的写入,会一直返回旧值,直到过期; +- 另一个实例可能把旧值回填进共享的 Redis。 + +目前靠 TTL 兜底,所以内存层和共享层的 TTL 都要按「能接受旧数据存活多久」来设。Redis 租约和失效广播在 [todo](todo.md) 里。见 [design/consistency.md](design/consistency.md)。 + +## 批量读 + +### `GetMany` 的结果是一个一个返回的,还是一起返回? + +一起返回。新鲜的值、陈旧的值(开启返回陈旧值时)、回源拿到的值都放进同一份结果,最后一次性返回。陈旧的 key 会在后台另外刷新。 + +### 并发的 `Get` 碰上 `GetMany` 正在回源的 key,要等多久? + +- 上游支持批量时,`Get` 要等这一次批量调用(设置了分段时是这一段)整体返回。 +- 上游不支持批量时,key 轮到它才被认领,所以 `Get` 不会被 `GetMany` 的排队拖住。 + +### `WithFetchConcurrency` 和 `WithGetManyFetchConcurrency` 有什么区别? + +- 前者限制**同一个 key** 最多同时有几个回源; +- 后者限制**一次 `GetMany`** 最多同时向上游发出几个请求(逐 key 的 `Get`,或分段的批量调用)。 + +## 后端 + +### MySQL 上用 GORMCache 有什么要求? + +- **新建表**需要 MySQL 8.0.17 及以上:`Migrate` 会用 `utf8mb4_0900_bin`,让 key 精确比较大小写和末尾空格,建表前会检查版本。 +- 已经存在的老表不会被改动,也不会读到别的 key 的值;只差大小写的 key 会互相挤占同一行。转换老表的语句见 [design/backends.md](design/backends.md#key-必须精确比较)。 + +### 多个实例同时写 GORMCache 会死锁吗? + +极少失败:写入统一按字节序加锁,偶发的死锁(MySQL 的间隙锁)会自动重试(最多执行 5 次)。重试用尽仍会报错;回填失败只记 WARN 日志,下次读取再回源。老的 MySQL `*_ci` 表加锁顺序不是字节序,只能靠重试兜底。在你自己的事务里(`WithGORMTx`)不会重试,因为死锁已经回滚了整个事务。见 [ADR 0010](adr/0010-gorm-deadlock-ordering-and-retry.md)。 diff --git a/docs/research/2026-10-batch-result-shape.md b/docs/research/2026-10-batch-result-shape.md new file mode 100644 index 0000000..dee5648 --- /dev/null +++ b/docs/research/2026-10-batch-result-shape.md @@ -0,0 +1,37 @@ +# 批量读的返回形态 + +日期:2026-10-09。对应决策:[ADR 0004](../adr/0004-batch-result-shape.md)。 + +## 问题 + +`GetMany` 该返回哪种形态?从性能角度看,哪种最快? + +- A. `map[string]T`:不存在的 key 不放进 map(现在的做法) +- B. `map[string]Result[T]`:每个 key 都有一项,不存在用 `Err = ErrKeyNotFound` 表示 +- C. `[]Result[T]`:按请求 key 的顺序一一对应 + +## 方法 + +构造结果的开销,一半 key 命中、一半不存在(缓存中常见的情况)。不存在用一个共享的错误实例,不为每个未命中单独分配。 + +## 结果(Apple M 系列,Go 1.27) + +| 形态 | 100 个 key | 10000 个 key | 内存(10000 个 key) | +|---|---|---|---| +| A. `map[string]T` | 633 ns | 66 µs | 328 KB | +| B. `map[string]Result[T]` | 1271 ns | 171 µs | 918 KB | +| C. `[]Result[T]` | 279 ns | 38 µs | 328 KB | + +- C 最快,但只比 A 快约 1.7 倍。B 最慢,耗时和内存都接近 A 的 3 倍:它要给每个未命中也放一项,而且每项多一个 error 接口(16 字节)。 +- 放到整次 `GetMany` 里看,差别很小:10000 个 key 时,A 和 C 相差不到 30µs,而一次 Redis 往返就要几百微秒,还有 10000 个值的解码。 +- 调用方拿到 C 之后,大多还是要按 key 查值,等于把建 map 的成本转移给了调用方。 + +所以性能不是决定因素。决定因素是:C 有「结果错位、拿到别的 key 的值」的风险,B 要求实现方为每个缺席的 key 补一项。在两者都安全的前提下,A 是最快的。 + +如果 `ErrKeyNotFound` 每次都用 `pkg/errors` 包一层,会额外抓取调用栈。B 方案下每个未命中都要付这个代价,所以如果真要采用 B,必须使用共享实例。 + +## 复跑 + +```sh +go test -tags bench -bench . ./tools/bench/2026-10-batch-result-shape/ +``` diff --git a/docs/research/2026-10-double-check.md b/docs/research/2026-10-double-check.md new file mode 100644 index 0000000..8eb8fe5 --- /dev/null +++ b/docs/research/2026-10-double-check.md @@ -0,0 +1,47 @@ +# 二次检查的价值 + +日期:2026-10-09。对应决策:[ADR 0008](../adr/0008-on-demand-double-check.md)。 + +## 问题 + +二次检查是在认领回源之后、去上游之前,再读一次本层(见 [design/read-path.md](../design/read-path.md#二次检查))。它有多大收益、多大成本?原来的默认规则「配置了不存在缓存就开启」合理吗? + +## 方法 + +- 上游每次回源耗时 5ms。 +- 后端用内存 map 模拟,**先读数据,再等一段延迟才返回**,模拟远程缓存「服务端很快读完,回复在网络上要走一段时间」。延迟分三档:0、200µs、1ms。 +- **开环负载**:每毫秒新发起 20 个 `Get`,持续 400ms,不管前面的请求有没有返回。 +- 两个场景: + - 热点 key:一个 key,每 20ms 过期一次(没有陈旧期,过期即回源); + - 冷 key:每个请求都是一个新 key,共 8000 个。 +- 每个组合跑 3 次取平均。 + +## 走过的弯路 + +前两版实验都显示「开不开二次检查没有区别」,原因都在实验本身: + +1. **后端先等延迟、再读数据**:竞态窗口就是「读完数据」到「客户端拿到结果去认领」之间的这段路程,这个模型把它压成了零。 +2. **闭环负载**(固定 200 个 goroutine 循环调用):回源期间所有 goroutine 都在等这次回源,没有新请求进来,自然撞不上窗口。真实流量是开环的。 + +## 结果 + +| 场景 | 后端延迟 | Enabled | Auto(按需) | Disabled | +|---|---|---|---|---| +| 热点 key:上游调用次数 | 0 | 18 | 18 | 19 | +| | 200µs | 18 | 18 | 19 | +| | 1ms | 18 | 19 | **30** | +| 热点 key:每次 Get 读后端次数 | 1ms | 1.004 | 1.002 | 1.000 | +| 冷 key:每次 Get 读后端次数 | 1ms | **2.000** | 1.005(另一次运行为 1.004) | 1.000 | + +- 竞态窗口约等于「后端读取的响应时间 × 这个 key 的请求速率」。后端在内存里时窗口几乎为零,二次检查没有收益。 +- 后端读取 1ms、key 很热时,关闭二次检查会多打约 60% 的上游(30 次对比 18 次);换句话说,开启后少打约 40%。 +- 成本只出现在认领回源的那个请求上:热点 key 上摊到每次 Get 几乎可以忽略;但冷 key 上,**总是开启**的话,每次未命中都要多读一次后端(2.000)。 +- 按需二次检查(只在「读取之后本 Client 往这个 key 所在的分片写过」时才再读)在热点 key 上拿到了几乎全部收益(19 对比 18),在冷 key 上几乎零成本(1.005 对比 1.000)。多出来的 0.5%,来自和别的 key 共用分片导致的误判。 + +这是一个合成负载:只有一个热点 key,没有开启返回陈旧值,并在 macOS 上用 `time.Sleep` 模拟延迟。数字的量级可信,具体比例不宜当成定论。 + +## 复跑 + +```sh +go test -tags bench -run TestDoubleCheckValue -v ./tools/bench/2026-10-double-check/ +``` diff --git a/docs/research/2026-10-gorm-deadlock.md b/docs/research/2026-10-gorm-deadlock.md new file mode 100644 index 0000000..87fae58 --- /dev/null +++ b/docs/research/2026-10-gorm-deadlock.md @@ -0,0 +1,70 @@ +# GORMCache 并发批量写的死锁 + +日期:2026-10-09。对应决策:[ADR 0010](../adr/0010-gorm-deadlock-ordering-and-retry.md)。 + +## 问题 + +多个实例同时用 `GetMany` 回填有重叠的 key 时,`GORMCache.SetMany`/`DelMany` 会在数据库里死锁。被数据库中止的那次回填只记一条 WARN 日志,这些 key 就一直没能缓存上;PostgreSQL 每次死锁还要先等 `deadlock_timeout`(默认 1 秒)才能检测出来,期间一直占着行锁和 cachex 的分片。 + +死锁有两个来源: + +1. `SetMany` 按 Go map 的随机顺序生成多行 upsert。两条语句以相反的顺序锁同样的几行。 +2. PostgreSQL 的 `DELETE … WHERE key IN (…)` 按索引顺序锁行,而索引顺序跟着列的排序规则走(官方镜像默认是 `en_US.utf8`),和 `SetMany` 排序用的字节序不一致。key 里大小写混排时(`a000`、`B001`……),两者的顺序正好相反。 + +## 方法 + +- 用 testcontainers 起 MySQL 8.4 和 PostgreSQL 16(默认配置,PostgreSQL 的数据库排序规则是 `en_US.utf8`)。 +- key 大小写混排,让字节序和 `en_US` 的顺序不同。 +- N 个 worker 并发,每轮从 key 空间里随机取 100 个 key,60% 的概率 `SetMany`、40% 的概率 `DelMany`。 +- 统计被数据库判为死锁的操作次数和吞吐量。「锁表」用 MySQL 的 `GET_LOCK` 或 PostgreSQL 的 `pg_advisory_xact_lock` 让同一张表的写入串行执行,效果等同于锁表。 + +## 结果 + +### 第一轮:8 个 worker × 40 轮,400 个 key + +这一轮的「现状」是当时的代码:`SetMany` 已经排序,`DelMany` 是普通的 `DELETE … IN`。 + +| 方案 | MySQL 死锁 | MySQL 吞吐 | PostgreSQL 死锁 | PostgreSQL 吞吐 | +|---|---|---|---|---| +| 现状 | 2 / 320 | 890 ops/s | **149 / 320** | **2 ops/s**(140 秒) | +| 只重试 | 0 | 892 | 51 / 320 | 1 ops/s(460 秒) | +| `DELETE` 也按字节序加锁 | 4 / 320 | 893 | **0** | **1566** | +| MySQL 改用 READ COMMITTED | 8 / 320 | 847 | — | — | +| 锁表 | 0 | 728 | 0 | 1227 | + +- PostgreSQL 的死锁绝大多数来自来源 2。让 `DELETE` 按字节序加锁后直接归零,吞吐也是所有方案里最高的。 +- 只重试,在 PostgreSQL 上反而更糟:重来一遍还会撞上。 +- MySQL 上即使加锁顺序统一,仍有少量死锁,来自间隙锁和插入意向锁的交互。改用 READ COMMITTED 反而更多。InnoDB 的文档要求应用对这类死锁自行重试。 + +### 第二轮:16 个 worker × 80 轮,2000 个 key + +| 方案 | MySQL | PostgreSQL | +|---|---|---| +| 统一加锁顺序 | 3 次死锁 / 1280,949 ops/s | 0,1922 ops/s | +| **统一加锁顺序 + 重试(采用)** | **0,840 ops/s** | **0,1936 ops/s** | +| 锁表 | 0,647 ops/s(-32%) | 0,1045 ops/s(-46%) | + +锁表的吞吐损失随并发上升:8 个 worker 时约 -20%,16 个时 -32% 到 -46%。缓存层正是高并发的地方,所以没有采用。 + +这两轮实验里,MySQL 的「锁表」在事务提交之前就释放了命名锁,锁得不够严格;严格的锁表吞吐只会更低,结论不变。复跑脚本已经改成提交之后才释放。 + +### 复跑脚本的抽样结果 + +`tools/bench/2026-10-gorm-deadlock` 把上面的方案整理成了四种:`unordered` 是修复之前的写法(随机顺序 upsert,普通 `DELETE`);`ordered` 是统一加锁顺序但不重试;`ordered+retry` 直接调用现在的 `GORMCache`;`table lock` 是锁表。用很小的负载(8 个 worker × 10 轮)验证过脚本: + +| 方案 | MySQL 死锁 | PostgreSQL 死锁 | +|---|---|---| +| unordered | 52 / 80 | 30 / 80(24 秒) | +| ordered | 0 / 80 | 0 / 80 | +| ordered+retry(GORMCache) | 0 / 80 | 0 / 80 | +| table lock | 0 / 80 | 0 / 80 | + +这么小的负载下,吞吐量没有参考意义;比较吞吐请用默认负载复跑。脚本只复现第二轮的设置(2000 个 key),第一轮的「只重试」和「READ COMMITTED」两种方案没有放进脚本。 + +## 复跑 + +```sh +# 需要 Docker。默认 16 个 worker × 80 轮;unordered 在 PostgreSQL 上很慢(每次死锁都要等 1 秒) +go test -tags bench -run TestDeadlockStrategies -v -timeout 60m ./tools/bench/2026-10-gorm-deadlock/ +WORKERS=8 ROUNDS=10 go test -tags bench -run TestDeadlockStrategies -v ./tools/bench/2026-10-gorm-deadlock/ +``` diff --git a/docs/research/README.md b/docs/research/README.md new file mode 100644 index 0000000..854a3c3 --- /dev/null +++ b/docs/research/README.md @@ -0,0 +1,9 @@ +# 实测与调研 + +| 报告 | 结论 | 复跑脚本 | +|---|---|---| +| [2026-10-gorm-deadlock.md](2026-10-gorm-deadlock.md) | 统一加锁顺序加有限重试,在 MySQL 和 PostgreSQL 上都消除了并发批量写的死锁;锁表也能做到,但吞吐低 32% 到 46% | [tools/bench/2026-10-gorm-deadlock](../../tools/bench/2026-10-gorm-deadlock/) | +| [2026-10-double-check.md](2026-10-double-check.md) | 二次检查只在后端读取有延迟、key 又很热时有收益;按需二次检查在热点 key 上拿到几乎全部收益,在冷 key 上几乎零成本 | [tools/bench/2026-10-double-check](../../tools/bench/2026-10-double-check/) | +| [2026-10-batch-result-shape.md](2026-10-batch-result-shape.md) | 批量读的三种返回形态里,按 key 顺序排列的切片最快,`map[string]Result` 最慢;和一次后端往返相比,差别可以忽略 | [tools/bench/2026-10-batch-result-shape](../../tools/bench/2026-10-batch-result-shape/) | + +复跑脚本都带 `bench` 这个 build tag,平时的 `go test ./...` 不会运行它们。复跑命令写在各报告和脚本的开头。 diff --git a/docs/todo.md b/docs/todo.md new file mode 100644 index 0000000..f6f1661 --- /dev/null +++ b/docs/todo.md @@ -0,0 +1,162 @@ +# 待办 + +发现了但这次不解决的问题、设计缺口。做完就从这里删掉。 + +## 1. 过期时间抖动(防缓存雪崩) + +- **问题:** cachex 用合并回源防击穿、用不存在缓存防穿透,但没有防**雪崩**的机制:同一时刻写入的大量 key(冷启动预热、一次 `GetMany` 回源取回 1000 个 key)会在同一时刻一起过期,届时大量请求同时回源。`EntryWithTTL` 的新鲜度判断完全确定,只看 `CachedAt + freshTTL`;Redis 等后端的 TTL 也是固定值。 +- **做法:** 加一个可选的抖动比例(例如 `WithTTLJitter(0.1)` 表示正负 10%),按 key 的哈希计算一个固定的偏移量:不用额外存储,同一个 key 每次判断结果一致。后端 TTL 的抖动在各后端的配置里单独考虑。 +- **注意:** 默认关闭,因为开启后会改变现有用户的过期时间。 + +## 2. 多实例一致性 + +分片锁只在单个 Client 所在的进程内保证顺序。多个实例共用 Redis 等下层时,下面两点目前只靠 TTL 兜底,见 [design/consistency.md](design/consistency.md) 和 [ADR 0011](adr/0011-cross-instance-consistency-via-ttl.md)。 + +### 2.1 Redis 租约:防止旧值回填进共享层,并做跨实例的回源去重 + +- **问题一(旧值回填):** 实例 A 未命中,从数据源读到旧值;实例 B 随即写入数据源,并更新或删除共享缓存;A 再把旧值回填进共享缓存,旧值一直留到 TTL 到期。 +- **问题二(跨实例回源):** 部署 20 个实例时,每个实例的合并回源只在自己进程内生效。一个热点 key 过期,数据源会被回源 20 次。 +- **做法:** + - 读未命中时,用一段 Lua 原子地执行 `GET k`,若为空就写入 `lease:k = 随机令牌`,并返回令牌。读和领租约必须在同一个原子操作里。 + - 任何写入(Set/Del)都顺带删除 `lease:k`,让所有在途令牌作废(可以放进写入的同一个 pipeline)。 + - 回填用另一段 Lua:只有 `lease:k` 仍等于自己的令牌时才写入值。 + - 别的实例发现已有租约时,等待一小段时间再读,或者先返回陈旧值,不再回源。这就解决了问题二。 +- **代价:** 往返次数不变;未命中时多写一个租约 key,回填改用 `EVALSHA`,写入多一个 `DEL`。不要求数据源提供版本号。 +- **实现考虑:** + - 新增可选接口(例如 `LeaseCache`),后端实现了它,Client 才走这条路;批量读要支持批量领租约。 + - 先做 `RedisCache`;`GORMCache` 视需要跟进(租约列或租约表,加条件更新)。 + - 延迟双删只能缩小窗口,进程退出就失效,不做进库里。 + +### 2.2 用 Redis Pub/Sub 广播失效(可选) + +- **问题:** 一个实例上的写入到达不了其他实例的内存层,它们会一直返回旧值,直到过期。 +- **做法:** 写入后在一个频道上发布被改动的 key,订阅的实例删除自己内存层里的这些 key。 +- **注意:** 断线期间的消息会丢失,最终仍要靠 TTL 兜底。做成可选功能,默认关闭。 + +## 3. 小问题 + +- **单 key 的后台刷新把「不存在」也记成 ERROR:** `asyncRefresh` 在上游返回不存在时会记一条 `async refresh failed` 的 ERROR 日志,而批量的 `asyncRefreshMany` 会跳过不存在。main 上就是这样。应该统一成跳过不存在。 +- **GORMCache 在 SQLite 上存不了 JSON 标量数字:** `T = float64` 这类值,SQLite 会把 JSON 存成数字类型,`datatypes.JSON` 读回来时扫描失败。结构体、字符串不受影响。需要确认 MySQL 和 PostgreSQL 上是否也有这个问题,再决定是在读取时兼容,还是在文档里说明限制。 + +## 4. GORM 缓存改进 + +### 清理 Worker + +为 `GORMCache` 实现后台清理 worker,用于删除过期条目: + +- **需求:** + + - 必须使用细粒度的分段操作(避免大批量删除) + - 应持续运行,具有可配置的间隔时间 + - 删除策略:细水长流(例如每批 100 条记录) + - 应考虑数据库负载并实现背压机制 + - 考虑添加监控指标以观察清理操作 + +- **实现考虑:** + - 使用 `updated_at` 时间戳识别过期条目 + - 可配置的过期阈值(例如删除 7 天前的条目) + - 支持优雅关闭(缓存关闭时停止 worker) + - 可选:基于数据库性能的自适应分段大小 + +## 5. 热度统计 + +### 核心热度追踪功能 + +实现热度统计机制以跟踪缓存 key的访问模式: + +- **需求:** + + - 跟踪每个 key的访问频率 + - 跟踪最后访问时间戳 + - 衰减机制以降低旧访问的权重 + - 高效的数据结构(例如并发 map 或时间窗口计数器) + - 可配置的统计数据保留期限 + +- **需要追踪的指标:** + - 每个 key的命中次数 + - 最后访问时间 + - 访问速率(每时间窗口的命中次数) + - 可选:区分缓存命中和缓存未命中 + +### 用于热点 Key 记录的 CacheWrapper + +实现一个 `CacheWrapper`,包装现有的 `Cache` 实现以记录热点 key: + +- **需求:** + + - 包装任何 `Cache[T]` 实现 + - 基于访问模式记录最热的 N 个 key + - 在 `Close()` 时导出热点 key列表以供持久化 + - 支持启动时读入热点 key进行缓存预热 + +- **使用场景:** + + - 识别应用重启时应预热哪些 key + - 分析缓存访问模式 + - 优化缓存分配策略 + +- **API 设计考虑:** + +```go +type HotKeyRecorder[T any] struct { + backend Cache[T] + stats *HotnessStats + topN int +} + +// 关闭时导出热点 key +func (h *HotKeyRecorder[T]) Close() (hotKeys []string, err error) + +// 读入热点 key进行预热 +// 注意:批量预热时(如使用 RistrettoCache),可以在所有 Set 操作完成后 +// 最后统一调用一次 Wait() 来提升性能 +func (h *HotKeyRecorder[T]) WarmUp(ctx context.Context, keys []string) error +``` + +### 基于热度的流量整形 + +实现流量整形机制以保护上游服务和数据库: + +- **需求:** + + - 根据 key 的热度区分回源并发度 + - 热点 key:更高并发度(为大多数用户提供更快响应) + - 冷门 key:较低并发度(保护数据库稳定性) + - 渐进式限流以避免突发流量峰值 + +- **实现策略:** + + - 为热点/冷门 key维护独立的 回源并发限制 + - 热点 key阈值:可配置的百分位数(例如按访问率排名前 20%) + - 冷门 key:使用较小的并发度或速率限制 + - 基于实时访问模式的动态调整 + +- **配置示例:** + +```go +type TrafficShapingConfig struct { + HotKeyConcurrency int // 例如 10 + ColdKeyConcurrency int // 例如 2 + HotKeyPercentile float64 // 例如 0.8(前 20%) +} +``` + +- **优势:** + - 保护数据库免受冷门 key风暴的影响 + - 确保大多数用户(热点 key)的良好性能 + - 防止冷门 key的慢查询影响热点 key性能 + - 高负载下更好的资源分配 + +## 6. 热度统计与 GORM 清理的实现顺序 + +1. **阶段 1:** 热度统计(其他功能的基础) +2. **阶段 2:** 用于热点 key记录的 CacheWrapper(启用缓存预热) +3. **阶段 3:** GORM 清理 Worker(运维稳定性) +4. **阶段 4:** 流量整形(高级优化) + +## 7. 其他考虑 + +- 所有功能应该是可选的且可配置的 +- 保持与现有 API 的向后兼容性 +- 添加全面的基准测试以衡量开销 +- 记录性能特征和权衡取舍 From 74ba540d946c29c58da5185efc0ee739a0a69de6 Mon Sep 17 00:00:00 2001 From: molon <3739161+molon@users.noreply.github.com> Date: Sat, 10 Oct 2026 12:55:23 +0800 Subject: [PATCH 37/40] refactor: move the flight group and the write stripes into internal packages internal/flight is the singleflight shared by Get and GetMany (Claim, Finish, Drop); internal/stripe is the striped lock with its write generation, backfill count and ctx-aware Lock. Both get their own unit tests. They stay internal until another package needs them; moving them to a public path later is a change of import path only. The publish-once layer (claimed) stays in cachex, as it logs through the Client. --- CLAUDE.md | 9 +-- batch.go | 99 +++++++---------------------- batch_test.go | 4 +- client.go | 100 ++++++++---------------------- docs/adr/0001-own-flight-group.md | 6 +- docs/design/batch.md | 4 +- docs/design/singleflight.md | 46 ++++++++------ docs/design/write-order.md | 28 +++++---- docs/{faq.md => faq_ZH.md} | 0 internal/flight/flight.go | 74 ++++++++++++++++++++++ internal/flight/flight_test.go | 56 +++++++++++++++++ internal/stripe/stripe.go | 96 ++++++++++++++++++++++++++++ internal/stripe/stripe_test.go | 68 ++++++++++++++++++++ write_order_test.go | 10 ++- 14 files changed, 400 insertions(+), 200 deletions(-) rename docs/{faq.md => faq_ZH.md} (100%) create mode 100644 internal/flight/flight.go create mode 100644 internal/flight/flight_test.go create mode 100644 internal/stripe/stripe.go create mode 100644 internal/stripe/stripe_test.go diff --git a/CLAUDE.md b/CLAUDE.md index f6155c1..c1ca036 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -10,12 +10,13 @@ Go 泛型多层缓存客户端:合并回源、二次检查、不存在缓存 | [GLOSSARY.md](GLOSSARY.md) | 写文档、写注释、和用户讨论时,用这里的叫法 | | [docs/adr/](docs/adr/) | 想改一个「看起来很奇怪」的做法之前,先看有没有对应的决策 | | [docs/todo.md](docs/todo.md) | 发现了但这次不解决的问题都在这里 | -| [docs/faq.md](docs/faq.md) | 用户问过的问题 | +| [docs/faq_ZH.md](docs/faq_ZH.md) | 用户问过的问题(英文版是 `docs/faq.md`) | | [docs/research/](docs/research/README.md) | 实测数据;复跑脚本在 `tools/bench/` | ## 仓库布局 -- 根目录就是 `cachex` 包:`client.go`(单 key 读取、写入、分片锁)、`batch.go`(批量读、合并回源的 `flightGroup`)、`double_check.go`、`entry.go`、各后端(`ristretto.go`、`syncmap.go`、`bigcache.go`、`redis.go`、`gorm.go`、`transform.go`)。 +- 根目录就是 `cachex` 包:`client.go`(单 key 读取、写入、回填)、`batch.go`(批量读、`claimed`:每个在途回源恰好发布一次)、`double_check.go`、`entry.go`、各后端(`ristretto.go`、`syncmap.go`、`bigcache.go`、`redis.go`、`gorm.go`、`transform.go`)。 +- `internal/flight`(合并回源的登记表)、`internal/stripe`(分片锁):从 cachex 里拆出来的通用部件,暂不公开;以后别的库需要时再挪到公开路径。 - 测试和代码放在一起。`get_compat_test.go` 固定了单 key `Get` 和 main 一致的可观察行为,改它要有对应的 ADR。`gorm_container_test.go` 用 testcontainers 在 MySQL 和 PostgreSQL 上跑,没有 Docker 时自动跳过。 - `tools/bench/<日期-主题>/`:实测的复跑脚本,带 `bench` build tag,平时的 `go test ./...` 不会运行。 @@ -32,11 +33,11 @@ go test -tags bench -v -run ./tools/bench/<目录>/ # 复跑实测 ## 协作约定 -- **文档语言**:`README.md`/`README_ZH.md` 和 `BENCHMARK.md`/`BENCHMARK_ZH.md` 是中英双语,**两份必须逐段一一对应**,改一份就同步改另一份。其余文档(`GLOSSARY.md`、`docs/` 下的全部、本文件)只写中文;术语表里保留每个术语对应的英文。 +- **文档语言**:`README.md`/`README_ZH.md`、`BENCHMARK.md`/`BENCHMARK_ZH.md`、`docs/faq.md`/`docs/faq_ZH.md` 是中英双语,**两份必须逐段一一对应**,改一份就同步改另一份。其余文档(`GLOSSARY.md`、`docs/` 下的全部、本文件)只写中文;术语表里保留每个术语对应的英文。 - **设计结论写回 design**:只写现在成立的设计,被推翻的直接删,理由写进 ADR。专题写进 `docs/design/` 的对应分篇,`docs/design.md` 跟着同步。 - **ADR**:只给难回退、没有背景会让人意外、确实有过取舍的决定写,编号递增。 - **不解决的问题记 todo**:当场记进 `docs/todo.md`,解决了就删。 -- **用户问过的问题记 faq**:先给结论,再给依据。 +- **用户问过的问题记 faq**:先给结论,再给依据;中英两份都要加。 - **实测存档**:报告写进 `docs/research/` 并更新索引,脚本放进 `tools/bench/<日期-主题>/`。 - **文档里不引用其他缓存库或同类项目**。依赖的库(例如 `golang.org/x/sync`)和 Go 官方的 issue 可以引用。 - **提交和 PR**:提交信息、PR 描述用英文,照仓库现有的风格写,不加任何 AI 署名。行为变了就更新 PR 描述里的行为变化表。 diff --git a/batch.go b/batch.go index 90a679d..1c7ea73 100644 --- a/batch.go +++ b/batch.go @@ -11,68 +11,12 @@ import ( "time" "github.com/pkg/errors" + "github.com/theplant/cachex/internal/flight" + "github.com/theplant/cachex/internal/stripe" ) var _ BatchUpstream[any] = &Client[any]{} -// flight is one in-flight upstream fetch of a singleflight key. -type flight[T any] struct { - done chan struct{} - value T - err error -} - -// flightGroup is the singleflight shared by Get and GetMany. Unlike -// x/sync/singleflight, claim tells the caller synchronously whether it now -// owns the fetch, which lets GetMany claim many keys and fetch the ones it -// owns as one batch without waiting on (and deadlocking with) other batches. -type flightGroup[T any] struct { - mu sync.Mutex - flights map[string]*flight[T] -} - -// claim returns the flight for sfKey and whether the caller owns it. The owner -// must call finish exactly once; everyone else waits on flight.done. -func (g *flightGroup[T]) claim(sfKey string) (*flight[T], bool) { - g.mu.Lock() - defer g.mu.Unlock() - if f, ok := g.flights[sfKey]; ok { - return f, false - } - if g.flights == nil { - g.flights = map[string]*flight[T]{} - } - f := &flight[T]{done: make(chan struct{})} - g.flights[sfKey] = f - return f, true -} - -// finish releases the claim before publishing the result, so a request that -// sees the result and comes back starts a new flight (where double-check -// finds the value this flight wrote) instead of joining a finished one. -func (g *flightGroup[T]) finish(sfKey string, f *flight[T], value T, err error) { - g.forget(sfKey, f) - f.value, f.err = value, err - close(f.done) -} - -// drop releases whatever flight holds sfKey without publishing a result: its -// waiters still get its result, and the next claim starts a new flight. -func (g *flightGroup[T]) drop(sfKey string) { - g.mu.Lock() - defer g.mu.Unlock() - delete(g.flights, sfKey) -} - -// forget releases the claim without publishing a result. -func (g *flightGroup[T]) forget(sfKey string, f *flight[T]) { - g.mu.Lock() - defer g.mu.Unlock() - if g.flights[sfKey] == f { - delete(g.flights, sfKey) - } -} - // claimed are flights one request has claimed. Each gets exactly one result, // published as soon as it is known; run makes sure an upstream that panics or // calls runtime.Goexit still answers every waiter, with an error. @@ -80,12 +24,12 @@ type claimed[T any] struct { c *Client[T] keys []string sfKeys []string - flights []*flight[T] + flights []*flight.Flight[T] mu sync.Mutex done []bool } -func (c *Client[T]) claimedFlights(keys, sfKeys []string, flights []*flight[T]) *claimed[T] { +func (c *Client[T]) claimedFlights(keys, sfKeys []string, flights []*flight.Flight[T]) *claimed[T] { return &claimed[T]{c: c, keys: keys, sfKeys: sfKeys, flights: flights, done: make([]bool, len(keys))} } @@ -97,7 +41,7 @@ func (p *claimed[T]) publish(i int, r result[T]) { return } p.done[i] = true - p.c.flights.finish(p.sfKeys[i], p.flights[i], r.value, r.err) + p.c.flights.Finish(p.sfKeys[i], p.flights[i], r.value, r.err) } // run runs body, which fetches flights idxs, and publishes an error for each @@ -239,7 +183,7 @@ func (c *Client[T]) lookupMany(ctx context.Context, keys []string, doubleCheck b } for i, key := range keys { - res[i].seen = c.stripe(key).epoch() + res[i].seen = c.stripe(key).Epoch() } values, err := getMany(ctx, c.backend, keys) var missing []int @@ -323,12 +267,12 @@ func (c *Client[T]) fetchMany(ctx context.Context, keys, sfKeys []string, seen [ if _, ok := c.upstream.(BatchUpstream[T]); !ok { return c.fetchEach(ctx, keys, sfKeys, seen) } - flights := make([]*flight[T], len(keys)) + flights := make([]*flight.Flight[T], len(keys)) var ownKeys, ownSFKeys []string - var ownFlights []*flight[T] + var ownFlights []*flight.Flight[T] var ownSeen []uint64 for i, sfKey := range sfKeys { - f, leader := c.flights.claim(sfKey) + f, leader := c.flights.Claim(sfKey) flights[i] = f if leader { ownKeys = append(ownKeys, keys[i]) @@ -344,12 +288,13 @@ func (c *Client[T]) fetchMany(ctx context.Context, keys, sfKeys []string, seen [ results := make([]result[T], len(keys)) for i, f := range flights { select { - case <-f.done: + case <-f.Done(): case <-ctx.Done(): } select { - case <-f.done: - results[i] = result[T]{value: f.value, err: f.err} + case <-f.Done(): + value, err := f.Result() + results[i] = result[T]{value: value, err: err} default: results[i].err = errors.Wrapf(ctx.Err(), "context cancelled during fetch for key: %s", keys[i]) } @@ -387,7 +332,7 @@ func (c *Client[T]) fetchEach(ctx context.Context, keys, sfKeys []string, seen [ // fetchClaimedMany is the batch form of fetchClaimed for a BatchUpstream: // double-check, then fetch what is still missing; every flight is answered as // soon as its result is known. -func (c *Client[T]) fetchClaimedMany(ctx context.Context, keys, sfKeys []string, flights []*flight[T], seen []uint64) { +func (c *Client[T]) fetchClaimedMany(ctx context.Context, keys, sfKeys []string, flights []*flight.Flight[T], seen []uint64) { p := c.claimedFlights(keys, sfKeys, flights) all := make([]int, len(keys)) for i := range all { @@ -485,7 +430,7 @@ func (c *Client[T]) doFetchMany(ctx context.Context, keys []string) []result[T] results := make([]result[T], len(keys)) gens := make([]uint64, len(keys)) for i, key := range keys { - gens[i] = c.stripe(key).gen.Load() + gens[i] = c.stripe(key).Generation() } values, err := c.upstream.(BatchUpstream[T]).GetMany(ctx, keys) @@ -502,25 +447,25 @@ func (c *Client[T]) doFetchMany(ctx context.Context, keys []string) []result[T] // The batch form of backfill: hold each key's stripe for reading (TryRLock // never blocks, so no lock order is needed) and skip the keys whose stripe // has a write in progress or whose gen moved since it was taken. - held := map[*writeStripe]bool{} + held := map[*stripe.Stripe]bool{} defer func() { for s, ok := range held { if ok { - s.mu.RUnlock() + s.RUnlock() } } }() found := map[string]T{} var notFound []string - filled := map[*writeStripe]bool{} + filled := map[*stripe.Stripe]bool{} for i, key := range keys { s := c.stripe(key) ok, seen := held[s] if !seen { - ok = s.mu.TryRLock() + ok = s.TryRLock() held[s] = ok } - if !ok || s.gen.Load() != gens[i] { + if !ok || s.Generation() != gens[i] { continue } switch { @@ -538,8 +483,8 @@ func (c *Client[T]) doFetchMany(ctx context.Context, keys []string) []result[T] if err := c.delManyWithoutUpstream(ctx, notFound); err != nil { c.logger.WarnContext(ctx, "failed to delete cache entries", "error", err) } - for s := range filled { // see writeStripe.epoch - s.fills.Add(1) + for s := range filled { // see stripe.Stripe.Epoch + s.AddFill() } return results diff --git a/batch_test.go b/batch_test.go index 08d7278..4a39a30 100644 --- a/batch_test.go +++ b/batch_test.go @@ -1190,9 +1190,7 @@ func TestClientGetManyOverAClientIsStillBounded(t *testing.T) { _, err := l1.GetMany(ctx, []string{"k"}) require.Error(t, err) require.Eventually(t, func() bool { - l1.flights.mu.Lock() - defer l1.flights.mu.Unlock() - return len(l1.flights.flights) == 0 + return l1.flights.Len() == 0 }, 2*time.Second, 5*time.Millisecond, "a lower layer that hangs does not keep the key claimed forever") } diff --git a/client.go b/client.go index bcf08b3..1502696 100644 --- a/client.go +++ b/client.go @@ -4,14 +4,14 @@ import ( "context" stderrors "errors" "fmt" - "hash/maphash" "log/slog" "math/rand/v2" "sync" - "sync/atomic" "time" "github.com/pkg/errors" + "github.com/theplant/cachex/internal/flight" + "github.com/theplant/cachex/internal/stripe" ) var ( @@ -39,12 +39,11 @@ type Client[T any] struct { getManyChunk int // keys per BatchUpstream call; 0 means all in one logger *slog.Logger - flights flightGroup[T] + flights flight.Group[T] asyncRefreshing sync.Map // Write ordering, see Set and backfill - writeSeed maphash.Seed - writes [writeStripeCount]writeStripe + stripes *stripe.Set // Double-check optimization doubleCheckMode DoubleCheckMode // User configuration (immutable) @@ -76,7 +75,7 @@ func NewClient[T any](backend Cache[T], upstream Upstream[T], opts ...ClientOpti getManyConc: DefaultGetManyFetchConcurrency, logger: slog.Default(), doubleCheckMode: DoubleCheckAuto, // Default: auto (smart heuristic) - writeSeed: maphash.MakeSeed(), + stripes: stripe.NewSet(), } // Apply user options @@ -110,7 +109,7 @@ func (c *Client[T]) Get(ctx context.Context, key string) (T, error) { func (c *Client[T]) get(ctx context.Context, key string, doubleCheck bool) (T, error) { var zero T - seen := c.stripe(key).epoch() // before reading, see shouldDoubleCheck + seen := c.stripe(key).Epoch() // before reading, see shouldDoubleCheck // Check backend cache first value, err := c.backend.Get(ctx, key) @@ -277,55 +276,7 @@ func (c *Client[T]) Set(ctx context.Context, key string, value T) error { ) } -// writeStripeCount is the number of write stripes per Client. -// -// Keys share stripes by hash, so two keys in one stripe serialize -// their writes and a write to one can skip the other's backfill (a spare -// cache miss, never a stale value); raise it if that shows up. -// 4096 stripes of 40 bytes cost 160 KB per Client, embedded, no allocation. -const writeStripeCount = 4096 - -// writeStripe orders writes and backfills of the keys that hash to it. -type writeStripe struct { - mu sync.RWMutex // Set/Del hold it, so all layers apply them in one order; backfills hold it for reading - gen atomic.Uint64 // bumped by every Set/Del, checked by backfills - fills atomic.Uint64 // bumped by every backfill that wrote this layer -} - -// epoch changes whenever this Client writes this layer for a key of the -// stripe (a Set/Del or a backfill). If it has not changed since a request read -// the layer, re-reading it (the double-check) would find the same miss. -func (s *writeStripe) epoch() uint64 { return s.gen.Load() + s.fills.Load() } - -// lock takes the stripe for writing. Waiting for another write or a backfill -// gives up when ctx is done; a free stripe is taken even with a done ctx. A -// lock given up on is still taken in the background, runs late while holding -// it, and is released. -func (s *writeStripe) lock(ctx context.Context, late func()) error { - if s.mu.TryLock() { - return nil - } - locked := make(chan struct{}) - go func() { - s.mu.Lock() - close(locked) - }() - select { - case <-locked: - return nil - case <-ctx.Done(): - go func() { - <-locked - late() - s.mu.Unlock() - }() - return ctx.Err() - } -} - -func (c *Client[T]) stripe(key string) *writeStripe { - return &c.writes[maphash.String(c.writeSeed, key)%writeStripeCount] -} +func (c *Client[T]) stripe(key string) *stripe.Stripe { return c.stripes.For(key) } // write runs a Set or Del: the upstream first (if it is a Cache), then this // layer. Any failure leaves this layer without an entry for the key. @@ -337,16 +288,16 @@ func (c *Client[T]) write(ctx context.Context, key string, toUpstream func(Cache // a read that starts from now on fetches anew instead of joining a fetch // that may have read the upstream before the write. written := func() { - s.gen.Add(1) + s.AddWrite() c.dropFlights(key) } // A write that gave up waiting writes nothing upstream, but like any failed // write it leaves this layer without an entry, once the stripe is free. - if err := s.lock(ctx, func() { written(); c.invalidate(ctx, key) }); err != nil { + if err := s.Lock(ctx, func() { written(); c.invalidate(ctx, key) }); err != nil { return errors.Wrapf(err, "context cancelled while waiting to write key: %s", key) } - defer s.mu.Unlock() + defer s.Unlock() // also drop fetches claimed while this layer was being written: their // double-check may have read the old value defer c.dropFlights(key) @@ -371,11 +322,11 @@ func (c *Client[T]) write(ctx context.Context, key string, toUpstream func(Cache // interrupting them: callers already waiting still get their result. func (c *Client[T]) dropFlights(key string) { if c.fetchConcurrency <= 1 { - c.flights.drop(key) + c.flights.Drop(key) return } for i := range c.fetchConcurrency { - c.flights.drop(fmt.Sprintf("%d:%s", i, key)) + c.flights.Drop(fmt.Sprintf("%d:%s", i, key)) } } @@ -402,17 +353,17 @@ func (c *Client[T]) invalidate(ctx context.Context, key string) { // (TryRLock): reads never wait on writes, at the cost of a spare cache miss. func (c *Client[T]) backfill(ctx context.Context, key string, gen uint64, fill func() error, failMsg string) { s := c.stripe(key) - if !s.mu.TryRLock() { + if !s.TryRLock() { return } - defer s.mu.RUnlock() - if s.gen.Load() != gen { + defer s.RUnlock() + if s.Generation() != gen { return } if err := fill(); err != nil { c.logger.WarnContext(ctx, failMsg, "key", key, "error", err) } - s.fills.Add(1) + s.AddFill() } // setWithoutUpstream clears a cached not-found and writes the backend; a failed @@ -439,7 +390,7 @@ func (c *Client[T]) fetchFromUpstreamWithSFKey(ctx context.Context, key string, c.testHooks.beforeSingleflightStart(ctx, key) } - f, leader := c.flights.claim(sfKey) + f, leader := c.flights.Claim(sfKey) if leader { go c.runClaimed(flightCtx(ctx), key, sfKey, f, seen) } @@ -447,14 +398,15 @@ func (c *Client[T]) fetchFromUpstreamWithSFKey(ctx context.Context, key string, select { case <-ctx.Done(): return zero, errors.Wrapf(ctx.Err(), "context cancelled during fetch for key: %s", key) - case <-f.done: + case <-f.Done(): if c.testHooks != nil && c.testHooks.afterSingleflightEnd != nil { c.testHooks.afterSingleflightEnd(ctx, key) } - if f.err != nil { - return zero, f.err + value, err := f.Result() + if err != nil { + return zero, err } - return f.value, nil + return value, nil } } @@ -466,8 +418,8 @@ func flightCtx(ctx context.Context) context.Context { } // runClaimed fetches a key this request has claimed and publishes the result. -func (c *Client[T]) runClaimed(ctx context.Context, key, sfKey string, f *flight[T], seen uint64) { - p := c.claimedFlights([]string{key}, []string{sfKey}, []*flight[T]{f}) +func (c *Client[T]) runClaimed(ctx context.Context, key, sfKey string, f *flight.Flight[T], seen uint64) { + p := c.claimedFlights([]string{key}, []string{sfKey}, []*flight.Flight[T]{f}) p.run(ctx, []int{0}, func() { value, err := c.fetchClaimed(ctx, key, seen) p.publish(0, result[T]{value: value, err: err}) @@ -537,7 +489,7 @@ func (c *Client[T]) asyncRefresh(ctx context.Context, key string, seen uint64) { } func (c *Client[T]) doFetch(ctx context.Context, key string) (T, error) { - gen := c.stripe(key).gen.Load() + gen := c.stripe(key).Generation() value, err := c.upstream.Get(ctx, key) if err != nil { if IsErrKeyNotFound(err) { @@ -563,7 +515,7 @@ func (c *Client[T]) shouldDoubleCheck(key string, seen uint64) bool { case DoubleCheckDisabled: return false default: - return c.stripe(key).epoch() != seen + return c.stripe(key).Epoch() != seen } } diff --git a/docs/adr/0001-own-flight-group.md b/docs/adr/0001-own-flight-group.md index 1d12ea9..1827228 100644 --- a/docs/adr/0001-own-flight-group.md +++ b/docs/adr/0001-own-flight-group.md @@ -1,6 +1,6 @@ -# 用自己的 flightGroup 替换 x/sync/singleflight +# 用自己的合并回源实现(internal/flight)替换 x/sync/singleflight -`GetMany` 要在同一套合并回源里**逐个认领**多个 key,然后把自己领头的那些 key 合成一次批量调用。认领时必须**当场**知道自己是不是领头请求。`golang.org/x/sync/singleflight` 的 `DoChan` 做不到:它在锁内决定谁是领头,但把回源函数放进另一个 goroutine 执行,不把结果告诉调用方。如果为了得到答案而等待,两个互相重叠的批量读会各自等对方手里的 key,从而死锁。所以我们写了 `flightGroup`:`claim` 立即返回(在途回源,是否领头),`finish` 负责发布。`Get` 和 `GetMany` 共用它,因此一个 `Get` 和一个包含同一 key 的 `GetMany` 也只回源一次。 +`GetMany` 要在同一套合并回源里**逐个认领**多个 key,然后把自己领头的那些 key 合成一次批量调用。认领时必须**当场**知道自己是不是领头请求。`golang.org/x/sync/singleflight` 的 `DoChan` 做不到:它在锁内决定谁是领头,但把回源函数放进另一个 goroutine 执行,不把结果告诉调用方。如果为了得到答案而等待,两个互相重叠的批量读会各自等对方手里的 key,从而死锁。所以我们写了 `flight.Group`(内部包 `internal/flight`):`Claim` 立即返回(在途回源,是否领头),`Finish` 负责发布。`Get` 和 `GetMany` 共用它,因此一个 `Get` 和一个包含同一 key 的 `GetMany` 也只回源一次。 ## 考虑过的方案 @@ -10,5 +10,5 @@ ## 后果 - 单 key 的行为逐项对照过 main:合并方式、回源槽位、panic 的错误信息和日志、调用方取消、超时、测试钩子都保持一致。有一个**有意的偏离**:Goexit 时会给等待方发布错误,见 [ADR 0006](0006-goexit-publishes-an-error.md)。`get_compat_test.go` 固定了单 key 的这些可观察行为。 -- `finish` 先移除登记、再发布结果,和 x/sync 的顺序相同。现有的二次检查依赖这个顺序。 +- `Finish` 先移除登记、再发布结果,和 x/sync 的顺序相同。现有的二次检查依赖这个顺序。 - `x/sync` 仍然留在 `go.mod` 里,基准测试用到了它的 semaphore。 diff --git a/docs/design/batch.md b/docs/design/batch.md index b388bb9..069621b 100644 --- a/docs/design/batch.md +++ b/docs/design/batch.md @@ -32,7 +32,7 @@ sequenceDiagram participant L as Client participant B as 后端 participant N as 不存在缓存 - participant G as flightGroup + participant G as flight.Group participant U as 批量上游 C->>L: GetMany(k1..k5) L->>L: 去重;记下每个 key 的分片纪元 @@ -58,7 +58,7 @@ sequenceDiagram 1. **去重**:重复的 key 只处理一次。 2. **读后端**:一次批量读。读到的每个值按新鲜度处理:新鲜的放进结果;陈旧的也放进结果(开启返回陈旧值时),同时这些 key 在后台合成一批刷新;腐烂的和未命中的继续往下走,后面查到的也放进同一份结果。**整份结果最后一次性返回。** 3. **查不存在缓存**:后端未命中的 key 一起查一次,规则同 `Get`。 -4. **合并回源**:需要回源的 key 逐个在同一个 flightGroup 里认领。别人正在回源的 key 直接等结果,自己领头的 key 由自己回源。见 [singleflight.md](singleflight.md#批量认领)。 +4. **合并回源**:需要回源的 key 逐个在同一个 flight.Group 里认领。别人正在回源的 key 直接等结果,自己领头的 key 由自己回源。见 [singleflight.md](singleflight.md#批量认领)。 5. **二次检查**:只对需要的 key 再读一次本层(默认的 `DoubleCheckAuto` 下,只检查读取之后本 Client 写过其分片的 key)。 6. **回源**:见下一节。 7. **回填**:找到的值写进后端,不存在的 key 写进不存在缓存,并删掉后端的旧值。只写本层。 diff --git a/docs/design/singleflight.md b/docs/design/singleflight.md index 57508e0..f8b2afd 100644 --- a/docs/design/singleflight.md +++ b/docs/design/singleflight.md @@ -2,32 +2,38 @@ 同一个 key 的并发未命中只回源一次:第一个请求**认领**这个 key、成为**领头请求**去回源,其他请求成为**等待方**,等它**发布**结果。`Get` 和 `GetMany` 共用同一套登记,所以一个 `Get` 和一个包含同一 key 的 `GetMany` 也只回源一次。 -实现是 `batch.go` 里的 `flightGroup`,替代了 main 上使用的 `golang.org/x/sync/singleflight`,原因见 [ADR 0001](../adr/0001-own-flight-group.md)。 +实现分两部分,替代了 main 上使用的 `golang.org/x/sync/singleflight`(原因见 [ADR 0001](../adr/0001-own-flight-group.md)): + +- `internal/flight`:通用的登记表 `flight.Group`,只管「认领、发布、摘除」; +- `batch.go` 里的 `claimed`:cachex 自己的一层,保证每个在途回源恰好发布一次(见下文「panic 与 Goexit」)。 + +`internal/flight` 是内部包,暂不对外公开,以后有别的库需要时再考虑挪出去。 ## 数据结构 ```go -type flight[T any] struct { - done chan struct{} // 发布时关闭 - value T +// package flight +type Flight[T any] struct { + done chan struct{} // 发布时关闭;对外是 Done() + value T // 对外是 Result() err error } -type flightGroup[T any] struct { +type Group[T any] struct { mu sync.Mutex - flights map[string]*flight[T] // 回源槽位 key → 在途回源 + flights map[string]*Flight[T] // 回源槽位 key → 在途回源 } ``` | 操作 | 做什么 | 谁调用 | |---|---|---| -| `claim(sfKey)` | 有在途回源就返回它(调用方成为等待方),没有就新建并返回「你是领头请求」。**当场**给出答案,不阻塞 | 每个要回源的请求 | -| `finish(sfKey, f, value, err)` | 先从登记中移除(只在登记的仍是这个在途回源时才移除),再写入结果、关闭 `done` | 领头请求,每个在途回源恰好一次 | -| `drop(sfKey)` | 从登记中移除,但不发布结果、不打断回源 | `Set`/`Del`,见 [write-order.md](write-order.md#摘除在途回源) | +| `Claim(sfKey)` | 有在途回源就返回它(调用方成为等待方),没有就新建并返回「你是领头请求」。**当场**给出答案,不阻塞 | 每个要回源的请求 | +| `Finish(sfKey, f, value, err)` | 先从登记中移除(只在登记的仍是这个在途回源时才移除),再写入结果、关闭 `done` | 领头请求,每个在途回源恰好一次 | +| `Drop(sfKey)` | 从登记中移除,但不发布结果、不打断回源 | `Set`/`Del`,见 [write-order.md](write-order.md#摘除在途回源) | 「只在登记的仍是这个在途回源时才移除」很重要:一个被 `Set`/`Del` 摘除的回源结束时,登记里可能已经是写入之后新建的回源,不能把它删掉(见 [write-order.md](write-order.md#摘除在途回源))。 -`finish` **先移除、再发布**:一个请求拿到结果后立刻再来读,会发现没有在途回源,于是新建一个;这时它的二次检查会读到刚回填的值。反过来,如果先发布再移除,它就可能加入一个已经结束的回源。 +`Finish` **先移除、再发布**:一个请求拿到结果后立刻再来读,会发现没有在途回源,于是新建一个;这时它的二次检查会读到刚回填的值。反过来,如果先发布再移除,它就可能加入一个已经结束的回源。 ## 单个 key 的时序 @@ -35,13 +41,13 @@ type flightGroup[T any] struct { sequenceDiagram participant A as 请求 A participant B as 请求 B - participant G as flightGroup + participant G as flight.Group participant F as 回源 goroutine participant U as 上游 - A->>G: claim(k) + A->>G: Claim(k) G-->>A: 新建 flight,A 是领头请求 A->>F: 启动回源(脱离 A 的取消) - B->>G: claim(k) + B->>G: Claim(k) G-->>B: 已有 flight,B 是等待方 par A 和 B 都等同一个 flight A->>A: 等 done 或自己的 ctx 结束 @@ -51,7 +57,7 @@ sequenceDiagram F->>U: Get(k) U-->>F: v F->>F: 回填本层 - F->>G: finish:先移除登记,再写入 v、关闭 done + F->>G: Finish:先移除登记,再写入 v、关闭 done G-->>A: v G-->>B: v ``` @@ -115,14 +121,14 @@ sequenceDiagram ```mermaid sequenceDiagram participant M as GetMany(k1, k2, k3) - participant G as flightGroup + participant G as flight.Group participant X as 另一个 Get(k2) participant F as 批量回源 goroutine participant U as 批量上游 - X->>G: claim(k2),成为 k2 的领头请求 - M->>G: claim(k1) → 领头 - M->>G: claim(k2) → 等待方(X 正在回源) - M->>G: claim(k3) → 领头 + X->>G: Claim(k2),成为 k2 的领头请求 + M->>G: Claim(k1) → 领头 + M->>G: Claim(k2) → 等待方(X 正在回源) + M->>G: Claim(k3) → 领头 M->>F: 回源自己领头的 k1、k3 F->>U: GetMany(k1, k3) U-->>F: 结果 @@ -142,4 +148,4 @@ sequenceDiagram ## 使用约束 -上游不能在回源时**同步**回调同一个 Client 读取同一个 key:这个 key 已经被调用方认领了,回调会等待它自己的结果,形成自锁。分层的 Client 不受影响,因为每一层都有自己的 flightGroup。 +上游不能在回源时**同步**回调同一个 Client 读取同一个 key:这个 key 已经被调用方认领了,回调会等待它自己的结果,形成自锁。分层的 Client 不受影响,因为每一层都有自己的 flight.Group。 diff --git a/docs/design/write-order.md b/docs/design/write-order.md index a138934..401cdd4 100644 --- a/docs/design/write-order.md +++ b/docs/design/write-order.md @@ -1,6 +1,6 @@ # 写入顺序与分片锁 -这篇讲 `Set`/`Del` 怎么写、写入和回填之间怎么排序,以及支撑这一切的**分片锁**。代码在 `client.go`:`write`、`writeStripe`、`backfill`;批量回填在 `batch.go` 的 `doFetchMany`。 +这篇讲 `Set`/`Del` 怎么写、写入和回填之间怎么排序,以及支撑这一切的**分片锁**。分片本身在内部包 `internal/stripe`(`stripe.Set`、`stripe.Stripe`);写入和回填怎么用它,在 `client.go` 的 `write`、`backfill`,批量回填在 `batch.go` 的 `doFetchMany`。 ## 先说结论:对使用者意味着什么 @@ -110,16 +110,22 @@ flowchart LR 不同的 key 可能落到同一个分片(上图的 `user:42` 和 `order:9`)。这不影响正确性,只是它们会共用一把锁,代价见文末。 ```go -const writeStripeCount = 4096 +// package stripe +const Count = 4096 -type writeStripe struct { +type Stripe struct { mu sync.RWMutex // Set/Del 持写锁;回填持读锁 gen atomic.Uint64 // 写入代数:每次 Set/Del 加 1 fills atomic.Uint64 // 每次回填写入本层加 1 } -func (c *Client[T]) stripe(key string) *writeStripe { - return &c.writes[maphash.String(c.writeSeed, key)%writeStripeCount] +type Set struct { + seed maphash.Seed + stripes [Count]Stripe +} + +func (s *Set) For(key string) *Stripe { + return &s.stripes[maphash.String(s.seed, key)%Count] } ``` @@ -239,14 +245,14 @@ sequenceDiagram sequenceDiagram participant A as 请求 A(写入前开始) participant W as Del(k) - participant G as flightGroup + participant G as flight.Group participant B as 请求 B(Del 返回后开始) participant U as 上游 - A->>G: claim(k),回源中(读到旧值 v1) + A->>G: Claim(k),回源中(读到旧值 v1) W->>W: 写上游(删除) - W->>G: drop(k) - W->>W: 删本层,再 drop(k),Del 返回 - B->>G: claim(k):没有登记,新建回源 + W->>G: Drop(k) + W->>W: 删本层,再 Drop(k),Del 返回 + B->>G: Claim(k):没有登记,新建回源 B->>U: Get(k) U-->>B: 不存在 ✓ A-->>A: A 自己拿到 v1(它开始得早),但回填被跳过 @@ -260,7 +266,7 @@ sequenceDiagram ## 等写锁时尊重 ctx -`sync.RWMutex` 的 `Lock()` 没法被取消。如果前一个 `Set` 卡在上游,后面的 `Set` 就会无视自己的超时一直等下去。所以 `writeStripe.lock` 这样实现: +`sync.RWMutex` 的 `Lock()` 没法被取消。如果前一个 `Set` 卡在上游,后面的 `Set` 就会无视自己的超时一直等下去。所以 `stripe.Stripe.Lock` 这样实现: ```mermaid flowchart TD diff --git a/docs/faq.md b/docs/faq_ZH.md similarity index 100% rename from docs/faq.md rename to docs/faq_ZH.md diff --git a/internal/flight/flight.go b/internal/flight/flight.go new file mode 100644 index 0000000..325e23e --- /dev/null +++ b/internal/flight/flight.go @@ -0,0 +1,74 @@ +// Package flight is a singleflight whose Claim answers at once whether the +// caller now leads the fetch of a key. Unlike golang.org/x/sync/singleflight, +// which decides that inside the goroutine it starts, this lets a batch read +// claim many keys, fetch the ones it leads together, and only then wait for +// the others, so two overlapping batches never wait on each other. +package flight + +import "sync" + +// Flight is one in-flight fetch of a key. +type Flight[T any] struct { + done chan struct{} + value T + err error +} + +// Done is closed once the result is published. +func (f *Flight[T]) Done() <-chan struct{} { return f.done } + +// Result is the published result; read it only after Done is closed. +func (f *Flight[T]) Result() (T, error) { return f.value, f.err } + +// Group registers the in-flight fetches by key. The zero value is ready to use. +type Group[T any] struct { + mu sync.Mutex + flights map[string]*Flight[T] +} + +// Claim returns the key's flight and whether the caller leads it (it was just +// created). The leader must call Finish exactly once; everyone else waits on +// Done. +func (g *Group[T]) Claim(key string) (*Flight[T], bool) { + g.mu.Lock() + defer g.mu.Unlock() + if f, ok := g.flights[key]; ok { + return f, false + } + if g.flights == nil { + g.flights = map[string]*Flight[T]{} + } + f := &Flight[T]{done: make(chan struct{})} + g.flights[key] = f + return f, true +} + +// Finish publishes f's result. It unregisters f first (if f is still the one +// registered for key), so a caller that sees the result and comes back starts +// a new flight instead of joining a finished one; and a flight that was +// dropped does not unregister the one that replaced it. +func (g *Group[T]) Finish(key string, f *Flight[T], value T, err error) { + g.mu.Lock() + if g.flights[key] == f { + delete(g.flights, key) + } + g.mu.Unlock() + f.value, f.err = value, err + close(f.done) +} + +// Drop unregisters whatever flight holds key without publishing or +// interrupting it: its waiters still get its result, and the next Claim +// starts a new flight. +func (g *Group[T]) Drop(key string) { + g.mu.Lock() + defer g.mu.Unlock() + delete(g.flights, key) +} + +// Len is the number of registered flights. +func (g *Group[T]) Len() int { + g.mu.Lock() + defer g.mu.Unlock() + return len(g.flights) +} diff --git a/internal/flight/flight_test.go b/internal/flight/flight_test.go new file mode 100644 index 0000000..d443bfe --- /dev/null +++ b/internal/flight/flight_test.go @@ -0,0 +1,56 @@ +package flight + +import ( + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func TestClaimAnswersAtOnce(t *testing.T) { + var g Group[string] + f, leader := g.Claim("k") + require.True(t, leader, "the first claim leads") + f2, leader2 := g.Claim("k") + assert.False(t, leader2, "a second claim waits") + assert.Same(t, f, f2) + _, leaderOther := g.Claim("other") + assert.True(t, leaderOther, "keys are independent") +} + +func TestFinishPublishesThenAClaimStartsAnew(t *testing.T) { + var g Group[string] + f, _ := g.Claim("k") + g.Finish("k", f, "v", nil) + <-f.Done() + v, err := f.Result() + require.NoError(t, err) + assert.Equal(t, "v", v) + + f2, leader := g.Claim("k") + assert.True(t, leader, "a finished flight is not joined") + assert.NotSame(t, f, f2) +} + +func TestDropKeepsTheOldFlightsWaitersAndItsReplacement(t *testing.T) { + var g Group[string] + old, _ := g.Claim("k") + g.Drop("k") + select { + case <-old.Done(): + t.Fatal("Drop must not publish") + default: + } + + replacement, leader := g.Claim("k") + require.True(t, leader, "after Drop, the next claim starts a new flight") + + g.Finish("k", old, "old", nil) + <-old.Done() + v, _ := old.Result() + assert.Equal(t, "old", v, "the dropped flight's waiters still get its result") + assert.Equal(t, 1, g.Len(), "finishing the dropped flight leaves its replacement registered") + f, leader := g.Claim("k") + assert.False(t, leader) + assert.Same(t, replacement, f) +} diff --git a/internal/stripe/stripe.go b/internal/stripe/stripe.go new file mode 100644 index 0000000..804a017 --- /dev/null +++ b/internal/stripe/stripe.go @@ -0,0 +1,96 @@ +// Package stripe orders the writes and backfills of keys without a lock per +// key: keys hash into a fixed number of stripes, each with a read-write lock +// and two counters. See docs/design/write-order.md. +package stripe + +import ( + "context" + "hash/maphash" + "sync" + "sync/atomic" +) + +// Count is the number of stripes in a Set. +// +// Keys share stripes by hash, so two keys in one stripe serialize their +// writes and a write to one can skip the other's backfill (a spare cache +// miss, never a stale value). 4096 stripes of 40 bytes cost 160 KB per Set. +const Count = 4096 + +// Stripe orders the writes and backfills of the keys that hash to it: a write +// holds it for writing, a backfill for reading. +type Stripe struct { + mu sync.RWMutex + gen atomic.Uint64 // writes so far + fills atomic.Uint64 // backfills so far +} + +// Generation counts the writes; a backfill compares it with the value it took +// before fetching to learn whether a write happened meanwhile. +func (s *Stripe) Generation() uint64 { return s.gen.Load() } + +// AddWrite counts a write. +func (s *Stripe) AddWrite() { s.gen.Add(1) } + +// AddFill counts a backfill that wrote the layer. +func (s *Stripe) AddFill() { s.fills.Add(1) } + +// Epoch changes whenever the layer is written for a key of the stripe (a +// write or a backfill). If it has not changed since a request read the layer, +// re-reading it would find the same miss. +func (s *Stripe) Epoch() uint64 { return s.gen.Load() + s.fills.Load() } + +// Lock takes the stripe for writing. A free stripe is taken even with a done +// ctx. Waiting (for another write, or a backfill writing the layer) gives up +// when ctx is done: Lock then returns ctx's error, and the lock it gave up on +// is still taken in the background, runs late while holding it, and is +// released. +func (s *Stripe) Lock(ctx context.Context, late func()) error { + if s.mu.TryLock() { + return nil + } + locked := make(chan struct{}) + go func() { + s.mu.Lock() + close(locked) + }() + select { + case <-locked: + return nil + case <-ctx.Done(): + go func() { + <-locked + late() + s.mu.Unlock() + }() + return ctx.Err() + } +} + +// Unlock releases a Lock. +func (s *Stripe) Unlock() { s.mu.Unlock() } + +// TryLock takes the stripe for writing if it is free. +func (s *Stripe) TryLock() bool { return s.mu.TryLock() } + +// TryRLock takes the stripe for reading if no write holds or awaits it; a +// backfill that cannot is skipped, so reads never wait on writes. +func (s *Stripe) TryRLock() bool { return s.mu.TryRLock() } + +// RUnlock releases a TryRLock. +func (s *Stripe) RUnlock() { s.mu.RUnlock() } + +// Set is Count stripes and the seed that maps keys to them. Each Set has its +// own random seed, so a key's stripe differs between Sets and processes. +type Set struct { + seed maphash.Seed + stripes [Count]Stripe +} + +// NewSet returns a Set with a random seed. +func NewSet() *Set { return &Set{seed: maphash.MakeSeed()} } + +// For returns the stripe of key. +func (s *Set) For(key string) *Stripe { + return &s.stripes[maphash.String(s.seed, key)%Count] +} diff --git a/internal/stripe/stripe_test.go b/internal/stripe/stripe_test.go new file mode 100644 index 0000000..bf6774f --- /dev/null +++ b/internal/stripe/stripe_test.go @@ -0,0 +1,68 @@ +package stripe + +import ( + "context" + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func TestLockTakesAFreeStripeEvenWithADoneCtx(t *testing.T) { + var s Stripe + ctx, cancel := context.WithCancel(context.Background()) + cancel() + require.NoError(t, s.Lock(ctx, func() { t.Error("late must not run") })) + s.Unlock() +} + +func TestLockGivesUpWaitingAndRunsLateWhileHoldingTheLock(t *testing.T) { + var s Stripe + require.True(t, s.TryLock()) // another write holds it + + ctx, cancel := context.WithTimeout(context.Background(), 20*time.Millisecond) + defer cancel() + lateRan := make(chan bool, 1) + err := s.Lock(ctx, func() { lateRan <- !s.TryRLock() }) + require.ErrorIs(t, err, context.DeadlineExceeded) + + s.Unlock() // the other write ends + select { + case held := <-lateRan: + assert.True(t, held, "late runs while the given-up lock is held") + case <-time.After(time.Second): + t.Fatal("late never ran") + } + require.Eventually(t, s.TryLock, time.Second, time.Millisecond, "and the lock is released after it") + s.Unlock() +} + +func TestBackfillsShareTheStripeButNotWithAWrite(t *testing.T) { + var s Stripe + require.True(t, s.TryRLock()) + assert.True(t, s.TryRLock(), "backfills share the stripe") + assert.False(t, s.TryLock(), "a write waits for backfills") + s.RUnlock() + s.RUnlock() + require.True(t, s.TryLock()) + assert.False(t, s.TryRLock(), "a backfill is skipped while a write holds the stripe") + s.Unlock() +} + +func TestCounters(t *testing.T) { + var s Stripe + gen, epoch := s.Generation(), s.Epoch() + s.AddFill() + assert.Equal(t, gen, s.Generation(), "a backfill is not a write") + assert.NotEqual(t, epoch, s.Epoch()) + epoch = s.Epoch() + s.AddWrite() + assert.NotEqual(t, gen, s.Generation()) + assert.NotEqual(t, epoch, s.Epoch()) +} + +func TestForIsStablePerSet(t *testing.T) { + set := NewSet() + assert.Same(t, set.For("k"), set.For("k")) +} diff --git a/write_order_test.go b/write_order_test.go index d5875fd..0b6661c 100644 --- a/write_order_test.go +++ b/write_order_test.go @@ -474,9 +474,7 @@ func TestReadAfterWriteDoesNotJoinAnOlderFetch(t *testing.T) { src.holdReads() require.Eventually(t, func() bool { go func() { _, _ = cli.Get(ctx, "k") }() - cli.flights.mu.Lock() - defer cli.flights.mu.Unlock() - return len(cli.flights.flights) == conc + return cli.flights.Len() == conc }, time.Second, time.Millisecond) for range conc { waitFor(t, src.entered) @@ -556,12 +554,12 @@ func TestWriteWaitingForTheStripeRespectsCtx(t *testing.T) { s := cli.stripe("k") // the given-up Set's lock is taken in the background once the first Set // releases it; it bumps the generation (the first Set did too) and unlocks - require.Eventually(t, func() bool { return s.gen.Load() == 2 }, time.Second, time.Millisecond) + require.Eventually(t, func() bool { return s.Generation() == 2 }, time.Second, time.Millisecond) require.Eventually(t, func() bool { - if !s.mu.TryLock() { + if !s.TryLock() { return false } - s.mu.Unlock() + s.Unlock() return true }, time.Second, time.Millisecond) done, cancel := context.WithCancel(ctx) From 2fa16bff644e1c15291eba2b61023fc5868ac85b Mon Sep 17 00:00:00 2001 From: molon <3739161+molon@users.noreply.github.com> Date: Sat, 10 Oct 2026 12:55:23 +0800 Subject: [PATCH 38/40] docs: the FAQ in English and Chinese docs/faq.md is the English FAQ and docs/faq_ZH.md the Chinese one, kept one to one like the README; the READMEs link to their own language. --- README.md | 4 +- README_ZH.md | 4 +- docs/design.md | 2 +- docs/faq.md | 134 +++++++++++++++++++++++++++++++++++++++++++++++++ docs/faq_ZH.md | 4 +- 5 files changed, 142 insertions(+), 6 deletions(-) create mode 100644 docs/faq.md diff --git a/README.md b/README.md index df2fb37..39c4109 100644 --- a/README.md +++ b/README.md @@ -523,10 +523,10 @@ user, err := userCache.Get(ctx, "user:123") ## Documentation -Design notes for maintainers and readers who want the details, in Chinese only: +Design notes for maintainers and readers who want the details; all in Chinese except the FAQ, which has both languages: - [Design overview](docs/design.md) (Chinese): the model, the architecture, and one page per mechanism: read path, singleflight, write order and striped locks, batch reads, backends, consistency across instances -- [FAQ](docs/faq.md) (Chinese) +- [FAQ](docs/faq.md) - [Glossary](GLOSSARY.md) (Chinese, with the English terms used in code) - [Architecture decision records](docs/adr/) (Chinese) - [Measurements](docs/research/README.md) (Chinese) and their re-runnable scripts in `tools/bench/` diff --git a/README_ZH.md b/README_ZH.md index b5e3de9..8da7a30 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -521,10 +521,10 @@ user, err := userCache.Get(ctx, "user:123") ## 文档 -面向维护者和想深入了解的读者的设计文档,只有中文版: +面向维护者和想深入了解的读者的设计文档;除常见问题有中英两版外,都只有中文版: - [设计总览](docs/design.md):核心模型、架构,以及每个机制的分篇(读取路径、合并回源、写入顺序与分片锁、批量读、后端、多实例一致性) -- [常见问题](docs/faq.md) +- [常见问题](docs/faq_ZH.md) - [术语表](GLOSSARY.md):附代码中使用的英文术语 - [架构决策记录](docs/adr/) - [实测与调研](docs/research/README.md),复跑脚本在 `tools/bench/` diff --git a/docs/design.md b/docs/design.md index 67c9026..a4224dc 100644 --- a/docs/design.md +++ b/docs/design.md @@ -120,6 +120,6 @@ flowchart LR | [GLOSSARY.md](../GLOSSARY.md) | 术语表 | | [adr/](adr/) | 架构决策记录 | | [todo.md](todo.md) | 发现了但还没做的事 | -| [faq.md](faq.md) | 常见问题 | +| [faq_ZH.md](faq_ZH.md) | 常见问题(英文版见 [faq.md](faq.md)) | | [research/](research/README.md) | 实测与调研报告 | | [../BENCHMARK.md](../BENCHMARK.md) | 性能基准(中英双语) | diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 0000000..1300e72 --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,134 @@ +# FAQ + +English | [中文](faq_ZH.md) + +Each answer gives the conclusion first, then the reasoning. The design notes, [design.md](design.md) and its pages (in Chinese), are the reference for details. + +## Usage + +### When should I use `Entry[T]`, and when a custom staleness check? + +Use `Entry[T]` with `EntryWithTTL(freshTTL, staleTTL)` when staleness depends on time only. When it depends on your data (a `version` field in the value, say), pass your own check with `WithStale`. See [design/read-path.md](design/read-path.md#新鲜度) (Chinese). + +### What is the difference between the fresh and the stale TTL? + +During the fresh TTL a value is returned as is. The stale TTL is an **additional** period after it: with `WithServeStale`, a read in that period gets the old value at once while it is refreshed in the background. An entry lives `freshTTL + staleTTL` in total. Give the backend's own TTL at least that much, or entries disappear before their stale period begins. + +### Should I cache every database query? + +No. Cache data that is read often and changes rarely. Poor candidates are: + +- data that changes very often (needs to be fresh within a second); +- per-user data with very high cardinality; +- large objects that are expensive to hold in memory. + +### What do I do after changing the data source? Do I take the stripe lock first? + +No; the stripe lock is internal and you cannot take it. Just keep one order: **change the data source first, then call `Set` or `Del` through the same Client**. In the opposite order (`Del` first, then change the source), a read that fetches in between gets the old value and legitimately backfills it. See [design/write-order.md](design/write-order.md#使用方式改数据源时要做什么) (Chinese). + +### A cached value is nil. How do I tell it from "does not exist"? + +A cached nil (a nil pointer, for example) is a hit: + +- `Get` returns `(nil, nil)`, not `ErrKeyNotFound`; +- `GetMany`'s map holds the key, with a nil value. + +So test presence with `v, ok := m[k]`, not with `m[k] == nil`. + +### Why are keys that do not exist missing from `GetMany`'s `BatchError`? + +In a batch read, **not existing is not an error**: a key that does not exist is simply absent from the map, and `BatchError` lists only the keys that failed. A cache's batch read almost always has misses; if they counted as errors, `err` would almost never be nil and every caller would have to filter them out. Each key ends in exactly one of three outcomes: + +| Outcome | `Get` | `GetMany` | +|---|---|---| +| found | `(value, nil)` | in the map | +| does not exist | `IsErrKeyNotFound(err)` | neither in the map nor in the `BatchError` | +| failed | any other error | in the `BatchError` | + +See [ADR 0004](adr/0004-batch-result-shape.md) (Chinese). + +### Why does `Get` still return `ErrKeyNotFound`? Isn't that inconsistent with `GetMany`? + +Both report the same three outcomes, each in its own way. `Get` returns a single value, so it cannot say "does not exist" by leaving something out: the value itself may legitimately be nil, and when `T` is an int, the zero value cannot mean "absent" at all. It is the same in `database/sql`: `QueryRow` returns `ErrNoRows` when nothing matches, while `Query` just returns no rows. + +## Singleflight and the double-check + +### How is cache stampede prevented? + +In two layers: + +1. **Singleflight** (primary): concurrent misses of one key fetch it once; the other requests wait for that result. `WithFetchConcurrency(n)` allows n concurrent fetches of one key (default 1, full deduplication), trading some redundancy for throughput. See [design/singleflight.md](design/singleflight.md) (Chinese). +2. **Double-check** (supplementary): request B reads a miss before request A's fetch backfills, but claims the key only after A's fetch has finished; B reads the cache again instead of fetching again. + +### Is the double-check worth it? Is it on by default? + +By default it runs on demand (`DoubleCheckAuto`): it re-reads only when this Client wrote the key's stripe after the request read the cache. Measured: + +- with a 1 ms backend read and a hot key, upstream calls drop from 30 to 19 (18 when always on); +- cold keys see almost no extra reads (1.005 reads per `Get`, against 2 when always on); +- with an in-memory backend it makes no difference. + +Use `DoubleCheckEnabled` when you need to see values other processes wrote to a shared cache. See [ADR 0008](adr/0008-on-demand-double-check.md) and [research/2026-10-double-check.md](research/2026-10-double-check.md) (Chinese). + +### What happens if the upstream panics or calls `runtime.Goexit`? + +Every waiter of that fetch gets an error; none hangs: + +- a panic gives `panic during upstream fetch: …`, and an ERROR log with the stack; +- `Goexit` gives `upstream fetch exited without returning (runtime.Goexit)`. + +The latter differs from `x/sync/singleflight` (where waiters wait until their own ctx ends), on purpose. See [ADR 0006](adr/0006-goexit-publishes-an-error.md) (Chinese). + +## Write order and the stripe lock + +### What is the point of guaranteeing the write order? The TTL applies anyway. + +The TTL bounds how long old data lives **when you do not write**. `Set`/`Del` is you asking for "the new value, now". The order guarantee makes sure that request is not quietly undone by a fetch that started earlier. Without it, after `Del` returns successfully, the old value can still be backfilled and live for the whole TTL, and a user can see data turn new and then old again. See [design/write-order.md](design/write-order.md#先说结论对使用者意味着什么) (Chinese). + +### In layered caching, does a read write the next layer through `Set`/`Del`, taking write locks? + +No. A read's backfill writes this layer's backend directly, holding only a read lock; on a miss, L1 calls L2's `Get`. Write locks are taken only when your code calls `Set`/`Del`. + +### How far does one slow operation reach? + +- A slow `Set`/`Del` holds only its own stripe (one of 4096); +- a large batch backfill holds the stripes of all its keys while it writes (about 22% for 1,000 keys), and writes to those stripes queue behind it; +- reads never wait. + +For batches well over 1,000 keys, `WithGetManyChunkSize` makes each chunk backfill on its own and hold only its own stripes; chunks run concurrently, so to limit the stripes held at once, also lower `WithGetManyFetchConcurrency`. A smaller backend `ChunkSize` does not help. See [design/write-order.md](design/write-order.md#慢操作会拖慢多大范围) (Chinese). + +### With several instances deployed, is the write order still guaranteed? + +No. The stripe lock works within one process only: + +- other instances' memory layers do not see your write and keep serving the old value until it expires; +- another instance can backfill an old value into the shared Redis. + +TTLs are the backstop for now, so set both the memory layer's and the shared layer's TTL to how long you can accept old data. Redis leases and invalidation broadcasts are in the [to-do list](todo.md) (Chinese). See [design/consistency.md](design/consistency.md) (Chinese). + +## Batch reads + +### Does `GetMany` return keys one by one, or all together? + +All together. Fresh values, stale values (with serve-stale) and fetched values all go into one result, returned at once. Stale keys are refreshed separately in the background. + +### How long does a concurrent `Get` wait for a key that `GetMany` is fetching? + +- With a batch upstream, the `Get` waits for that whole batch call (or, with chunking, that chunk) to return. +- Without one, a key is claimed only when its turn comes, so the `Get` is not held up by `GetMany`'s queue. + +### What is the difference between `WithFetchConcurrency` and `WithGetManyFetchConcurrency`? + +- The former bounds how many fetches **one key** can have at once; +- the latter bounds how many requests **one `GetMany`** sends upstream at once (per-key `Get`s, or chunk calls of a batch upstream). + +## Backends + +### What does GORMCache need on MySQL? + +- **Creating the table** needs MySQL 8.0.17 or later: `Migrate` uses `utf8mb4_0900_bin`, so keys compare case and trailing spaces exactly, and it checks the version before creating the table. +- Existing tables are left as they are and never return another key's value; keys that differ only in case take a shared row over from each other. The statement to convert an old table is in [design/backends.md](design/backends.md#key-必须精确比较) (Chinese). + +### Do concurrent writes to GORMCache from several instances deadlock? + +They rarely fail: writes lock rows in byte order, and the occasional deadlock (MySQL's gap locks) is retried automatically (at most 5 attempts). When the attempts run out, the error is returned; a failed backfill is only logged at WARN and the next read fetches again. Old MySQL `*_ci` tables do not lock in byte order and rely on the retry alone. Inside your own transaction (`WithGORMTx`) nothing is retried, since the deadlock has rolled the whole transaction back. See [ADR 0010](adr/0010-gorm-deadlock-ordering-and-retry.md) (Chinese). diff --git a/docs/faq_ZH.md b/docs/faq_ZH.md index 85f1e2b..10e40a9 100644 --- a/docs/faq_ZH.md +++ b/docs/faq_ZH.md @@ -1,5 +1,7 @@ # 常见问题 +[English](faq.md) | 中文 + 每个问题先给结论,再给依据。设计细节以 [design.md](design.md) 及其分篇为准。 ## 使用 @@ -93,7 +95,7 @@ TTL 是**不主动写入**时旧数据的存活上限。`Set`/`Del` 是你主动 - 一次大批量回填会在回填期间占住它所有 key 的分片(1000 个 key 约 22%),这些分片上的写入要排队; - 读永远不等。 -批量远超 1000 个 key 时,用 `WithGetManyChunkSize` 让每段各自回填、只占自己的分片。调小后端的 `ChunkSize` 没有这个效果。见 [design/write-order.md](design/write-order.md#慢操作会拖慢多大范围)。 +批量远超 1000 个 key 时,用 `WithGetManyChunkSize` 让每段各自回填、只占自己的分片;各段是并发的,要限制同时占住的分片,还要调小 `WithGetManyFetchConcurrency`。调小后端的 `ChunkSize` 没有这个效果。见 [design/write-order.md](design/write-order.md#慢操作会拖慢多大范围)。 ### 多个实例部署时,还保证写入顺序吗? From e022fecaff27e567dbff2f96bbb5ef0a4a6c56cb Mon Sep 17 00:00:00 2001 From: molon <3739161+molon@users.noreply.github.com> Date: Sat, 10 Oct 2026 12:55:23 +0800 Subject: [PATCH 39/40] test: the deadlock script checks its own results, and runs the table lock strictly Each strategy now asserts what makes the run valid: the unordered writes must reproduce deadlocks, GORMCache must let none reach the caller, and the table lock must admit one write at a time; a sample deadlock error shows what was counted. The MySQL table lock now holds its named lock from before BEGIN to after COMMIT on one connection. Two full runs and the checks of the checks are in the research report. --- .../0010-gorm-deadlock-ordering-and-retry.md | 2 +- docs/research/2026-10-gorm-deadlock.md | 37 +++++++--- docs/research/README.md | 2 +- .../2026-10-gorm-deadlock/deadlock_test.go | 69 ++++++++++++++++--- 4 files changed, 89 insertions(+), 21 deletions(-) diff --git a/docs/adr/0010-gorm-deadlock-ordering-and-retry.md b/docs/adr/0010-gorm-deadlock-ordering-and-retry.md index d9c0143..a89d03f 100644 --- a/docs/adr/0010-gorm-deadlock-ordering-and-retry.md +++ b/docs/adr/0010-gorm-deadlock-ordering-and-retry.md @@ -15,7 +15,7 @@ ## 考虑过的方案 -- **锁表**:死锁也能降到 0,但吞吐损失随并发上升(8 个 worker 时约 -20%,16 个时 -32% 到 -46%)。缓存层正是高并发的地方,代价太大。 +- **锁表**:死锁也能降到 0,但吞吐损失随并发上升(8 个 worker 时约 -20%,16 个时 -32% 到 -46%)。上表的锁表实现在 MySQL 上提交前就释放了锁,不够严格;改成严格锁表后复跑两遍,损失是 -41% 到 -50%,见研究报告的「复跑脚本的完整验证」一节。缓存层正是高并发的地方,代价太大。 - **只重试、不统一顺序**:PostgreSQL 上反而更糟,重来一遍还会撞上;第一轮的 320 次操作跑了 460 秒。 - **改用 READ COMMITTED 隔离级别以减少间隙锁**:MySQL 上的死锁反而更多。 diff --git a/docs/research/2026-10-gorm-deadlock.md b/docs/research/2026-10-gorm-deadlock.md index 87fae58..acda840 100644 --- a/docs/research/2026-10-gorm-deadlock.md +++ b/docs/research/2026-10-gorm-deadlock.md @@ -46,20 +46,39 @@ 锁表的吞吐损失随并发上升:8 个 worker 时约 -20%,16 个时 -32% 到 -46%。缓存层正是高并发的地方,所以没有采用。 -这两轮实验里,MySQL 的「锁表」在事务提交之前就释放了命名锁,锁得不够严格;严格的锁表吞吐只会更低,结论不变。复跑脚本已经改成提交之后才释放。 +这两轮实验里,MySQL 的「锁表」在事务提交之前就释放了命名锁,锁得不够严格。复跑脚本已经改成提交之后才释放,严格锁表的结果见下一节。 -### 复跑脚本的抽样结果 +### 复跑脚本的完整验证(2026-10-10) -`tools/bench/2026-10-gorm-deadlock` 把上面的方案整理成了四种:`unordered` 是修复之前的写法(随机顺序 upsert,普通 `DELETE`);`ordered` 是统一加锁顺序但不重试;`ordered+retry` 直接调用现在的 `GORMCache`;`table lock` 是锁表。用很小的负载(8 个 worker × 10 轮)验证过脚本: +`tools/bench/2026-10-gorm-deadlock` 把上面的方案整理成四种: -| 方案 | MySQL 死锁 | PostgreSQL 死锁 | +| 策略 | 是什么 | 脚本断言 | |---|---|---| -| unordered | 52 / 80 | 30 / 80(24 秒) | -| ordered | 0 / 80 | 0 / 80 | -| ordered+retry(GORMCache) | 0 / 80 | 0 / 80 | -| table lock | 0 / 80 | 0 / 80 | +| `unordered` | 修复之前的写法:随机顺序 upsert,普通 `DELETE` | **必须**复现出死锁,否则说明负载没有触发竞态,实验无效 | +| `ordered` | 统一加锁顺序,不重试 | PostgreSQL 上必须零死锁(MySQL 的间隙锁允许少量死锁) | +| `ordered+retry` | 直接调用现在的 `GORMCache` | 零死锁、零错误传到调用方 | +| `table lock` | 整表串行写:MySQL 在同一个连接上,于事务开始前取命名锁、提交后释放;PostgreSQL 用事务级咨询锁 | 零死锁、零错误,并且锁内同一时刻最多只有 1 个写入 | -这么小的负载下,吞吐量没有参考意义;比较吞吐请用默认负载复跑。脚本只复现第二轮的设置(2000 个 key),第一轮的「只重试」和「READ COMMITTED」两种方案没有放进脚本。 +每种策略还会记录一条真实的死锁错误样本,确认计数的确实是数据库的死锁(MySQL 是 `Error 1213 (40001): Deadlock found…`,PostgreSQL 是 `ERROR: deadlock detected (SQLSTATE 40P01)`)。 + +**断言本身也做过反向验证**: +- 把「锁表」改成不加锁,断言报告「8 writes ran inside the lock at once」,测试失败; +- 把 `GORMCache.SetMany` 的排序去掉(脚本引用的是本地的库代码),断言报告 PostgreSQL 上「22 deadlocks … reached the caller」,测试失败。MySQL 上的死锁全部被重试吸收,这也说明重试只能兜住少量死锁,PostgreSQL 必须靠统一加锁顺序。 + +默认负载(16 个 worker × 80 轮,2000 个 key)完整跑了两遍,断言全部通过: + +| 策略 | MySQL 第 1 遍 | MySQL 第 2 遍 | PostgreSQL 第 1 遍 | PostgreSQL 第 2 遍 | +|---|---|---|---|---| +| unordered | 1072 次死锁 | 1052 次死锁 | 781 次死锁(646 秒) | 747 次死锁(620 秒) | +| ordered | 11 次死锁,796 ops/s | 8 次死锁,607 ops/s | 0,1326 ops/s | 0,1516 ops/s | +| ordered+retry(GORMCache) | **0,794 ops/s** | **0,533 ops/s** | **0,1561 ops/s** | **0,1613 ops/s** | +| table lock | 0,462 ops/s(-42%) | 0,315 ops/s(-41%) | 0,787 ops/s(-50%) | 0,833 ops/s(-48%) | + +- 第 2 遍运行时,机器上同时在跑其他测试,MySQL 的绝对吞吐偏低;各策略之间的相对关系不变。 +- 严格的锁表比前两轮测到的更慢(-41% 到 -50%,前两轮是 -32% 到 -46%),「不锁表」的结论更站得住。 +- `unordered` 在 MySQL 上看起来吞吐很高,是因为大部分操作直接以死锁失败返回了。 + +脚本只复现第二轮的设置(2000 个 key);第一轮的「只重试」和「READ COMMITTED」两种方案没有放进脚本。 ## 复跑 diff --git a/docs/research/README.md b/docs/research/README.md index 854a3c3..2ab8202 100644 --- a/docs/research/README.md +++ b/docs/research/README.md @@ -2,7 +2,7 @@ | 报告 | 结论 | 复跑脚本 | |---|---|---| -| [2026-10-gorm-deadlock.md](2026-10-gorm-deadlock.md) | 统一加锁顺序加有限重试,在 MySQL 和 PostgreSQL 上都消除了并发批量写的死锁;锁表也能做到,但吞吐低 32% 到 46% | [tools/bench/2026-10-gorm-deadlock](../../tools/bench/2026-10-gorm-deadlock/) | +| [2026-10-gorm-deadlock.md](2026-10-gorm-deadlock.md) | 统一加锁顺序加有限重试,在 MySQL 和 PostgreSQL 上都消除了并发批量写的死锁;严格的锁表也能做到,但吞吐低 41% 到 50%;复跑脚本自带断言,完整负载验证过两遍 | [tools/bench/2026-10-gorm-deadlock](../../tools/bench/2026-10-gorm-deadlock/) | | [2026-10-double-check.md](2026-10-double-check.md) | 二次检查只在后端读取有延迟、key 又很热时有收益;按需二次检查在热点 key 上拿到几乎全部收益,在冷 key 上几乎零成本 | [tools/bench/2026-10-double-check](../../tools/bench/2026-10-double-check/) | | [2026-10-batch-result-shape.md](2026-10-batch-result-shape.md) | 批量读的三种返回形态里,按 key 顺序排列的切片最快,`map[string]Result` 最慢;和一次后端往返相比,差别可以忽略 | [tools/bench/2026-10-batch-result-shape](../../tools/bench/2026-10-batch-result-shape/) | diff --git a/tools/bench/2026-10-gorm-deadlock/deadlock_test.go b/tools/bench/2026-10-gorm-deadlock/deadlock_test.go index 5af5e1b..b30b1f5 100644 --- a/tools/bench/2026-10-gorm-deadlock/deadlock_test.go +++ b/tools/bench/2026-10-gorm-deadlock/deadlock_test.go @@ -54,10 +54,21 @@ func isDeadlock(err error) bool { return strings.Contains(s, "deadlock") || strings.Contains(s, "40p01") || strings.Contains(s, "(40001)") } +// expectation is what a strategy must show for the run to be valid. +type expectation int + +const ( + expectDeadlocks expectation = iota // must reproduce the race, or the load did not exercise it + expectNoneOnPG // no deadlocks on PostgreSQL; MySQL's gap locks may still cause a few + expectNoFailures // no deadlocks and no errors at all + expectNoFailuresSerial // same, and at most one write inside the lock at a time +) + type strategy struct { - name string - set func(ctx context.Context, db *gorm.DB, c *cachex.GORMCache[string], table string, values map[string]string) error - del func(ctx context.Context, db *gorm.DB, c *cachex.GORMCache[string], table string, keys []string) error + name string + expect expectation + set func(ctx context.Context, db *gorm.DB, c *cachex.GORMCache[string], table string, values map[string]string) error + del func(ctx context.Context, db *gorm.DB, c *cachex.GORMCache[string], table string, keys []string) error } var keyCol = clause.Column{Name: "key"} @@ -100,6 +111,17 @@ func anys(keys []string) []any { return out } +// inLock and maxInLock check that the table lock really serializes writes. +var inLock, maxInLock atomic.Int32 + +func locked(f func() error) error { + n := inLock.Add(1) + for m := maxInLock.Load(); n > m && !maxInLock.CompareAndSwap(m, n); m = maxInLock.Load() { + } + defer inLock.Add(-1) + return f() +} + // tableLocked serializes every write to the table: a named lock on MySQL, held // on one connection around the whole transaction (taken before BEGIN, released // after COMMIT); an advisory transaction lock on PostgreSQL. Either has the @@ -110,7 +132,7 @@ func tableLocked(ctx context.Context, db *gorm.DB, table string, f func(ctx cont if err := tx.Exec("SELECT pg_advisory_xact_lock(hashtext(?))", "bench:"+table).Error; err != nil { return err } - return f(cachex.WithGORMTx(ctx, tx)) + return locked(func() error { return f(cachex.WithGORMTx(ctx, tx)) }) }) } return db.WithContext(ctx).Connection(func(conn *gorm.DB) error { @@ -118,21 +140,23 @@ func tableLocked(ctx context.Context, db *gorm.DB, table string, f func(ctx cont return err } defer conn.Exec("SELECT RELEASE_LOCK(?)", "bench:"+table) - return conn.Transaction(func(tx *gorm.DB) error { return f(cachex.WithGORMTx(ctx, tx)) }) + return conn.Transaction(func(tx *gorm.DB) error { + return locked(func() error { return f(cachex.WithGORMTx(ctx, tx)) }) + }) }) } var strategies = []strategy{ - {name: "unordered", set: rawSet(false), del: rawDel(false)}, - {name: "ordered", set: rawSet(true), del: rawDel(true)}, - {name: "ordered+retry (GORMCache)", + {name: "unordered", expect: expectDeadlocks, set: rawSet(false), del: rawDel(false)}, + {name: "ordered", expect: expectNoneOnPG, set: rawSet(true), del: rawDel(true)}, + {name: "ordered+retry (GORMCache)", expect: expectNoFailures, set: func(ctx context.Context, _ *gorm.DB, c *cachex.GORMCache[string], _ string, v map[string]string) error { return c.SetMany(ctx, v) }, del: func(ctx context.Context, _ *gorm.DB, c *cachex.GORMCache[string], _ string, k []string) error { return c.DelMany(ctx, k) }}, - {name: "table lock", + {name: "table lock", expect: expectNoFailuresSerial, set: func(ctx context.Context, db *gorm.DB, c *cachex.GORMCache[string], table string, v map[string]string) error { return tableLocked(ctx, db, table, func(ctx context.Context) error { return c.SetMany(ctx, v) }) }, @@ -186,7 +210,9 @@ func TestDeadlockStrategies(t *testing.T) { c := cachex.NewGORMCache[string](&cachex.GORMCacheConfig{DB: db, TableName: table}) require.NoError(t, c.Migrate(ctx)) - var deadlocks, ops atomic.Int64 + var deadlocks, failures, ops atomic.Int64 + var sample atomic.Value // one real deadlock error, to show what was counted + maxInLock.Store(0) start := time.Now() var wg sync.WaitGroup for range workers { @@ -210,7 +236,9 @@ func TestDeadlockStrategies(t *testing.T) { ops.Add(1) if isDeadlock(err) { deadlocks.Add(1) + sample.CompareAndSwap(nil, err.Error()) } else if err != nil { + failures.Add(1) t.Errorf("%s/%s: %v", d.name, st.name, err) } } @@ -220,6 +248,27 @@ func TestDeadlockStrategies(t *testing.T) { elapsed := time.Since(start) t.Logf("%-8s %-26s deadlocks %4d / %d %7.2fs %6.0f ops/s", d.name, st.name, deadlocks.Load(), ops.Load(), elapsed.Seconds(), float64(ops.Load())/elapsed.Seconds()) + if msg, ok := sample.Load().(string); ok { + t.Logf(" sample: %.140s", msg) + } + + switch st.expect { + case expectDeadlocks: + if deadlocks.Load() == 0 { + t.Errorf("%s/%s: no deadlock reproduced; the load is too light to show the race", d.name, st.name) + } + case expectNoneOnPG: + if d.name == "postgres" && deadlocks.Load() > 0 { + t.Errorf("%s/%s: %d deadlocks with one lock order", d.name, st.name, deadlocks.Load()) + } + case expectNoFailures, expectNoFailuresSerial: + if deadlocks.Load()+failures.Load() > 0 { + t.Errorf("%s/%s: %d deadlocks and %d other failures reached the caller", d.name, st.name, deadlocks.Load(), failures.Load()) + } + if st.expect == expectNoFailuresSerial && maxInLock.Load() != 1 { + t.Errorf("%s/%s: %d writes ran inside the lock at once", d.name, st.name, maxInLock.Load()) + } + } } } } From f1a105b3e3321fab1bda9eab9ac8355fc47602c8 Mon Sep 17 00:00:00 2001 From: molon <3739161+molon@users.noreply.github.com> Date: Sat, 10 Oct 2026 13:17:19 +0800 Subject: [PATCH 40/40] feat: Migrate rejects an existing MySQL table whose key column is not utf8mb4_0900_bin On any other collation keys differing in case or trailing spaces share a row and rows are not locked in byte order. The error includes the ALTER statement. Docs state that only each database's default isolation level is supported, and why the deadlock retry stays on byte-exact tables. --- CLAUDE.md | 2 +- README.md | 2 +- README_ZH.md | 2 +- .../adr/0009-gorm-exact-keys-and-collation.md | 11 ++++---- .../0010-gorm-deadlock-ordering-and-retry.md | 2 +- docs/design/backends.md | 17 +++++++++--- docs/faq.md | 12 +++++++-- docs/faq_ZH.md | 12 +++++++-- gorm.go | 26 ++++++++++++++++--- gorm_container_test.go | 16 +++++++----- 10 files changed, 76 insertions(+), 26 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index c1ca036..a7249cc 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -51,5 +51,5 @@ go test -tags bench -v -run ./tools/bench/<目录>/ # 复跑实测 - **每个在途回源恰好发布一次结果**,panic 和 Goexit 也不例外。不要让等待方去等一个永远不会来的结果。见 [ADR 0006](docs/adr/0006-goexit-publishes-an-error.md)。 - **回源用的 ctx 不带领头请求的取消,也不带它的 GORM 事务。** 见 [ADR 0007](docs/adr/0007-detached-fetch-context.md)。 - **批量读里,不存在不是错误**,缺席的 key 就是不存在;整批失败的错误不能被当成「全部不存在」。见 [ADR 0004](docs/adr/0004-batch-result-shape.md)。 -- **GORMCache 的 key 列条件要用 clause 构造**(`key` 是 MySQL 的保留字),**只返回 key 完全相等的行**,**批量写按字节序加锁**。见 [ADR 0009](docs/adr/0009-gorm-exact-keys-and-collation.md)、[ADR 0010](docs/adr/0010-gorm-deadlock-ordering-and-retry.md)。 +- **GORMCache 的 key 列条件要用 clause 构造**(`key` 是 MySQL 的保留字),**只返回 key 完全相等的行**,**批量写按字节序加锁**,MySQL 表的 `key` 列只认 `utf8mb4_0900_bin`,**只支持各数据库默认的隔离级别**、不在代码里设置它。见 [ADR 0009](docs/adr/0009-gorm-exact-keys-and-collation.md)、[ADR 0010](docs/adr/0010-gorm-deadlock-ordering-and-retry.md)。 - **Redis pipeline 的错误要逐条命令判断**,连接层面的失败要设到没发出去的命令上,否则 `GET` 会把故障读成空值。见 [design/backends.md](docs/design/backends.md#批量pipeline)。 diff --git a/README.md b/README.md index 39c4109..e76ea2f 100644 --- a/README.md +++ b/README.md @@ -215,7 +215,7 @@ if err := cache.Migrate(ctx); err != nil { } ``` -Cache keys are case-sensitive, so the `key` column should compare them exactly. PostgreSQL and SQLite do by default, and on MySQL (8.0.17 or later) `Migrate` creates the table with `utf8mb4_0900_bin`, which compares case and trailing spaces exactly. Before creating it, `Migrate` checks the server version and returns an error naming it on an older MySQL or on MariaDB, which lack that collation. A table created before that (or by hand) keeps its collation, usually case- and accent-insensitive (`*_ci`); convert it with `ALTER TABLE cache_products CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_bin`. Even without it nothing wrong is ever served: `GORMCache` only returns the row stored under exactly the requested key, so keys differing only in case just take the row over from each other (extra misses). +Cache keys are case-sensitive, so the `key` column should compare them exactly. PostgreSQL and SQLite do by default, and on MySQL (8.0.17 or later) `Migrate` creates the table with `utf8mb4_0900_bin`, which compares case and trailing spaces exactly. Before creating it, `Migrate` checks the server version and returns an error naming it on an older MySQL or on MariaDB, which lack that collation. When the table already exists, `Migrate` checks that its `key` column uses `utf8mb4_0900_bin` and otherwise returns an error; a table created with MySQL's defaults is case- and accent-insensitive (`*_ci`), so convert it first with `ALTER TABLE cache_products CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_bin`. Only each database's default isolation level is supported. Concurrent batch writes (from several instances' `GetMany` write-backs) lock rows in one order, so they do not deadlock each other; a write the database still aborts as a deadlock victim (MySQL's gap locks can) is retried a few times. Inside a transaction passed with `WithGORMTx` it is not retried, since the deadlock has rolled that whole transaction back; the error is returned. diff --git a/README_ZH.md b/README_ZH.md index 8da7a30..3230643 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -215,7 +215,7 @@ if err := cache.Migrate(ctx); err != nil { } ``` -缓存 key 区分大小写,所以 `key` 列应当精确比较。PostgreSQL 和 SQLite 默认如此;MySQL(需 8.0.17 及以上)上 `Migrate` 建表时会用 `utf8mb4_0900_bin`,大小写和末尾空格都精确比较。建表前 `Migrate` 会检查服务端版本:低于 8.0.17 的 MySQL 或 MariaDB 都没有这个排序规则,会返回写明版本号的错误。在这之前建的表(或手工建的表)保留原来的排序规则,通常不区分大小写和重音(`*_ci`),可以用 `ALTER TABLE cache_products CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_bin` 转换。即使不转换也不会读到错的值:`GORMCache` 只返回 key 完全相等的那一行,只差大小写的几个 key 只会互相挤占这一行(多几次未命中)。 +缓存 key 区分大小写,所以 `key` 列应当精确比较。PostgreSQL 和 SQLite 默认如此;MySQL(需 8.0.17 及以上)上 `Migrate` 建表时会用 `utf8mb4_0900_bin`,大小写和末尾空格都精确比较。建表前 `Migrate` 会检查服务端版本:低于 8.0.17 的 MySQL 或 MariaDB 都没有这个排序规则,会返回写明版本号的错误。表已经存在时,`Migrate` 会检查 `key` 列是不是 `utf8mb4_0900_bin`,不是就返回错误;MySQL 默认配置下建的表不区分大小写和重音(`*_ci`),要先用 `ALTER TABLE cache_products CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_bin` 转换。只支持各数据库默认的隔离级别。 并发的批量写入(多个实例的 `GetMany` 回填)按同一顺序锁行,彼此不会死锁;数据库仍判为死锁牺牲者的写入(MySQL 的间隙锁可能导致)会重试几次。通过 `WithGORMTx` 传入的事务里不重试,因为死锁已经回滚了整个事务,直接返回错误。 diff --git a/docs/adr/0009-gorm-exact-keys-and-collation.md b/docs/adr/0009-gorm-exact-keys-and-collation.md index a2ad435..d996dd8 100644 --- a/docs/adr/0009-gorm-exact-keys-and-collation.md +++ b/docs/adr/0009-gorm-exact-keys-and-collation.md @@ -4,17 +4,18 @@ 1. `Get`/`GetMany` 只返回存储的 key 和请求的 key 完全相等的行; 2. upsert 时连同 key 列一起改写,一行共享的数据只属于最后写入它的 key; -3. `Migrate` 在 MySQL 上建表时使用 `utf8mb4_0900_bin`,大小写和末尾空格都精确比较。这要求 MySQL 8.0.17 及以上(MariaDB 没有这个排序规则),所以建表前会先检查版本。 +3. 只支持 `key` 列为 `utf8mb4_0900_bin` 的 MySQL 表,大小写和末尾空格都精确比较。`Migrate` 建表时使用它,这要求 MySQL 8.0.17 及以上(MariaDB 没有这个排序规则),所以建表前会先检查版本;表已经存在时,检查 `key` 列的排序规则,不符合就返回错误,并给出转换语句。 -前两点保证不管表用什么排序规则,**都不会读到别的 key 的值**;第三点让新表从根上避免冲突。 +第三点从根上避免冲突;前两点是多一道防线,万一碰上不符合的表(比如没调 `Migrate`、自己建的表),也**不会读到别的 key 的值**。 ## 考虑过的方案 - **大小写不敏感地匹配,和 `Get` 保持一致**:这是本 PR 的一个中间版本。它只是让 `GetMany` 和 `Get` 错得一样,读到别的 key 的值这个问题依然存在。 - **`utf8mb4_bin`**:支持更老的 MySQL,但它是 PAD SPACE 排序规则,会忽略末尾空格,`"a"` 和 `"a "` 仍会共用一行。我们选择只支持 MySQL 8.0.17 及以上。 -- **改写已有表的排序规则**:会对老用户的表执行 ALTER,风险不应由库来承担。已有的表保持不动,README 给出了手动转换的语句。 +- **改写已有表的排序规则**:会对老用户的表执行 ALTER,锁表时间和风险不应由库来承担。`Migrate` 只报错并给出语句,由用户自己执行。 +- **继续支持已有的 `*_ci` 表**:只差大小写的 key 会互相挤占同一行,批量写的加锁顺序也不再是字节序,只能靠重试兜底。main 上的 GORMCache 读取时用了未加引号的 `key`,在 MySQL 上本来就报语法错误,实际没有需要兼容的老表。 ## 后果 -- 老表上只差大小写的几个 key 会互相挤占同一行,表现为多几次未命中,但不会串值。 -- 不再支持在 MySQL 8.0.17 以下的版本和 MariaDB 上**新建**表;已经存在的表照常可以使用。 +- 不支持 MySQL 8.0.17 以下的版本和 MariaDB。 +- 已有的 `*_ci` 表要先手动转换,`Migrate` 才会通过。 diff --git a/docs/adr/0010-gorm-deadlock-ordering-and-retry.md b/docs/adr/0010-gorm-deadlock-ordering-and-retry.md index a89d03f..7635c10 100644 --- a/docs/adr/0010-gorm-deadlock-ordering-and-retry.md +++ b/docs/adr/0010-gorm-deadlock-ordering-and-retry.md @@ -22,4 +22,4 @@ ## 后果 - 死锁的识别要区分驱动:PostgreSQL 用 SQLSTATE;MySQL 只能匹配错误文本 `Error 1213 (40001)`,因为 go-sql-driver 的错误类型没有 SQLState 方法。驱动如果改了错误格式,MySQL 这边的重试就会失效。 -- 老的 MySQL `*_ci` 表的索引顺序不是字节序,那里只能靠重试兜底。 +- 只支持各数据库的默认隔离级别。MySQL 的 REPEATABLE READ 下,间隙锁仍会偶发死锁,所以 MySQL 上去不掉重试;PostgreSQL 的 READ COMMITTED 下实测没有死锁,重试只是保险。没有死锁时,重试不产生任何额外开销。 diff --git a/docs/design/backends.md b/docs/design/backends.md index 3ec79d9..4f5ae35 100644 --- a/docs/design/backends.md +++ b/docs/design/backends.md @@ -63,14 +63,16 @@ type cacheEntry struct { | 数据库 | key 列默认怎么比较 | cachex 的处理 | |---|---|---| | PostgreSQL、SQLite | 逐字节 | 不需要额外处理 | -| MySQL | 默认排序规则(`utf8mb4_0900_ai_ci`)**不区分大小写和重音** | `Migrate` 建表时使用 `utf8mb4_0900_bin`。建表前检查版本:低于 8.0.17 的 MySQL 和 MariaDB 都没有这个排序规则,会返回写明版本号的错误。已经存在的表不会改动 | +| MySQL | 默认排序规则(`utf8mb4_0900_ai_ci`)**不区分大小写和重音** | `Migrate` 建表时使用 `utf8mb4_0900_bin`。建表前检查版本:低于 8.0.17 的 MySQL 和 MariaDB 都没有这个排序规则,会返回写明版本号的错误。表已经存在时,检查 `key` 列的排序规则,不是 `utf8mb4_0900_bin` 就返回错误,错误里带转换语句 | -即使 key 列不能精确比较(比如升级前建的老表),也**不会读到别的 key 的值**: +`Migrate` 不替你改表。老表(比如 MySQL 默认配置下建的 `*_ci` 表)要自己转换:`ALTER TABLE <表> CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_bin`。不调 `Migrate`、自己建表时,同样要用这个排序规则。 + +读写本身还多一道防线,万一碰上不能精确比较的表,也**不会读到别的 key 的值**: - `Get`/`GetMany` 只返回存储的 key 和请求的 key **完全相等**的那一行; - upsert 时连同 key 列一起改写,所以一行共享的数据只属于最后写入它的那个 key。 -代价是只差大小写的几个 key 会互相挤占同一行,表现为多几次未命中。把老表转成精确比较:`ALTER TABLE <表> CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_bin`。决策过程见 [ADR 0009](../adr/0009-gorm-exact-keys-and-collation.md)。 +决策过程见 [ADR 0009](../adr/0009-gorm-exact-keys-and-collation.md)。 ### `key` 是 MySQL 的保留字 @@ -82,10 +84,17 @@ type cacheEntry struct { - **统一加锁顺序**: - `SetMany` 插入前按 key 的字节序排序。否则多个实例同时回填有重叠的 key 时,会以相反的顺序锁行而死锁。 - PostgreSQL 的 `DelMany` 先用 `SELECT … ORDER BY key COLLATE "C" FOR UPDATE` 按字节序锁好行,再删除。`DELETE` 是按索引顺序加锁的,而索引顺序跟着列的排序规则走(官方镜像默认是 `en_US.utf8`),和 `SetMany` 的字节序不一致。 - - MySQL 新表的 `utf8mb4_0900_bin` 按码点排序,和 UTF-8 的字节序一致,所以不需要额外处理。 + - MySQL 的 `utf8mb4_0900_bin` 按码点排序,和 UTF-8 的字节序一致,所以不需要额外处理。 - **死锁重试**:MySQL 的间隙锁仍可能偶发死锁,InnoDB 要求应用自行重试。所以 `Set`/`Del`/`SetMany`/`DelMany` 被数据库判为死锁牺牲者时会重试,最多执行 5 次(即重试 4 次),每次退避的时间带随机抖动,并尊重 ctx。识别方式:PostgreSQL 看 SQLSTATE `40P01`/`40001`;MySQL 匹配驱动的错误文本 `Error 1213 (40001)`,因为 go-sql-driver 的错误类型没有提供 SQLState 方法。 - **调用方自己的事务里不重试**:用 `WithGORMTx` 把事务放进 ctx 时,死锁已经让数据库回滚了整个事务,只重试一条语句是错的,所以直接把错误返回给调用方。 +### 隔离级别 + +只支持、也只测过各数据库的**默认**隔离级别:MySQL InnoDB 的 REPEATABLE READ、PostgreSQL 的 READ COMMITTED、SQLite 的 SERIALIZABLE。cachex 不设置隔离级别,每一段写入都是一条自动提交的语句,用的是连接的默认值;不要把缓存表所用连接的默认隔离级别改掉。 + +- MySQL 上剩下的偶发死锁正是 REPEATABLE READ 的间隙锁造成的,靠重试兜住。改用 READ COMMITTED 实测死锁反而更多。 +- 统一加锁顺序之后,PostgreSQL 在默认级别下实测没有死锁,重试只是保险。 + 这几种做法的实测对比(包括锁表)见 [research/2026-10-gorm-deadlock.md](../research/2026-10-gorm-deadlock.md),决策见 [ADR 0010](../adr/0010-gorm-deadlock-ordering-and-retry.md)。 ### 事务 diff --git a/docs/faq.md b/docs/faq.md index 1300e72..4331d22 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -127,8 +127,16 @@ All together. Fresh values, stale values (with serve-stale) and fetched values a ### What does GORMCache need on MySQL? - **Creating the table** needs MySQL 8.0.17 or later: `Migrate` uses `utf8mb4_0900_bin`, so keys compare case and trailing spaces exactly, and it checks the version before creating the table. -- Existing tables are left as they are and never return another key's value; keys that differ only in case take a shared row over from each other. The statement to convert an old table is in [design/backends.md](design/backends.md#key-必须精确比较) (Chinese). +- **An existing table** needs its `key` column in `utf8mb4_0900_bin`; otherwise `Migrate` returns an error that includes the statement to convert it (`ALTER TABLE CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_bin`). A `*_ci` table created with MySQL's defaults must be converted first. See [design/backends.md](design/backends.md#key-必须精确比较) (Chinese). ### Do concurrent writes to GORMCache from several instances deadlock? -They rarely fail: writes lock rows in byte order, and the occasional deadlock (MySQL's gap locks) is retried automatically (at most 5 attempts). When the attempts run out, the error is returned; a failed backfill is only logged at WARN and the next read fetches again. Old MySQL `*_ci` tables do not lock in byte order and rely on the retry alone. Inside your own transaction (`WithGORMTx`) nothing is retried, since the deadlock has rolled the whole transaction back. See [ADR 0010](adr/0010-gorm-deadlock-ordering-and-retry.md) (Chinese). +They rarely fail: writes lock rows in byte order, and the occasional deadlock (MySQL's gap locks) is retried automatically (at most 5 attempts). When the attempts run out, the error is returned; a failed backfill is only logged at WARN and the next read fetches again. Inside your own transaction (`WithGORMTx`) nothing is retried, since the deadlock has rolled the whole transaction back. See [ADR 0010](adr/0010-gorm-deadlock-ordering-and-retry.md) (Chinese). + +### Does GORMCache need a particular isolation level? + +Only each database's default isolation level is supported and tested (REPEATABLE READ on MySQL, READ COMMITTED on PostgreSQL, SERIALIZABLE on SQLite). cachex sets no isolation level; each chunk is written by one autocommit statement. Do not change the default isolation level of the connection the cache table uses. + +### My key column is already `utf8mb4_0900_bin`. Do I still need the deadlock retry? + +Yes. `utf8mb4_0900_bin` makes rows lock in byte order, which removes most deadlocks; the rest come from gap locks under MySQL's default isolation level, which ordering cannot remove, so they are retried. On PostgreSQL no deadlock was measured once the order is uniform. A retry happens only after a statement has failed as a deadlock victim, so it costs nothing when there is no deadlock. See [design/backends.md](design/backends.md#隔离级别) (Chinese). diff --git a/docs/faq_ZH.md b/docs/faq_ZH.md index 10e40a9..d323133 100644 --- a/docs/faq_ZH.md +++ b/docs/faq_ZH.md @@ -127,8 +127,16 @@ TTL 是**不主动写入**时旧数据的存活上限。`Set`/`Del` 是你主动 ### MySQL 上用 GORMCache 有什么要求? - **新建表**需要 MySQL 8.0.17 及以上:`Migrate` 会用 `utf8mb4_0900_bin`,让 key 精确比较大小写和末尾空格,建表前会检查版本。 -- 已经存在的老表不会被改动,也不会读到别的 key 的值;只差大小写的 key 会互相挤占同一行。转换老表的语句见 [design/backends.md](design/backends.md#key-必须精确比较)。 +- **已经存在的表**,`key` 列必须是 `utf8mb4_0900_bin`,否则 `Migrate` 会报错,错误里带转换语句(`ALTER TABLE <表> CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_bin`)。MySQL 默认配置下建的 `*_ci` 表要先转换。见 [design/backends.md](design/backends.md#key-必须精确比较)。 ### 多个实例同时写 GORMCache 会死锁吗? -极少失败:写入统一按字节序加锁,偶发的死锁(MySQL 的间隙锁)会自动重试(最多执行 5 次)。重试用尽仍会报错;回填失败只记 WARN 日志,下次读取再回源。老的 MySQL `*_ci` 表加锁顺序不是字节序,只能靠重试兜底。在你自己的事务里(`WithGORMTx`)不会重试,因为死锁已经回滚了整个事务。见 [ADR 0010](adr/0010-gorm-deadlock-ordering-and-retry.md)。 +极少失败:写入统一按字节序加锁,偶发的死锁(MySQL 的间隙锁)会自动重试(最多执行 5 次)。重试用尽仍会报错;回填失败只记 WARN 日志,下次读取再回源。在你自己的事务里(`WithGORMTx`)不会重试,因为死锁已经回滚了整个事务。见 [ADR 0010](adr/0010-gorm-deadlock-ordering-and-retry.md)。 + +### GORMCache 对数据库的隔离级别有要求吗? + +只支持、也只测过各数据库的默认隔离级别(MySQL 的 REPEATABLE READ、PostgreSQL 的 READ COMMITTED、SQLite 的 SERIALIZABLE)。cachex 不设置隔离级别,每段写入都是一条自动提交的语句。不要改掉缓存表所用连接的默认隔离级别。 + +### 表的 key 列已经是 `utf8mb4_0900_bin`,还需要死锁重试吗? + +需要。`utf8mb4_0900_bin` 让加锁顺序和字节序一致,消除了大部分死锁;剩下的来自 MySQL 默认隔离级别下的间隙锁,排序消除不了,要靠重试。PostgreSQL 上统一顺序之后实测没有死锁。重试只在语句已经因为死锁失败时才发生,没有死锁时不产生任何开销。见 [design/backends.md](design/backends.md#隔离级别)。 diff --git a/gorm.go b/gorm.go index fdc2884..ecd8495 100644 --- a/gorm.go +++ b/gorm.go @@ -3,6 +3,7 @@ package cachex import ( "cmp" "context" + "database/sql" "encoding/json" stderrors "errors" "fmt" @@ -154,7 +155,11 @@ func (g *GORMCache[T]) prefixedKey(key string) string { func (g *GORMCache[T]) Migrate(ctx context.Context) error { tx := cmp.Or(GetGORMTx(ctx), g.db).WithContext(ctx).Table(g.tableName) if tx.Name() == "mysql" { - if !tx.Migrator().HasTable(g.tableName) { + if tx.Migrator().HasTable(g.tableName) { + if err := g.checkMySQLKeyCollation(tx); err != nil { + return err + } + } else { var version string if err := tx.Raw("SELECT VERSION()").Scan(&version).Error; err != nil { return errors.Wrap(err, "failed to read the MySQL version") @@ -163,8 +168,7 @@ func (g *GORMCache[T]) Migrate(ctx context.Context) error { return err } } - // keys compare exactly (case, trailing spaces), MySQL's defaults do not; applies - // only when the table is created, an existing one is left as it is + // keys compare exactly (case, trailing spaces), MySQL's defaults do not tx = tx.Set("gorm:table_options", "CHARSET=utf8mb4 COLLATE=utf8mb4_0900_bin") // MySQL 8.0.17+ } if err := tx.AutoMigrate(&cacheEntry{}); err != nil { @@ -173,6 +177,22 @@ func (g *GORMCache[T]) Migrate(ctx context.Context) error { return nil } +// checkMySQLKeyCollation fails unless the existing table's key column uses +// utf8mb4_0900_bin: under any other collation keys differing in case or +// trailing spaces share a row, and rows are not locked in byte order. +func (g *GORMCache[T]) checkMySQLKeyCollation(tx *gorm.DB) error { + var collation sql.NullString + if err := tx.Raw("SELECT COLLATION_NAME FROM information_schema.COLUMNS WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ? AND COLUMN_NAME = ?", + g.tableName, "key").Scan(&collation).Error; err != nil { + return errors.Wrapf(err, "failed to read the key column's collation for table: %s", g.tableName) + } + if collation.String != "utf8mb4_0900_bin" { + return errors.Errorf("GORMCache needs the key column of table %s to use utf8mb4_0900_bin, found %q; convert it with: ALTER TABLE %s CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_bin", + g.tableName, collation.String, g.tableName) + } + return nil +} + type ctxKeyGORMTx struct{} // WithGORMTx attaches a GORM transaction to the context. diff --git a/gorm_container_test.go b/gorm_container_test.go index 51b8773..8861b58 100644 --- a/gorm_container_test.go +++ b/gorm_container_test.go @@ -94,19 +94,23 @@ func TestGORMCacheOnRealDatabases(t *testing.T) { }) if name == "mysql" { - t.Run("an existing case-insensitive table never serves another key's value", func(t *testing.T) { + t.Run("Migrate rejects an existing table whose keys do not compare exactly", func(t *testing.T) { table := "cache_legacy_ci" require.NoError(t, db.Exec("CREATE TABLE "+table+" (`key` varchar(255) NOT NULL PRIMARY KEY, `value` json NOT NULL, `updated_at` datetime(3) NOT NULL) COLLATE=utf8mb4_0900_ai_ci").Error) c := NewGORMCache[string](&GORMCacheConfig{DB: db, TableName: table}) - require.NoError(t, c.Migrate(ctx), "an existing table is left as it is") + err := c.Migrate(ctx) + require.Error(t, err) + assert.Contains(t, err.Error(), "utf8mb4_0900_ai_ci") + alter := "ALTER TABLE " + table + " CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_bin" + assert.Contains(t, err.Error(), alter, "the error says how to convert the table") + require.NoError(t, db.Exec(alter).Error) + require.NoError(t, c.Migrate(ctx)) require.NoError(t, c.Set(ctx, "ABC", "upper")) - _, err := c.Get(ctx, "abc") - assert.True(t, IsErrKeyNotFound(err), "abc does not get ABC's row: %v", err) - require.NoError(t, c.Set(ctx, "abc", "lower")) // takes the shared row over + require.NoError(t, c.Set(ctx, "abc", "lower")) got, err := c.GetMany(ctx, []string{"ABC", "abc"}) require.NoError(t, err) - assert.Equal(t, map[string]string{"abc": "lower"}, got) + assert.Equal(t, map[string]string{"ABC": "upper", "abc": "lower"}, got) }) }