《MMO 服务器开发》11.3 至少一次投递下的正确性

请求 ──► ① 幂等窗口（内存，上界 r×ttl）
          │ 命中 → 判重，不落库、不执行 handler
          ▼ 未命中
        ② 唯一约束（持久，键 = fingerprint + 业务主键）
          │ 命中 → 判重（这正是「窗口已过期」的边界）
          ▼ insert 成功
        ③ 状态机（New → Granted → Delivered）
            推进状态，真正发奖

// file: internal/idem/reward.go
// tier: L1
// verify: go test ./internal/idem/ -run TestSettle -v

package idem

import (
	"sync"
	"time"
)

// State is the lifecycle of one reward grant. The state machine is what makes a
// replayed grant a no-op instead of a second payout: a key that is already past
// StateNew can never be granted again.
type State uint8

const (
	StateNew State = iota
	StateGranted
	StateDelivered
)

// Store is the durable half of dedup: a unique constraint keyed by the request
// fingerprint. Begin must be atomic, which is exactly what a SQL UNIQUE index
// or a Redis SET NX gives you.
type Store interface {
	// Begin inserts key if absent and reports the resulting state. created
	// tells the caller whether it now owns the grant; when created is false the
	// returned state is the one already on record.
	Begin(key uint64) (st State, created bool)
	// Commit advances the recorded state for key.
	Commit(key uint64, st State)
}

// MemStore is an in-process Store. A real deployment backs the same interface
// with a UNIQUE index (SQL) or SETNX plus a state field (Redis).
type MemStore struct {
	mu sync.Mutex
	m  map[uint64]State
}

// NewMemStore returns an empty store.
func NewMemStore() *MemStore { return &MemStore{m: make(map[uint64]State)} }

// Begin implements Store.
func (s *MemStore) Begin(key uint64) (State, bool) {
	s.mu.Lock()
	defer s.mu.Unlock()
	if st, ok := s.m[key]; ok {
		return st, false
	}
	s.m[key] = StateGranted
	return StateGranted, true
}

// Commit implements Store.
func (s *MemStore) Commit(key uint64, st State) {
	s.mu.Lock()
	s.m[key] = st
	s.mu.Unlock()
}

// SettlerStats counts where duplicates were caught.
type SettlerStats struct {
	Granted   int // first time a fingerprint was seen
	WindowDup int // retry caught by the in-memory window (fast path)
	StoreDup  int // retry caught by the durable constraint (window had expired)
}

// Settler grants a reward at most once per fingerprint. It stacks three layers:
// a cheap in-memory window for the common retry, a durable unique constraint
// that survives window expiry, and a state machine so a replay is a no-op.
type Settler struct {
	win   *Window
	store Store
	mu    sync.Mutex
	stats SettlerStats
}

// NewSettler builds a settler from a window and a store.
func NewSettler(win *Window, store Store) *Settler {
	return &Settler{win: win, store: store}
}

// Settle applies the reward identified by fp. fresh=true means this call
// granted it; fresh=false means the request was a duplicate, rejected either by
// the window (fast path) or by the durable constraint (window-expired path).
func (s *Settler) Settle(fp Fingerprint, now time.Time) (st State, fresh bool) {
	// Layer 1: the in-memory window. A retry inside the window never reaches
	// the store.
	if prev, existed := s.win.Put(uint64(fp), uint64(StateDelivered), now); existed {
		s.count(func(st *SettlerStats) { st.WindowDup++ })
		return State(prev), false
	}
	// Layer 2: the durable unique constraint. This is what catches a retry that
	// arrives after the window has slid past it.
	cur, created := s.store.Begin(uint64(fp))
	if !created {
		s.count(func(st *SettlerStats) { st.StoreDup++ })
		return cur, false
	}
	// Layer 3: we own the grant, so advance the state machine. A crash between
	// Begin and Commit leaves StateGranted on record; recovery resumes from
	// there rather than re-granting.
	s.store.Commit(uint64(fp), StateDelivered)
	s.count(func(st *SettlerStats) { st.Granted++ })
	return StateDelivered, true
}

// Stats returns a snapshot of the counters.
func (s *Settler) Stats() SettlerStats {
	s.mu.Lock()
	defer s.mu.Unlock()
	return s.stats
}

func (s *Settler) count(f func(*SettlerStats)) {
	s.mu.Lock()
	f(&s.stats)
	s.mu.Unlock()
}

// snippet: internal/idem/reward_test.go（节选）

func TestSettleCatchesRetryAfterWindowExpiry(t *testing.T) {
	win := NewWindow(100*time.Millisecond, 4)
	s := NewSettler(win, NewMemStore())
	fp := FingerprintOf(0x0103, 42, 7, 9001)

	if _, fresh := s.Settle(fp, base); !fresh {
		t.Fatal("first settle was not fresh")
	}
	// The window has slid past the request...
	if _, ok := win.Lookup(uint64(fp), base.Add(500*time.Millisecond)); ok {
		t.Fatal("fingerprint still in window after ttl")
	}
	// ...but the durable constraint still rejects the late retry.
	st, fresh := s.Settle(fp, base.Add(500*time.Millisecond))
	if fresh || st != StateDelivered {
		t.Fatalf("late retry = (%v, %v), want (Delivered, false)", st, fresh)
	}
	if got := s.Stats(); got.StoreDup != 1 || got.Granted != 1 {
		t.Fatalf("stats = %+v, want StoreDup=1 Granted=1", got)
	}
}

// snippet: internal/idem/reward_test.go（节选）

func TestSettleExactlyOnceUnderReplay(t *testing.T) {
	s := NewSettler(NewWindow(time.Millisecond, 4), NewMemStore())
	fp := FingerprintOf(0x0201, 42, 7, 100, 200)

	granted := 0
	for i := 0; i < 200; i++ {
		// Deliver the same request once per millisecond; the 1ms window
		// expires almost immediately, so most of these reach the store.
		if _, fresh := s.Settle(fp, base.Add(time.Duration(i)*time.Millisecond)); fresh {
			granted++
		}
	}
	if granted != 1 {
		t.Fatalf("granted %d times, want exactly 1", granted)
	}
}

func TestSettleConcurrentReplay(t *testing.T) {
	s := NewSettler(NewWindow(time.Minute, 8), NewMemStore())
	fp := FingerprintOf(0x0301, 42, 7, 77)

	var grants int64
	var wg sync.WaitGroup
	for g := 0; g < 64; g++ {
		wg.Add(1)
		go func() {
			defer wg.Done()
			if _, fresh := s.Settle(fp, base); fresh {
				atomic.AddInt64(&grants, 1)
			}
		}()
	}
	wg.Wait()
	if grants != 1 {
		t.Fatalf("granted %d times under concurrency, want exactly 1", grants)
	}
}