《游戏服务端架构·核心系统与契约》9.2 写缓冲、结算与赛季边界

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

import (
	"crypto/sha256"
	"encoding/hex"
	"errors"
	"fmt"
	"sort"
)

var (
	ErrSeason      = errors.New("rankbuffer: empty season")
	ErrCutoff      = errors.New("rankbuffer: cutoff must be positive")
	ErrLimit       = errors.New("rankbuffer: limit must be positive")
	ErrPlayer      = errors.New("rankbuffer: empty player id")
	ErrScore       = errors.New("rankbuffer: negative score")
	ErrTime        = errors.New("rankbuffer: negative timestamp")
	ErrLateWrite   = errors.New("rankbuffer: write arrived after the season cutoff")
	ErrSealed      = errors.New("rankbuffer: season is sealed")
	ErrNilSnapshot = errors.New("rankbuffer: nil snapshot")
	ErrAmounts     = errors.New("rankbuffer: reward amounts must be non-negative")
	ErrSettled     = errors.New("rankbuffer: season was already settled with a different result")
)

// Entry is one accepted write. Seq is assigned by the buffer and is the id a
// durable log can use to deduplicate replays.
type Entry struct {
	PlayerID string
	Score    int64
	At       int64
	Seq      uint64
}

// better must match the ordering used by the board model. Duplicating the
// three comparisons keeps this package extractable without importing the
// write-model package, but the rule itself is a shared contract.
func better(a, b Entry) bool {
	if a.Score != b.Score {
		return a.Score > b.Score
	}
	if a.At != b.At {
		return a.At < b.At
	}
	return a.PlayerID < b.PlayerID
}

// Buffer coalesces writes for one season. At is event time supplied by the
// game server, not the wall clock of the flush loop; a write with at >= cutoff
// belongs to no season and is rejected even before Seal runs.
type Buffer struct {
	season   string
	cutoff   int64
	limit    int
	seq      uint64
	pending  map[string]Entry
	best     map[string]Entry
	sealed   bool
	sealedAt int64
}

// New creates an open buffer. limit is the number of reward ranks the season
// promises; it also caps the snapshot's displayed top list.
func New(season string, cutoff int64, limit int) (*Buffer, error) {
	if season == "" {
		return nil, ErrSeason
	}
	if cutoff <= 0 {
		return nil, ErrCutoff
	}
	if limit <= 0 {
		return nil, ErrLimit
	}
	return &Buffer{
		season:  season,
		cutoff:  cutoff,
		limit:   limit,
		pending: make(map[string]Entry),
		best:    make(map[string]Entry),
	}, nil
}

// Submit accepts a score into the write buffer. Writes are coalesced per
// player: only the best score and its sequence number survive until the next
// flush. The returned Entry is always the candidate with its assigned Seq; a
// false-looking no-op is not an error, because the caller only needs the ack.
func (b *Buffer) Submit(playerID string, score, at int64) (Entry, error) {
	if b.sealed {
		return Entry{}, ErrSealed
	}
	if playerID == "" {
		return Entry{}, ErrPlayer
	}
	if score < 0 {
		return Entry{}, ErrScore
	}
	if at < 0 {
		return Entry{}, ErrTime
	}
	if at >= b.cutoff {
		return Entry{}, ErrLateWrite
	}
	b.seq++
	candidate := Entry{PlayerID: playerID, Score: score, At: at, Seq: b.seq}
	if old, ok := b.best[playerID]; ok && !better(candidate, old) {
		return candidate, nil
	}
	b.best[playerID] = candidate
	b.pending[playerID] = candidate
	return candidate, nil
}

// Flush drains pending writes in player-id order. The result is a delta for
// durable storage; the buffer keeps the full best map so a crash between
// flushes loses only the pending delta, never already flushed scores.
func (b *Buffer) Flush() ([]Entry, error) {
	if b.sealed {
		return nil, ErrSealed
	}
	out := make([]Entry, 0, len(b.pending))
	for _, e := range b.pending {
		out = append(out, e)
	}
	sort.Slice(out, func(i, j int) bool { return out[i].PlayerID < out[j].PlayerID })
	b.pending = make(map[string]Entry)
	return out, nil
}

// Seal freezes the season and returns an immutable snapshot. Pending writes
// are included: they were accepted before the cutoff, so dropping them would
// lose legitimate scores that the player already saw acknowledged.
func (b *Buffer) Seal(at int64) (*Snapshot, error) {
	if b.sealed {
		return nil, ErrSealed
	}
	if at < 0 {
		return nil, ErrTime
	}
	b.sealed = true
	b.sealedAt = at
	entries := make([]Entry, 0, len(b.best))
	for _, e := range b.best {
		entries = append(entries, e)
	}
	sort.Slice(entries, func(i, j int) bool { return better(entries[i], entries[j]) })
	return &Snapshot{
		season:   b.season,
		cutoff:   b.cutoff,
		sealedAt: at,
		limit:    b.limit,
		entries:  entries,
	}, nil
}

// Snapshot is the frozen result of one season. It holds every ranked entry so
// rank queries stay exact while Top still truncates to the promised limit.
type Snapshot struct {
	season   string
	cutoff   int64
	sealedAt int64
	limit    int
	entries  []Entry
}

// Total is the number of ranked players, including those outside Top.
func (s *Snapshot) Total() int { return len(s.entries) }

// Top returns at most min(n, limit) entries. n <= 0 means the display limit.
func (s *Snapshot) Top(n int) []Entry {
	if n <= 0 || n > s.limit {
		n = s.limit
	}
	if n > len(s.entries) {
		n = len(s.entries)
	}
	out := make([]Entry, n)
	copy(out, s.entries[:n])
	return out
}

// Rank returns the 1-based rank and whether the player appears at all.
func (s *Snapshot) Rank(playerID string) (int, bool) {
	for i, e := range s.entries {
		if e.PlayerID == playerID {
			return i + 1, true
		}
	}
	return 0, false
}

// Award is one reward line produced by settlement.
type Award struct {
	PlayerID string
	Rank     int
	Amount   int64
}

// Receipt is the idempotency record for a settled season. Digest covers the
// season, cutoff, seal time and every award, so a replayed settlement with a
// different result is detectable instead of silently paying twice.
type Receipt struct {
	Season   string
	Cutoff   int64
	SealedAt int64
	Awards   []Award
	Digest   string
}

// Settler records one receipt per season. It is not safe for concurrent use;
// the scheduler that owns a season calls Settle from a single goroutine.
type Settler struct {
	receipts map[string]Receipt
}

// NewSettler creates an empty settlement ledger.
func NewSettler() *Settler {
	return &Settler{receipts: make(map[string]Receipt)}
}

// Settle computes awards from a frozen snapshot and records the receipt by
// season. Replaying the same input returns the stored receipt and fresh=false;
// replaying a different result for an already settled season is a conflict.
func (st *Settler) Settle(s *Snapshot, amounts []int64) (Receipt, bool, error) {
	if s == nil {
		return Receipt{}, false, ErrNilSnapshot
	}
	for _, amount := range amounts {
		if amount < 0 {
			return Receipt{}, false, ErrAmounts
		}
	}
	awards := make([]Award, 0, len(amounts))
	for i := 0; i < len(s.entries) && i < len(amounts); i++ {
		if amounts[i] == 0 {
			continue
		}
		awards = append(awards, Award{PlayerID: s.entries[i].PlayerID, Rank: i + 1, Amount: amounts[i]})
	}
	digest := digestOf(s, awards)
	if prev, ok := st.receipts[s.season]; ok {
		if prev.Digest != digest {
			return Receipt{}, false, ErrSettled
		}
		return cloneReceipt(prev), false, nil
	}
	receipt := Receipt{
		Season:   s.season,
		Cutoff:   s.cutoff,
		SealedAt: s.sealedAt,
		Awards:   awards,
		Digest:   digest,
	}
	st.receipts[s.season] = receipt
	return cloneReceipt(receipt), true, nil
}

func digestOf(s *Snapshot, awards []Award) string {
	h := sha256.New()
	fmt.Fprintf(h, "season=%s\ncutoff=%d\nsealedAt=%d\n", s.season, s.cutoff, s.sealedAt)
	for _, a := range awards {
		fmt.Fprintf(h, "%d,%s,%d\n", a.Rank, a.PlayerID, a.Amount)
	}
	return hex.EncodeToString(h.Sum(nil))
}

func cloneReceipt(r Receipt) Receipt {
	out := r
	out.Awards = make([]Award, len(r.Awards))
	copy(out.Awards, r.Awards)
	return out
}