《游戏服务端架构·核心系统与契约》9.3 榜单的读模型与缓存

// file: internal/rankread/rankread.go
// tier: L1
// verify: go test ./internal/rankread/
package rankread

import (
	"errors"
	"fmt"
	"time"
)

var (
	ErrSource       = errors.New("rankread: nil source")
	ErrTTL          = errors.New("rankread: ttl must be positive")
	ErrStaleWindow  = errors.New("rankread: stale window must not be shorter than ttl")
	ErrRankCapacity = errors.New("rankread: rank cache capacity must be positive")
	ErrPage         = errors.New("rankread: offset must be non-negative and limit positive")
	ErrPlayer       = errors.New("rankread: empty player id")
	ErrUnavailable  = errors.New("rankread: cache expired and source is unavailable")
)

// Entry is one rendered leaderboard row. Rank is absolute, so a page at
// offset 100 still tells the client that the first row is rank 101.
type Entry struct {
	PlayerID string
	Score    int64
	Rank     int
}

// Source is the read interface of the authoritative board. Version must be a
// cheap locally published counter, not a query: the cache calls it on every
// request to decide whether its snapshot is still current.
type Source interface {
	Version() uint64
	Page(offset, limit int) ([]Entry, error)
	Rank(playerID string) (int, error)
}

// Stats is a snapshot of cache counters for dashboards and tests.
type Stats struct {
	PageHits      int
	PageMisses    int
	RankHits      int
	RankMisses    int
	StaleServed   int
	Evictions     int
	Invalidations int
}

// PageResult marks whether the rows came from a stale snapshot. Version is the
// board version the rows were fetched at, which may be older than the current
// version when Stale is true.
type PageResult struct {
	Rows    []Entry
	Version uint64
	Stale   bool
}

// RankResult is the personal rank view. Drift is visible to the client as the
// difference between Version and the live board version, not as a silent lie.
type RankResult struct {
	PlayerID string
	Rank     int
	Version  uint64
	Stale    bool
}

type pageKey struct {
	offset int
	limit  int
}

type pageEntry struct {
	rows        []Entry
	version     uint64
	refreshedAt int64
	valid       bool
}

type rankEntry struct {
	rank        int
	version     uint64
	refreshedAt int64
	valid       bool
}

// Cache wraps a Source with whole-page and personal-rank caches. A version
// change invalidates freshness but keeps the last snapshot, so a source outage
// during a deploy can still serve stale rows inside maxStale. It is not safe
// for concurrent use; shard by board or guard it with a mutex.
type Cache struct {
	src      Source
	ttl      int64
	maxStale int64
	rankCap  int
	now      func() int64

	version     uint64
	initialized bool
	pages       map[pageKey]pageEntry
	ranks       map[string]rankEntry
	stats       Stats
}

// New creates a cache. ttl and maxStale are in milliseconds; maxStale must be
// at least ttl. rankCap bounds the number of per-player rank entries because
// that key space grows with the player population, not with the board size.
func New(src Source, ttl, maxStale int64, rankCap int, now func() int64) (*Cache, error) {
	if src == nil {
		return nil, ErrSource
	}
	if ttl <= 0 {
		return nil, ErrTTL
	}
	if maxStale < ttl {
		return nil, ErrStaleWindow
	}
	if rankCap <= 0 {
		return nil, ErrRankCapacity
	}
	if now == nil {
		now = func() int64 { return time.Now().UnixMilli() }
	}
	return &Cache{
		src:      src,
		ttl:      ttl,
		maxStale: maxStale,
		rankCap:  rankCap,
		now:      now,
		pages:    make(map[pageKey]pageEntry),
		ranks:    make(map[string]rankEntry),
	}, nil
}

// sync refreshes the version and invalidates freshness without deleting the
// old rows. Keeping them is the whole point of the stale window.
func (c *Cache) sync() {
	v := c.src.Version()
	if !c.initialized {
		c.initialized = true
		c.version = v
		return
	}
	if v == c.version {
		return
	}
	c.stats.Invalidations++
	c.version = v
	for k, e := range c.pages {
		e.valid = false
		c.pages[k] = e
	}
	for k, e := range c.ranks {
		e.valid = false
		c.ranks[k] = e
	}
}

// Page returns one page. A fresh hit costs no source call; an expired entry is
// refreshed once and served stale if the source fails inside the stale window.
func (c *Cache) Page(offset, limit int) (PageResult, error) {
	if offset < 0 || limit <= 0 {
		return PageResult{}, ErrPage
	}
	c.sync()
	now := c.now()
	key := pageKey{offset: offset, limit: limit}
	old, ok := c.pages[key]
	if ok && old.valid && now < old.refreshedAt+c.ttl {
		c.stats.PageHits++
		return PageResult{Rows: cloneEntries(old.rows), Version: old.version}, nil
	}
	c.stats.PageMisses++
	rows, err := c.src.Page(offset, limit)
	if err != nil {
		if ok && now-old.refreshedAt <= c.maxStale {
			c.stats.StaleServed++
			return PageResult{Rows: cloneEntries(old.rows), Version: old.version, Stale: true}, nil
		}
		return PageResult{}, fmt.Errorf("%w: %v", ErrUnavailable, err)
	}
	c.pages[key] = pageEntry{rows: cloneEntries(rows), version: c.version, refreshedAt: now, valid: true}
	return PageResult{Rows: cloneEntries(rows), Version: c.version}, nil
}

// Rank returns the personal rank. The cache is bounded: when rankCap is
// reached the whole rank map is dropped, which costs a refill burst but never
// grows without limit.
func (c *Cache) Rank(playerID string) (RankResult, error) {
	if playerID == "" {
		return RankResult{}, ErrPlayer
	}
	c.sync()
	now := c.now()
	old, ok := c.ranks[playerID]
	if ok && old.valid && now < old.refreshedAt+c.ttl {
		c.stats.RankHits++
		return RankResult{PlayerID: playerID, Rank: old.rank, Version: old.version}, nil
	}
	c.stats.RankMisses++
	rank, err := c.src.Rank(playerID)
	if err != nil {
		if ok && now-old.refreshedAt <= c.maxStale {
			c.stats.StaleServed++
			return RankResult{PlayerID: playerID, Rank: old.rank, Version: old.version, Stale: true}, nil
		}
		return RankResult{}, fmt.Errorf("%w: %v", ErrUnavailable, err)
	}
	if !ok && len(c.ranks) >= c.rankCap {
		c.ranks = make(map[string]rankEntry)
		c.stats.Evictions++
	}
	c.ranks[playerID] = rankEntry{rank: rank, version: c.version, refreshedAt: now, valid: true}
	return RankResult{PlayerID: playerID, Rank: rank, Version: c.version}, nil
}

// Stats returns a copy of the current counters.
func (c *Cache) Stats() Stats { return c.stats }

// Version is the board version observed by the last call.
func (c *Cache) Version() uint64 { return c.version }

func cloneEntries(in []Entry) []Entry {
	out := make([]Entry, len(in))
	copy(out, in)
	return out
}