459 lines
14 KiB
Go
459 lines
14 KiB
Go
// Package readmodelcache provides telesrv 统一的进程内 read-model 缓存原语。
|
|
//
|
|
// 它是 ~21 个手搓 read-model 缓存(map + mutex + TTL + 整表 flush + 偶尔 singleflight +
|
|
// 偶尔 epoch)收敛后的唯一实现。它**不是**通用响应缓存:Telegram 响应对 viewer 敏感,
|
|
// 可缓存单元仍是 docs/read-model-architecture.md 定义的 per-viewer 事实/投影。本类型只是
|
|
// 机制——键、TTL、版本 token 仍是各缓存自己的策略。
|
|
//
|
|
// 它替每个使用方免费保证(正是 2026-06-17 缓存审计发现的整类 bug):
|
|
// - 有界:LRU 单条驱逐,绝不整表 flush(避免 thundering-herd 重载悬崖);
|
|
// - 一致:跨越一次失效的 load 不会把陈旧值写回(epoch 守卫)——曾钉死版本脊与
|
|
// ChannelMemberCache 的 lost-update;
|
|
// - 去重:同键并发 miss 收敛为一次 load(singleflight);
|
|
// - 可选版本闸门:仅当 storedHash == currentHash 时复用缓存项。
|
|
//
|
|
// epoch 刻意是**进程内**的:它只关掉进程内 load-vs-invalidate 竞态。跨实例新鲜度由
|
|
// NOTIFY 监听器(以及尚未落地的 durable 失效层)负责,本原语不改变跨进程契约。
|
|
package readmodelcache
|
|
|
|
import (
|
|
"container/list"
|
|
"context"
|
|
"fmt"
|
|
"strconv"
|
|
"sync"
|
|
"time"
|
|
|
|
"golang.org/x/sync/singleflight"
|
|
)
|
|
|
|
// Config 配置一个 Cache 实例。MaxEntries 是强制的:不允许构造无界缓存。
|
|
type Config[K comparable, V any] struct {
|
|
// MaxEntries 是 LRU 上界。<=0 时 New 返回 nil(等价"禁用缓存",沿用各处
|
|
// New*Cache(max<=0)->nil 的惯例;所有方法对 nil 安全,退化为直接 load)。
|
|
MaxEntries int
|
|
// TTL 仅作安全兜底(漏掉的带外写)。0 = 纯事件驱动,无时间过期。
|
|
TTL time.Duration
|
|
// Clone 在 store 与返回两个边界上对值做深拷贝,隔离调用方与缓存项的别名突变。
|
|
// nil = 值本身 copy-safe(标量/扁平结构),不拷贝。
|
|
Clone func(V) V
|
|
// KeyString 生成 singleflight 键;nil 时默认 fmt.Sprint(K)。仅当 K 的 fmt 表示
|
|
// 有歧义(可能两个不同键打印相同)时才需要自定义。
|
|
KeyString func(K) string
|
|
// Now 注入时钟,仅用于 TTL 过期判断;nil 时默认 time.Now。生产一律留空,
|
|
// 测试可注入假时钟以确定地推进 TTL。
|
|
Now func() time.Time
|
|
}
|
|
|
|
type lruEntry[K comparable, V any] struct {
|
|
key K
|
|
value V
|
|
hash int64
|
|
expireAt time.Time // 零值 = 不过期
|
|
}
|
|
|
|
// Cache 是泛型 read-model 缓存。零值不可用,必须经 New 构造。nil *Cache 合法:
|
|
// 所有方法对 nil 安全,GetOrLoad 退化为直接调用 load。
|
|
type Cache[K comparable, V any] struct {
|
|
mu sync.Mutex
|
|
ll *list.List // LRU 顺序,Front=最近使用
|
|
items map[K]*list.Element
|
|
cap int
|
|
ttl time.Duration
|
|
epoch uint64
|
|
sf singleflight.Group
|
|
clone func(V) V
|
|
keyString func(K) string
|
|
now func() time.Time
|
|
}
|
|
|
|
// New 构造一个 Cache。MaxEntries<=0 时返回 nil(禁用缓存,沿用既有惯例)。
|
|
func New[K comparable, V any](cfg Config[K, V]) *Cache[K, V] {
|
|
if cfg.MaxEntries <= 0 {
|
|
return nil
|
|
}
|
|
keyString := cfg.KeyString
|
|
if keyString == nil {
|
|
keyString = func(k K) string { return fmt.Sprint(k) }
|
|
}
|
|
now := cfg.Now
|
|
if now == nil {
|
|
now = time.Now
|
|
}
|
|
return &Cache[K, V]{
|
|
ll: list.New(),
|
|
items: make(map[K]*list.Element, initialMapHint(cfg.MaxEntries)),
|
|
cap: cfg.MaxEntries,
|
|
ttl: cfg.TTL,
|
|
clone: cfg.Clone,
|
|
keyString: keyString,
|
|
now: now,
|
|
}
|
|
}
|
|
|
|
func initialMapHint(max int) int {
|
|
if max < 1024 {
|
|
return max
|
|
}
|
|
return 1024
|
|
}
|
|
|
|
type loadResult[V any] struct {
|
|
value V
|
|
stored bool
|
|
}
|
|
|
|
// GetOrLoad 命中即返回,否则经 singleflight 调 load。load 受 epoch 守卫:
|
|
// 在 load 前快照 epoch,若 load 期间发生过任何 Invalidate/Flush,则**拒绝**把这次
|
|
// load 的结果写回缓存,并重查/重载以取最新值(避免 lost-update 把陈旧值钉进缓存)。
|
|
func (c *Cache[K, V]) GetOrLoad(ctx context.Context, key K, load func() (V, error)) (V, error) {
|
|
return c.getOrLoad(ctx, key, 0, false, load)
|
|
}
|
|
|
|
// GetOrLoadVersioned 在 GetOrLoad 基础上加版本闸门:仅当缓存项的 storedHash ==
|
|
// currentHash 时复用,否则重载。currentHash==0 表示"版本未知/绕过版本闸门"
|
|
// (与既有 snap.hash==currentHash 检查的语义一致)。
|
|
func (c *Cache[K, V]) GetOrLoadVersioned(ctx context.Context, key K, currentHash int64, load func() (V, error)) (V, error) {
|
|
return c.getOrLoad(ctx, key, currentHash, true, load)
|
|
}
|
|
|
|
func (c *Cache[K, V]) getOrLoad(ctx context.Context, key K, currentHash int64, versioned bool, load func() (V, error)) (V, error) {
|
|
if c == nil {
|
|
return load()
|
|
}
|
|
for {
|
|
if v, ok := c.lookup(key, currentHash, versioned); ok {
|
|
return v, nil
|
|
}
|
|
res, err, _ := c.sf.Do(c.singleflightKey(key, currentHash, versioned), func() (any, error) {
|
|
// 进入 singleflight 后再查一次:可能有并发者刚写入。
|
|
if v, ok := c.lookup(key, currentHash, versioned); ok {
|
|
return loadResult[V]{value: v, stored: true}, nil
|
|
}
|
|
loadEpoch := c.cacheEpoch()
|
|
v, err := load()
|
|
if err != nil {
|
|
return loadResult[V]{}, err
|
|
}
|
|
stored := c.storeIfEpoch(key, v, currentHash, loadEpoch)
|
|
return loadResult[V]{value: c.cloneValue(v), stored: stored}, nil
|
|
})
|
|
if err != nil {
|
|
var zero V
|
|
return zero, err
|
|
}
|
|
result := res.(loadResult[V])
|
|
if result.stored {
|
|
return result.value, nil
|
|
}
|
|
// store 被 epoch 守卫拒绝(load 期间发生过失效):本次 load 的值可能已陈旧。
|
|
// 重查缓存——若有更新值(warm/后续 load)直接用,否则重新 load 取 DB 最新态。
|
|
if err := ctx.Err(); err != nil {
|
|
var zero V
|
|
return zero, err
|
|
}
|
|
}
|
|
}
|
|
|
|
func (c *Cache[K, V]) lookup(key K, currentHash int64, versioned bool) (V, bool) {
|
|
var zero V
|
|
c.mu.Lock()
|
|
defer c.mu.Unlock()
|
|
el, ok := c.items[key]
|
|
if !ok {
|
|
return zero, false
|
|
}
|
|
ent := el.Value.(*lruEntry[K, V])
|
|
if c.expired(ent) {
|
|
// 被动 TTL 过期:纯 per-key 删除,**不**自增 epoch——否则会误杀此刻在飞的
|
|
// 不相关 load(epoch 是全局的),造成 thrash。
|
|
c.removeElement(el)
|
|
return zero, false
|
|
}
|
|
if versioned && currentHash != 0 && ent.hash != currentHash {
|
|
return zero, false
|
|
}
|
|
c.ll.MoveToFront(el)
|
|
return c.cloneValue(ent.value), true
|
|
}
|
|
|
|
// storeIfEpoch 仅在 epoch 未变(load 期间无失效)时写入,返回是否写入。
|
|
func (c *Cache[K, V]) storeIfEpoch(key K, v V, hash int64, loadEpoch uint64) bool {
|
|
c.mu.Lock()
|
|
defer c.mu.Unlock()
|
|
if c.epoch != loadEpoch {
|
|
return false
|
|
}
|
|
c.storeLocked(key, v, hash)
|
|
return true
|
|
}
|
|
|
|
func (c *Cache[K, V]) storeLocked(key K, v V, hash int64) {
|
|
if el, ok := c.items[key]; ok {
|
|
ent := el.Value.(*lruEntry[K, V])
|
|
ent.value = c.cloneValue(v)
|
|
ent.hash = hash
|
|
ent.expireAt = c.expireAt()
|
|
c.ll.MoveToFront(el)
|
|
return
|
|
}
|
|
ent := &lruEntry[K, V]{key: key, value: c.cloneValue(v), hash: hash, expireAt: c.expireAt()}
|
|
c.items[key] = c.ll.PushFront(ent)
|
|
if c.ll.Len() > c.cap {
|
|
c.evictOldest()
|
|
}
|
|
}
|
|
|
|
// Store 把一个已在手的值写入缓存(warm-from-list 路径)。不自增 epoch:它不是失效,
|
|
// 不应取消其它在飞 load。
|
|
func (c *Cache[K, V]) Store(key K, v V) {
|
|
if c == nil {
|
|
return
|
|
}
|
|
c.mu.Lock()
|
|
c.storeLocked(key, v, 0)
|
|
c.mu.Unlock()
|
|
}
|
|
|
|
// LoadEpoch 在「外部构建值再写回」模式下,于构建前快照 epoch;之后用 StoreIfEpoch 写回。
|
|
// 适用于值在缓存之外构建(需要 ctx、多次往返)、无法套进 GetOrLoad 的调用方(如 RPC 投影)。
|
|
func (c *Cache[K, V]) LoadEpoch() uint64 {
|
|
if c == nil {
|
|
return 0
|
|
}
|
|
return c.cacheEpoch()
|
|
}
|
|
|
|
// StoreIfEpoch 仅在 epoch 自 loadEpoch 以来未变(构建期间没有失效)时写回外部构建的值。
|
|
// 与 LoadEpoch 配对,把 GetOrLoad 内建的 epoch 守卫开放给外部构建路径。
|
|
func (c *Cache[K, V]) StoreIfEpoch(key K, v V, loadEpoch uint64) {
|
|
if c == nil {
|
|
return
|
|
}
|
|
c.storeIfEpoch(key, v, 0, loadEpoch)
|
|
}
|
|
|
|
// StoreVersioned 同 Store,但带版本 hash(供版本闸门缓存的 warm 路径使用)。
|
|
func (c *Cache[K, V]) StoreVersioned(key K, hash int64, v V) {
|
|
if c == nil {
|
|
return
|
|
}
|
|
c.mu.Lock()
|
|
c.storeLocked(key, v, hash)
|
|
c.mu.Unlock()
|
|
}
|
|
|
|
// GetOrLoadBatch 一趟解析多个键:per-key 命中(TTL + 可选版本闸门)→ 把所有 miss 一次性
|
|
// 批量 load → per-key epoch 守卫写回。服务那些「按键查缓存、把 miss 合批打一次后端」的缓存
|
|
// (dialog-peer / privacy / photo / bot profile),避免单键 GetOrLoad 把一次批量 DB 退化成 N 次。
|
|
//
|
|
// - versionOf(key) 返回 (hash, cacheable):cacheable=false 表示该键绕过缓存(永远重载、不写回,
|
|
// 如 dialog-peer 中 version 缺失的 peer);hash!=0 启用版本闸门(仅当 stored hash 匹配才复用);
|
|
// hash==0 且 cacheable 表示纯 TTL 缓存(无版本,如 photo/privacy/bot)。
|
|
// - loadMissing 必须为它收到的**每个** key 返回一个值(含「查过但不存在」的负缓存哨兵),
|
|
// 这样负结果也会被缓存,杜绝无结果键反复打后端。
|
|
//
|
|
// 若一次失效在批量 load 期间到达(epoch 变更),整趟重试,确保 pre-invalidation 的批量数据
|
|
// 不会遮蔽这次失效(比各缓存原先「静默拒绝写回但仍返回旧批数据」更强;ctx 取消兜底防自旋)。
|
|
func (c *Cache[K, V]) GetOrLoadBatch(
|
|
ctx context.Context,
|
|
keys []K,
|
|
versionOf func(K) (hash int64, cacheable bool),
|
|
loadMissing func(context.Context, []K) (map[K]V, error),
|
|
) (map[K]V, error) {
|
|
if len(keys) == 0 {
|
|
return map[K]V{}, nil
|
|
}
|
|
if c == nil {
|
|
return loadMissing(ctx, dedupeKeys(keys))
|
|
}
|
|
for {
|
|
out := make(map[K]V, len(keys))
|
|
loadEpoch := c.cacheEpoch()
|
|
// 在查阶段就把每个 miss 的 (hash, cacheable) 快照下来,写回时复用同一份——绝不在写回
|
|
// 时重算 versionOf:否则一个版本在查与写之间变更的 key,会把按旧 hash 加载的值以新 hash
|
|
// 戳入缓存,随后被当作新版数据命中(stale-as-fresh,旁路版本闸门)。
|
|
missing := make([]batchMiss[K], 0, len(keys))
|
|
seen := make(map[K]struct{}, len(keys))
|
|
for _, key := range keys {
|
|
if _, dup := seen[key]; dup {
|
|
continue
|
|
}
|
|
seen[key] = struct{}{}
|
|
hash, cacheable := versionOf(key)
|
|
if cacheable {
|
|
if v, ok := c.lookup(key, hash, hash != 0); ok {
|
|
out[key] = v
|
|
continue
|
|
}
|
|
}
|
|
missing = append(missing, batchMiss[K]{key: key, hash: hash, cacheable: cacheable})
|
|
}
|
|
if len(missing) == 0 {
|
|
return out, nil
|
|
}
|
|
missingKeys := make([]K, len(missing))
|
|
for i := range missing {
|
|
missingKeys[i] = missing[i].key
|
|
}
|
|
loaded, err := loadMissing(ctx, missingKeys)
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
if c.cacheEpoch() != loadEpoch {
|
|
// 失效在批量 load 期间到达:重试整趟,避免用 pre-invalidation 数据遮蔽它。
|
|
if err := ctx.Err(); err != nil {
|
|
return nil, err
|
|
}
|
|
continue
|
|
}
|
|
for _, m := range missing {
|
|
v, ok := loaded[m.key]
|
|
if !ok {
|
|
continue
|
|
}
|
|
out[m.key] = v
|
|
if m.cacheable {
|
|
c.storeIfEpoch(m.key, v, m.hash, loadEpoch)
|
|
}
|
|
}
|
|
return out, nil
|
|
}
|
|
}
|
|
|
|
type batchMiss[K comparable] struct {
|
|
key K
|
|
hash int64
|
|
cacheable bool
|
|
}
|
|
|
|
func dedupeKeys[K comparable](keys []K) []K {
|
|
seen := make(map[K]struct{}, len(keys))
|
|
out := make([]K, 0, len(keys))
|
|
for _, key := range keys {
|
|
if _, ok := seen[key]; ok {
|
|
continue
|
|
}
|
|
seen[key] = struct{}{}
|
|
out = append(out, key)
|
|
}
|
|
return out
|
|
}
|
|
|
|
// Peek 直接读,不触发 load、不算 LRU touch(warm/测试路径)。过期项报 miss 但不删除
|
|
// (保持 Peek 无副作用)。
|
|
func (c *Cache[K, V]) Peek(key K) (V, bool) {
|
|
var zero V
|
|
if c == nil {
|
|
return zero, false
|
|
}
|
|
c.mu.Lock()
|
|
defer c.mu.Unlock()
|
|
el, ok := c.items[key]
|
|
if !ok {
|
|
return zero, false
|
|
}
|
|
ent := el.Value.(*lruEntry[K, V])
|
|
if c.expired(ent) {
|
|
return zero, false
|
|
}
|
|
return c.cloneValue(ent.value), true
|
|
}
|
|
|
|
// Invalidate 删除指定键并自增 epoch(关掉任何此刻在飞 load 的写回)。
|
|
func (c *Cache[K, V]) Invalidate(keys ...K) {
|
|
if c == nil || len(keys) == 0 {
|
|
return
|
|
}
|
|
c.mu.Lock()
|
|
c.epoch++
|
|
for _, key := range keys {
|
|
if el, ok := c.items[key]; ok {
|
|
c.removeElement(el)
|
|
}
|
|
}
|
|
c.mu.Unlock()
|
|
}
|
|
|
|
// InvalidateWhere 删除所有满足 pred 的键并自增 epoch(viewer/channel 维度扇出失效,
|
|
// 取代各缓存手写的 deleteChannel/InvalidateViewer 遍历)。
|
|
func (c *Cache[K, V]) InvalidateWhere(pred func(K) bool) {
|
|
if c == nil || pred == nil {
|
|
return
|
|
}
|
|
c.mu.Lock()
|
|
c.epoch++
|
|
for key, el := range c.items {
|
|
if pred(key) {
|
|
c.removeElement(el)
|
|
}
|
|
}
|
|
c.mu.Unlock()
|
|
}
|
|
|
|
// Flush 清空缓存并自增 epoch(监听器断线重连兜底)。
|
|
func (c *Cache[K, V]) Flush() {
|
|
if c == nil {
|
|
return
|
|
}
|
|
c.mu.Lock()
|
|
c.epoch++
|
|
c.ll.Init()
|
|
c.items = make(map[K]*list.Element, initialMapHint(c.cap))
|
|
c.mu.Unlock()
|
|
}
|
|
|
|
// Len 返回当前缓存项数(测试/指标用)。
|
|
func (c *Cache[K, V]) Len() int {
|
|
if c == nil {
|
|
return 0
|
|
}
|
|
c.mu.Lock()
|
|
n := c.ll.Len()
|
|
c.mu.Unlock()
|
|
return n
|
|
}
|
|
|
|
func (c *Cache[K, V]) cacheEpoch() uint64 {
|
|
c.mu.Lock()
|
|
e := c.epoch
|
|
c.mu.Unlock()
|
|
return e
|
|
}
|
|
|
|
func (c *Cache[K, V]) expired(ent *lruEntry[K, V]) bool {
|
|
return c.ttl > 0 && !ent.expireAt.IsZero() && !ent.expireAt.After(c.now())
|
|
}
|
|
|
|
func (c *Cache[K, V]) expireAt() time.Time {
|
|
if c.ttl <= 0 {
|
|
return time.Time{}
|
|
}
|
|
return c.now().Add(c.ttl)
|
|
}
|
|
|
|
func (c *Cache[K, V]) evictOldest() {
|
|
if el := c.ll.Back(); el != nil {
|
|
c.removeElement(el)
|
|
}
|
|
}
|
|
|
|
func (c *Cache[K, V]) removeElement(el *list.Element) {
|
|
c.ll.Remove(el)
|
|
delete(c.items, el.Value.(*lruEntry[K, V]).key)
|
|
}
|
|
|
|
func (c *Cache[K, V]) cloneValue(v V) V {
|
|
if c.clone == nil {
|
|
return v
|
|
}
|
|
return c.clone(v)
|
|
}
|
|
|
|
func (c *Cache[K, V]) singleflightKey(key K, hash int64, versioned bool) string {
|
|
s := c.keyString(key)
|
|
if versioned && hash != 0 {
|
|
s += "@" + strconv.FormatInt(hash, 10)
|
|
}
|
|
return s
|
|
}
|