scrabble-game/backend/internal/lobby/lobby.go

// Package lobby forms games: an auto-match maker that drops a player straight into a
// game with an empty opponent seat (or joins them into another player's waiting one),
// and friend-game invitations (invite -> accept) that start a 2-4 player game once
// every invitee has accepted. Both produce games through the game domain; neither
// imports the engine. Auto-match state is the open games in the database, so it
// survives a restart; a background reaper substitutes a pooled robot for any open game
// that waits too long, guaranteeing every game gets an opponent.
package lobby

import (
	"context"
	"errors"

	"github.com/google/uuid"

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

// GameCreator is the slice of the game domain the lobby needs: starting a seated
// game and reading a player's initial view of it. game.Service satisfies it.
type GameCreator interface {
	Create(ctx context.Context, params game.CreateParams) (game.Game, error)
	// InitialState returns a seated player's full initial view of a started game, used
	// to enrich the game_started event so the client renders the new game without a
	// follow-up fetch.
	InitialState(ctx context.Context, gameID, accountID uuid.UUID) (notify.PlayerState, error)
}

// RobotProvider supplies a robot account to substitute for a missing human in
// auto-match. robot.Service satisfies it; it returns an error when no robot is
// available so the matchmaker can defer substitution.
type RobotProvider interface {
	Pick(variant engine.Variant) (uuid.UUID, error)
	// PickNamed selects a robot and composes a fresh per-game display name for it, for
	// the disguised auto-match path (the name is stamped on the robot's seat).
	PickNamed(variant engine.Variant) (uuid.UUID, string, error)
}

// Blocker exposes the per-user block graph the lobby needs. social.Service satisfies it.
// Invitations consult the exact direction (Blocks) so the inviter's block refuses while a
// block the invitee placed on the inviter is silently suppressed; auto-match consults
// BlockedWith so a block either way keeps the pair out of the same anonymous game.
type Blocker interface {
	// Blocks reports whether blocker has blocked blocked (exact direction).
	Blocks(ctx context.Context, blocker, blocked uuid.UUID) (bool, error)
	// BlockedWith returns every account in a block with accountID in either direction.
	BlockedWith(ctx context.Context, accountID uuid.UUID) ([]uuid.UUID, error)
}

// Auto-match defaults: a casual two-player game on the longest move clock with one
// hint per player (docs/ARCHITECTURE.md §6). The drop-out tile disposition is moot
// for two players, so the engine default (remove) applies.
const (
	autoMatchHintsAllowed   = true
	autoMatchHintsPerPlayer = 1
)

// Sentinel errors returned by the lobby.
var (
	// ErrInvalidInvitation is returned for a malformed invitation (bad player
	// count, duplicate or self invitee, or unacceptable settings).
	ErrInvalidInvitation = errors.New("lobby: invalid invitation")
	// ErrInvitationBlocked is returned when a block stands between the inviter and
	// an invitee.
	ErrInvitationBlocked = errors.New("lobby: invitation blocked between accounts")
	// ErrInvitationNotFound is returned when no invitation matches the lookup.
	ErrInvitationNotFound = errors.New("lobby: invitation not found")
	// ErrInvitationNotPending is returned when an invitation is no longer open.
	ErrInvitationNotPending = errors.New("lobby: invitation is not pending")
	// ErrInvitationExpired is returned when an invitation has passed its deadline.
	ErrInvitationExpired = errors.New("lobby: invitation has expired")
	// ErrNotInvited is returned when an account is not an invitee of the invitation.
	ErrNotInvited = errors.New("lobby: account was not invited")
	// ErrAlreadyResponded is returned when an invitee has already accepted or declined.
	ErrAlreadyResponded = errors.New("lobby: invitee has already responded")
	// ErrNotInviter is returned when a non-inviter tries to cancel an invitation.
	ErrNotInviter = errors.New("lobby: only the inviter may cancel")
)