《游戏服务端架构·平台化与架构治理》4.3 黑产对抗的架构边界

// file: internal/anticheatboundary/anticheatboundary.go
// tier: L1
// verify: go test ./internal/anticheatboundary/
package anticheatboundary

import (
	"errors"
	"fmt"
	"math"
	"time"
)

// Authority says who produced the value the server is about to act on: a
// client claim, a server-side validation, or a fully authoritative server
// computation. Cheaper assets may accept validation; transferable assets
// require authority.
type Authority string

const (
	AuthorityClient        Authority = "client_claimed"
	AuthorityValidated     Authority = "server_validated"
	AuthorityAuthoritative Authority = "server_authoritative"
)

func authorityRank(a Authority) (int, bool) {
	switch a {
	case AuthorityClient:
		return 0, true
	case AuthorityValidated:
		return 1, true
	case AuthorityAuthoritative:
		return 2, true
	}
	return 0, false
}

// Asset classifies what an action can change. The more valuable and
// transferable the asset, the higher the authority bar.
type Asset string

const (
	AssetCosmetic Asset = "cosmetic"
	AssetProgress Asset = "progress"
	AssetItem     Asset = "item"
	AssetCurrency Asset = "currency"
	AssetRanking  Asset = "ranking"
)

func assetKnown(a Asset) bool {
	switch a {
	case AssetCosmetic, AssetProgress, AssetItem, AssetCurrency, AssetRanking:
		return true
	}
	return false
}

// Rule is the boundary for one asset: the minimum authority, how long a
// reward stays pending, and how many rate-limit tokens one action costs.
type Rule struct {
	MinAuthority Authority
	RewardDelay  time.Duration
	RateCost     int
}

// Policy maps assets to rules. An asset with no rule is denied, not defaulted.
type Policy struct {
	Rules map[Asset]Rule
}

// DefaultPolicy is the starting boundary for a live game: cosmetic and
// progress can be validated, while items, currency and ranking must be
// server-authoritative. Currency rewards wait before delivery.
func DefaultPolicy() Policy {
	return Policy{Rules: map[Asset]Rule{
		AssetCosmetic: {MinAuthority: AuthorityValidated, RateCost: 1},
		AssetProgress: {MinAuthority: AuthorityValidated, RateCost: 2},
		AssetItem:     {MinAuthority: AuthorityAuthoritative, RateCost: 3},
		AssetCurrency: {MinAuthority: AuthorityAuthoritative, RewardDelay: 10 * time.Minute, RateCost: 5},
		AssetRanking:  {MinAuthority: AuthorityAuthoritative, RateCost: 5},
	}}
}

// RuleFor fails closed: an unknown asset, a non-positive rate cost, or an
// unknown authority makes the whole rule unusable.
func (p Policy) RuleFor(a Asset) (Rule, error) {
	r, ok := p.Rules[a]
	if !ok {
		return Rule{}, fmt.Errorf("anticheatboundary: no rule for asset %q", a)
	}
	if _, ok := authorityRank(r.MinAuthority); !ok {
		return Rule{}, fmt.Errorf("anticheatboundary: unknown authority %q", r.MinAuthority)
	}
	if r.RateCost <= 0 {
		return Rule{}, errors.New("anticheatboundary: rate cost must be positive")
	}
	if r.RewardDelay < 0 {
		return Rule{}, errors.New("anticheatboundary: reward delay must not be negative")
	}
	return r, nil
}

// Action is a request that would change an asset.
type Action struct {
	PlayerID       string
	Asset          Asset
	Authority      Authority
	IdempotencyKey string
	At             time.Time
}

func needsIdempotency(a Asset) bool {
	return a == AssetItem || a == AssetCurrency || a == AssetRanking
}

// Decision is the boundary result. RetryAfter is set only for rate limiting;
// RewardDelay is advisory and tells the caller how long to hold the payout.
type Decision struct {
	Allowed     bool
	Reason      string
	RetryAfter  time.Duration
	RewardDelay time.Duration
}

// Check applies the boundary in a fixed order: rule, identity, authority,
// idempotency, then rate limit. The order matters because a denied request
// must not consume a token.
func Check(p Policy, a Action, bucket *Bucket, now time.Time) Decision {
	r, err := p.RuleFor(a.Asset)
	if err != nil {
		return Decision{Reason: err.Error()}
	}
	if a.PlayerID == "" {
		return Decision{Reason: "anticheatboundary: player id is required"}
	}
	got, ok := authorityRank(a.Authority)
	if !ok {
		return Decision{Reason: "anticheatboundary: unknown authority"}
	}
	want, _ := authorityRank(r.MinAuthority)
	if got < want {
		return Decision{Reason: fmt.Sprintf("anticheatboundary: %s requires %s", a.Asset, r.MinAuthority)}
	}
	if needsIdempotency(a.Asset) && a.IdempotencyKey == "" {
		return Decision{Reason: "anticheatboundary: idempotency key is required for a transferable asset"}
	}
	if bucket != nil {
		ok, retry := bucket.Allow(now, float64(r.RateCost))
		if !ok {
			return Decision{Reason: "anticheatboundary: rate limited", RetryAfter: retry}
		}
	}
	return Decision{Allowed: true, Reason: "within boundary", RewardDelay: r.RewardDelay}
}

// Bucket is a token bucket for one key, such as a player and endpoint pair.
// Tokens refill continuously; a cost above capacity can never succeed.
type Bucket struct {
	capacity        float64
	refillPerSecond float64
	tokens          float64
	last            time.Time
}

// NewBucket creates a full bucket. Zero refill is allowed and means the
// bucket only recovers when the policy or process restarts.
func NewBucket(capacity, refillPerSecond float64, now time.Time) (*Bucket, error) {
	if capacity <= 0 {
		return nil, errors.New("anticheatboundary: bucket capacity must be positive")
	}
	if refillPerSecond < 0 {
		return nil, errors.New("anticheatboundary: refill rate must not be negative")
	}
	return &Bucket{capacity: capacity, refillPerSecond: refillPerSecond, tokens: capacity, last: now}, nil
}

// Allow consumes cost tokens. When it fails, RetryAfter is the whole-second
// wait until enough tokens accumulate; zero means the request can never pass
// with the current bucket.
func (b *Bucket) Allow(now time.Time, cost float64) (bool, time.Duration) {
	if b == nil || cost <= 0 || cost > b.capacity {
		return false, 0
	}
	if now.Before(b.last) {
		now = b.last
	}
	if b.refillPerSecond > 0 {
		b.tokens += now.Sub(b.last).Seconds() * b.refillPerSecond
		if b.tokens > b.capacity {
			b.tokens = b.capacity
		}
	}
	b.last = now
	if b.tokens >= cost {
		b.tokens -= cost
		return true, 0
	}
	if b.refillPerSecond <= 0 {
		return false, 0
	}
	missing := cost - b.tokens
	seconds := math.Ceil(missing / b.refillPerSecond)
	return false, time.Duration(seconds) * time.Second
}

// Reward is a payout that is earned immediately but delivered later, after a
// delay and a final account check. Voided rewards are never paid.
type Reward struct {
	ID          string
	PlayerID    string
	Asset       Asset
	Amount      int64
	EarnedAt    time.Time
	Delay       time.Duration
	Voided      bool
	DeliveredAt time.Time
}

// NewReward validates the payout before it enters the delayed queue.
func NewReward(id, playerID string, asset Asset, amount int64, now time.Time, delay time.Duration) (Reward, error) {
	switch {
	case id == "":
		return Reward{}, errors.New("anticheatboundary: reward id is required")
	case playerID == "":
		return Reward{}, errors.New("anticheatboundary: reward player is required")
	case !assetKnown(asset):
		return Reward{}, fmt.Errorf("anticheatboundary: unknown reward asset %q", asset)
	case amount <= 0:
		return Reward{}, errors.New("anticheatboundary: reward amount must be positive")
	case delay < 0:
		return Reward{}, errors.New("anticheatboundary: reward delay must not be negative")
	}
	return Reward{ID: id, PlayerID: playerID, Asset: asset, Amount: amount, EarnedAt: now, Delay: delay}, nil
}

// DeliverOutcome is the result of one delivery attempt.
type DeliverOutcome string

const (
	DeliverPending DeliverOutcome = "pending"
	DeliverPaid    DeliverOutcome = "paid"
	DeliverVoided  DeliverOutcome = "voided"
)

// Deliver pays a reward only after its delay and only if the account is not
// flagged. Delivery is idempotent: a second successful call returns Paid
// without paying again.
func Deliver(r Reward, now time.Time, flagged bool) (Reward, DeliverOutcome) {
	if !r.DeliveredAt.IsZero() {
		return r, DeliverPaid
	}
	if r.Voided {
		return r, DeliverVoided
	}
	if flagged {
		r.Voided = true
		return r, DeliverVoided
	}
	if now.Before(r.EarnedAt.Add(r.Delay)) {
		return r, DeliverPending
	}
	r.DeliveredAt = now
	return r, DeliverPaid
}

cd .local/checks/gsarch-lab
go test -count=1 ./internal/anticheatboundary/
ok  gsarchlab/internal/anticheatboundary