《游戏服务端架构·品类、状态与拓扑》3.2 大厅、房间与战斗：竞技品类的标准形态

client ──► lobby (stateless) ──► allocator ──► room N
              │                      │
              └─ matchmaking         └─ lease store (TTL)

回收过期租约 → 拒绝重复会话 → 检查容量 → 从暖池取房

// file: internal/alloc/allocator.go
// tier: L1
// verify: go test ./internal/alloc/
package alloc

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

var (
	ErrInvalidSession = errors.New("alloc: empty session id")
	ErrDuplicate      = errors.New("alloc: session already holds a room")
	ErrCapacity       = errors.New("alloc: concurrent lease capacity reached")
	ErrPoolExhausted  = errors.New("alloc: warm pool exhausted")
	ErrUnknownSession = errors.New("alloc: session holds no room")
)

type Room struct {
	ID string
}

type Lease struct {
	RoomID    string
	SessionID string
	ExpiresAt time.Time
}

type Allocator struct {
	mu        sync.Mutex
	now       func() time.Time
	capacity  int
	leaseTTL  time.Duration
	warm      []Room
	active    map[string]Lease
	bySession map[string]string
	nextRoom  int
}

// New caps concurrently leased rooms at capacity. leaseTTL bounds how long a
// client may hold a room without renewing; capacity is not the warm-pool size.
func New(capacity int, leaseTTL time.Duration, now func() time.Time) *Allocator {
	if capacity < 0 {
		capacity = 0
	}
	if now == nil {
		now = time.Now
	}
	return &Allocator{
		now: now, capacity: capacity, leaseTTL: leaseTTL,
		active: make(map[string]Lease), bySession: make(map[string]string),
	}
}

// Warm pre-creates n idle rooms, never exceeding capacity.
func (a *Allocator) Warm(n int) {
	a.mu.Lock()
	defer a.mu.Unlock()
	for i := 0; i < n && len(a.warm) < a.capacity; i++ {
		a.nextRoom++
		a.warm = append(a.warm, Room{ID: fmt.Sprintf("room-%03d", a.nextRoom)})
	}
}

// Acquire reclaims expired leases first, then checks duplicate and capacity,
// then pops a warm room. A crashed client therefore cannot pin a room forever.
func (a *Allocator) Acquire(sessionID string) (Lease, error) {
	if sessionID == "" {
		return Lease{}, ErrInvalidSession
	}
	a.mu.Lock()
	defer a.mu.Unlock()

	a.reclaimLocked()
	if _, ok := a.bySession[sessionID]; ok {
		return Lease{}, ErrDuplicate
	}
	if len(a.active) >= a.capacity {
		return Lease{}, ErrCapacity
	}
	if len(a.warm) == 0 {
		return Lease{}, ErrPoolExhausted
	}

	room := a.warm[len(a.warm)-1]
	a.warm = a.warm[:len(a.warm)-1]
	lease := Lease{
		RoomID: room.ID, SessionID: sessionID,
		ExpiresAt: a.now().Add(a.leaseTTL),
	}
	a.active[room.ID] = lease
	a.bySession[sessionID] = room.ID
	return lease, nil
}

// Release returns a room to the warm pool. Releasing an expired or unknown
// session is an error, not a no-op: it signals a stale client.
func (a *Allocator) Release(sessionID string) error {
	a.mu.Lock()
	defer a.mu.Unlock()
	roomID, ok := a.bySession[sessionID]
	if !ok {
		return ErrUnknownSession
	}
	delete(a.bySession, sessionID)
	delete(a.active, roomID)
	a.returnToPoolLocked(Room{ID: roomID})
	return nil
}

// ReclaimExpired frees every lease past its deadline, sorted by room id.
func (a *Allocator) ReclaimExpired() []Lease {
	a.mu.Lock()
	defer a.mu.Unlock()
	return a.reclaimLocked()
}

func (a *Allocator) reclaimLocked() []Lease {
	now := a.now()
	var expired []Lease
	for roomID, lease := range a.active {
		if now.Before(lease.ExpiresAt) {
			continue
		}
		expired = append(expired, lease)
		delete(a.active, roomID)
		delete(a.bySession, lease.SessionID)
		a.returnToPoolLocked(Room{ID: roomID})
	}
	sort.Slice(expired, func(i, j int) bool { return expired[i].RoomID < expired[j].RoomID })
	return expired
}

func (a *Allocator) returnToPoolLocked(room Room) {
	if len(a.warm) < a.capacity {
		a.warm = append(a.warm, room)
	}
}

// file: internal/alloc/allocator_test.go
// tier: L1
// verify: go test ./internal/alloc/
package alloc

import (
	"errors"
	"testing"
	"time"
)

func newTestAllocator(capacity, warm int, ttl time.Duration) (*Allocator, *time.Time) {
	now := time.Date(2026, 10, 21, 12, 0, 0, 0, time.UTC)
	a := New(capacity, ttl, func() time.Time { return now })
	a.Warm(warm)
	return a, &now
}

func TestAcquireReleaseReusesWarmRoom(t *testing.T) {
	a, _ := newTestAllocator(10, 2, 30*time.Second)
	first, err := a.Acquire("session-a")
	if err != nil {
		t.Fatalf("Acquire: %v", err)
	}
	if err := a.Release("session-a"); err != nil {
		t.Fatalf("Release: %v", err)
	}
	second, err := a.Acquire("session-b")
	if err != nil {
		t.Fatalf("Acquire after release: %v", err)
	}
	if second.RoomID != first.RoomID {
		t.Fatalf("recycled room = %s, want %s", second.RoomID, first.RoomID)
	}
}

func TestPoolExhausted(t *testing.T) {
	a, _ := newTestAllocator(10, 2, 30*time.Second)
	for _, id := range []string{"s1", "s2"} {
		if _, err := a.Acquire(id); err != nil {
			t.Fatalf("Acquire(%s): %v", id, err)
		}
	}
	if _, err := a.Acquire("s3"); !errors.Is(err, ErrPoolExhausted) {
		t.Fatalf("error = %v, want ErrPoolExhausted", err)
	}
}

func TestCapacityLimit(t *testing.T) {
	a, _ := newTestAllocator(2, 5, 30*time.Second)
	for _, id := range []string{"s1", "s2"} {
		if _, err := a.Acquire(id); err != nil {
			t.Fatalf("Acquire(%s): %v", id, err)
		}
	}
	if _, err := a.Acquire("s3"); !errors.Is(err, ErrCapacity) {
		t.Fatalf("error = %v, want ErrCapacity", err)
	}
}

func TestLeaseExpiryReclaimsRoom(t *testing.T) {
	a, clock := newTestAllocator(10, 1, 30*time.Second)
	expired, err := a.Acquire("crashed-client")
	if err != nil {
		t.Fatalf("Acquire: %v", err)
	}
	*clock = clock.Add(30 * time.Second)
	replacement, err := a.Acquire("new-client")
	if err != nil {
		t.Fatalf("Acquire after expiry: %v", err)
	}
	if replacement.RoomID != expired.RoomID {
		t.Fatalf("replacement = %s, want %s", replacement.RoomID, expired.RoomID)
	}
	if err := a.Release("crashed-client"); !errors.Is(err, ErrUnknownSession) {
		t.Fatalf("stale Release = %v, want ErrUnknownSession", err)
	}
}

func TestDuplicateAllocationRejected(t *testing.T) {
	a, _ := newTestAllocator(10, 2, 30*time.Second)
	if _, err := a.Acquire("same-session"); err != nil {
		t.Fatalf("first Acquire: %v", err)
	}
	if _, err := a.Acquire("same-session"); !errors.Is(err, ErrDuplicate) {
		t.Fatalf("second Acquire = %v, want ErrDuplicate", err)
	}
	if err := a.Release("same-session"); err != nil {
		t.Fatalf("Release after duplicate: %v", err)
	}
	if err := a.Release("same-session"); !errors.Is(err, ErrUnknownSession) {
		t.Fatalf("second Release = %v, want ErrUnknownSession", err)
	}
}

func TestReclaimExpiredIsSortedAndIdempotent(t *testing.T) {
	a, clock := newTestAllocator(10, 2, 10*time.Second)
	for _, id := range []string{"s1", "s2"} {
		if _, err := a.Acquire(id); err != nil {
			t.Fatal(err)
		}
	}
	*clock = clock.Add(10 * time.Second)
	got := a.ReclaimExpired()
	if len(got) != 2 || got[0].RoomID > got[1].RoomID {
		t.Fatalf("reclaimed = %v", got)
	}
	if again := a.ReclaimExpired(); len(again) != 0 {
		t.Fatalf("second reclaim = %v", again)
	}
}

$ cd .local/checks/gsarch-lab
$ gofmt -l .
$ go vet ./...
$ go test -count=1 -v ./internal/alloc/
=== RUN   TestAcquireReleaseReusesWarmRoom
--- PASS: TestAcquireReleaseReusesWarmRoom (0.00s)
=== RUN   TestPoolExhausted
--- PASS: TestPoolExhausted (0.00s)
=== RUN   TestCapacityLimit
--- PASS: TestCapacityLimit (0.00s)
=== RUN   TestLeaseExpiryReclaimsRoom
--- PASS: TestLeaseExpiryReclaimsRoom (0.00s)
=== RUN   TestDuplicateAllocationRejected
--- PASS: TestDuplicateAllocationRejected (0.00s)
=== RUN   TestReclaimExpiredIsSortedAndIdempotent
--- PASS: TestReclaimExpiredIsSortedAndIdempotent (0.00s)
PASS
ok  	gsarchlab/internal/alloc	0.392s