《游戏服务端架构·核心系统与契约》12.3 平台 SLA 与产品团队的契约

// file: internal/platformsla/evaluate.go
// tier: L1
// verify: go test ./internal/platformsla/
package platformsla

import (
	"fmt"
	"time"
)

// EvaluateAt filters samples to the window ending at now, then computes the
// achieved level and the remaining error budget. The cutoff is exclusive and
// now itself is included, so a caller can evaluate a closed interval.
func EvaluateAt(s SLA, samples []Sample, now time.Time) (Report, error) {
	if err := s.Validate(); err != nil {
		return Report{}, err
	}
	min := s.MinSamples
	if min <= 0 {
		min = 1
	}
	cutoff := now.Add(-s.Window)
	in := make([]Sample, 0, len(samples))
	for _, sample := range samples {
		if sample.At.After(cutoff) && !sample.At.After(now) {
			in = append(in, sample)
		}
	}
	if len(in) < min {
		return Report{}, fmt.Errorf("%w: %d samples, need %d", ErrInsufficientData, len(in), min)
	}

	report := Report{Capability: s.Capability, Budget: 1 - s.Target}
	switch s.Objective {
	case Availability:
		report.Total = len(in)
		for _, sample := range in {
			if !sample.Success {
				report.Failures++
			}
		}
	case Latency:
		for _, sample := range in {
			if !sample.Success {
				continue
			}
			report.Total++
			if sample.Latency > s.Threshold {
				report.Failures++
			}
		}
		if report.Total < min {
			return Report{}, fmt.Errorf("%w: %d successful samples, need %d", ErrInsufficientData, report.Total, min)
		}
	}

	report.Achieved = float64(report.Total-report.Failures) / float64(report.Total)
	report.Burned = 1 - report.Achieved
	report.Remaining = report.Budget - report.Burned
	report.BurnRate = report.Burned / report.Budget
	report.Breached = report.Achieved < s.Target
	return report, nil
}

// file: internal/platformsla/budget_test.go
// tier: L1
package platformsla

import (
	"errors"
	"testing"
	"time"
)

func TestErrorBudgetMath(t *testing.T) {
	sla := SLA{Capability: "payment", Objective: Availability, Target: 0.99, Window: 5 * time.Minute}
	tests := []struct {
		name          string
		failures      int
		wantRemaining float64
		wantBurnRate  float64
		wantBreached  bool
	}{
		{"half of budget", 5, 0.005, 0.5, false},
		{"budget exhausted", 10, 0, 1, false},
		{"budget overspent", 20, -0.01, 2, true},
	}
	for _, tc := range tests {
		t.Run(tc.name, func(t *testing.T) {
			report, err := EvaluateAt(sla, availabilitySamples(1000, tc.failures), evalNow)
			if err != nil {
				t.Fatalf("EvaluateAt: %v", err)
			}
			if !closeTo(report.Remaining, tc.wantRemaining) {
				t.Fatalf("Remaining = %v, want %v", report.Remaining, tc.wantRemaining)
			}
			if !closeTo(report.BurnRate, tc.wantBurnRate) {
				t.Fatalf("BurnRate = %v, want %v", report.BurnRate, tc.wantBurnRate)
			}
			if report.Breached != tc.wantBreached {
				t.Fatalf("Breached = %v, want %v", report.Breached, tc.wantBreached)
			}
		})
	}
}

func TestLatencyExcludesFailures(t *testing.T) {
	sla := SLA{
		Capability: "matchmaking",
		Objective:  Latency,
		Target:     0.99,
		Threshold:  200 * time.Millisecond,
		Window:     5 * time.Minute,
		MinSamples: 100,
	}
	samples := append(latencySamples(990, 10, 250*time.Millisecond), availabilitySamples(500, 500)...)
	report, err := EvaluateAt(sla, samples, evalNow)
	if err != nil {
		t.Fatalf("EvaluateAt: %v", err)
	}
	if report.Total != 1000 || report.Failures != 10 || !closeTo(report.Achieved, 0.99) {
		t.Fatalf("report = %+v, want 990 of 1000 successful calls under threshold", report)
	}
}

func TestWindowCutoff(t *testing.T) {
	sla := SLA{Capability: "data", Objective: Availability, Target: 0.99, Window: 5 * time.Minute, MinSamples: 1}
	tests := []struct {
		name      string
		at        time.Time
		wantTotal int
	}{
		{"inside window", evalNow.Add(-time.Minute), 1},
		{"before cutoff", evalNow.Add(-10 * time.Minute), 0},
	}
	for _, tc := range tests {
		t.Run(tc.name, func(t *testing.T) {
			report, err := EvaluateAt(sla, []Sample{{At: tc.at, Success: true}}, evalNow)
			if tc.wantTotal == 0 {
				if !errors.Is(err, ErrInsufficientData) {
					t.Fatalf("EvaluateAt() error = %v, want ErrInsufficientData", err)
				}
				return
			}
			if err != nil || report.Total != tc.wantTotal {
				t.Fatalf("report = %+v, err = %v", report, err)
			}
		})
	}
}

$ cd .local/checks/gsarch-lab
$ gofmt -l internal/platformsla
$ go vet ./internal/platformsla/...
$ go test -count=1 ./internal/platformsla/...
ok  	gsarchlab/internal/platformsla