《游戏服务端架构·平台化与架构治理》1.3 平台服务的版本与兼容

// file: internal/platformversion/compatibility.go
// tier: L1
// verify: go test ./internal/platformversion/
package platformversion

import (
	"fmt"
	"hash/fnv"
	"time"
)

// Matrix is the compatibility contract for one capability. MinClient and
// MaxClient are inclusive. DeprecatedAt starts upgrade warnings; SunsetAt
// stops serving the recorded client range entirely.
type Matrix struct {
	Capability   string
	MinClient    Version
	MaxClient    Version
	DeprecatedAt time.Time
	SunsetAt     time.Time
}

func (m Matrix) Validate() error {
	if m.Capability == "" {
		return fmt.Errorf("%w: capability is empty", ErrMatrix)
	}
	if m.MinClient.Compare(m.MaxClient) > 0 {
		return fmt.Errorf("%w: min %s is above max %s", ErrMatrix, m.MinClient, m.MaxClient)
	}
	if !m.DeprecatedAt.IsZero() && !m.SunsetAt.IsZero() && !m.SunsetAt.After(m.DeprecatedAt) {
		return fmt.Errorf("%w: sunset must follow deprecation", ErrMatrix)
	}
	return nil
}

// Evaluate checks sunset before version bounds. A client on a sunset
// capability is blocked even if its version is inside the recorded range;
// otherwise a stale matrix row would keep a retired feature alive.
func (m Matrix) Evaluate(client Version, at time.Time) Decision {
	if !m.SunsetAt.IsZero() && !at.Before(m.SunsetAt) {
		return Decision{Verdict: Blocked, Reason: "capability sunset"}
	}
	if client.Compare(m.MinClient) < 0 {
		return Decision{Verdict: Blocked, Reason: "client is older than the minimum supported version"}
	}
	if client.Compare(m.MaxClient) > 0 {
		return Decision{Verdict: Blocked, Reason: "client is newer than the supported maximum"}
	}
	if !m.DeprecatedAt.IsZero() && !at.Before(m.DeprecatedAt) {
		return Decision{Verdict: Warned, Reason: "capability is deprecated; upgrade before sunset"}
	}
	return Decision{Verdict: Allowed}
}

// Phase is the timeline phase at a point in time.
type Phase string

const (
	PhaseActive     Phase = "active"
	PhaseAnnounced  Phase = "announced"
	PhaseDeprecated Phase = "deprecated"
	PhaseSunset     Phase = "sunset"
)

// Timeline is the published deprecation schedule. It is separate from Matrix:
// the matrix says who may call today, the timeline says what changes and when.
type Timeline struct {
	Capability   string
	AnnouncedAt  time.Time
	DeprecatedAt time.Time
	SunsetAt     time.Time
}

type TimelinePolicy struct {
	MinNotice  time.Duration
	MinSupport time.Duration
}

func DefaultTimelinePolicy() TimelinePolicy {
	return TimelinePolicy{MinNotice: 30 * 24 * time.Hour, MinSupport: 90 * 24 * time.Hour}
}

func (t Timeline) Validate(p TimelinePolicy) error {
	if t.Capability == "" {
		return fmt.Errorf("%w: capability is empty", ErrTimeline)
	}
	if t.AnnouncedAt.IsZero() || t.DeprecatedAt.IsZero() || t.SunsetAt.IsZero() {
		return fmt.Errorf("%w: all three timestamps are required", ErrTimeline)
	}
	if !t.DeprecatedAt.After(t.AnnouncedAt) {
		return fmt.Errorf("%w: deprecation must follow announcement", ErrTimeline)
	}
	if !t.SunsetAt.After(t.DeprecatedAt) {
		return fmt.Errorf("%w: sunset must follow deprecation", ErrTimeline)
	}
	if t.DeprecatedAt.Sub(t.AnnouncedAt) < p.MinNotice {
		return fmt.Errorf("%w: %s < %s", ErrNotice, t.DeprecatedAt.Sub(t.AnnouncedAt), p.MinNotice)
	}
	if t.SunsetAt.Sub(t.DeprecatedAt) < p.MinSupport {
		return fmt.Errorf("%w: %s < %s", ErrSupport, t.SunsetAt.Sub(t.DeprecatedAt), p.MinSupport)
	}
	return nil
}

func (t Timeline) Phase(at time.Time) Phase {
	switch {
	case !at.Before(t.SunsetAt):
		return PhaseSunset
	case !at.Before(t.DeprecatedAt):
		return PhaseDeprecated
	case !at.Before(t.AnnouncedAt):
		return PhaseAnnounced
	default:
		return PhaseActive
	}
}

func (t Timeline) DaysUntilSunset(at time.Time) int {
	if !at.Before(t.SunsetAt) {
		return 0
	}
	return int(t.SunsetAt.Sub(at).Hours() / 24)
}

// Rollout is tenant-level exposure for a new capability version. Percent is a
// stable hash bucket; Allow names tenants included regardless of the bucket,
// which is how an internal test guild gets a build early.
type Rollout struct {
	Percent int
	Allow   []string
}

func (r Rollout) Validate() error {
	if r.Percent < 0 || r.Percent > 100 {
		return fmt.Errorf("%w: %d", ErrPercent, r.Percent)
	}
	return nil
}

func (r Rollout) Includes(tenant string) bool {
	if tenant == "" {
		return false
	}
	for _, allowed := range r.Allow {
		if allowed == tenant {
			return true
		}
	}
	if r.Percent >= 100 {
		return true
	}
	if r.Percent <= 0 {
		return false
	}
	h := fnv.New32a()
	_, _ = h.Write([]byte(tenant))
	return int(h.Sum32()%100) < r.Percent
}