《游戏服务端架构·规模化、全球化与成本》3.1 全球延迟预算与路由

client ── access ──▶ gateway ── region ──▶ game/storage
         (最后一公里)          (区域间骨干)      (区域内调用)

// file: internal/latencybudget/budget.go
// tier: L1
// verify: go test ./internal/latencybudget/
package latencybudget

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

// Segment names one hop in the end-to-end RTT budget. Each hop has a different
// owner and a different failure mode, so a single aggregate number cannot tell
// an operator which half of the path to fix.
type Segment string

const (
	SegmentAccess  Segment = "access"
	SegmentRegion  Segment = "region"
	SegmentStorage Segment = "storage"
)

var (
	ErrBadBudget = errors.New("latencybudget: invalid budget")
	ErrBadSample = errors.New("latencybudget: invalid sample")
)

// Budget is the design target for one product profile. Total is the
// player-visible target. The three caps bound each hop so an overrun can be
// attributed instead of hidden inside an aggregate.
type Budget struct {
	Access  time.Duration
	Region  time.Duration
	Storage time.Duration
	Total   time.Duration
}

// Validate rejects budgets that cannot be enforced. Every cap must be
// positive and no cap may exceed the total, otherwise a single hop could pass
// its own check while still breaking the player-visible target.
func (b Budget) Validate() error {
	if b.Total <= 0 {
		return fmt.Errorf("%w: total must be positive", ErrBadBudget)
	}
	for name, cap := range map[Segment]time.Duration{
		SegmentAccess:  b.Access,
		SegmentRegion:  b.Region,
		SegmentStorage: b.Storage,
	} {
		if cap <= 0 {
			return fmt.Errorf("%w: %s cap must be positive", ErrBadBudget, name)
		}
		if cap > b.Total {
			return fmt.Errorf("%w: %s cap %s exceeds total %s", ErrBadBudget, name, cap, b.Total)
		}
	}
	return nil
}

// Action is what the gateway may do when a reading is over budget. Degrading
// is a product decision, not a networking one: it is allowed only for profiles
// that already declared a cheaper mode.
type Action string

const (
	ActionAllow      Action = "ALLOW"
	ActionReduceRate Action = "REDUCE_RATE"
	ActionReject     Action = "REJECT"
)

// Reading is one measured hop. The caller samples access and region RTT, and
// records the storage call observed during the same request.
type Reading struct {
	Segment Segment
	RTT     time.Duration
}

// Report explains a verdict. Over lists the hops that individually exceeded
// their caps, which is not the same as the total being over.
type Report struct {
	Action Action
	Used   time.Duration
	Limit  time.Duration
	Over   []Segment
	Reason string
}

// Evaluate applies a budget to one set of readings. A profile that declared a
// degraded mode gets ActionReduceRate; every other profile is rejected. The
// function never silently accepts a partial reading: all three segments are
// required so the total has a defined meaning.
func Evaluate(b Budget, readings []Reading, degrade bool) (Report, error) {
	if err := b.Validate(); err != nil {
		return Report{}, err
	}
	seen := map[Segment]bool{}
	var used time.Duration
	var over []Segment
	for _, r := range readings {
		if r.Segment != SegmentAccess && r.Segment != SegmentRegion && r.Segment != SegmentStorage {
			return Report{}, fmt.Errorf("%w: unknown segment %q", ErrBadSample, r.Segment)
		}
		if seen[r.Segment] {
			return Report{}, fmt.Errorf("%w: duplicate segment %q", ErrBadSample, r.Segment)
		}
		if r.RTT < 0 {
			return Report{}, fmt.Errorf("%w: negative rtt for %q", ErrBadSample, r.Segment)
		}
		seen[r.Segment] = true
		used += r.RTT
		var cap time.Duration
		switch r.Segment {
		case SegmentAccess:
			cap = b.Access
		case SegmentRegion:
			cap = b.Region
		case SegmentStorage:
			cap = b.Storage
		}
		if r.RTT > cap {
			over = append(over, r.Segment)
		}
	}
	for _, s := range []Segment{SegmentAccess, SegmentRegion, SegmentStorage} {
		if !seen[s] {
			return Report{}, fmt.Errorf("%w: missing segment %q", ErrBadSample, s)
		}
	}
	report := Report{Used: used, Limit: b.Total, Over: over}
	switch {
	case used <= b.Total && len(over) == 0:
		report.Action = ActionAllow
		report.Reason = "within budget"
	case used > b.Total && degrade:
		report.Action = ActionReduceRate
		report.Reason = fmt.Sprintf("over budget by %s", used-b.Total)
	case used > b.Total:
		report.Action = ActionReject
		report.Reason = fmt.Sprintf("over budget by %s", used-b.Total)
	case degrade:
		report.Action = ActionReduceRate
		report.Reason = "hop cap exceeded"
	default:
		report.Action = ActionReject
		report.Reason = "hop cap exceeded"
	}
	return report, nil
}