《MMO 服务器开发》1.2 状态归谁：防重复发奖与旧数据覆盖

// file: internal/ownership/state.go
// tier: L1
// verify: go test ./internal/ownership/
// Package ownership turns "who owns the state" into two concrete guards that
// the logic tier applies on every write:
//
//   - a monotonic version, so a slow writer that read an old snapshot can never
//     overwrite a newer one ("old data overwrites new");
//   - an idempotency key per settlement, so a retried or duplicated reward can
//     only ever be granted once ("duplicate reward").
//
// Both are single-process guards in this chapter. Turning them into a
// cross-process protocol is a later chapter's job; the invariant is the same
// either way.
package ownership

import (
	"errors"
	"fmt"
	"sync"
)

// PlayerID is a globally unique character id.
type PlayerID uint64

// ErrStale is returned when a commit carries a version that is not strictly
// newer than the stored one.
var ErrStale = errors.New("ownership: stale snapshot rejected")

// Snapshot is one versioned slice of player state as the data tier would store
// it. Version increases monotonically for a given player; the store accepts a
// write only if its version is strictly greater than the current one.
type Snapshot struct {
	PlayerID PlayerID
	Version  uint64
	Gold     int64
}

// Store is the authoritative in-memory copy owned by the logic tier.
type Store struct {
	mu   sync.Mutex
	byID map[PlayerID]Snapshot
}

// NewStore builds an empty store.
func NewStore() *Store {
	return &Store{byID: make(map[PlayerID]Snapshot)}
}

// Commit applies snap if it is newer than what is already stored. A snapshot
// whose version is less than or equal to the stored version is rejected with
// ErrStale and leaves the store untouched, so a writer that raced with a newer
// one cannot clobber it.
func (s *Store) Commit(snap Snapshot) error {
	s.mu.Lock()
	defer s.mu.Unlock()
	cur, ok := s.byID[snap.PlayerID]
	if ok && snap.Version <= cur.Version {
		return fmt.Errorf("%w: have v%d, got v%d for player %d",
			ErrStale, cur.Version, snap.Version, snap.PlayerID)
	}
	s.byID[snap.PlayerID] = snap
	return nil
}

// Get returns the stored snapshot for a player.
func (s *Store) Get(id PlayerID) (Snapshot, bool) {
	s.mu.Lock()
	defer s.mu.Unlock()
	snap, ok := s.byID[id]
	return snap, ok
}

// RewardGuard makes reward grants idempotent. A settlement may be applied at
// most once, even if the client retries the claim or two workers race on the
// same settlement id.
type RewardGuard struct {
	mu      sync.Mutex
	applied map[string]struct{}
}

// NewRewardGuard builds an empty guard.
func NewRewardGuard() *RewardGuard {
	return &RewardGuard{applied: make(map[string]struct{})}
}

// SettleKey derives the idempotency key for a reward. It must be a pure
// function of the settlement identity: the same battle must always produce the
// same key, on any process, so a retry cannot mint a second key and slip past
// the guard.
func SettleKey(p PlayerID, battleID uint64) string {
	return fmt.Sprintf("reward:%d:%d", p, battleID)
}

// Apply records that key has been granted and reports whether this call was the
// one that granted it. The first call for a key returns true; every later call
// returns false and must not hand out a second reward.
func (g *RewardGuard) Apply(key string) bool {
	g.mu.Lock()
	defer g.mu.Unlock()
	if _, dup := g.applied[key]; dup {
		return false
	}
	g.applied[key] = struct{}{}
	return true
}

// file: internal/ownership/state_test.go
// tier: L1
// verify: go test ./internal/ownership/
package ownership

import (
	"errors"
	"sync"
	"sync/atomic"
	"testing"
)

func TestStaleSnapshotIsRejected(t *testing.T) {
	s := NewStore()
	if err := s.Commit(Snapshot{PlayerID: 1001, Version: 2, Gold: 200}); err != nil {
		t.Fatalf("commit v2: %v", err)
	}
	// A writer that read the old v1 snapshot arrives late and tries to write it
	// back. It must lose, or the player's gold silently rolls back.
	err := s.Commit(Snapshot{PlayerID: 1001, Version: 1, Gold: 100})
	if !errors.Is(err, ErrStale) {
		t.Fatalf("commit v1 = %v, want ErrStale", err)
	}
	got, _ := s.Get(1001)
	if got.Version != 2 || got.Gold != 200 {
		t.Fatalf("stored = %+v, want v2/gold200", got)
	}
}

func TestEqualVersionIsAlsoStale(t *testing.T) {
	s := NewStore()
	_ = s.Commit(Snapshot{PlayerID: 7, Version: 5, Gold: 50})
	// Replaying the same version is a duplicate write, not a new one.
	if err := s.Commit(Snapshot{PlayerID: 7, Version: 5, Gold: 50}); !errors.Is(err, ErrStale) {
		t.Fatalf("duplicate version = %v, want ErrStale", err)
	}
}

func TestRewardAppliedAtMostOnce(t *testing.T) {
	g := NewRewardGuard()
	key := SettleKey(1001, 42)
	if !g.Apply(key) {
		t.Fatal("first apply must grant")
	}
	if g.Apply(key) {
		t.Fatal("second apply must be rejected: duplicate reward")
	}
	if !g.Apply(SettleKey(1001, 43)) {
		t.Fatal("a different battle must grant")
	}
}

func TestSettleKeyIsDeterministic(t *testing.T) {
	if SettleKey(1001, 42) != SettleKey(1001, 42) {
		t.Fatal("SettleKey must be pure")
	}
	if SettleKey(1001, 42) == SettleKey(1002, 42) {
		t.Fatal("different players must not collide")
	}
}

func TestConcurrentClaimGrantsOnce(t *testing.T) {
	g := NewRewardGuard()
	key := SettleKey(1001, 99)
	var granted int32
	var wg sync.WaitGroup
	for i := 0; i < 64; i++ {
		wg.Add(1)
		go func() {
			defer wg.Done()
			if g.Apply(key) {
				atomic.AddInt32(&granted, 1)
			}
		}()
	}
	wg.Wait()
	if n := atomic.LoadInt32(&granted); n != 1 {
		t.Fatalf("granted %d times, want exactly 1", n)
	}
}

=== RUN   TestStaleSnapshotIsRejected
--- PASS: TestStaleSnapshotIsRejected (0.00s)
=== RUN   TestEqualVersionIsAlsoStale
--- PASS: TestEqualVersionIsAlsoStale (0.00s)
=== RUN   TestRewardAppliedAtMostOnce
--- PASS: TestRewardAppliedAtMostOnce (0.00s)
=== RUN   TestSettleKeyIsDeterministic
--- PASS: TestSettleKeyIsDeterministic (0.00s)
=== RUN   TestConcurrentClaimGrantsOnce
--- PASS: TestConcurrentClaimGrantsOnce (0.00s)
PASS
ok  	aegis/internal/ownership	0.349s