Stage 5: robot opponent (pool, seed-derived strategy, move driver, matchmaker substitution)

- internal/robot: durable kind='robot' account pool (migration 00004); every per-game and per-turn choice derived deterministically from the game seed (restart-stable FNV mix); a background move driver; margin targeting (band 1-30, closest-to-band); right-skewed [2,90]min delays (median ~10m); opponent-anchored sleep with +/-3h drift; daytime nudge reply + proactive 12h nudge; friend/chat blocked via profile toggles. - engine.Candidates (decoded ranked plays); game.Candidates + RobotTurns; social.LastNudgeAt. - matchmaker: 10s wait then robot substitution (reaper) + Poll delivery seam. - config (BACKEND_ROBOT_DRIVE_INTERVAL, BACKEND_LOBBY_ROBOT_WAIT, BACKEND_LOBBY_REAPER_INTERVAL); main wiring + boot-time pool provisioning. - metrics: robot account_stats (authoritative balance) + robot_games_finished_total OTel counter + per-finish log. - docs: PLAN, ARCHITECTURE, FUNCTIONAL(+ru), TESTING, README; account.go comment. - tests: robot strategy units, matchmaker reaper/Poll, engine.Candidates; inttest robot full-game / substitution / proactive-nudge.
2026-06-02 21:02:20 +02:00
parent 12fc6e498e
commit 85baabe4ba
26 changed files with 1700 additions and 85 deletions
@@ -7,34 +7,56 @@ import (
 	"time"

 	"github.com/google/uuid"
+	"go.uber.org/zap"

 	"scrabble/backend/internal/engine"
 	"scrabble/backend/internal/game"
 )

 // Matchmaker is the in-memory auto-match pool: a FIFO queue per variant that pairs
-// the next two humans into a two-player game. It holds no database state and is
-// lost on restart (players simply re-queue). It is safe for concurrent use.
+// the next two humans into a two-player game, or — when no human arrives within
+// the wait window — substitutes a robot. It holds no database state and is lost on
+// restart (players simply re-queue). It is safe for concurrent use.
 //
 // Auto-match is anonymous, so the pool does not consult per-user blocks (those
-// govern friends, chat and invitations between known players). Robot substitution
-// for a missing human is added in a later stage.
+// govern friends, chat and invitations between known players).
+//
+// A player who is queued learns of a match — by a waiting human being paired, or
+// by robot substitution — through Poll, the interim delivery seam: production
+// delivery is a notification (session/in-app push and the platform side-service,
+// docs/ARCHITECTURE.md §10), wired with the gateway in a later stage.
 type Matchmaker struct {
-	games GameCreator
+	games     GameCreator
+	robots    RobotProvider
+	waitDelay time.Duration
+	clock     func() time.Time
+	log       *zap.Logger

-	mu     sync.Mutex
-	queues map[engine.Variant][]uuid.UUID
-	queued map[uuid.UUID]engine.Variant
-	rng    *rand.Rand
+	mu           sync.Mutex
+	queues       map[engine.Variant][]uuid.UUID
+	queued       map[uuid.UUID]engine.Variant
+	waitingSince map[uuid.UUID]time.Time
+	results      map[uuid.UUID]game.Game
+	rng          *rand.Rand
 }

-// NewMatchmaker constructs a Matchmaker that starts matched games through games.
-func NewMatchmaker(games GameCreator) *Matchmaker {
+// NewMatchmaker constructs a Matchmaker that starts matched games through games
+// and substitutes a robot from robots when a player waits longer than waitDelay.
+func NewMatchmaker(games GameCreator, robots RobotProvider, waitDelay time.Duration, log *zap.Logger) *Matchmaker {
+	if log == nil {
+		log = zap.NewNop()
+	}
 	return &Matchmaker{
-		games:  games,
-		queues: make(map[engine.Variant][]uuid.UUID),
-		queued: make(map[uuid.UUID]engine.Variant),
-		rng:    rand.New(rand.NewSource(time.Now().UnixNano())),
+		games:        games,
+		robots:       robots,
+		waitDelay:    waitDelay,
+		clock:        func() time.Time { return time.Now().UTC() },
+		log:          log,
+		queues:       make(map[engine.Variant][]uuid.UUID),
+		queued:       make(map[uuid.UUID]engine.Variant),
+		waitingSince: make(map[uuid.UUID]time.Time),
+		results:      make(map[uuid.UUID]game.Game),
+		rng:          rand.New(rand.NewSource(time.Now().UnixNano())),
 	}
 }

@@ -47,7 +69,8 @@ type EnqueueResult struct {

 // Enqueue joins accountID to the variant pool. If an opponent already waits, the
 // two are paired (seat order randomised for first-move fairness) and a game starts
-// immediately; otherwise the account waits. An account already waiting in any pool
+// immediately; otherwise the account waits, and a later pairing or robot
+// substitution is delivered through Poll. An account already waiting in any pool
 // gets ErrAlreadyQueued.
 func (m *Matchmaker) Enqueue(ctx context.Context, accountID uuid.UUID, variant engine.Variant) (EnqueueResult, error) {
 	m.mu.Lock()
@@ -59,31 +82,42 @@ func (m *Matchmaker) Enqueue(ctx context.Context, accountID uuid.UUID, variant e
 	if len(q) == 0 {
 		m.queues[variant] = append(q, accountID)
 		m.queued[accountID] = variant
+		m.waitingSince[accountID] = m.clock()
 		m.mu.Unlock()
 		return EnqueueResult{}, nil
 	}
 	opponent := q[0]
-	m.queues[variant] = q[1:]
-	delete(m.queued, opponent)
+	m.removeLocked(opponent, variant)
 	seats := []uuid.UUID{opponent, accountID}
 	if m.rng.Intn(2) == 0 {
 		seats[0], seats[1] = seats[1], seats[0]
 	}
 	m.mu.Unlock()

-	g, err := m.games.Create(ctx, game.CreateParams{
-		Variant:        variant,
-		Seats:          seats,
-		TurnTimeout:    game.DefaultTurnTimeout,
-		HintsAllowed:   autoMatchHintsAllowed,
-		HintsPerPlayer: autoMatchHintsPerPlayer,
-	})
+	g, err := m.games.Create(ctx, autoMatchParams(variant, seats))
 	if err != nil {
 		return EnqueueResult{}, err
 	}
+	// The opponent was waiting; record the game so they can collect it via Poll.
+	m.mu.Lock()
+	m.results[opponent] = g
+	m.mu.Unlock()
 	return EnqueueResult{Matched: true, Game: g}, nil
 }

+// Poll reports whether accountID has been matched since it queued, returning the
+// started game once (the result is drained on read). It reports Matched=false
+// while the account is still waiting or has no pending result.
+func (m *Matchmaker) Poll(_ context.Context, accountID uuid.UUID) (EnqueueResult, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	if g, ok := m.results[accountID]; ok {
+		delete(m.results, accountID)
+		return EnqueueResult{Matched: true, Game: g}, nil
+	}
+	return EnqueueResult{}, nil
+}
+
 // Cancel removes accountID from whatever pool it waits in, reporting whether it
 // was queued.
 func (m *Matchmaker) Cancel(_ context.Context, accountID uuid.UUID) bool {
@@ -93,14 +127,7 @@ func (m *Matchmaker) Cancel(_ context.Context, accountID uuid.UUID) bool {
 	if !ok {
 		return false
 	}
-	delete(m.queued, accountID)
-	q := m.queues[variant]
-	for i, id := range q {
-		if id == accountID {
-			m.queues[variant] = append(q[:i], q[i+1:]...)
-			break
-		}
-	}
+	m.removeLocked(accountID, variant)
 	return true
 }

@@ -110,3 +137,91 @@ func (m *Matchmaker) QueueLen(variant engine.Variant) int {
 	defer m.mu.Unlock()
 	return len(m.queues[variant])
 }
+
+// RunReaper substitutes a robot for any player that has waited past waitDelay,
+// scanning every interval until ctx is cancelled. It is started once from main.
+func (m *Matchmaker) RunReaper(ctx context.Context, interval time.Duration) {
+	ticker := time.NewTicker(interval)
+	defer ticker.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-ticker.C:
+			m.Reap(ctx, m.clock())
+		}
+	}
+}
+
+// Reap pairs every player that has waited past waitDelay with a freshly picked
+// robot and starts the game, recording it for the player's Poll. RunReaper calls
+// it on a timer; it takes now explicitly so tests and ops can drive a single pass
+// at a chosen instant. A waiter is only dequeued once a robot is secured, so a
+// momentarily empty pool just defers substitution to a later tick.
+func (m *Matchmaker) Reap(ctx context.Context, now time.Time) {
+	type sub struct {
+		human   uuid.UUID
+		variant engine.Variant
+		seats   []uuid.UUID
+	}
+	m.mu.Lock()
+	var due []uuid.UUID
+	for acc, since := range m.waitingSince {
+		if now.Sub(since) >= m.waitDelay {
+			due = append(due, acc)
+		}
+	}
+	var subs []sub
+	for _, acc := range due {
+		robotID, err := m.robots.Pick()
+		if err != nil {
+			m.log.Warn("robot substitution deferred", zap.Error(err))
+			continue
+		}
+		variant := m.queued[acc]
+		m.removeLocked(acc, variant)
+		seats := []uuid.UUID{acc, robotID}
+		if m.rng.Intn(2) == 0 {
+			seats[0], seats[1] = seats[1], seats[0]
+		}
+		subs = append(subs, sub{human: acc, variant: variant, seats: seats})
+	}
+	m.mu.Unlock()
+
+	for _, s := range subs {
+		g, err := m.games.Create(ctx, autoMatchParams(s.variant, s.seats))
+		if err != nil {
+			m.log.Warn("robot substitution failed", zap.String("human", s.human.String()), zap.Error(err))
+			continue
+		}
+		m.mu.Lock()
+		m.results[s.human] = g
+		m.mu.Unlock()
+	}
+}
+
+// removeLocked drops accountID from the queue, the queued index and the waiting
+// clock. The caller holds m.mu.
+func (m *Matchmaker) removeLocked(accountID uuid.UUID, variant engine.Variant) {
+	delete(m.queued, accountID)
+	delete(m.waitingSince, accountID)
+	q := m.queues[variant]
+	for i, id := range q {
+		if id == accountID {
+			m.queues[variant] = append(q[:i], q[i+1:]...)
+			break
+		}
+	}
+}
+
+// autoMatchParams builds the create parameters for a two-player auto-match with
+// the casual defaults.
+func autoMatchParams(variant engine.Variant, seats []uuid.UUID) game.CreateParams {
+	return game.CreateParams{
+		Variant:        variant,
+		Seats:          seats,
+		TurnTimeout:    game.DefaultTurnTimeout,
+		HintsAllowed:   autoMatchHintsAllowed,
+		HintsPerPlayer: autoMatchHintsPerPlayer,
+	}
+}