《游戏服务端架构·平台化与架构治理》10.1 绞杀者与增量迁移

// file: internal/stranglermigration/stranglermigration.go
// tier: L1
// verify: go test ./internal/stranglermigration/
package stranglermigration

import (
	"errors"
	"fmt"
	"hash/fnv"
	"sort"
	"strings"
)

// Stage is the lifecycle position of one migration unit.
type Stage string

const (
	// StageShadowRead mirrors writes and reads only from the old path.
	StageShadowRead Stage = "shadow_read"
	// StageDualWrite writes both paths; reads still come from the old path.
	StageDualWrite Stage = "dual_write"
	// StageCutoverRead sends an increasing share of reads to the new path.
	StageCutoverRead Stage = "cutover_read"
	// StageRetired means the old path carries no traffic and can be removed.
	StageRetired Stage = "retired"
)

var (
	ErrUnknownStage      = errors.New("stranglermigration: unknown stage")
	ErrIllegalTransition = errors.New("stranglermigration: illegal stage transition")
	ErrBadBuckets        = errors.New("stranglermigration: buckets must be positive")
	ErrBadRatio          = errors.New("stranglermigration: ratio must be within 0..100")
	ErrRetireBlocked     = errors.New("stranglermigration: retirement blocked")
)

var stageOrder = []Stage{StageShadowRead, StageDualWrite, StageCutoverRead, StageRetired}

func stageIndex(s Stage) (int, bool) {
	for i, cur := range stageOrder {
		if cur == s {
			return i, true
		}
	}
	return 0, false
}

// NextStage returns the forward transition. Retirement has no successor.
func NextStage(s Stage) (Stage, bool) {
	i, ok := stageIndex(s)
	if !ok || i+1 >= len(stageOrder) {
		return "", false
	}
	return stageOrder[i+1], true
}

// ValidateTransition accepts only a single forward step. Skipping a stage
// hides a failed verification, so it is rejected even when the operator is in a
// hurry.
func ValidateTransition(from, to Stage) error {
	fi, okFrom := stageIndex(from)
	ti, okTo := stageIndex(to)
	if !okFrom || !okTo {
		return ErrUnknownStage
	}
	if fi+1 != ti {
		return fmt.Errorf("%w: %s -> %s", ErrIllegalTransition, from, to)
	}
	return nil
}

// ValidateRollback accepts a single step back, except from retired. Once the
// old code is deleted a rollback is a new migration, not a state transition.
func ValidateRollback(from, to Stage) error {
	fi, okFrom := stageIndex(from)
	ti, okTo := stageIndex(to)
	if !okFrom || !okTo {
		return ErrUnknownStage
	}
	if from == StageRetired {
		return fmt.Errorf("%w: retired is terminal", ErrIllegalTransition)
	}
	if ti+1 != fi {
		return fmt.Errorf("%w: rollback %s -> %s", ErrIllegalTransition, from, to)
	}
	return nil
}

// Target names the read path chosen for one key.
type Target string

const (
	TargetOld Target = "old"
	TargetNew Target = "new"
)

// Bucket maps a key to a stable bucket. Callers must keep the bucket count
// fixed for the whole migration: changing it re-shuffles every key and turns a
// canary into a second migration.
func Bucket(key string, buckets int) (int, error) {
	if buckets <= 0 {
		return 0, ErrBadBuckets
	}
	h := fnv.New32a()
	if _, err := h.Write([]byte(key)); err != nil {
		return 0, err
	}
	return int(h.Sum32() % uint32(buckets)), nil
}

// Route picks the read path for a key at the given new-path percentage.
// Percentages are bucket counts, not wall-clock promises.
func Route(key string, newReadPercent int) (Target, error) {
	if newReadPercent < 0 || newReadPercent > 100 {
		return "", ErrBadRatio
	}
	b, err := Bucket(key, 100)
	if err != nil {
		return "", err
	}
	if b < newReadPercent {
		return TargetNew, nil
	}
	return TargetOld, nil
}

// ValidateSplit makes the old/new read shares explicit and total 100.
func ValidateSplit(oldPercent, newPercent int) error {
	if oldPercent < 0 || newPercent < 0 || oldPercent > 100 || newPercent > 100 {
		return ErrBadRatio
	}
	if oldPercent+newPercent != 100 {
		return fmt.Errorf("%w: old=%d new=%d", ErrBadRatio, oldPercent, newPercent)
	}
	return nil
}

// Mismatch records one key whose two copies disagree.
type Mismatch struct {
	Key      string
	OldValue string
	NewValue string
}

// Report is the result of one reconciliation pass. Slices are sorted so two
// runs over the same state produce the same report.
type Report struct {
	MissingInNew []string
	ExtraInNew   []string
	Mismatched   []Mismatch
}

func (r Report) Equal() bool {
	return len(r.MissingInNew) == 0 && len(r.ExtraInNew) == 0 && len(r.Mismatched) == 0
}

func (r Report) Summary() string {
	return fmt.Sprintf("missing=%d extra=%d mismatched=%d",
		len(r.MissingInNew), len(r.ExtraInNew), len(r.Mismatched))
}

// Reconcile compares value snapshots taken at the same logical point. It says
// nothing about writes that land after the snapshot; the dual-write log has to
// cover that gap.
func Reconcile(oldState, newState map[string]string) Report {
	var report Report
	oldKeys := make([]string, 0, len(oldState))
	for k := range oldState {
		oldKeys = append(oldKeys, k)
	}
	sort.Strings(oldKeys)
	for _, k := range oldKeys {
		nv, ok := newState[k]
		switch {
		case !ok:
			report.MissingInNew = append(report.MissingInNew, k)
		case nv != oldState[k]:
			report.Mismatched = append(report.Mismatched, Mismatch{Key: k, OldValue: oldState[k], NewValue: nv})
		}
	}
	newKeys := make([]string, 0, len(newState))
	for k := range newState {
		newKeys = append(newKeys, k)
	}
	sort.Strings(newKeys)
	for _, k := range newKeys {
		if _, ok := oldState[k]; !ok {
			report.ExtraInNew = append(report.ExtraInNew, k)
		}
	}
	return report
}

// RetireCheck is the evidence required before deleting the old path.
type RetireCheck struct {
	OldReadPercent   int
	DualWriteStopped bool
	ReconcileEqual   bool
	RollbackClosed   bool
}

// CanRetire lists every unmet condition instead of failing on the first one.
func CanRetire(c RetireCheck) error {
	var problems []string
	if c.OldReadPercent != 0 {
		problems = append(problems, fmt.Sprintf("old path still reads %d%%", c.OldReadPercent))
	}
	if !c.DualWriteStopped {
		problems = append(problems, "dual write still active")
	}
	if !c.ReconcileEqual {
		problems = append(problems, "reconciliation not equal")
	}
	if !c.RollbackClosed {
		problems = append(problems, "rollback window still open")
	}
	if len(problems) > 0 {
		return fmt.Errorf("%w: %s", ErrRetireBlocked, strings.Join(problems, "; "))
	}
	return nil
}