《后端架构设计·演进与治理》7.2 错误预算：发布门禁与冻结策略

// file: internal/platform/slo/budget.go
// tier: L1
// verify: go test ./internal/platform/slo/ -count=1 -run 'TestBudget|TestBurn|TestGate'
package slo

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

// Budget is the error allowance for one SLO over one period.
type Budget struct {
	Target float64 // e.g. 0.999
	Total  int     // valid events in the period
	Bad    int     // events that were not good
}

func (b Budget) Validate() error {
	if b.Target <= 0 || b.Target >= 1 {
		return fmt.Errorf("slo: target %.6f outside (0,1)", b.Target)
	}
	if b.Total < 0 || b.Bad < 0 || b.Bad > b.Total {
		return fmt.Errorf("slo: bad=%d total=%d is not a valid sample", b.Bad, b.Total)
	}
	return nil
}

// Allowed stays fractional: 43.2 errors per 28 days is a rate, and rounding it
// to 43 hides 0.2.
func (b Budget) Allowed() float64 { return (1 - b.Target) * float64(b.Total) }

// Remaining may go negative; clamping it would hide overspend.
func (b Budget) Remaining() float64 { return b.Allowed() - float64(b.Bad) }

// RemainingRatio is 1 when untouched, 0 when exactly spent, negative when the
// SLO is already missed for this period.
func (b Budget) RemainingRatio() float64 {
	if allowed := b.Allowed(); allowed > 0 {
		return b.Remaining() / allowed
	}
	return 0
}

// BurnSample is one lookback window used for burn-rate evaluation.
type BurnSample struct {
	Window time.Duration
	Total  int
	Bad    int
}

// Rate is the bad ratio divided by the allowed bad ratio. 1.0 spends the
// period budget exactly over the period. An empty window yields NaN instead of
// a healthy zero.
func (s BurnSample) Rate(target float64) float64 {
	if s.Total == 0 || target <= 0 || target >= 1 {
		return math.NaN()
	}
	return (float64(s.Bad) / float64(s.Total)) / (1 - target)
}

// BurnPolicy is a multi-window rule: the long window proves the burn is
// sustained, the short window proves it is still happening.
type BurnPolicy struct {
	Long, Short                   time.Duration
	LongThreshold, ShortThreshold float64
	MinEvents                     int
}

func (p BurnPolicy) Validate() error {
	if p.Long <= 0 || p.Short <= 0 || p.Short > p.Long {
		return fmt.Errorf("slo: burn windows long=%s short=%s are invalid", p.Long, p.Short)
	}
	if p.LongThreshold <= 0 || p.ShortThreshold <= 0 || p.MinEvents < 0 {
		return errors.New("slo: burn thresholds and minimum events must be positive")
	}
	return nil
}

// BurnResult is one multi-window evaluation at a fixed end time.
type BurnResult struct {
	LongRate, ShortRate float64
	Long, Short         BurnSample
	Data, Firing        bool
}

// EvaluateBurn counts events in both windows and applies the thresholds.
func EvaluateBurn(events []Event, s SLI, end time.Time, target float64, p BurnPolicy) (BurnResult, error) {
	if err := s.Validate(); err != nil {
		return BurnResult{}, err
	}
	if err := p.Validate(); err != nil {
		return BurnResult{}, err
	}
	if target <= 0 || target >= 1 {
		return BurnResult{}, fmt.Errorf("slo: target %.6f outside (0,1)", target)
	}
	long, err := countSample(events, s, Rolling(end, p.Long))
	if err != nil {
		return BurnResult{}, err
	}
	short, err := countSample(events, s, Rolling(end, p.Short))
	if err != nil {
		return BurnResult{}, err
	}
	r := BurnResult{Long: long, Short: short, LongRate: long.Rate(target), ShortRate: short.Rate(target)}
	r.Data = long.Total >= p.MinEvents && short.Total >= p.MinEvents
	r.Firing = r.Data && r.LongRate >= p.LongThreshold && r.ShortRate >= p.ShortThreshold
	return r, nil
}

func countSample(events []Event, s SLI, w Window) (BurnSample, error) {
	m, err := Measure(events, s, w, 0)
	if err != nil {
		return BurnSample{}, err
	}
	return BurnSample{Window: w.End.Sub(w.Start), Total: m.Valid, Bad: m.Valid - m.Good}, nil
}

// Verdict is a release decision. Hold means the data cannot support a
// decision, which is not the same as allow.
type Verdict string

const (
	VerdictAllow  Verdict = "allow"
	VerdictCanary Verdict = "canary-only"
	VerdictFreeze Verdict = "freeze"
	VerdictHold   Verdict = "hold-no-data"
)

// GatePolicy converts budget state into a release decision.
type GatePolicy struct {
	FreezeBelow float64 // remaining ratio that freezes all releases
	CanaryBelow float64 // remaining ratio that limits releases to canary
	MaxBurnRate float64 // sustained burn that freezes regardless of budget
	MinEvents   int
}

func (p GatePolicy) Validate() error {
	if p.FreezeBelow < 0 || p.CanaryBelow < p.FreezeBelow || p.MaxBurnRate <= 0 || p.MinEvents < 0 {
		return fmt.Errorf("slo: invalid gate policy %+v", p)
	}
	return nil
}

// Decide returns the verdict and a one-line reason for the release ticket.
func (p GatePolicy) Decide(b Budget, burn BurnResult) (Verdict, string, error) {
	if err := b.Validate(); err != nil {
		return "", "", err
	}
	if err := p.Validate(); err != nil {
		return "", "", err
	}
	if b.Total < p.MinEvents {
		return VerdictHold, fmt.Sprintf("only %d valid events, need %d", b.Total, p.MinEvents), nil
	}
	remaining := b.RemainingRatio()
	if burn.Firing && burn.LongRate >= p.MaxBurnRate {
		return VerdictFreeze, fmt.Sprintf("burn %.2fx over %.2fx limit", burn.LongRate, p.MaxBurnRate), nil
	}
	if remaining < p.FreezeBelow {
		return VerdictFreeze, fmt.Sprintf("remaining %.1f%% below freeze %.1f%%", remaining*100, p.FreezeBelow*100), nil
	}
	if remaining < p.CanaryBelow {
		return VerdictCanary, fmt.Sprintf("remaining %.1f%% below canary %.1f%%", remaining*100, p.CanaryBelow*100), nil
	}
	if !burn.Data {
		return VerdictAllow, fmt.Sprintf("remaining %.1f%%; burn windows below %d events, budget-only", remaining*100, p.MinEvents), nil
	}
	return VerdictAllow, fmt.Sprintf("remaining %.1f%%, burn %.2fx", remaining*100, burn.LongRate), nil
}

=== RUN   TestBudgetArithmetic
    budget_test.go:25: ten percent left allowed=1000.00 bad=900 remaining=100.00 ratio=0.100
    budget_test.go:25: overspent allowed=1000.00 bad=1300 remaining=-300.00 ratio=-0.300
    budget_test.go:25: fine grained allowed=200.00 bad=50 remaining=150.00 ratio=0.750
--- PASS: TestBudgetArithmetic (0.00s)
=== RUN   TestBurnRate
    budget_test.go:47: window=1h0m0s total=10000 bad=10 rate=1.00
    budget_test.go:47: window=6h0m0s total=60000 bad=120 rate=2.00
    budget_test.go:47: window=1h0m0s total=5000 bad=0 rate=0.00
    budget_test.go:47: window=1h0m0s total=0 bad=0 rate=NaN
--- PASS: TestBurnRate (0.00s)
=== RUN   TestBurnMultiWindow
    budget_test.go:62: during long=25.00x short=200.00x firing=true
    budget_test.go:71: after  long=25.00x short=0.00x firing=false
--- PASS: TestBurnMultiWindow (0.00s)
=== RUN   TestGateDecisions
    budget_test.go:98: healthy verdict=allow reason="remaining 90.0%; burn windows below 1000 events, budget-only"
    budget_test.go:98: budget low verdict=canary-only reason="remaining 20.0% below canary 25.0%"
    budget_test.go:98: budget empty verdict=freeze reason="remaining 2.0% below freeze 5.0%"
    budget_test.go:98: burning fast verdict=freeze reason="burn 20.00x over 14.40x limit"
    budget_test.go:98: no data verdict=hold-no-data reason="only 500 valid events, need 1000"
--- PASS: TestGateDecisions (0.00s)
PASS
ok  	archlab/internal/platform/slo	0.238s

// file: internal/platform/slo/budget_test.go
// tier: L1
// verify: go test ./internal/platform/slo/ -count=1 -run 'TestBudget|TestBurn|TestGate'
package slo

import (
	"math"
	"testing"
	"time"
)

func TestBudgetArithmetic(t *testing.T) {
	cases := []struct {
		name string
		b    Budget
	}{
		{"ten percent left", Budget{Target: 0.999, Total: 1_000_000, Bad: 900}},
		{"overspent", Budget{Target: 0.999, Total: 1_000_000, Bad: 1300}},
		{"fine grained", Budget{Target: 0.9999, Total: 2_000_000, Bad: 50}},
	}
	for _, c := range cases {
		if err := c.b.Validate(); err != nil {
			t.Fatalf("%s: %v", c.name, err)
		}
		t.Logf("%s allowed=%.2f bad=%d remaining=%.2f ratio=%.3f",
			c.name, c.b.Allowed(), c.b.Bad, c.b.Remaining(), c.b.RemainingRatio())
	}
	for _, b := range []Budget{{Target: 1.0, Total: 10}, {Target: 0.999, Total: 10, Bad: 11}} {
		if err := b.Validate(); err == nil {
			t.Fatalf("invalid budget accepted: %+v", b)
		}
	}
}

func TestBurnRate(t *testing.T) {
	samples := []BurnSample{
		{Window: time.Hour, Total: 10000, Bad: 10},
		{Window: 6 * time.Hour, Total: 60000, Bad: 120},
		{Window: time.Hour, Total: 5000, Bad: 0},
		{Window: time.Hour},
	}
	for _, s := range samples {
		rate := s.Rate(0.999)
		if s.Total == 0 && !math.IsNaN(rate) {
			t.Fatalf("empty window rate = %v, want NaN", rate)
		}
		t.Logf("window=%s total=%d bad=%d rate=%.2f", s.Window, s.Total, s.Bad, rate)
	}
}

func TestBurnMultiWindow(t *testing.T) {
	events := sampleEvents()
	policy := BurnPolicy{Long: 24 * time.Hour, Short: time.Hour, LongThreshold: 6, ShortThreshold: 6, MinEvents: 100}

	during, err := EvaluateBurn(events, SLI{Name: "orders-availability"}, t0.Add(71*time.Hour), 0.999, policy)
	if err != nil {
		t.Fatalf("during: %v", err)
	}
	if !during.Data || !during.Firing {
		t.Fatalf("expected a sustained firing burn: %+v", during)
	}
	t.Logf("during long=%.2fx short=%.2fx firing=%v", during.LongRate, during.ShortRate, during.Firing)

	after, err := EvaluateBurn(events, SLI{Name: "orders-availability"}, t0.Add(72*time.Hour), 0.999, policy)
	if err != nil {
		t.Fatalf("after: %v", err)
	}
	if after.Firing {
		t.Fatalf("short window should have stopped firing: %+v", after)
	}
	t.Logf("after  long=%.2fx short=%.2fx firing=%v", after.LongRate, after.ShortRate, after.Firing)
}

func TestGateDecisions(t *testing.T) {
	policy := GatePolicy{FreezeBelow: 0.05, CanaryBelow: 0.25, MaxBurnRate: 14.4, MinEvents: 1000}
	healthy := BurnResult{}
	hot := BurnResult{Data: true, Firing: true, LongRate: 20, ShortRate: 60}
	cases := []struct {
		name string
		b    Budget
		burn BurnResult
		want Verdict
	}{
		{"healthy", Budget{Target: 0.999, Total: 1_000_000, Bad: 100}, healthy, VerdictAllow},
		{"budget low", Budget{Target: 0.999, Total: 1_000_000, Bad: 800}, healthy, VerdictCanary},
		{"budget empty", Budget{Target: 0.999, Total: 1_000_000, Bad: 980}, healthy, VerdictFreeze},
		{"burning fast", Budget{Target: 0.999, Total: 1_000_000, Bad: 500}, hot, VerdictFreeze},
		{"no data", Budget{Target: 0.999, Total: 500}, healthy, VerdictHold},
	}
	for _, c := range cases {
		got, reason, err := policy.Decide(c.b, c.burn)
		if err != nil {
			t.Fatalf("%s: %v", c.name, err)
		}
		if got != c.want {
			t.Fatalf("%s: got %s want %s (%s)", c.name, got, c.want, reason)
		}
		t.Logf("%s verdict=%s reason=%q", c.name, got, reason)
	}
	if _, _, err := (GatePolicy{FreezeBelow: 0.3, CanaryBelow: 0.2, MaxBurnRate: 1}).Decide(cases[0].b, healthy); err == nil {
		t.Fatal("inverted thresholds accepted")
	}
}