《游戏服务端架构·平台化与架构治理》6.2 错误预算与发布节奏

允许失败数 = (1 - SLO) × 可计失败事件数
剩余预算   = 允许失败数 - 已失败数
剩余比例   = 剩余预算 / 允许失败数

// file: internal/errorbudget/budget.go
// tier: L1
// verify: go test ./internal/errorbudget/

package errorbudget

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

var (
	ErrInvalidConfig    = errors.New("errorbudget: invalid config")
	ErrDuplicateDay     = errors.New("errorbudget: duplicate day")
	ErrInconsistentDay  = errors.New("errorbudget: bad or eligible count is invalid")
	ErrApprovalRequired = errors.New("errorbudget: emergency release needs incident, reason and approver")
	ErrExemptionExpired = errors.New("errorbudget: exemption has expired")
)

type Day struct {
	Date     time.Time
	Eligible int
	Bad      int
}

type Config struct {
	SLO            float64 // promised success ratio, for example 0.999
	WindowDays     int     // rolling budget window, 28 for a four-week promise
	BurnWindowDays int     // recent window used for burn rate, usually 1 or 3
	TightRemaining float64 // remaining budget ratio below which releases are limited
	FreezeBurn     float64 // burn rate at which releases stop
}

func (c Config) normalize() Config {
	if c.TightRemaining == 0 {
		c.TightRemaining = 0.5
	}
	if c.FreezeBurn == 0 {
		c.FreezeBurn = 4
	}
	return c
}

func (c Config) validate() error {
	if c.SLO <= 0 || c.SLO >= 1 {
		return fmt.Errorf("%w: SLO must be in (0,1)", ErrInvalidConfig)
	}
	if c.WindowDays < 1 {
		return fmt.Errorf("%w: window days must be positive", ErrInvalidConfig)
	}
	if c.BurnWindowDays < 1 || c.BurnWindowDays > c.WindowDays {
		return fmt.Errorf("%w: burn window must be within the budget window", ErrInvalidConfig)
	}
	if c.TightRemaining <= 0 || c.TightRemaining >= 1 {
		return fmt.Errorf("%w: tight remaining must be in (0,1)", ErrInvalidConfig)
	}
	if c.FreezeBurn <= 0 {
		return fmt.Errorf("%w: freeze burn must be positive", ErrInvalidConfig)
	}
	return nil
}

func dateOnly(t time.Time) time.Time {
	y, m, d := t.UTC().Date()
	return time.Date(y, m, d, 0, 0, 0, 0, time.UTC)
}

type Snapshot struct {
	Start          time.Time
	End            time.Time
	WindowDays     int
	ObservedDays   int
	MissingDays    int
	Eligible       int
	Bad            int
	AllowedBad     float64
	RemainingBad   float64
	RemainingRatio float64
	Observed       float64
	BurnStart      time.Time
	BurnEligible   int
	BurnBad        int
	BurnRate       float64
	HasData        bool
	HasBurnData    bool
}

// Rolling folds the calendar days inside [asOf-(WindowDays-1), asOf] into a
// budget snapshot. The long window decides how much budget is left; the short
// window decides how fast it is being burned. Keeping the two separate is what
// lets a team freeze a release during a fast burn while the monthly budget
// still looks healthy.
func Rolling(days []Day, asOf time.Time, cfg Config) (Snapshot, error) {
	cfg = cfg.normalize()
	if err := cfg.validate(); err != nil {
		return Snapshot{}, err
	}
	end := dateOnly(asOf).AddDate(0, 0, 1)
	start := end.AddDate(0, 0, -cfg.WindowDays)
	burnStart := end.AddDate(0, 0, -cfg.BurnWindowDays)

	s := Snapshot{
		Start:      start,
		End:        end,
		WindowDays: cfg.WindowDays,
		BurnStart:  burnStart,
	}
	seen := make(map[string]bool, len(days))
	for _, d := range days {
		if d.Eligible < 0 || d.Bad < 0 || d.Bad > d.Eligible {
			return Snapshot{}, ErrInconsistentDay
		}
		key := dateOnly(d.Date).Format("2006-01-02")
		if seen[key] {
			return Snapshot{}, fmt.Errorf("%w: %s", ErrDuplicateDay, key)
		}
		seen[key] = true
		day := dateOnly(d.Date)
		if day.Before(start) || !day.Before(end) {
			continue
		}
		s.ObservedDays++
		s.Eligible += d.Eligible
		s.Bad += d.Bad
		if !day.Before(burnStart) {
			s.BurnEligible += d.Eligible
			s.BurnBad += d.Bad
		}
	}
	s.MissingDays = s.WindowDays - s.ObservedDays
	if s.Eligible == 0 {
		s.RemainingRatio = 1
		return s, nil
	}
	s.HasData = true
	allowedRate := 1 - cfg.SLO
	s.AllowedBad = allowedRate * float64(s.Eligible)
	s.RemainingBad = s.AllowedBad - float64(s.Bad)
	s.RemainingRatio = s.RemainingBad / s.AllowedBad
	s.Observed = float64(s.Bad) / float64(s.Eligible)
	if s.BurnEligible > 0 {
		s.HasBurnData = true
		s.BurnRate = (float64(s.BurnBad) / float64(s.BurnEligible)) / allowedRate
	}
	return s, nil
}

type Tier string

const (
	Green  Tier = "green"
	Yellow Tier = "yellow"
	Red    Tier = "red"
)

type Decision struct {
	Tier       Tier
	Allowed    bool
	CanaryOnly bool
	Reason     string
	Emergency  bool
	Incident   string
	Approver   string
}

// Gate maps a snapshot to one of three release postures. It never silently
// allows a full release when the data is missing: no data is yellow, not green.
func Gate(s Snapshot, cfg Config) Decision {
	cfg = cfg.normalize()
	if !s.HasData {
		return Decision{
			Tier:       Yellow,
			Allowed:    true,
			CanaryOnly: true,
			Reason:     "no eligible events in window; canary only",
		}
	}
	if s.RemainingRatio <= 0 {
		return Decision{Tier: Red, Reason: "error budget exhausted"}
	}
	if s.HasBurnData && s.BurnRate >= cfg.FreezeBurn-1e-9 {
		return Decision{Tier: Red, Reason: "burn rate above freeze threshold"}
	}
	if s.RemainingRatio < cfg.TightRemaining-1e-9 {
		return Decision{Tier: Yellow, Allowed: true, CanaryOnly: true, Reason: "remaining budget below tight threshold"}
	}
	if s.HasBurnData && s.BurnRate > 1+1e-9 {
		return Decision{Tier: Yellow, Allowed: true, CanaryOnly: true, Reason: "burning faster than the promise allows"}
	}
	return Decision{Tier: Green, Allowed: true, Reason: "budget and burn rate healthy"}
}

type Exemption struct {
	Incident string
	Reason   string
	Approver string
	Expires  time.Time
}

// EmergencyRelease is an explicit, recorded exception. It does not erase the
// red tier; it attaches the incident and approver to the decision so the next
// review can ask why the exception was needed.
func EmergencyRelease(s Snapshot, cfg Config, ex Exemption, now time.Time) (Decision, error) {
	if ex.Incident == "" || ex.Reason == "" || ex.Approver == "" {
		return Decision{}, ErrApprovalRequired
	}
	if !ex.Expires.IsZero() && !ex.Expires.After(now) {
		return Decision{}, ErrExemptionExpired
	}
	d := Gate(s, cfg)
	d.Allowed = true
	d.CanaryOnly = false
	d.Emergency = true
	d.Incident = ex.Incident
	d.Approver = ex.Approver
	d.Reason = fmt.Sprintf("emergency release for %s approved by %s: %s", ex.Incident, ex.Approver, ex.Reason)
	return d, nil
}