《游戏服务端架构·规模化、全球化与成本》2.2 暖池、冷启动与扩容速度

Reconcile 创建 → warming --Warmup 到期--> ready --Acquire--> leased
                                            ▲                  │
                                            └── Release(健康) ─┤
                                                               └── 超时/崩溃 → dead

// file: internal/warmpool/pool.go
// tier: L1
// verify: go test ./internal/warmpool/

package warmpool

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

var (
	ErrInvalidConfig = errors.New("warmpool: min/max or water levels are invalid")
	ErrUnknownKey    = errors.New("warmpool: key is not registered")
	ErrNoReady       = errors.New("warmpool: no ready instance")
	ErrUnknownSlot   = errors.New("warmpool: unknown slot")
	ErrNotLeased     = errors.New("warmpool: slot is not leased")
)

type Key struct {
	Region   string
	Version  string
	RoomType string
}

type State string

const (
	Warming State = "warming"
	Ready   State = "ready"
	Leased  State = "leased"
	Dead    State = "dead" // crashed or timed out; never reused
)

type Config struct {
	Min       int
	Max       int
	Warmup    time.Duration
	LeaseTTL  time.Duration
	HighWater int
	LowWater  int
}

type Slot struct {
	ID        string
	Key       Key
	State     State
	ReadyAt   time.Time
	LeaseID   string
	ExpiresAt time.Time
}

type Lease struct {
	ID        string
	SlotID    string
	Key       Key
	ExpiresAt time.Time
}

type Stats struct {
	Target  int
	Warming int
	Ready   int
	Leased  int
	Dead    int
}

type Pool struct {
	mu     sync.Mutex
	now    func() time.Time
	cfg    map[Key]Config
	target map[Key]int
	slots  map[string]*Slot
	seq    int
}

func New(now func() time.Time) *Pool {
	if now == nil {
		now = time.Now
	}
	return &Pool{
		now:    now,
		cfg:    map[Key]Config{},
		target: map[Key]int{},
		slots:  map[string]*Slot{},
	}
}

func (p *Pool) Register(k Key, c Config) error {
	if k.Region == "" || k.Version == "" || k.RoomType == "" ||
		c.Min < 0 || c.Max < c.Min || c.Warmup <= 0 || c.LeaseTTL <= 0 ||
		c.HighWater <= c.LowWater {
		return ErrInvalidConfig
	}
	p.mu.Lock()
	defer p.mu.Unlock()
	p.cfg[k] = c
	p.target[k] = c.Min
	return nil
}

func (p *Pool) SetTarget(k Key, n int) error {
	p.mu.Lock()
	defer p.mu.Unlock()
	c, ok := p.cfg[k]
	if !ok {
		return ErrUnknownKey
	}
	p.target[k] = clamp(n, c.Min, c.Max)
	return nil
}

func (p *Pool) promoteLocked(k Key, now time.Time) {
	for _, s := range p.slots {
		if s.Key == k && s.State == Warming && !now.Before(s.ReadyAt) {
			s.State = Ready
		}
	}
}

// Reconcile promotes warming slots, fills up to the target and removes excess
// warm capacity. It never touches a leased slot.
func (p *Pool) Reconcile(k Key) (created, killed int) {
	p.mu.Lock()
	defer p.mu.Unlock()
	if _, ok := p.cfg[k]; !ok {
		return 0, 0
	}
	for id, s := range p.slots {
		if s.State == Dead {
			delete(p.slots, id)
		}
	}
	now := p.now()
	p.reclaimLocked(now)
	p.promoteLocked(k, now)

	target := p.target[k]
	alive := p.countAliveLocked(k)
	for alive < target {
		p.seq++
		id := fmt.Sprintf("warm-%s-%04d", k.Region, p.seq)
		p.slots[id] = &Slot{ID: id, Key: k, State: Warming, ReadyAt: now.Add(p.cfg[k].Warmup)}
		alive++
		created++
	}
	for alive > target {
		id := p.killCandidateLocked(k)
		if id == "" {
			break
		}
		delete(p.slots, id)
		alive--
		killed++
	}
	return created, killed
}

func (p *Pool) countAliveLocked(k Key) int {
	n := 0
	for _, s := range p.slots {
		if s.Key == k && s.State != Dead {
			n++
		}
	}
	return n
}

func (p *Pool) killCandidateLocked(k Key) string {
	var ready, warming []string
	for id, s := range p.slots {
		if s.Key != k {
			continue
		}
		switch s.State {
		case Ready:
			ready = append(ready, id)
		case Warming:
			warming = append(warming, id)
		}
	}
	sort.Strings(ready)
	sort.Strings(warming)
	if len(ready) > 0 {
		return ready[len(ready)-1] // newest ready first, keep the long-warmed
	}
	if len(warming) > 0 {
		return warming[len(warming)-1]
	}
	return ""
}

// Acquire leases one ready instance; an empty pool means "queue the player".
func (p *Pool) Acquire(k Key, holder string) (Lease, error) {
	p.mu.Lock()
	defer p.mu.Unlock()
	if _, ok := p.cfg[k]; !ok {
		return Lease{}, ErrUnknownKey
	}
	now := p.now()
	p.reclaimLocked(now)
	p.promoteLocked(k, now)

	var pick *Slot
	for _, s := range p.slots {
		if s.Key != k || s.State != Ready {
			continue
		}
		if pick == nil || s.ReadyAt.Before(pick.ReadyAt) ||
			(s.ReadyAt.Equal(pick.ReadyAt) && s.ID < pick.ID) {
			pick = s
		}
	}
	if pick == nil {
		return Lease{}, ErrNoReady
	}
	p.seq++
	lease := Lease{
		ID:        fmt.Sprintf("lease-%04d", p.seq),
		SlotID:    pick.ID,
		Key:       k,
		ExpiresAt: now.Add(p.cfg[k].LeaseTTL),
	}
	pick.State = Leased
	pick.LeaseID = lease.ID
	pick.ExpiresAt = lease.ExpiresAt
	return lease, nil
}

// Release returns a healthy slot to ready; an unhealthy one becomes dead.
func (p *Pool) Release(slotID string, healthy bool) error {
	p.mu.Lock()
	defer p.mu.Unlock()
	s, ok := p.slots[slotID]
	if !ok {
		return ErrUnknownSlot
	}
	if s.State != Leased {
		return ErrNotLeased
	}
	s.LeaseID = ""
	s.ExpiresAt = time.Time{}
	if healthy {
		s.State = Ready
	} else {
		s.State = Dead
	}
	return nil
}

// ReclaimExpired marks timed-out leases dead; the room is fenced by epoch.
func (p *Pool) ReclaimExpired() []Lease {
	p.mu.Lock()
	defer p.mu.Unlock()
	return p.reclaimLocked(p.now())
}

func (p *Pool) reclaimLocked(now time.Time) []Lease {
	var out []Lease
	for _, s := range p.slots {
		if s.State != Leased || now.Before(s.ExpiresAt) {
			continue
		}
		out = append(out, Lease{ID: s.LeaseID, SlotID: s.ID, Key: s.Key, ExpiresAt: s.ExpiresAt})
		s.State = Dead
		s.LeaseID = ""
		s.ExpiresAt = time.Time{}
	}
	sort.Slice(out, func(i, j int) bool { return out[i].SlotID < out[j].SlotID })
	return out
}

func (p *Pool) Stats(k Key) Stats {
	p.mu.Lock()
	defer p.mu.Unlock()
	st := Stats{Target: p.target[k]}
	for _, s := range p.slots {
		if s.Key != k {
			continue
		}
		switch s.State {
		case Warming:
			st.Warming++
		case Ready:
			st.Ready++
		case Leased:
			st.Leased++
		case Dead:
			st.Dead++
		}
	}
	return st
}