《MMO 服务器开发》7.2 命令、补偿与重试

// file: internal/gm/command.go
// tier: L1
// verify: go test ./internal/gm/
package gm

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

// Operations-domain command numbers, shared with the wire protocol of volume
// one. The fixed header is unchanged: length(4, BE) | cmd(2, BE) | seq(4, BE) |
// flags(1), HeaderSize 11, MaxPayload 1<<20.
const (
	CmdGmCommandReq  uint16 = 0x1101
	CmdGmCommandResp uint16 = 0x1102
	CmdGmAuditNotify uint16 = 0x1103
)

// PlayerID is the cross-volume alias for a globally unique character id.
type PlayerID uint64

// GmCommand is one operator-issued action. Ticket is the idempotency key: two
// requests that carry the same ticket are the same command, however many times
// the client retries them.
type GmCommand struct {
	CmdID    string
	Operator string
	Target   PlayerID
	Ticket   string
	Args     map[string]int64
}

// Fingerprint is the stable identity of a command. It hashes the command id,
// operator, target, ticket and a sorted view of the arguments, so retries of
// the same logical command collide on purpose while a genuinely different
// command never does.
func (c GmCommand) Fingerprint() string {
	keys := make([]string, 0, len(c.Args))
	for k := range c.Args {
		keys = append(keys, k)
	}
	sort.Strings(keys)
	h := sha256.New()
	fmt.Fprintf(h, "%s|%s|%d|%s", c.CmdID, c.Operator, c.Target, c.Ticket)
	for _, k := range keys {
		fmt.Fprintf(h, "|%s=%d", k, c.Args[k])
	}
	return hex.EncodeToString(h.Sum(nil))
}

// Result records what a command did, so a duplicate can return the same answer
// without re-applying it.
type Result struct {
	Fingerprint string
	Applied     bool
	Detail      string
}

// CommandStore dedups commands by fingerprint. It is the memory of "I already
// did this", and it is the reason a retry is safe.
type CommandStore struct{ done map[string]Result }

// NewCommandStore returns an empty store.
func NewCommandStore() *CommandStore { return &CommandStore{done: map[string]Result{}} }

// Execute applies a command exactly once. The second call with the same
// fingerprint returns the stored result with Applied=false and does not call
// apply again.
func (s *CommandStore) Execute(c GmCommand, apply func(GmCommand) error) (Result, error) {
	fp := c.Fingerprint()
	if prev, ok := s.done[fp]; ok {
		prev.Applied = false
		return prev, nil
	}
	if err := apply(c); err != nil {
		return Result{}, err
	}
	r := Result{Fingerprint: fp, Applied: true, Detail: c.CmdID}
	s.done[fp] = r
	return r, nil
}

// Retry runs apply up to maxAttempts times, stopping at the first success.
// Because Execute dedups by fingerprint, a retry after a success is a no-op
// rather than a second grant; a retry after a failure starts clean.
func (s *CommandStore) Retry(c GmCommand, maxAttempts int, apply func(GmCommand) error) (Result, int, error) {
	for attempt := 1; attempt <= maxAttempts; attempt++ {
		if r, err := s.Execute(c, apply); err == nil {
			return r, attempt, nil
		}
	}
	return Result{}, maxAttempts, fmt.Errorf("gm: command %s failed after %d attempts", c.CmdID, maxAttempts)
}

// Ledger is the currency balance of the world. Grant, compensation and retry
// all move the same two counters, so a conservation check is meaningful: the
// sum of every balance plus the total refunded must equal the total granted.
type Ledger struct {
	balances map[PlayerID]int64
	granted  int64
	refunded int64
}

// NewLedger returns an empty ledger.
func NewLedger() *Ledger { return &Ledger{balances: map[PlayerID]int64{}} }

// Balance returns a player's current currency.
func (l *Ledger) Balance(id PlayerID) int64 { return l.balances[id] }

// Grant moves amount to the player and counts it as granted.
func (l *Ledger) Grant(id PlayerID, amount int64) {
	l.balances[id] += amount
	l.granted += amount
}

// Refund moves amount back from the player and counts it as refunded. It is the
// compensation half of a grant that must be undone.
func (l *Ledger) Refund(id PlayerID, amount int64) {
	l.balances[id] -= amount
	l.refunded += amount
}

// Total is the sum of every player balance.
func (l *Ledger) Total() int64 {
	var sum int64
	for _, v := range l.balances {
		sum += v
	}
	return sum
}

// TotalGranted and TotalRefunded expose the running counters.
func (l *Ledger) TotalGranted() int64  { return l.granted }
func (l *Ledger) TotalRefunded() int64 { return l.refunded }

// Conserved reports the invariant every grant path must keep: granted minus
// refunded equals the sum of all balances. A compensation that forgets to debit
// the player, or a retry that double-credits, breaks this.
func (l *Ledger) Conserved() bool { return l.granted-l.refunded == l.Total() }

// DeliverGrant applies a grant and, on failure, compensates it. This is the
// "发奖失败怎么补" path: the currency is added first, then the item is delivered;
// if delivery fails the currency is refunded so the ledger stays conserved and
// the player is left exactly where they started.
func (s *CommandStore) DeliverGrant(l *Ledger, c GmCommand, amount int64, deliver func(PlayerID) error) (Result, error) {
	return s.Execute(c, func(cmd GmCommand) error {
		l.Grant(cmd.Target, amount)
		if err := deliver(cmd.Target); err != nil {
			l.Refund(cmd.Target, amount)
			return fmt.Errorf("gm: grant for %d failed and was compensated: %w", cmd.Target, err)
		}
		return nil
	})
}

// file: internal/gm/command_test.go
// tier: L1
// verify: go test ./internal/gm/
package gm

import (
	"errors"
	"testing"
)

func TestCommandNumbersAreStable(t *testing.T) {
	if CmdGmCommandReq != 0x1101 || CmdGmCommandResp != 0x1102 || CmdGmAuditNotify != 0x1103 {
		t.Fatalf("gm command numbers drifted: %#x %#x %#x", CmdGmCommandReq, CmdGmCommandResp, CmdGmAuditNotify)
	}
}

func TestSameTicketAppliesOnce(t *testing.T) {
	store := NewCommandStore()
	calls := 0
	cmd := GmCommand{CmdID: "grant_item", Operator: "alice", Target: 1001, Ticket: "t-1", Args: map[string]int64{"count": 5}}
	apply := func(GmCommand) error { calls++; return nil }

	first, err := store.Execute(cmd, apply)
	if err != nil || !first.Applied {
		t.Fatalf("first execute: applied=%v err=%v", first.Applied, err)
	}
	second, err := store.Execute(cmd, apply)
	if err != nil {
		t.Fatalf("second execute: %v", err)
	}
	if second.Applied || second.Fingerprint != first.Fingerprint {
		t.Fatal("a duplicate ticket must not re-apply, but must return the stored result")
	}
	if calls != 1 {
		t.Fatalf("apply called %d times, want 1", calls)
	}
}

func TestRetryDedupsAfterSuccess(t *testing.T) {
	store := NewCommandStore()
	ledger := NewLedger()
	cmd := GmCommand{CmdID: "grant_currency", Operator: "alice", Target: 1001, Ticket: "t-2", Args: map[string]int64{"amount": 100}}
	calls := 0
	apply := func(c GmCommand) error { calls++; ledger.Grant(c.Target, c.Args["amount"]); return nil }

	if _, attempts, err := store.Retry(cmd, 3, apply); err != nil || attempts != 1 {
		t.Fatalf("first retry loop: attempts=%d err=%v", attempts, err)
	}
	// A second retry loop with the same ticket must not grant again.
	if _, attempts, err := store.Retry(cmd, 3, apply); err != nil || attempts != 1 {
		t.Fatalf("second retry loop: attempts=%d err=%v", attempts, err)
	}
	if ledger.Balance(1001) != 100 || calls != 1 {
		t.Fatalf("balance=%d calls=%d, want 100 and 1 (no double grant)", ledger.Balance(1001), calls)
	}
	if !ledger.Conserved() {
		t.Fatal("ledger must stay conserved")
	}
}

func TestGrantCompensationConservesLedger(t *testing.T) {
	store := NewCommandStore()
	ledger := NewLedger()
	cmd := GmCommand{CmdID: "grant_currency", Operator: "alice", Target: 1001, Ticket: "t-4", Args: map[string]int64{"amount": 500}}
	// Delivery fails: the grant must be compensated so no currency leaks.
	if _, err := store.DeliverGrant(ledger, cmd, 500, func(PlayerID) error { return errors.New("mailbox full") }); err == nil {
		t.Fatal("a failed delivery must surface an error")
	}
	if ledger.Balance(1001) != 0 {
		t.Fatalf("balance = %d, want 0 after compensation", ledger.Balance(1001))
	}
	if ledger.TotalGranted() != 500 || ledger.TotalRefunded() != 500 {
		t.Fatalf("granted=%d refunded=%d, want 500/500", ledger.TotalGranted(), ledger.TotalRefunded())
	}
	if !ledger.Conserved() {
		t.Fatal("ledger must stay conserved after compensation")
	}
}

func TestGrantSuccessThenDuplicateKeepsBooks(t *testing.T) {
	store := NewCommandStore()
	ledger := NewLedger()
	cmd := GmCommand{CmdID: "grant_currency", Operator: "alice", Target: 1001, Ticket: "t-5", Args: map[string]int64{"amount": 200}}
	deliver := func(PlayerID) error { return nil }
	if _, err := store.DeliverGrant(ledger, cmd, 200, deliver); err != nil {
		t.Fatalf("first grant: %v", err)
	}
	if r, err := store.DeliverGrant(ledger, cmd, 200, deliver); err != nil || r.Applied {
		t.Fatalf("duplicate grant: applied=%v err=%v", r.Applied, err)
	}
	if ledger.Balance(1001) != 200 || !ledger.Conserved() {
		t.Fatalf("balance=%d conserved=%v, want 200 and true", ledger.Balance(1001), ledger.Conserved())
	}
}

=== RUN   TestCommandNumbersAreStable
--- PASS: TestCommandNumbersAreStable (0.00s)
=== RUN   TestSameTicketAppliesOnce
--- PASS: TestSameTicketAppliesOnce (0.00s)
=== RUN   TestRetryDedupsAfterSuccess
--- PASS: TestRetryDedupsAfterSuccess (0.00s)
=== RUN   TestGrantCompensationConservesLedger
--- PASS: TestGrantCompensationConservesLedger (0.00s)
=== RUN   TestGrantSuccessThenDuplicateKeepsBooks
--- PASS: TestGrantSuccessThenDuplicateKeepsBooks (0.00s)
PASS
ok  	aegis/internal/gm	0.527s