《MMO 服务器开发》11.2 命令编号与业务指纹

// file: internal/idem/fingerprint.go
// tier: L1
// verify: go test ./internal/idem/ -run 'TestFingerprint|TestDeduper' -v

package idem

import (
	"encoding/binary"
	"hash/fnv"
	"time"
)

// CommandID is the transport identity of one command instance: which player,
// which command, and the per-session sequence number carried in the aegis frame
// header (cmd 2 bytes | seq 4 bytes, per the wire spec in chapter 3).
type CommandID struct {
	Actor uint64
	Cmd   uint16
	Seq   uint32
}

// Fingerprint identifies the business intent of a command, independent of the
// transport that carried it. Two retries of "buy item 1001 for 50 gold" share a
// fingerprint even if they carry different Seq values or arrive on different
// connections.
type Fingerprint uint64

// FingerprintOf hashes the semantic fields of a command into a Fingerprint.
// Only fields that define the intent go in: the command, the actor, a
// client-minted idempotency token, and the business arguments. Sequence
// numbers, timestamps and connection ids deliberately do not, because they
// change on every retry.
func FingerprintOf(cmd uint16, actor, token uint64, args ...uint64) Fingerprint {
	h := fnv.New64a()
	var buf [8]byte
	binary.BigEndian.PutUint16(buf[:2], cmd)
	_, _ = h.Write(buf[:2])
	binary.BigEndian.PutUint64(buf[:], actor)
	_, _ = h.Write(buf[:])
	binary.BigEndian.PutUint64(buf[:], token)
	_, _ = h.Write(buf[:])
	for _, a := range args {
		binary.BigEndian.PutUint64(buf[:], a)
		_, _ = h.Write(buf[:])
	}
	return Fingerprint(h.Sum64())
}

// Deduper is the window from 11.1 keyed by business fingerprint instead of by
// transport sequence. It is the cheap first filter: a retry that lands inside
// the window never touches durable storage.
type Deduper struct {
	win *Window
}

// NewDeduper returns a deduper whose window remembers fingerprints for ttl
// across n buckets.
func NewDeduper(ttl time.Duration, n int) *Deduper {
	return &Deduper{win: NewWindow(ttl, n)}
}

// Observe hashes a request and reports whether it is a duplicate. The
// fingerprint is returned so the caller can log it or persist it.
func (d *Deduper) Observe(cmd uint16, actor, token uint64, now time.Time, args ...uint64) (Fingerprint, bool) {
	fp := FingerprintOf(cmd, actor, token, args...)
	return fp, d.win.Seen(uint64(fp), now)
}

// Window exposes the underlying window for lookups and tests.
func (d *Deduper) Window() *Window { return d.win }

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

func TestFingerprintStableAndSeparating(t *testing.T) {
	a := FingerprintOf(0x0201, 42, 7, 100, 200)
	if b := FingerprintOf(0x0201, 42, 7, 100, 200); a != b {
		t.Fatalf("fingerprint not stable: %d != %d", a, b)
	}
	cases := map[string]Fingerprint{
		"token ignored": FingerprintOf(0x0201, 42, 8, 100, 200),
		"actor ignored": FingerprintOf(0x0201, 43, 7, 100, 200),
		"arg order":     FingerprintOf(0x0201, 42, 7, 200, 100),
		"cmd ignored":   FingerprintOf(0x0202, 42, 7, 100, 200),
		"arity ignored": FingerprintOf(0x0201, 42, 7, 100, 200, 0),
	}
	for name, got := range cases {
		if got == a {
			t.Fatalf("%s: fingerprint collided with the base request", name)
		}
	}
}

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

func TestDeduperWithinWindow(t *testing.T) {
	d := NewDeduper(100*time.Millisecond, 4)
	fp1, dup := d.Observe(0x0201, 42, 7, base, 100, 200)
	if dup {
		t.Fatal("first observe reported a duplicate")
	}
	fp2, dup := d.Observe(0x0201, 42, 7, base.Add(5*time.Millisecond), 100, 200)
	if !dup || fp1 != fp2 {
		t.Fatalf("retry not deduped: fp %d vs %d, dup=%v", fp1, fp2, dup)
	}
	// A different token is a different intent, not a retry.
	if _, dup := d.Observe(0x0201, 42, 8, base.Add(5*time.Millisecond), 100, 200); dup {
		t.Fatal("distinct token reported as duplicate")
	}
	// Past the window the deduper has forgotten the intent entirely.
	if _, dup := d.Observe(0x0201, 42, 7, base.Add(time.Second), 100, 200); dup {
		t.Fatal("window should have forgotten the fingerprint")
	}
}

// snippet: internal/gateway/dedup.go（接线示意，随第 17 章落地）

// onCommand handles a mutating command. It binds the actor from the
// authenticated session, recomputes the fingerprint, and either replays the
// cached response or runs the handler exactly once.
func (g *Gateway) onCommand(sess *Session, f *proto.Frame) (*proto.Frame, error) {
	actor := sess.ActorID()        // server-side identity, never a client field
	token, args := decodeIntent(f) // token + business args from the payload
	fp, dup := g.deduper.Observe(f.Cmd, actor, token, time.Now(), args...)
	if dup {
		return g.responses.Get(uint64(fp)), nil // replay, do not re-execute
	}
	resp, err := g.dispatch(sess, f)
	if err == nil {
		g.responses.Put(uint64(fp), resp, time.Now())
	}
	return resp, err
}