《游戏服务端架构·品类、状态与拓扑》4.1 内存态、持久态与快照

tick 内：内存态权威
提交后：持久态权威
恢复时：快照提供起点，日志/事务提供增量，持久态负责对账

// file: internal/state/snapshot.go
// tier: L1
// verify: go test ./internal/state/
package state

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

var (
	ErrEmptySnapshot   = errors.New("state: empty snapshot")
	ErrFormat          = errors.New("state: malformed snapshot")
	ErrVersionMismatch = errors.New("state: snapshot version mismatch")
	ErrChecksum        = errors.New("state: snapshot checksum mismatch")
)

// magic is "GSS1": game state snapshot, format 1.
const magic uint32 = 0x47535331

// Snapshot is a point-in-time copy of a world shard. Version is the data
// schema version, Tick is the simulation tick the copy was taken at, and
// Checksum covers version, tick and payload.
type Snapshot struct {
	Version  int
	Tick     uint64
	Payload  []byte
	Checksum uint32
}

// Capture copies the payload so later mutation of the caller's buffer cannot
// silently change a snapshot that was already sealed.
func Capture(version int, tick uint64, payload []byte) *Snapshot {
	s := &Snapshot{
		Version: version,
		Tick:    tick,
		Payload: append([]byte(nil), payload...),
	}
	s.Checksum = checksum(s)
	return s
}

func checksum(s *Snapshot) uint32 {
	h := crc32.NewIEEE()
	var b4 [4]byte
	binary.BigEndian.PutUint32(b4[:], uint32(s.Version))
	h.Write(b4[:])
	var b8 [8]byte
	binary.BigEndian.PutUint64(b8[:], s.Tick)
	h.Write(b8[:])
	h.Write(s.Payload)
	return h.Sum32()
}

// Encode serializes the snapshot into a self-describing byte slice:
//
//	magic(4) | version(4) | tick(8) | payload len(4) | payload | crc32(4)
//
// The length prefix is what lets Decode reject a truncated file instead of
// slicing past the buffer.
func (s *Snapshot) Encode() []byte {
	out := make([]byte, 0, 20+len(s.Payload)+4)
	var b [8]byte
	binary.BigEndian.PutUint32(b[:4], magic)
	out = append(out, b[:4]...)
	binary.BigEndian.PutUint32(b[:4], uint32(s.Version))
	out = append(out, b[:4]...)
	binary.BigEndian.PutUint64(b[:], s.Tick)
	out = append(out, b[:]...)
	binary.BigEndian.PutUint32(b[:4], uint32(len(s.Payload)))
	out = append(out, b[:4]...)
	out = append(out, s.Payload...)
	binary.BigEndian.PutUint32(b[:4], checksum(s))
	return append(out, b[:4]...)
}

// Decode validates framing and checksum before returning a snapshot. A
// corrupted file must fail here, not after the world has already been
// overwritten in memory.
func Decode(data []byte) (*Snapshot, error) {
	if len(data) == 0 {
		return nil, ErrEmptySnapshot
	}
	if len(data) < 20+4 {
		return nil, ErrFormat
	}
	if binary.BigEndian.Uint32(data[0:4]) != magic {
		return nil, ErrFormat
	}
	version := int(int32(binary.BigEndian.Uint32(data[4:8])))
	tick := binary.BigEndian.Uint64(data[8:16])
	n := int(binary.BigEndian.Uint32(data[16:20]))
	if n < 0 || len(data) != 20+n+4 {
		return nil, ErrFormat
	}
	s := &Snapshot{
		Version: version,
		Tick:    tick,
		Payload: append([]byte(nil), data[20:20+n]...),
	}
	want := binary.BigEndian.Uint32(data[20+n:])
	if got := checksum(s); got != want {
		return nil, fmt.Errorf("%w: stored=%08x computed=%08x", ErrChecksum, want, got)
	}
	s.Checksum = want
	return s, nil
}

// Restore is the gate between a decoded snapshot and live memory. It refuses
// nil, checksum-damaged and version-incompatible snapshots. Only an exact
// schema match is accepted: reading a v3 payload with v4 code is a guess, and
// guessing about world state is how silent corruption ships.
func Restore(s *Snapshot, currentVersion int) error {
	if s == nil {
		return ErrEmptySnapshot
	}
	if s.Checksum != checksum(s) {
		return fmt.Errorf("%w: stored=%08x computed=%08x", ErrChecksum, s.Checksum, checksum(s))
	}
	if s.Version != currentVersion {
		return fmt.Errorf("%w: snapshot=%d current=%d", ErrVersionMismatch, s.Version, currentVersion)
	}
	return nil
}

// file: internal/state/snapshot_test.go
// tier: L1
// verify: go test ./internal/state/
package state

import (
	"bytes"
	"errors"
	"testing"
)

func TestCaptureEncodeDecodeRestore(t *testing.T) {
	payload := []byte(`{"island":"harbor","gold":1200}`)
	snap := Capture(7, 88231, payload)

	encoded := snap.Encode()
	got, err := Decode(encoded)
	if err != nil {
		t.Fatalf("Decode: %v", err)
	}
	if err := Restore(got, 7); err != nil {
		t.Fatalf("Restore: %v", err)
	}
	if got.Version != 7 || got.Tick != 88231 {
		t.Fatalf("header lost: version=%d tick=%d", got.Version, got.Tick)
	}
	if !bytes.Equal(got.Payload, payload) {
		t.Fatalf("payload changed: %q", got.Payload)
	}
}

func TestRestoreRejectsVersionMismatch(t *testing.T) {
	snap := Capture(3, 100, []byte("v3-world"))
	err := Restore(snap, 4)
	if !errors.Is(err, ErrVersionMismatch) {
		t.Fatalf("got %v, want ErrVersionMismatch", err)
	}
}

func TestDecodeRejectsCorruptedChecksum(t *testing.T) {
	snap := Capture(7, 1, []byte("world"))
	data := snap.Encode()
	data[len(data)-1] ^= 0xff // flip a payload/checksum-adjacent byte
	if _, err := Decode(data); !errors.Is(err, ErrChecksum) {
		t.Fatalf("got %v, want ErrChecksum", err)
	}
}

func TestRestoreRejectsTamperedStruct(t *testing.T) {
	snap := Capture(7, 1, []byte("world"))
	snap.Payload[0] = 'W' // checksum was computed before this mutation
	if err := Restore(snap, 7); !errors.Is(err, ErrChecksum) {
		t.Fatalf("got %v, want ErrChecksum", err)
	}
}

func TestEmptySnapshot(t *testing.T) {
	if _, err := Decode(nil); !errors.Is(err, ErrEmptySnapshot) {
		t.Fatalf("Decode(nil): got %v", err)
	}
	if err := Restore(nil, 1); !errors.Is(err, ErrEmptySnapshot) {
		t.Fatalf("Restore(nil): got %v", err)
	}
	if _, err := Decode([]byte{0x00}); !errors.Is(err, ErrFormat) {
		t.Fatalf("Decode(short): got %v", err)
	}
}

$ cd .local/checks/gsarch-lab
$ gofmt -l internal/state
$ go vet ./internal/state
$ go test ./internal/state/ -v
=== RUN   TestCaptureEncodeDecodeRestore
--- PASS: TestCaptureEncodeDecodeRestore (0.00s)
=== RUN   TestRestoreRejectsVersionMismatch
--- PASS: TestRestoreRejectsVersionMismatch (0.00s)
=== RUN   TestDecodeRejectsCorruptedChecksum
--- PASS: TestDecodeRejectsCorruptedChecksum (0.00s)
=== RUN   TestRestoreRejectsTamperedStruct
--- PASS: TestRestoreRejectsTamperedStruct (0.00s)
=== RUN   TestEmptySnapshot
--- PASS: TestEmptySnapshot (0.00s)
PASS
ok  	gsarchlab/internal/state	0.236s

1. 选择最新一份通过校验的快照
2. 校验 magic / version / checksum
3. 加载到内存，得到 tick = N
4. 从事件日志重放 tick N+1 到当前已提交位置
5. 与持久态做对账，处理快照之后已提交但日志缺失的记录
6. 确认世界时间、玩家资产、联盟状态一致
7. 才允许接入流量