《MMO 服务器开发》14.3 高延迟玩家的公平性

   允许回退 = min( 绝对上限 , 最大补偿RTT / 2 )

   ↑ 绝对上限：无论玩家多卡，回退都不会超过它（例如 150ms）
   ↑ 最大补偿RTT/2：RTT 超过「最大补偿 RTT」后，补偿不再增长

   允许回退
    150ms ┤───────────────┐   ← 绝对上限，曲线在此拉平
          │               └────────────────
          │          ╱
     75ms ┤       ╱
          │    ╱
     25ms ┤ ╱
          ┼─────────────────────────────→ RTT
             50    100    200    400
          ↑ 曲线斜率 1/2：回退 ≈ RTT/2 + 插值

// file: internal/clock/fairness/guard.go
// tier: L1
// verify: go test ./internal/clock/fairness/

package fairness

import "time"

// Policy caps how much lag compensation a single shooter may claim.
type Policy struct {
	MaxRewind time.Duration // absolute ceiling on any rewind window
	MaxRTT    time.Duration // compensation stops growing past this RTT
}

// ClampRewind limits a claimed rewind window. It returns the window actually
// granted and whether the claim was trimmed. The effective ceiling is the
// smaller of the absolute cap and half the largest compensated RTT.
func (p Policy) ClampRewind(claimed time.Duration) (time.Duration, bool) {
	if claimed < 0 {
		claimed = 0
	}
	limit := p.MaxRewind
	if half := p.MaxRTT / 2; half < limit {
		limit = half
	}
	if claimed > limit {
		return limit, true
	}
	return claimed, false
}

// LagTracker watches a client's RTT samples to flag a lag switch: a link that is
// normally fast but spikes exactly when the player needs to win an exchange.
type LagTracker struct {
	baseline time.Duration
	spike    time.Duration // a sample above baseline+spike counts as a spike
	window   int
	recent   []bool
}

// NewLagTracker builds a tracker seeded with a baseline RTT and a spike margin.
func NewLagTracker(baseline, spike time.Duration, window int) *LagTracker {
	if window < 1 {
		window = 1
	}
	return &LagTracker{baseline: baseline, spike: spike, window: window}
}

// Observe records one RTT sample. A sample well above the baseline is a spike;
// the baseline is a slow EWMA over every sample, so a genuine sustained latency
// shift becomes the new baseline while a one-off spike barely moves it.
func (t *LagTracker) Observe(rtt time.Duration) {
	isSpike := rtt > t.baseline+t.spike
	t.recent = append(t.recent, isSpike)
	if len(t.recent) > t.window {
		t.recent = t.recent[len(t.recent)-t.window:]
	}
	t.baseline = (t.baseline*7 + rtt) / 8
}

// SpikeRate returns the fraction of the last window samples that were spikes.
func (t *LagTracker) SpikeRate() float64 {
	if len(t.recent) == 0 {
		return 0
	}
	n := 0
	for _, s := range t.recent {
		if s {
			n++
		}
	}
	return float64(n) / float64(len(t.recent))
}

// Suspicious reports whether recent spikes are frequent enough to warrant
// dropping compensation for this client.
func (t *LagTracker) Suspicious() bool {
	if len(t.recent) < t.window {
		return false
	}
	return t.SpikeRate() >= 0.5
}

// snippet: internal/clock/fairness/guard_test.go（节选）

func TestLagSwitchDetection(t *testing.T) {
	lt := NewLagTracker(30*time.Millisecond, 50*time.Millisecond, 8)
	for i := 0; i < 8; i++ {
		lt.Observe(28 * time.Millisecond)
	}
	if lt.Suspicious() {
		t.Fatalf("steady low latency flagged: rate=%v", lt.SpikeRate())
	}
	for i := 0; i < 8; i++ {
		lt.Observe(200 * time.Millisecond)
	}
	if !lt.Suspicious() {
		t.Fatalf("sustained spikes not flagged: rate=%v", lt.SpikeRate())
	}
}

func TestSustainedLatencyBecomesBaseline(t *testing.T) {
	lt := NewLagTracker(30*time.Millisecond, 50*time.Millisecond, 4)
	// A player who genuinely lives on a 120ms link: once the slow EWMA baseline
	// has drifted up, samples stop exceeding baseline+50ms.
	for i := 0; i < 40; i++ {
		lt.Observe(120 * time.Millisecond)
	}
	if lt.Suspicious() {
		t.Fatalf("genuine high latency flagged as abuse: baseline=%v rate=%v",
			lt.baseline, lt.SpikeRate())
	}
}