feat(lobby): enter the game immediately and wait for the opponent inside it

Quick auto-match no longer waits on a separate screen: Enqueue opens a real game seating the caller with an empty opponent seat (new game status 'open') and the player enters it at once. A second human searching the same variant+rule joins that open game; otherwise a background reaper seats a robot after a 90s + random 0-90s wait, pushing a new in-app opponent_joined event that fills the opponent card and re-enables resign and chat in place.

Matchmaking state is now the open games in the database (the in-memory pool, lobby.poll and lobby.cancel are gone), serialised by a per-bucket advisory lock. While a game is open the starter may move on their turn, but resign, chat and nudge are refused; the lobby and opponent card show "searching for opponent".

Schema edited in the baseline (no prod data): 'open' status, nullable game_players.account_id for the empty seat, and a games.open_deadline_at stamp; jet code regenerated.

backend/internal/lobby/matchmaker_test.go

@@ -14,28 +14,51 @@ import (
 	"scrabble/backend/internal/notify"
 )
 
-// fakeCreator records the games a matchmaker asks it to start.
-type fakeCreator struct {
-	created []game.CreateParams
-	err     error
+// stubMatcher is a fake GameMatcher: it returns canned games and records the calls the
+// matchmaker makes, so the unit tests cover delegation, the opponent_joined emit and
+// the wait-window math without a database. The DB-backed open/join/substitute logic is
+// covered by the integration suite.
+type stubMatcher struct {
+	openGame     game.Game
+	openJoined   bool
+	openErr      error
+	openCalls    int
+	lastDeadline time.Time
+
+	expired []game.OpenGame
+
+	attachGame    game.Game
+	attached      bool
+	attachErr     error
+	attachedGames []uuid.UUID
 }
 
-func (f *fakeCreator) Create(_ context.Context, p game.CreateParams) (game.Game, error) {
-	if f.err != nil {
-		return game.Game{}, f.err
+func (s *stubMatcher) OpenOrJoin(_ context.Context, _ uuid.UUID, _ game.CreateParams, deadline time.Time) (game.Game, bool, error) {
+	s.openCalls++
+	s.lastDeadline = deadline
+	return s.openGame, s.openJoined, s.openErr
+}
+
+func (s *stubMatcher) AttachRobot(_ context.Context, gameID, _ uuid.UUID) (game.Game, bool, error) {
+	if s.attachErr != nil {
+		return game.Game{}, false, s.attachErr
 	}
-	f.created = append(f.created, p)
-	return game.Game{ID: uuid.New(), Players: len(p.Seats)}, nil
+	if s.attached {
+		s.attachedGames = append(s.attachedGames, gameID)
+	}
+	return s.attachGame, s.attached, nil
 }
 
-// InitialState satisfies GameCreator; the matchmaker reads it to enrich match_found. The pairing
-// tests assert on matching behaviour, not the payload, so an empty state is enough.
-func (f *fakeCreator) InitialState(_ context.Context, _, _ uuid.UUID) (notify.PlayerState, error) {
+func (s *stubMatcher) ExpiredOpen(_ context.Context, _ time.Time) ([]game.OpenGame, error) {
+	return s.expired, nil
+}
+
+func (s *stubMatcher) InitialState(_ context.Context, _, _ uuid.UUID) (notify.PlayerState, error) {
 	return notify.PlayerState{}, nil
 }
 
-// fakeRobots is a RobotProvider returning a fixed robot id, or an error to model
-// an empty pool. It records the variant of the last substitution request.
+// fakeRobots is a RobotProvider returning a fixed robot id, or an error to model an
+// empty pool. It records the variant of the last substitution request.
 type fakeRobots struct {
 	id          uuid.UUID
 	err         error
@@ -50,294 +73,137 @@ func (f *fakeRobots) Pick(variant engine.Variant) (uuid.UUID, error) {
 	return f.id, nil
 }
 
-// testWaitDelay is long enough that the reaper never fires in the pairing tests
-// (which do not run it); the substitution tests drive reap directly.
-const testWaitDelay = 10 * time.Second
+// capturePub records every published intent.
+type capturePub struct{ intents []notify.Intent }
 
-func newTestMatchmaker(creator GameCreator, robotID uuid.UUID) *Matchmaker {
-	return NewMatchmaker(creator, &fakeRobots{id: robotID}, testWaitDelay, zap.NewNop())
-}
+func (c *capturePub) Publish(intents ...notify.Intent) { c.intents = append(c.intents, intents...) }
 
-func seatsContain(seats []uuid.UUID, want ...uuid.UUID) bool {
-	for _, w := range want {
-		found := false
-		for _, s := range seats {
-			if s == w {
-				found = true
-				break
-			}
-		}
-		if !found {
-			return false
-		}
+// twoSeatGame is a two-player game seating starter at seat 0 and opponent at seat 1
+// (uuid.Nil for a still-empty opponent seat).
+func twoSeatGame(starter, opponent uuid.UUID) game.Game {
+	return game.Game{
+		ID:      uuid.New(),
+		Variant: engine.VariantEnglish,
+		Seats: []game.Seat{
+			{Seat: 0, AccountID: starter},
+			{Seat: 1, AccountID: opponent},
+		},
 	}
-	return true
 }
 
-func TestMatchmakerPairsTwoHumans(t *testing.T) {
-	creator := &fakeCreator{}
-	mm := newTestMatchmaker(creator, uuid.New())
-	ctx := context.Background()
-	a, b := uuid.New(), uuid.New()
+func TestEnqueueOpensGameWithoutOpponent(t *testing.T) {
+	starter := uuid.New()
+	m := &stubMatcher{openGame: twoSeatGame(starter, uuid.Nil)}
+	pub := &capturePub{}
+	mm := NewMatchmaker(m, &fakeRobots{id: uuid.New()}, time.Minute, time.Minute, zap.NewNop())
+	mm.SetNotifier(pub)
 
-	r1, err := mm.Enqueue(ctx, a, engine.VariantEnglish, true)
+	res, err := mm.Enqueue(context.Background(), starter, engine.VariantEnglish, true)
 	if err != nil {
-		t.Fatalf("enqueue a: %v", err)
+		t.Fatalf("enqueue: %v", err)
 	}
-	if r1.Matched {
-		t.Fatal("first enqueue must wait, not match")
+	if res.Matched {
+		t.Error("opening a game must report Matched=false")
 	}
-	if mm.QueueLen(engine.VariantEnglish) != 1 {
-		t.Fatalf("queue len = %d, want 1", mm.QueueLen(engine.VariantEnglish))
+	if m.openCalls != 1 {
+		t.Errorf("OpenOrJoin calls = %d, want 1", m.openCalls)
 	}
+	if len(pub.intents) != 0 {
+		t.Errorf("opening a game must not emit opponent_joined; got %d intents", len(pub.intents))
+	}
+}
 
-	r2, err := mm.Enqueue(ctx, b, engine.VariantEnglish, true)
+func TestEnqueueJoinEmitsOpponentJoinedToStarter(t *testing.T) {
+	starter, joiner := uuid.New(), uuid.New()
+	m := &stubMatcher{openGame: twoSeatGame(starter, joiner), openJoined: true}
+	pub := &capturePub{}
+	mm := NewMatchmaker(m, &fakeRobots{id: uuid.New()}, time.Minute, time.Minute, zap.NewNop())
+	mm.SetNotifier(pub)
+
+	res, err := mm.Enqueue(context.Background(), joiner, engine.VariantEnglish, true)
 	if err != nil {
-		t.Fatalf("enqueue b: %v", err)
-	}
-	if !r2.Matched {
-		t.Fatal("second enqueue must match")
-	}
-	if mm.QueueLen(engine.VariantEnglish) != 0 {
-		t.Fatalf("queue len = %d, want 0 after match", mm.QueueLen(engine.VariantEnglish))
-	}
-	if len(creator.created) != 1 {
-		t.Fatalf("created %d games, want 1", len(creator.created))
-	}
-	p := creator.created[0]
-	if len(p.Seats) != 2 || !seatsContain(p.Seats, a, b) {
-		t.Errorf("seats = %v, want both %s and %s", p.Seats, a, b)
-	}
-	if p.TurnTimeout != game.DefaultTurnTimeout || !p.HintsAllowed || p.HintsPerPlayer != autoMatchHintsPerPlayer {
-		t.Errorf("auto-match defaults not applied: %+v", p)
-	}
-
-	// The waiting opponent learns of the match through Poll, exactly once.
-	got, err := mm.Poll(ctx, a)
-	if err != nil {
-		t.Fatalf("poll a: %v", err)
-	}
-	if !got.Matched || got.Game.ID != r2.Game.ID {
-		t.Errorf("poll a = %+v, want the matched game %s", got, r2.Game.ID)
-	}
-	if again, _ := mm.Poll(ctx, a); again.Matched {
-		t.Error("poll result must drain after the first read")
-	}
-}
-
-func TestMatchmakerAlreadyQueued(t *testing.T) {
-	mm := newTestMatchmaker(&fakeCreator{}, uuid.New())
-	ctx := context.Background()
-	a := uuid.New()
-	if _, err := mm.Enqueue(ctx, a, engine.VariantEnglish, true); err != nil {
 		t.Fatalf("enqueue: %v", err)
 	}
-	if _, err := mm.Enqueue(ctx, a, engine.VariantEnglish, true); !errors.Is(err, ErrAlreadyQueued) {
-		t.Fatalf("second enqueue err = %v, want ErrAlreadyQueued", err)
+	if !res.Matched {
+		t.Error("joining a waiting game must report Matched=true")
+	}
+	if len(pub.intents) != 1 {
+		t.Fatalf("joining must emit one opponent_joined; got %d", len(pub.intents))
+	}
+	if got := pub.intents[0]; got.Kind != notify.KindOpponentJoined || got.UserID != starter {
+		t.Errorf("opponent_joined = (kind %q, user %s), want (%q, starter %s)", got.Kind, got.UserID, notify.KindOpponentJoined, starter)
 	}
 }
 
-func TestMatchmakerCancel(t *testing.T) {
-	mm := newTestMatchmaker(&fakeCreator{}, uuid.New())
-	ctx := context.Background()
-	a := uuid.New()
-	if _, err := mm.Enqueue(ctx, a, engine.VariantEnglish, true); err != nil {
-		t.Fatalf("enqueue: %v", err)
-	}
-	if !mm.Cancel(ctx, a) {
-		t.Fatal("cancel of a queued account must report true")
-	}
-	if mm.QueueLen(engine.VariantEnglish) != 0 {
-		t.Fatalf("queue len = %d, want 0 after cancel", mm.QueueLen(engine.VariantEnglish))
-	}
-	if mm.Cancel(ctx, a) {
-		t.Fatal("cancel of an unqueued account must report false")
-	}
-}
-
-func TestMatchmakerVariantsAreSeparate(t *testing.T) {
-	creator := &fakeCreator{}
-	mm := newTestMatchmaker(creator, uuid.New())
-	ctx := context.Background()
-	if _, err := mm.Enqueue(ctx, uuid.New(), engine.VariantEnglish, true); err != nil {
-		t.Fatalf("enqueue en: %v", err)
-	}
-	if _, err := mm.Enqueue(ctx, uuid.New(), engine.VariantRussianScrabble, true); err != nil {
-		t.Fatalf("enqueue ru: %v", err)
-	}
-	if len(creator.created) != 0 {
-		t.Fatalf("different variants must not match; created %d", len(creator.created))
-	}
-	if mm.QueueLen(engine.VariantEnglish) != 1 || mm.QueueLen(engine.VariantRussianScrabble) != 1 {
-		t.Errorf("each variant pool should hold one waiter")
-	}
-}
-
-func TestMatchmakerFIFO(t *testing.T) {
-	creator := &fakeCreator{}
-	mm := newTestMatchmaker(creator, uuid.New())
-	ctx := context.Background()
-	a, b, c := uuid.New(), uuid.New(), uuid.New()
-	for _, id := range []uuid.UUID{a, b, c} {
-		if _, err := mm.Enqueue(ctx, id, engine.VariantEnglish, true); err != nil {
-			t.Fatalf("enqueue %s: %v", id, err)
-		}
-	}
-	// a waited, b matched a (oldest), c waits.
-	if len(creator.created) != 1 {
-		t.Fatalf("created %d games, want 1", len(creator.created))
-	}
-	if !seatsContain(creator.created[0].Seats, a, b) {
-		t.Errorf("FIFO match should pair a and b, got %v", creator.created[0].Seats)
-	}
-	if mm.QueueLen(engine.VariantEnglish) != 1 {
-		t.Errorf("c should remain queued; len = %d", mm.QueueLen(engine.VariantEnglish))
-	}
-}
-
-func TestMatchmakerReaperSubstitutesRobot(t *testing.T) {
-	creator := &fakeCreator{}
-	robotID := uuid.New()
-	mm := newTestMatchmaker(creator, robotID)
+func TestEnqueueDeadlineWithinWindow(t *testing.T) {
 	base := time.Now()
+	m := &stubMatcher{openGame: twoSeatGame(uuid.New(), uuid.Nil)}
+	mm := NewMatchmaker(m, &fakeRobots{id: uuid.New()}, 90*time.Second, 90*time.Second, zap.NewNop())
 	mm.clock = func() time.Time { return base }
-	ctx := context.Background()
-	a := uuid.New()
 
-	if _, err := mm.Enqueue(ctx, a, engine.VariantEnglish, true); err != nil {
+	if _, err := mm.Enqueue(context.Background(), uuid.New(), engine.VariantEnglish, true); err != nil {
 		t.Fatalf("enqueue: %v", err)
 	}
-
-	mm.Reap(ctx, base.Add(5*time.Second)) // before the wait window
-	if len(creator.created) != 0 || mm.QueueLen(engine.VariantEnglish) != 1 {
-		t.Fatalf("must not substitute before the wait: created=%d queued=%d", len(creator.created), mm.QueueLen(engine.VariantEnglish))
-	}
-
-	mm.Reap(ctx, base.Add(testWaitDelay+time.Second)) // past the wait window
-	if len(creator.created) != 1 {
-		t.Fatalf("created %d games, want 1 after substitution", len(creator.created))
-	}
-	if !seatsContain(creator.created[0].Seats, a, robotID) {
-		t.Errorf("substituted game seats = %v, want human %s and robot %s", creator.created[0].Seats, a, robotID)
-	}
-	if mm.QueueLen(engine.VariantEnglish) != 0 {
-		t.Errorf("waiter should be dequeued after substitution")
-	}
-	got, err := mm.Poll(ctx, a)
-	if err != nil || !got.Matched {
-		t.Errorf("poll after substitution = %+v err=%v, want matched", got, err)
+	lo, hi := base.Add(90*time.Second), base.Add(180*time.Second)
+	if m.lastDeadline.Before(lo) || !m.lastDeadline.Before(hi) {
+		t.Errorf("deadline %s not in [%s, %s)", m.lastDeadline, lo, hi)
 	}
 }
 
-func TestMatchmakerReaperSkipsCancelled(t *testing.T) {
-	creator := &fakeCreator{}
-	mm := newTestMatchmaker(creator, uuid.New())
-	base := time.Now()
-	mm.clock = func() time.Time { return base }
-	ctx := context.Background()
-	a := uuid.New()
-
-	if _, err := mm.Enqueue(ctx, a, engine.VariantEnglish, true); err != nil {
-		t.Fatalf("enqueue: %v", err)
+func TestReapSubstitutesRobotAndEmits(t *testing.T) {
+	human, robotID := uuid.New(), uuid.New()
+	og := game.OpenGame{ID: uuid.New(), Variant: engine.VariantRussianScrabble}
+	m := &stubMatcher{
+		expired:    []game.OpenGame{og},
+		attachGame: twoSeatGame(human, robotID),
+		attached:   true,
 	}
-	mm.Cancel(ctx, a)
-	mm.Reap(ctx, base.Add(testWaitDelay+time.Second))
-	if len(creator.created) != 0 {
-		t.Errorf("a cancelled waiter must not be substituted; created %d", len(creator.created))
+	robots := &fakeRobots{id: robotID}
+	pub := &capturePub{}
+	mm := NewMatchmaker(m, robots, time.Minute, time.Minute, zap.NewNop())
+	mm.SetNotifier(pub)
+
+	mm.Reap(context.Background(), time.Now())
+
+	if robots.lastVariant != engine.VariantRussianScrabble {
+		t.Errorf("robot picked for %v, want the open game's variant", robots.lastVariant)
+	}
+	if len(m.attachedGames) != 1 || m.attachedGames[0] != og.ID {
+		t.Errorf("attached games = %v, want [%s]", m.attachedGames, og.ID)
+	}
+	if len(pub.intents) != 1 || pub.intents[0].Kind != notify.KindOpponentJoined || pub.intents[0].UserID != human {
+		t.Errorf("reap must emit opponent_joined to the human starter; got %+v", pub.intents)
 	}
 }
 
-// TestMatchmakerCancelClearsPendingResult covers the race where the reaper substitutes a
-// robot just before the player cancels: Cancel must drop the pending result so the
-// abandoned game never surfaces through Poll.
-func TestMatchmakerCancelClearsPendingResult(t *testing.T) {
-	creator := &fakeCreator{}
-	mm := newTestMatchmaker(creator, uuid.New())
-	base := time.Now()
-	mm.clock = func() time.Time { return base }
-	ctx := context.Background()
-	a := uuid.New()
+func TestReapDefersWithoutRobot(t *testing.T) {
+	m := &stubMatcher{expired: []game.OpenGame{{ID: uuid.New(), Variant: engine.VariantEnglish}}}
+	pub := &capturePub{}
+	mm := NewMatchmaker(m, &fakeRobots{err: errors.New("empty pool")}, time.Minute, time.Minute, zap.NewNop())
+	mm.SetNotifier(pub)
 
-	if _, err := mm.Enqueue(ctx, a, engine.VariantEnglish, true); err != nil {
-		t.Fatalf("enqueue: %v", err)
+	mm.Reap(context.Background(), time.Now())
+
+	if len(m.attachedGames) != 0 {
+		t.Errorf("no robot available: must not attach; attached %v", m.attachedGames)
 	}
-	mm.Reap(ctx, base.Add(testWaitDelay+time.Second)) // substitution stores a pending result
-	mm.Cancel(ctx, a)                                 // ... then the player cancels
-	if got, _ := mm.Poll(ctx, a); got.Matched {
-		t.Error("cancel must drop the pending substituted game; Poll still matched")
+	if len(pub.intents) != 0 {
+		t.Errorf("no robot available: must not emit; got %d intents", len(pub.intents))
 	}
 }
 
-func TestMatchmakerReaperDefersWithoutRobot(t *testing.T) {
-	creator := &fakeCreator{}
-	mm := NewMatchmaker(creator, &fakeRobots{err: errors.New("empty pool")}, testWaitDelay, zap.NewNop())
-	base := time.Now()
-	mm.clock = func() time.Time { return base }
-	ctx := context.Background()
-	a := uuid.New()
+func TestReapSkipsWhenHumanJoinedFirst(t *testing.T) {
+	m := &stubMatcher{
+		expired:  []game.OpenGame{{ID: uuid.New(), Variant: engine.VariantEnglish}},
+		attached: false, // AttachRobot reports the game already filled by a human
+	}
+	pub := &capturePub{}
+	mm := NewMatchmaker(m, &fakeRobots{id: uuid.New()}, time.Minute, time.Minute, zap.NewNop())
+	mm.SetNotifier(pub)
 
-	if _, err := mm.Enqueue(ctx, a, engine.VariantEnglish, true); err != nil {
-		t.Fatalf("enqueue: %v", err)
-	}
-	mm.Reap(ctx, base.Add(testWaitDelay+time.Second))
-	if len(creator.created) != 0 {
-		t.Errorf("no robot available: must not create a game; created %d", len(creator.created))
-	}
-	if mm.QueueLen(engine.VariantEnglish) != 1 {
-		t.Errorf("waiter must stay queued when substitution is deferred; len %d", mm.QueueLen(engine.VariantEnglish))
-	}
-}
-
-// TestMatchmakerRulesAreSeparate confirms two players who chose the same variant but a
-// different per-turn word rule are not paired, and that the rule reaches the started game.
-func TestMatchmakerRulesAreSeparate(t *testing.T) {
-	creator := &fakeCreator{}
-	mm := newTestMatchmaker(creator, uuid.New())
-	ctx := context.Background()
-
-	// Same variant, opposite rules: they must not match.
-	if _, err := mm.Enqueue(ctx, uuid.New(), engine.VariantRussianScrabble, false); err != nil {
-		t.Fatalf("enqueue single-word: %v", err)
-	}
-	if _, err := mm.Enqueue(ctx, uuid.New(), engine.VariantRussianScrabble, true); err != nil {
-		t.Fatalf("enqueue standard: %v", err)
-	}
-	if len(creator.created) != 0 {
-		t.Fatalf("different rules must not match; created %d", len(creator.created))
-	}
-
-	// A second single-word player pairs with the first; the game carries the rule.
-	r, err := mm.Enqueue(ctx, uuid.New(), engine.VariantRussianScrabble, false)
-	if err != nil {
-		t.Fatalf("enqueue single-word opponent: %v", err)
-	}
-	if !r.Matched {
-		t.Fatal("same variant and rule must match")
-	}
-	if len(creator.created) != 1 {
-		t.Fatalf("created %d games, want 1", len(creator.created))
-	}
-	if creator.created[0].MultipleWordsPerTurn {
-		t.Error("single-word match must create a game with MultipleWordsPerTurn=false")
-	}
-}
-
-// TestMatchmakerReaperKeepsRule confirms a robot substitution carries the waiter's rule.
-func TestMatchmakerReaperKeepsRule(t *testing.T) {
-	creator := &fakeCreator{}
-	mm := newTestMatchmaker(creator, uuid.New())
-	base := time.Now()
-	mm.clock = func() time.Time { return base }
-	ctx := context.Background()
-
-	if _, err := mm.Enqueue(ctx, uuid.New(), engine.VariantRussianScrabble, false); err != nil {
-		t.Fatalf("enqueue: %v", err)
-	}
-	mm.Reap(ctx, base.Add(testWaitDelay+time.Second))
-	if len(creator.created) != 1 {
-		t.Fatalf("created %d games, want 1", len(creator.created))
-	}
-	if creator.created[0].MultipleWordsPerTurn {
-		t.Error("robot substitution must keep the waiter's single-word rule")
+	mm.Reap(context.Background(), time.Now())
+
+	if len(pub.intents) != 0 {
+		t.Errorf("a human-filled game must not emit opponent_joined; got %d", len(pub.intents))
 	}
 }