《游戏服务端架构·平台化与架构治理》1.1 平台团队与产品团队的契约

30 天 × (1 - 99.9%) = 43 分 12 秒

// file: internal/platformcontract/contract.go
// tier: L1
// verify: go test ./internal/platformcontract/
package platformcontract

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

var (
	ErrName      = errors.New("platformcontract: capability name is empty")
	ErrOwner     = errors.New("platformcontract: owner is empty")
	ErrConsumers = errors.New("platformcontract: consumers are empty")
	ErrContact   = errors.New("platformcontract: primary and escalation contacts are required")
	ErrSLA       = errors.New("platformcontract: invalid sla")
	ErrQuota     = errors.New("platformcontract: invalid quota")
	ErrBilling   = errors.New("platformcontract: invalid billing mode")
	ErrNotice    = errors.New("platformcontract: notice is shorter than policy")
	ErrExit      = errors.New("platformcontract: incomplete exit plan")
	ErrFreeze    = errors.New("platformcontract: change falls in a freeze window")
	ErrDuplicate = errors.New("platformcontract: duplicate capability")
)

// SLA is a promise with a measurement window. Availability must stay below 1:
// a target of exactly 1 leaves no error budget and cannot be measured.
type SLA struct {
	Availability float64
	LatencyP99   time.Duration
	Window       time.Duration
}

func (s SLA) Validate() error {
	if s.Availability <= 0 || s.Availability >= 1 {
		return fmt.Errorf("%w: availability %v must be in (0,1)", ErrSLA, s.Availability)
	}
	if s.LatencyP99 <= 0 || s.Window <= 0 {
		return fmt.Errorf("%w: latency and window must be positive", ErrSLA)
	}
	return nil
}

// ErrorBudget turns the target into allowed downtime inside the window.
func (s SLA) ErrorBudget() time.Duration {
	if s.Validate() != nil {
		return 0
	}
	return time.Duration(float64(s.Window) * (1 - s.Availability))
}

// Quota is a per-consumer ceiling. A burst below the steady rate would make
// the quota impossible to honor, so it is rejected instead of auto-raised.
type Quota struct {
	RequestsPerSecond int
	Burst             int
	DailyOps          int
}

func (q Quota) Validate() error {
	if q.RequestsPerSecond <= 0 || q.DailyOps <= 0 {
		return fmt.Errorf("%w: rate and daily operations must be positive", ErrQuota)
	}
	if q.Burst < q.RequestsPerSecond {
		return fmt.Errorf("%w: burst %d is below rate %d", ErrQuota, q.Burst, q.RequestsPerSecond)
	}
	return nil
}

const (
	BillingFree         = "free"
	BillingMetered      = "metered"
	BillingSeat         = "seat"
	BillingRevenueShare = "revenue_share"
)

// Billing records the unit the platform will invoice. A metered capability
// without a unit is not a price, it is a future argument.
type Billing struct {
	Mode      string
	Unit      string
	UnitPrice float64
}

func (b Billing) Validate() error {
	switch b.Mode {
	case BillingFree:
		if b.UnitPrice != 0 {
			return fmt.Errorf("%w: free capability must have zero price", ErrBilling)
		}
	case BillingMetered, BillingSeat, BillingRevenueShare:
		if b.Unit == "" || b.UnitPrice < 0 {
			return fmt.Errorf("%w: %s needs a unit and a non-negative price", ErrBilling, b.Mode)
		}
	default:
		return fmt.Errorf("%w: %q", ErrBilling, b.Mode)
	}
	return nil
}

// Freeze is a recurring weekly window in the deployer's local time. When
// EndMinute is not greater than StartMinute it crosses midnight and starts on
// Weekday.
type Freeze struct {
	Weekday     time.Weekday
	StartMinute int
	EndMinute   int
}

func (f Freeze) validate() error {
	if f.StartMinute < 0 || f.StartMinute >= 24*60 || f.EndMinute < 0 || f.EndMinute > 24*60 {
		return fmt.Errorf("%w: minutes out of range", ErrFreeze)
	}
	if f.StartMinute == f.EndMinute {
		return fmt.Errorf("%w: empty window on %s", ErrFreeze, f.Weekday)
	}
	return nil
}

func (f Freeze) contains(at time.Time) bool {
	minute := at.Hour()*60 + at.Minute()
	if f.StartMinute < f.EndMinute {
		return at.Weekday() == f.Weekday && minute >= f.StartMinute && minute < f.EndMinute
	}
	if at.Weekday() == f.Weekday && minute >= f.StartMinute {
		return true
	}
	next := time.Weekday((int(f.Weekday) + 1) % 7)
	return at.Weekday() == next && minute < f.EndMinute
}

// ChangePolicy decides when a change may land. Notice is counted from the
// announcement, not from the code review.
type ChangePolicy struct {
	Notice  time.Duration
	Freezes []Freeze
}

func (p ChangePolicy) Validate() error {
	if p.Notice <= 0 {
		return fmt.Errorf("%w: change notice must be positive", ErrNotice)
	}
	for _, f := range p.Freezes {
		if err := f.validate(); err != nil {
			return err
		}
	}
	return nil
}

// Allow answers two questions separately: was the change announced early
// enough, and does the deploy time sit outside every freeze window?
func (p ChangePolicy) Allow(announcedAt, deployAt time.Time) error {
	if err := p.Validate(); err != nil {
		return err
	}
	if deployAt.Before(announcedAt) || deployAt.Sub(announcedAt) < p.Notice {
		return fmt.Errorf("%w: need %s, got %s", ErrNotice, p.Notice, deployAt.Sub(announcedAt))
	}
	for _, f := range p.Freezes {
		if f.contains(deployAt) {
			return fmt.Errorf("%w: %s %02d:%02d-%02d:%02d", ErrFreeze,
				f.Weekday, f.StartMinute/60, f.StartMinute%60, f.EndMinute/60, f.EndMinute%60)
		}
	}
	return nil
}

// Contact names humans, not a group alias. An alias with no owner is how a
// page goes unanswered during an incident.
type Contact struct {
	Primary    string
	Escalation string
	Channel    string
}

func (c Contact) Validate() error {
	if c.Primary == "" || c.Escalation == "" {
		return ErrContact
	}
	return nil
}

// Exit is the condition under which a consumer may leave. ExportDays is how
// long data remains retrievable after the capability stops serving.
type Exit struct {
	Notice     time.Duration
	ExportDays int
	Plan       string
}

func (e Exit) Validate(p Policy) error {
	if e.Notice < p.MinExitNotice {
		return fmt.Errorf("%w: exit notice %s is below %s", ErrExit, e.Notice, p.MinExitNotice)
	}
	if e.ExportDays <= 0 || e.Plan == "" {
		return fmt.Errorf("%w: export window and migration plan are required", ErrExit)
	}
	return nil
}

// Capability is one row of the platform catalog. Consumers are the teams that
// may call it; an empty list means nobody has agreed to depend on it yet.
type Capability struct {
	Name      string
	Owner     string
	Consumers []string
	SLA       SLA
	Quota     Quota
	Billing   Billing
	Change    ChangePolicy
	Contact   Contact
	Exit      Exit
}

// Policy holds the organization-wide floors every capability must meet.
type Policy struct {
	MinChangeNotice time.Duration
	MinExitNotice   time.Duration
}

func DefaultPolicy() Policy {
	return Policy{MinChangeNotice: 72 * time.Hour, MinExitNotice: 90 * 24 * time.Hour}
}

func (c Capability) Validate(p Policy) error {
	if c.Name == "" {
		return ErrName
	}
	if c.Owner == "" {
		return ErrOwner
	}
	if len(c.Consumers) == 0 {
		return ErrConsumers
	}
	if err := c.Contact.Validate(); err != nil {
		return err
	}
	if err := c.SLA.Validate(); err != nil {
		return err
	}
	if err := c.Quota.Validate(); err != nil {
		return err
	}
	if err := c.Billing.Validate(); err != nil {
		return err
	}
	if c.Change.Notice < p.MinChangeNotice {
		return fmt.Errorf("%w: change notice %s is below %s", ErrNotice, c.Change.Notice, p.MinChangeNotice)
	}
	if err := c.Change.Validate(); err != nil {
		return err
	}
	return c.Exit.Validate(p)
}