《MMO 服务器开发》15.3 异常行为信号与限速

// file: internal/authority/anomaly.go
// tier: L1
// verify: go test ./internal/authority/ -run 'TestTokenBucket|TestAccumulator|TestScorer'

package authority

import (
	"math"
	"time"
)

// Disposition is the graduated server response to accumulated evidence. It is
// ordered from most permissive to most severe, so comparisons are meaningful.
type Disposition uint8

const (
	Allow Disposition = iota
	Throttle
	Flag
	Disconnect
	Ban
)

var dispositionNames = [...]string{"allow", "throttle", "flag", "disconnect", "ban"}

// String renders a Disposition for logs and metrics labels.
func (d Disposition) String() string {
	if int(d) < len(dispositionNames) {
		return dispositionNames[d]
	}
	return "unknown"
}

// TokenBucket is the request-rate limiter. Capacity is the burst a client may
// spend at once; Refill is tokens per second. It is not a cheat detector by
// itself -- a fast but honest client can exhaust it -- so it only ever lowers a
// client to Throttle, never to Ban.
type TokenBucket struct {
	capacity float64
	refill   float64
	tokens   float64
	last     time.Time
}

// NewTokenBucket returns a bucket that starts full.
func NewTokenBucket(capacity, refill float64, now time.Time) *TokenBucket {
	return &TokenBucket{capacity: capacity, refill: refill, tokens: capacity, last: now}
}

// Allow consumes one token if available and reports the outcome.
func (b *TokenBucket) Allow(now time.Time) bool {
	if elapsed := now.Sub(b.last).Seconds(); elapsed > 0 {
		b.tokens = math.Min(b.capacity, b.tokens+elapsed*b.refill)
		b.last = now
	}
	if b.tokens < 1 {
		return false
	}
	b.tokens--
	return true
}

// Accumulator is an exponentially decaying suspicion score. Each signal adds
// weight; the score halves every halfLife so that one bad packet from an hour
// ago does not outweigh a clean hour since.
type Accumulator struct {
	halfLife time.Duration
	score    float64
	last     time.Time
}

// NewAccumulator returns an accumulator whose score decays with the given
// half-life.
func NewAccumulator(halfLife time.Duration, now time.Time) *Accumulator {
	return &Accumulator{halfLife: halfLife, last: now}
}

func (a *Accumulator) decay(now time.Time) {
	if a.score == 0 || a.halfLife <= 0 {
		a.last = now
		return
	}
	dt := now.Sub(a.last)
	if dt <= 0 {
		return
	}
	a.score *= math.Pow(0.5, float64(dt)/float64(a.halfLife))
	a.last = now
}

// Add folds one weighted signal into the score and returns the new value.
func (a *Accumulator) Add(now time.Time, weight float64) float64 {
	a.decay(now)
	a.score += weight
	return a.score
}

// Score returns the current decayed score without changing it.
func (a *Accumulator) Score(now time.Time) float64 {
	a.decay(now)
	return a.score
}

// Scorer maps a suspicion score to a disposition. Thresholds are cumulative:
// every higher step implies every lower one.
type Scorer struct {
	ThrottleAbove   float64
	FlagAbove       float64
	DisconnectAbove float64
	BanAbove        float64
}

// Decide returns the disposition for a score. Ties go to the more severe step.
func (s Scorer) Decide(score float64) Disposition {
	switch {
	case score >= s.BanAbove:
		return Ban
	case score >= s.DisconnectAbove:
		return Disconnect
	case score >= s.FlagAbove:
		return Flag
	case score >= s.ThrottleAbove:
		return Throttle
	default:
		return Allow
	}
}

// snippet: internal/authority/anomaly_test.go（节选）

// 突发 3 个请求放行，第 4 个立刻拒绝；1 秒后恰好回 1 个。
b := NewTokenBucket(3, 1, base)
for i := 0; i < 3; i++ { if !b.Allow(base) { t.Fatalf("burst %d denied", i) } }
if b.Allow(base) { t.Fatal("fourth immediate request should be denied") }

// 嫌疑分每过一个半衰期减半：4 -> 2 -> 1。
if got := a.Score(base.Add(10 * time.Second)); math.Abs(got-2) > 1e-6 {
	t.Fatalf("score after one half-life = %v, want 2", got)
}

// 阈值累积：分数落在哪一段就返回哪一档处置。
{score: 0, want: Allow}, {score: 5, want: Flag},
{score: 20, want: Disconnect}, {score: 50, want: Ban},