《MMO 服务器开发》17.2 大厅生命周期：防幽灵房间

// file: internal/match/lobby.go
// tier: L1
// verify: go test ./internal/match/
package match

// RoomState 是房间的生命周期状态。幽灵房间几乎总是「停在某个非终态、却已经没人」。
type RoomState uint8

const (
	RoomWaiting  RoomState = iota // 已建房，等人齐
	RoomStarting                  // 人齐，等各客户端 ack 开局
	RoomInGame                    // 对局进行中
	RoomSettling                  // 结算中
	RoomClosed                    // 终态：槽位已释放
)

// Room 是一个大厅房间。成员用「租约」表示在线：成员必须周期性续约，
// 租约到期即视为掉线并从房间移除——这是防幽灵的第一道闸。
type Room struct {
	ID           uint64
	Owner        PlayerID
	State        RoomState
	Members      map[PlayerID]int64 // 成员 -> 租约到期时刻(ms)
	CreatedAt    int64
	LastActivity int64
	Deadline     int64  // Waiting 状态的最晚匹配时刻
	StartAckAt   int64  // Starting 状态开始等 ack 的时刻
	ClosedReason string // 终态原因，便于排障与埋点
}

// LobbyConfig 是房间的超时参数。全部用毫秒，避免 time.Time 带来的时区/单调时钟差异。
type LobbyConfig struct {
	LeaseTTL          int64 // 成员租约 TTL
	WaitTimeout       int64 // Waiting 最长等待
	StartAckTimeout   int64 // Starting 等 ack 的上限
	InGameIdleTimeout int64 // InGame 无活动上限
}

// DefaultLobbyConfig 是一套保守的默认值。
func DefaultLobbyConfig() LobbyConfig {
	return LobbyConfig{
		LeaseTTL:          15000,
		WaitTimeout:       60000,
		StartAckTimeout:   10000,
		InGameIdleTimeout: 300000,
	}
}

// Lobby 管理单服内的全部房间。单线程 tick 驱动，不做内部加锁（由外层 actor 串行调用）。
type Lobby struct {
	cfg     LobbyConfig
	rooms   map[uint64]*Room
	nextID  uint64
	slotCap int
}

// NewLobby 建房上限 slotCap；超过即拒绝 Create，防止实例槽位被无限占用。
func NewLobby(cfg LobbyConfig, slotCap int) *Lobby {
	return &Lobby{cfg: cfg, rooms: make(map[uint64]*Room), slotCap: slotCap}
}

// Create 建房并把房主加入。槽位满时返回 nil。
func (l *Lobby) Create(owner PlayerID, now int64) *Room {
	if len(l.rooms) >= l.slotCap {
		return nil
	}
	l.nextID++
	r := &Room{
		ID:           l.nextID,
		Owner:        owner,
		State:        RoomWaiting,
		Members:      map[PlayerID]int64{owner: now + l.cfg.LeaseTTL},
		CreatedAt:    now,
		LastActivity: now,
		Deadline:     now + l.cfg.WaitTimeout,
	}
	l.rooms[r.ID] = r
	return r
}

// Join 加入房间并把该成员的租约重置。房间不存在或已关则返回 false。
func (l *Lobby) Join(id uint64, p PlayerID, now int64) bool {
	r, ok := l.rooms[id]
	if !ok || r.State == RoomClosed {
		return false
	}
	r.Members[p] = now + l.cfg.LeaseTTL
	r.LastActivity = now
	return true
}

// Heartbeat 续约单个成员；租约到期后被移除的成员不会被自动复活。
func (l *Lobby) Heartbeat(id uint64, p PlayerID, now int64) bool {
	r, ok := l.rooms[id]
	if !ok || r.State == RoomClosed {
		return false
	}
	if _, alive := r.Members[p]; !alive {
		return false
	}
	r.Members[p] = now + l.cfg.LeaseTTL
	r.LastActivity = now
	return true
}

// MarkStarting 把房间从 Waiting 推进到 Starting，并记下等 ack 的起点。
func (l *Lobby) MarkStarting(id uint64, now int64) bool {
	r, ok := l.rooms[id]
	if !ok || r.State != RoomWaiting {
		return false
	}
	r.State = RoomStarting
	r.StartAckAt = now
	r.LastActivity = now
	return true
}

// AckStart 收齐 ack 后把房间推进到 InGame。
func (l *Lobby) AckStart(id uint64, now int64) bool {
	r, ok := l.rooms[id]
	if !ok || r.State != RoomStarting {
		return false
	}
	r.State = RoomInGame
	r.LastActivity = now
	return true
}

// Tick 是唯一的清理入口，返回本轮被关闭的房间 ID。四条规则都指向同一件事：
// 任何非终态房间，只要「没人续约」或「超过该状态的超时」，就必须走向 Closed。
func (l *Lobby) Tick(now int64) []uint64 {
	var closed []uint64
	for id, r := range l.rooms {
		// 规则 1：租约到期的成员视为掉线。
		for p, exp := range r.Members {
			if exp <= now {
				delete(r.Members, p)
			}
		}
		// 规则 2：房间空了就是幽灵，立刻回收。
		if len(r.Members) == 0 {
			l.close(r, now, "empty")
			closed = append(closed, id)
			continue
		}
		// 规则 3：各状态各自的超时。
		switch r.State {
		case RoomWaiting:
			if now >= r.Deadline {
				l.close(r, now, "wait_timeout")
				closed = append(closed, id)
			}
		case RoomStarting:
			if now >= r.StartAckAt+l.cfg.StartAckTimeout {
				// 有人没 ack：回滚到 Waiting 重新等，而不是卡死在 Starting。
				r.State = RoomWaiting
				r.Deadline = now + l.cfg.WaitTimeout
				r.LastActivity = now
			}
		case RoomInGame, RoomSettling:
			if now >= r.LastActivity+l.cfg.InGameIdleTimeout {
				l.close(r, now, "game_idle")
				closed = append(closed, id)
			}
		}
	}
	return closed
}

func (l *Lobby) close(r *Room, now int64, reason string) {
	r.State = RoomClosed
	r.ClosedReason = reason
	r.LastActivity = now
	r.Members = map[PlayerID]int64{}
	delete(l.rooms, r.ID)
}

// snippet: internal/match/lobby_test.go（摘录）
// 幽灵一：建房后所有人都不续约，租约到期后房间必须被回收。
func TestGhostRoomIsReaped(t *testing.T) {
	cfg := DefaultLobbyConfig()
	l := NewLobby(cfg, 10)
	r := l.Create(1, 0)
	if len(l.rooms) != 1 {
		t.Fatalf("活跃房间 %d，期望 1", len(l.rooms))
	}
	if closed := l.Tick(1000); len(closed) != 0 { // 未到 TTL：健在
		t.Fatalf("t=1000 不应回收，实际回收 %v", closed)
	}
	closed := l.Tick(cfg.LeaseTTL + 1) // 超过 TTL：掉线 -> 空房 -> 回收
	if len(closed) != 1 || closed[0] != r.ID {
		t.Fatalf("t=%d 应回收房间 %d，实际 %v", cfg.LeaseTTL+1, r.ID, closed)
	}
}

// 幽灵二：卡在 Starting 等 ack，超时必须回滚到 Waiting。
func TestStartAckTimeoutRollsBack(t *testing.T) {
	cfg := DefaultLobbyConfig()
	l := NewLobby(cfg, 10)
	r := l.Create(1, 0)
	l.MarkStarting(r.ID, 0)
	l.Heartbeat(r.ID, 1, 0)
	l.Tick(cfg.StartAckTimeout - 1) // 未超时：仍是 Starting
	if r.State != RoomStarting {
		t.Fatalf("未超时应保持 starting，实际 %v", r.State)
	}
	l.Heartbeat(r.ID, 1, cfg.StartAckTimeout)
	l.Tick(cfg.StartAckTimeout) // 超时：回滚
	if r.State != RoomWaiting {
		t.Fatalf("ack 超时应回滚到 waiting，实际 %v", r.State)
	}
}

$ go test ./internal/match/
ok  	aegis/internal/match	1.170s     （19 个 test 全绿，含 6 个大厅用例）