《游戏服务端架构·品类、状态与拓扑》9.1 无状态大厅加有状态房间

payload = player_id "\n" room_id "\n" unix_expiry
token   = base64url(payload) "." base64url(HMAC-SHA256(secret, payload))

租约存储                                房间进程 host-a
  room-042 owner=host-a epoch=7
       ▲                                      │
       └──────── heartbeat(room, host-a, 7) ──┘  每 10s
       │
  到期未续约 → 回收 → 房间内玩家回大厅

// file: internal/hybrid/registry.go
// tier: L1
// verify: go test ./internal/hybrid/
package hybrid

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

// MaxRoomPlayers is the room size for 《泡泡工坊》-style casual matches. A
// room process may allow more, but the lightweight registry stays bounded.
const MaxRoomPlayers = 8

var (
	ErrRoomExists   = errors.New("hybrid: room already open")
	ErrRoomNotFound = errors.New("hybrid: room not found")
	ErrRoomFull     = errors.New("hybrid: room full")
	ErrCapacity     = errors.New("hybrid: room capacity reached")
	ErrStaleOwner   = errors.New("hybrid: stale room owner")
	ErrPlayerBusy   = errors.New("hybrid: player is in another room")
)

// Room is the stateful half. Epoch increases every time a room ID is opened,
// so a restarted host cannot keep renewing the lease of its previous life.
type Room struct {
	ID        string
	Owner     string
	Epoch     uint64
	Players   map[string]struct{}
	ExpiresAt time.Time
}

type RoomView struct {
	ID        string
	Owner     string
	Epoch     uint64
	Players   int
	ExpiresAt time.Time
}

type JoinResult struct {
	RoomID   string
	PlayerID string
	Epoch    uint64
	Rejoined bool
}

type Reclaim struct {
	RoomID  string
	Epoch   uint64
	Players []string
}

// Registry owns the lease table and player placement. In production the same
// records live in Redis; the fencing rules do not change.
type Registry struct {
	mu       sync.Mutex
	now      func() time.Time
	ttl      time.Duration
	capacity int
	epoch    uint64
	rooms    map[string]*Room
	byPlayer map[string]string
}

func NewRegistry(capacity int, ttl time.Duration, now func() time.Time) *Registry {
	if now == nil {
		now = time.Now
	}
	return &Registry{
		now: now, ttl: ttl, capacity: capacity,
		rooms: map[string]*Room{}, byPlayer: map[string]string{},
	}
}

func (g *Registry) expiredLocked(r *Room) bool {
	return !g.now().Before(r.ExpiresAt)
}

func view(r *Room) RoomView {
	return RoomView{ID: r.ID, Owner: r.Owner, Epoch: r.Epoch,
		Players: len(r.Players), ExpiresAt: r.ExpiresAt}
}

// Open creates a room under a new epoch. An expired room with the same ID is
// reclaimed first, so a crash never blocks the ID forever.
func (g *Registry) Open(id, owner string) (RoomView, error) {
	if id == "" || owner == "" {
		return RoomView{}, ErrEmptyID
	}
	g.mu.Lock()
	defer g.mu.Unlock()
	if old, ok := g.rooms[id]; ok {
		if !g.expiredLocked(old) {
			return RoomView{}, ErrRoomExists
		}
		g.dropLocked(old)
	}
	if len(g.rooms) >= g.capacity {
		return RoomView{}, ErrCapacity
	}
	g.epoch++
	r := &Room{ID: id, Owner: owner, Epoch: g.epoch, Players: map[string]struct{}{},
		ExpiresAt: g.now().Add(g.ttl)}
	g.rooms[id] = r
	return view(r), nil
}

// Join is idempotent: a surviving player re-entering the same room gets the
// same seat instead of a duplicate occupancy.
func (g *Registry) Join(roomID, playerID string) (JoinResult, error) {
	if roomID == "" || playerID == "" {
		return JoinResult{}, ErrEmptyID
	}
	g.mu.Lock()
	defer g.mu.Unlock()
	r, ok := g.rooms[roomID]
	if !ok {
		return JoinResult{}, ErrRoomNotFound
	}
	if g.expiredLocked(r) {
		g.dropLocked(r)
		return JoinResult{}, ErrRoomNotFound
	}
	if _, seated := r.Players[playerID]; seated {
		return JoinResult{RoomID: roomID, PlayerID: playerID, Epoch: r.Epoch, Rejoined: true}, nil
	}
	if other, busy := g.byPlayer[playerID]; busy {
		if o, ok := g.rooms[other]; ok && !g.expiredLocked(o) {
			return JoinResult{}, ErrPlayerBusy
		}
		delete(g.byPlayer, playerID)
	}
	if len(r.Players) >= MaxRoomPlayers {
		return JoinResult{}, ErrRoomFull
	}
	r.Players[playerID] = struct{}{}
	g.byPlayer[playerID] = roomID
	return JoinResult{RoomID: roomID, PlayerID: playerID, Epoch: r.Epoch}, nil
}

// Heartbeat renews a lease only for the current owner and epoch. An expired
// lease is dropped before replying, so a paused host cannot revive it.
func (g *Registry) Heartbeat(roomID, owner string, epoch uint64) (time.Time, error) {
	g.mu.Lock()
	defer g.mu.Unlock()
	r, ok := g.rooms[roomID]
	if !ok {
		return time.Time{}, ErrRoomNotFound
	}
	if r.Owner != owner || r.Epoch != epoch {
		return time.Time{}, ErrStaleOwner
	}
	if g.expiredLocked(r) {
		g.dropLocked(r)
		return time.Time{}, ErrRoomNotFound
	}
	r.ExpiresAt = g.now().Add(g.ttl)
	return r.ExpiresAt, nil
}

// Expire reclaims every lease at or past its deadline and returns the players
// that must be sent back to the lobby.
func (g *Registry) Expire() []Reclaim {
	g.mu.Lock()
	defer g.mu.Unlock()
	out := make([]Reclaim, 0)
	for _, r := range g.rooms {
		if g.expiredLocked(r) {
			out = append(out, g.dropLocked(r))
		}
	}
	sort.Slice(out, func(i, j int) bool { return out[i].RoomID < out[j].RoomID })
	return out
}

// Close removes a room immediately, but only under the caller's epoch.
func (g *Registry) Close(roomID, owner string, epoch uint64) (Reclaim, error) {
	g.mu.Lock()
	defer g.mu.Unlock()
	r, ok := g.rooms[roomID]
	if !ok {
		return Reclaim{}, ErrRoomNotFound
	}
	if r.Owner != owner || r.Epoch != epoch {
		return Reclaim{}, ErrStaleOwner
	}
	return g.dropLocked(r), nil
}

func (g *Registry) dropLocked(r *Room) Reclaim {
	delete(g.rooms, r.ID)
	players := make([]string, 0, len(r.Players))
	for p := range r.Players {
		delete(g.byPlayer, p)
		players = append(players, p)
	}
	sort.Strings(players)
	return Reclaim{RoomID: r.ID, Epoch: r.Epoch, Players: players}
}

$ cd .local/checks/gsarch-lab
$ gofmt -l internal/hybrid
$ go vet ./internal/hybrid/
$ go test -count=1 ./internal/hybrid/
ok  	gsarchlab/internal/hybrid	0.538s