《游戏服务端架构·规模化、全球化与成本》2.3 缩容、排空与成本

active --StartDrain--> draining --最后一个房间结束--> drained --> removed
                          └── 截止时间到达且仍有房间 --> forced --> removed

月成本 = 预留节点数 × 预留单价 + 按需节点数 × 使用小时 × 按需单价

// file: internal/scalein/drain.go
// tier: L1
// verify: go test ./internal/scalein/

package scalein

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

var (
	ErrUnknownNode       = errors.New("scalein: unknown node")
	ErrInvalidNode       = errors.New("scalein: invalid node")
	ErrInvalidKind       = errors.New("scalein: node kind cannot be drained")
	ErrInvalidTransition = errors.New("scalein: invalid phase transition")
)

type Kind string

const (
	Match Kind = "match" // holds running matches; drain waits for settlement
	Lobby Kind = "lobby" // stateless or short-lived; quick drain
	World Kind = "world" // long-lived state; never scale in without migration
)

type Phase string

const (
	Active   Phase = "active"
	Draining Phase = "draining"
	Drained  Phase = "drained"
	Forced   Phase = "forced" // deadline hit while rooms were still running
	Removed  Phase = "removed"
)

// Grace returns how long a node of this kind may wait for its rooms to end.
// A world node has no safe grace: scaling it in requires a migration plan,
// which is a separate operation from draining a match host.
func Grace(k Kind) (time.Duration, bool) {
	switch k {
	case Match:
		return 10 * time.Minute, true
	case Lobby:
		return time.Minute, true
	default:
		return 0, false
	}
}

type Node struct {
	ID         string
	Kind       Kind
	Phase      Phase
	Rooms      int
	DrainStart time.Time
	Deadline   time.Time
	Forced     int // rooms terminated by the deadline, not by settlement
}

type Event struct {
	NodeID string
	Phase  Phase
	Rooms  int
}

type Manager struct {
	now   func() time.Time
	nodes map[string]*Node
}

func New(now func() time.Time) *Manager {
	if now == nil {
		now = time.Now
	}
	return &Manager{now: now, nodes: map[string]*Node{}}
}

func (m *Manager) Add(n Node) error {
	if n.ID == "" || n.Rooms < 0 {
		return ErrInvalidNode
	}
	if _, ok := Grace(n.Kind); !ok && n.Kind != World {
		return ErrInvalidNode
	}
	if _, exists := m.nodes[n.ID]; exists {
		return fmt.Errorf("%w: %s", ErrInvalidNode, n.ID)
	}
	n.Phase = Active
	m.nodes[n.ID] = &n
	return nil
}

func (m *Manager) Node(id string) (Node, bool) {
	n, ok := m.nodes[id]
	if !ok {
		return Node{}, false
	}
	return *n, true
}

// StartDrain stops accepting new rooms and starts the grace timer. A match
// node keeps serving its current matches; the caller removes it from match
// making first, which is why this method does not touch the room count.
func (m *Manager) StartDrain(id string) (Node, error) {
	n, ok := m.nodes[id]
	if !ok {
		return Node{}, ErrUnknownNode
	}
	if n.Phase != Active {
		return Node{}, ErrInvalidTransition
	}
	grace, ok := Grace(n.Kind)
	if !ok {
		return Node{}, ErrInvalidKind
	}
	n.Phase = Draining
	n.DrainStart = m.now()
	n.Deadline = n.DrainStart.Add(grace)
	if n.Rooms == 0 {
		n.Phase = Drained
	}
	return *n, nil
}

// FinishRoom records one room ending normally. When the last room ends before
// the deadline the node becomes drained and can be removed in this release.
func (m *Manager) FinishRoom(id string) (Node, error) {
	n, ok := m.nodes[id]
	if !ok {
		return Node{}, ErrUnknownNode
	}
	if n.Phase != Draining {
		return Node{}, ErrInvalidTransition
	}
	if n.Rooms > 0 {
		n.Rooms--
	}
	if n.Rooms == 0 {
		n.Phase = Drained
	}
	return *n, nil
}

// Tick forces every draining node whose deadline has passed. Forcing evicts
// the remaining rooms, so it is recorded separately for player-impact review.
func (m *Manager) Tick() []Event {
	now := m.now()
	var out []Event
	for _, n := range m.nodes {
		if n.Phase != Draining || now.Before(n.Deadline) {
			continue
		}
		if n.Rooms == 0 {
			n.Phase = Drained
			out = append(out, Event{NodeID: n.ID, Phase: Drained})
			continue
		}
		n.Forced += n.Rooms
		out = append(out, Event{NodeID: n.ID, Phase: Forced, Rooms: n.Rooms})
		n.Rooms = 0
		n.Phase = Forced
	}
	sort.Slice(out, func(i, j int) bool { return out[i].NodeID < out[j].NodeID })
	return out
}

func (m *Manager) Remove(id string) error {
	n, ok := m.nodes[id]
	if !ok {
		return ErrUnknownNode
	}
	if n.Phase != Drained && n.Phase != Forced {
		return ErrInvalidTransition
	}
	if n.Rooms != 0 {
		return ErrInvalidTransition
	}
	n.Phase = Removed
	return nil
}

// Reclaimable lists nodes that can be drained in this cycle. Idle match hosts
// come first, then idle lobby hosts; world hosts are never candidates.
func (m *Manager) Reclaimable() []string {
	type cand struct {
		id   string
		rank int
	}
	var list []cand
	for _, n := range m.nodes {
		if n.Phase != Active || n.Rooms != 0 {
			continue
		}
		switch n.Kind {
		case Match:
			list = append(list, cand{n.ID, 0})
		case Lobby:
			list = append(list, cand{n.ID, 1})
		}
	}
	sort.Slice(list, func(i, j int) bool {
		if list[i].rank != list[j].rank {
			return list[i].rank < list[j].rank
		}
		return list[i].id < list[j].id
	})
	out := make([]string, len(list))
	for i, c := range list {
		out[i] = c.id
	}
	return out
}

type Policy struct {
	Threshold float64       // below this utilization a node is a candidate
	Sustain   time.Duration // how long it must stay low
	Cooldown  time.Duration // minimum gap between two scale-in actions
	MinNodes  int           // reserved floor for sudden peaks
}

type Decision struct {
	ScaleIn bool
	Reason  string
}

type Decider struct {
	policy   Policy
	low      bool
	lowSince time.Time
	last     time.Time
}

func NewDecider(p Policy) *Decider {
	return &Decider{policy: p}
}

// Observe answers "may we remove one node now". The sustain window and the
// cooldown are both hysteresis: either alone still allows flapping when the
// utilization signal oscillates around the threshold.
func (d *Decider) Observe(at time.Time, util float64, nodes int) Decision {
	if nodes <= d.policy.MinNodes {
		d.low = false
		return Decision{Reason: "floor"}
	}
	if util > d.policy.Threshold {
		d.low = false
		return Decision{Reason: "busy"}
	}
	if !d.low {
		d.low = true
		d.lowSince = at
		return Decision{Reason: "sustain"}
	}
	if at.Sub(d.lowSince) < d.policy.Sustain {
		return Decision{Reason: "sustain"}
	}
	if !d.last.IsZero() && at.Sub(d.last) < d.policy.Cooldown {
		return Decision{Reason: "cooldown"}
	}
	d.last = at
	d.low = false
	return Decision{ScaleIn: true, Reason: "scale-in"}
}

// Price separates the reserved baseline from burst capacity. Reserved nodes
// are paid monthly even when idle; on-demand nodes are paid per hour.
type Price struct {
	ReservedPerNodeMonth float64
	OnDemandPerNodeHour  float64
	ReservedNodes        int
}

func MonthlyCost(nodes int, hours float64, p Price) float64 {
	if nodes <= 0 {
		return 0
	}
	reserved := nodes
	if reserved > p.ReservedNodes {
		reserved = p.ReservedNodes
	}
	if reserved < 0 {
		reserved = 0
	}
	onDemand := nodes - reserved
	return float64(reserved)*p.ReservedPerNodeMonth + float64(onDemand)*hours*p.OnDemandPerNodeHour
}