《游戏服务端架构·核心系统与契约》3.2 房间生命周期与幽灵房间

租约表                         房间进程 host-a
  room-042 owner=host-a epoch=7 create_key=match-991
       ▲                                  │
       └────── heartbeat(room, owner, 7) ─┘  每 10 秒
       │
  到期未续约 → 扫描 → 对账 → 回收 → 玩家回大厅

// file: internal/roomlifecycle/lifecycle.go
// tier: L1
// verify: go test ./internal/roomlifecycle/
package roomlifecycle

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

type State string

const (
	Created  State = "CREATED"
	Waiting  State = "WAITING"
	Filling  State = "FILLING"
	Running  State = "RUNNING"
	Settling State = "SETTLING"
	Closed   State = "CLOSED"
)

// allowed is the only place that decides which transitions are legal.
var allowed = map[State][]State{
	Created:  {Waiting, Closed},
	Waiting:  {Filling, Closed},
	Filling:  {Running, Closed},
	Running:  {Settling, Closed},
	Settling: {Closed},
	Closed:   {},
}

func CanTransition(from, to State) bool {
	for _, s := range allowed[from] {
		if s == to {
			return true
		}
	}
	return false
}

var (
	ErrEmptyID       = errors.New("roomlifecycle: empty room id or owner")
	ErrNotFound      = errors.New("roomlifecycle: room not found")
	ErrFence         = errors.New("roomlifecycle: stale owner or epoch")
	ErrIllegal       = errors.New("roomlifecycle: illegal state transition")
	ErrLeaseExpired  = errors.New("roomlifecycle: lease expired")
	ErrSettlePending = errors.New("roomlifecycle: settlement not committed")
	ErrKeyConflict   = errors.New("roomlifecycle: create key already used")
	ErrActive        = errors.New("roomlifecycle: room is still active")
)

type Room struct {
	ID         string
	State      State
	Owner      string
	Epoch      uint64
	LeaseUntil time.Time
	CreateKey  string
	Settled    bool
	UpdatedAt  time.Time
}

type Ghost struct {
	RoomID string
	Epoch  uint64
	State  State
	Reason string
}

// Manager keeps the rooms it has not reclaimed yet. Closed rooms stay in the
// map so an idempotent create replay can still return the same answer.
type Manager struct {
	mu    sync.Mutex
	now   func() time.Time
	ttl   time.Duration
	epoch uint64
	rooms map[string]*Room
	byKey map[string]string
}

func New(ttl time.Duration, now func() time.Time) *Manager {
	if now == nil {
		now = time.Now
	}
	return &Manager{now: now, ttl: ttl, rooms: map[string]*Room{}, byKey: map[string]string{}}
}

func (m *Manager) expired(r *Room) bool { return !m.now().Before(r.LeaseUntil) }

// Create is idempotent by create key. A replay with the same key and room id
// returns the existing room; any other reuse is a conflict, not a new epoch.
func (m *Manager) Create(id, owner, key string) (Room, bool, error) {
	if id == "" || owner == "" {
		return Room{}, false, ErrEmptyID
	}
	m.mu.Lock()
	defer m.mu.Unlock()
	if key != "" {
		if existing, ok := m.rooms[m.byKey[key]]; ok {
			if existing.ID != id {
				return Room{}, false, ErrKeyConflict
			}
			return *existing, true, nil
		}
	}
	if _, ok := m.rooms[id]; ok {
		return Room{}, false, ErrKeyConflict
	}
	m.epoch++
	r := &Room{ID: id, State: Created, Owner: owner, Epoch: m.epoch,
		LeaseUntil: m.now().Add(m.ttl), CreateKey: key, UpdatedAt: m.now()}
	m.rooms[id] = r
	if key != "" {
		m.byKey[key] = id
	}
	return *r, false, nil
}

func (m *Manager) Get(id string) (Room, bool) {
	m.mu.Lock()
	defer m.mu.Unlock()
	r, ok := m.rooms[id]
	if !ok {
		return Room{}, false
	}
	return *r, true
}

// Transition fences on owner and epoch before touching the state machine. A
// transition into CLOSED from SETTLING additionally requires a committed
// settlement, so resources are never released before the result is durable.
func (m *Manager) Transition(id, owner string, epoch uint64, to State) error {
	m.mu.Lock()
	defer m.mu.Unlock()
	r, ok := m.rooms[id]
	if !ok {
		return ErrNotFound
	}
	if r.Owner != owner || r.Epoch != epoch {
		return ErrFence
	}
	if r.State == Closed {
		return ErrIllegal
	}
	if m.expired(r) {
		return ErrLeaseExpired
	}
	if !CanTransition(r.State, to) {
		return ErrIllegal
	}
	if to == Closed && r.State == Settling && !r.Settled {
		return ErrSettlePending
	}
	r.State = to
	r.UpdatedAt = m.now()
	return nil
}

// Renew refreshes an unexpired lease. An expired lease is reported, never
// revived: the reclaim path may already have handed the room to a new owner.
func (m *Manager) Renew(id, owner string, epoch uint64) (time.Time, error) {
	m.mu.Lock()
	defer m.mu.Unlock()
	r, ok := m.rooms[id]
	if !ok {
		return time.Time{}, ErrNotFound
	}
	if r.Owner != owner || r.Epoch != epoch {
		return time.Time{}, ErrFence
	}
	if r.State == Closed || m.expired(r) {
		return time.Time{}, ErrLeaseExpired
	}
	r.LeaseUntil = m.now().Add(m.ttl)
	return r.LeaseUntil, nil
}

// MarkSettled commits the settlement handoff. It is idempotent so a retried
// "settlement written" callback does not turn into an error.
func (m *Manager) MarkSettled(id, owner string, epoch uint64) error {
	m.mu.Lock()
	defer m.mu.Unlock()
	r, ok := m.rooms[id]
	if !ok {
		return ErrNotFound
	}
	if r.Owner != owner || r.Epoch != epoch {
		return ErrFence
	}
	if r.State != Settling {
		return ErrIllegal
	}
	if m.expired(r) {
		return ErrLeaseExpired
	}
	r.Settled = true
	return nil
}

// ScanGhosts reports rooms whose lease expired or whose owner is missing.
// Closed rooms are skipped: they are retained only for idempotent replays.
func (m *Manager) ScanGhosts() []Ghost {
	m.mu.Lock()
	defer m.mu.Unlock()
	now := m.now()
	var out []Ghost
	for _, r := range m.rooms {
		if r.State == Closed {
			continue
		}
		switch {
		case r.Owner == "":
			out = append(out, Ghost{r.ID, r.Epoch, r.State, "missing_owner"})
		case !now.Before(r.LeaseUntil):
			out = append(out, Ghost{r.ID, r.Epoch, r.State, "lease_expired"})
		}
	}
	sort.Slice(out, func(i, j int) bool { return out[i].RoomID < out[j].RoomID })
	return out
}

// Reclaim removes a ghost. An active, unexpired room is refused: killing a
// healthy room is worse than leaving a stale record for the next scan.
func (m *Manager) Reclaim(id string, epoch uint64) error {
	m.mu.Lock()
	defer m.mu.Unlock()
	r, ok := m.rooms[id]
	if !ok {
		return ErrNotFound
	}
	if r.Epoch != epoch {
		return ErrFence
	}
	if r.State != Closed && !m.expired(r) {
		return ErrActive
	}
	delete(m.rooms, id)
	if r.CreateKey != "" {
		delete(m.byKey, r.CreateKey)
	}
	return nil
}

RUNNING → SETTLING → 写结算（幂等，按 match_id）→ MarkSettled → CLOSED → 释放资源