《游戏服务端架构·品类、状态与拓扑》7.3 观战、回放与赛事架构

比赛服时间轴  ----t----t----t----t----t---->
观战服时间轴  ----------t----t----t----t-->  (固定延迟)
导播输出      --------------t----t----t-->  (可再叠加制作延迟)

事件 = kind(1) + actor(4) + tick(8) + delta(8) = 21 字节
关键帧 = tick(8) + count(4) + crc(4) + 每个 actor(4 + 8)

// file: internal/replay/log.go
// tier: L1
// verify: go test ./internal/replay/
package replay

import (
	"encoding/binary"
	"errors"
	"fmt"
	"hash/crc32"
	"sort"
)

var (
	ErrKeyframeMismatch = errors.New("replay: keyframe does not match event log")
	ErrFutureTick       = errors.New("replay: target tick beyond last event")
	ErrNonMonotonic     = errors.New("replay: event tick went backwards")
)

// Event kinds are part of the on-disk format. Never renumber them: a replay
// written by last season's build must still decode this season.
const (
	KindSpawn  uint8 = 1
	KindMove   uint8 = 2
	KindDamage uint8 = 3
	KindScore  uint8 = 4
)

// Fixed encoding sizes live next to the reader and writer so the size estimate
// and the actual framing cannot drift apart.
const (
	EventBytes     = 1 + 4 + 8 + 8 // kind, actor, tick, delta
	KeyframeHeader = 8 + 4 + 4     // tick, entry count, crc32
	KeyframeEntry  = 4 + 8         // actor, accumulated value
)

// Event is one authoritative state change. Replays store events, not frames:
// the same input can be re-simulated, but an event that already passed the
// server's arbitration is what the observer actually saw.
type Event struct {
	Tick  uint64
	Kind  uint8
	Actor uint32
	Delta int64
}

// State is deliberately small and deterministic: a per-actor accumulator whose
// digest depends only on sorted actor IDs, never on map iteration order.
type State struct {
	Tick  uint64
	Score map[uint32]int64
}

func newState() State { return State{Score: make(map[uint32]int64)} }

// Digest covers tick and the sorted actor/value pairs. Two rebuilds that agree
// on this value agree on everything the replay format claims to preserve.
func (s State) Digest() uint32 {
	h := crc32.NewIEEE()
	var b [8]byte
	binary.BigEndian.PutUint64(b[:], s.Tick)
	h.Write(b[:])
	ids := make([]uint32, 0, len(s.Score))
	for id := range s.Score {
		ids = append(ids, id)
	}
	sort.Slice(ids, func(i, j int) bool { return ids[i] < ids[j] })
	for _, id := range ids {
		binary.BigEndian.PutUint32(b[:4], id)
		h.Write(b[:4])
		binary.BigEndian.PutUint64(b[:], uint64(s.Score[id]))
		h.Write(b[:])
	}
	return h.Sum32()
}

func (s *State) apply(e Event) {
	s.Tick = e.Tick
	s.Score[e.Actor] += e.Delta
}

func cloneState(s State) State {
	out := State{Tick: s.Tick, Score: make(map[uint32]int64, len(s.Score))}
	for k, v := range s.Score {
		out.Score[k] = v
	}
	return out
}

// Keyframe is a periodic checkpoint. Events is the number of log entries
// already folded into State, which is how a rebuild knows where to resume.
type Keyframe struct {
	Tick   uint64
	State  State
	Events int
	Digest uint32
}

// Log is an append-only event stream with periodic keyframes.
type Log struct {
	KeyEvery uint64
	Events   []Event
	Keys     []Keyframe
	cur      State
}

// NewLog builds a log that snapshots state at least every keyEvery ticks.
func NewLog(keyEvery uint64) *Log {
	if keyEvery == 0 {
		keyEvery = 1
	}
	return &Log{KeyEvery: keyEvery, cur: newState()}
}

// Append records one event and emits a keyframe when the configured interval
// has elapsed. Backwards ticks are rejected because they would make the
// smallest-resume-index assumption false.
func (l *Log) Append(e Event) error {
	if n := len(l.Events); n > 0 && e.Tick < l.Events[n-1].Tick {
		return fmt.Errorf("%w: tick=%d previous=%d", ErrNonMonotonic, e.Tick, l.Events[n-1].Tick)
	}
	l.cur.apply(e)
	l.Events = append(l.Events, e)
	if len(l.Keys) == 0 || e.Tick-l.Keys[len(l.Keys)-1].Tick >= l.KeyEvery {
		l.Keys = append(l.Keys, Keyframe{
			Tick:   e.Tick,
			State:  cloneState(l.cur),
			Events: len(l.Events),
			Digest: l.cur.Digest(),
		})
	}
	return nil
}

// StateAt rebuilds the world at target by loading the newest keyframe at or
// before it and replaying only the events in between. The target tick is
// stamped onto the result so an idle interval still has a stable digest.
func (l *Log) StateAt(target uint64) (State, error) {
	if len(l.Events) == 0 {
		return State{}, fmt.Errorf("%w: log is empty", ErrFutureTick)
	}
	last := l.Events[len(l.Events)-1].Tick
	if target > last {
		return State{}, fmt.Errorf("%w: target=%d last=%d", ErrFutureTick, target, last)
	}
	base := newState()
	start := 0
	for i := len(l.Keys) - 1; i >= 0; i-- {
		if l.Keys[i].Tick <= target {
			base = cloneState(l.Keys[i].State)
			start = l.Keys[i].Events
			break
		}
	}
	for _, e := range l.Events[start:] {
		if e.Tick > target {
			break
		}
		base.apply(e)
	}
	base.Tick = target
	return base, nil
}

// Verify replays the log from zero and checks every keyframe against the
// recomputed digest. A tampered keyframe, a reordered event, or a truncated log
// must fail here, before the replay is published or used for ranking.
func (l *Log) Verify() error {
	s := newState()
	seq := 0
	next := 0
	for _, e := range l.Events {
		s.apply(e)
		seq++
		for next < len(l.Keys) && l.Keys[next].Events == seq {
			kf := l.Keys[next]
			computed := s.Digest()
			if kf.Digest != computed || kf.State.Digest() != computed {
				return fmt.Errorf("%w: tick=%d stored=%08x state=%08x computed=%08x",
					ErrKeyframeMismatch, kf.Tick, kf.Digest, kf.State.Digest(), computed)
			}
			next++
		}
	}
	if next != len(l.Keys) {
		return fmt.Errorf("%w: %d keyframes not covered by %d events",
			ErrKeyframeMismatch, len(l.Keys)-next, len(l.Events))
	}
	return nil
}

// SizeEstimate separates event bytes from keyframe bytes. Compression is not
// modelled here; measure the real artifact before promising a transfer budget.
type SizeEstimate struct {
	Events     int
	Keyframes  int
	EventBytes int
	KeyBytes   int
	TotalBytes int
}

// Estimate computes the uncompressed size of this log using the fixed framing
// constants above.
func (l *Log) Estimate() SizeEstimate {
	e := len(l.Events) * EventBytes
	k := 0
	for _, kf := range l.Keys {
		k += KeyframeHeader + len(kf.State.Score)*KeyframeEntry
	}
	return SizeEstimate{
		Events:     len(l.Events),
		Keyframes:  len(l.Keys),
		EventBytes: e,
		KeyBytes:   k,
		TotalBytes: e + k,
	}
}

// ProjectBytesPerMinute estimates a longer match from an observed event rate.
// Keyframe bodies grow with the number of actors, so the result is a lower
// bound; treat it as a planning example, not a measured file size.
func (l *Log) ProjectBytesPerMinute(ticksPerSecond, eventsPerTick int) int {
	if ticksPerSecond <= 0 || eventsPerTick <= 0 {
		return 0
	}
	events := 60 * ticksPerSecond * eventsPerTick
	keys := events/int(l.KeyEvery) + 1
	return events*EventBytes + keys*KeyframeHeader
}