feat: game lobby service

lobby/internal/service/listgames/service.go

@@ -0,0 +1,270 @@
+// Package listgames implements the `lobby.games.list` message type. It
+// returns the public game list per `lobby/README.md` §«User-Facing Lists»
+// — public records in `enrollment_open`, `ready_to_start`, `running`,
+// or `finished` — and additionally surfaces every private game the
+// caller currently belongs to (membership in any status, except games
+// in `draft` or `cancelled`). Admin actors bypass the visibility filter
+// and see every record regardless of game type or status, which is the
+// surface used by the internal-port `adminListGames` route.
+package listgames
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"log/slog"
+	"sort"
+
+	"galaxy/lobby/internal/domain/common"
+	"galaxy/lobby/internal/domain/game"
+	"galaxy/lobby/internal/ports"
+	"galaxy/lobby/internal/service/shared"
+)
+
+// publicVisibleStatuses lists the user-visible public-game statuses
+// allowed in the public list per README §«Public game list».
+var publicVisibleStatuses = []game.Status{
+	game.StatusEnrollmentOpen,
+	game.StatusReadyToStart,
+	game.StatusRunning,
+	game.StatusFinished,
+}
+
+// adminAllStatuses enumerates every status used by the admin variant to
+// produce an unrestricted list (see `lobby/api/internal-openapi.yaml`
+// `adminListGames`).
+var adminAllStatuses = []game.Status{
+	game.StatusDraft,
+	game.StatusEnrollmentOpen,
+	game.StatusReadyToStart,
+	game.StatusStarting,
+	game.StatusStartFailed,
+	game.StatusRunning,
+	game.StatusPaused,
+	game.StatusFinished,
+	game.StatusCancelled,
+}
+
+// privateMembershipExcludedStatuses lists the statuses removed from the
+// user-visible private list. Draft games are owner-only (handled by
+// `getgame`); cancelled games drop off the user-facing list entirely.
+var privateMembershipExcludedStatuses = map[game.Status]struct{}{
+	game.StatusDraft:     {},
+	game.StatusCancelled: {},
+}
+
+// Service executes the list-games use case.
+type Service struct {
+	games       ports.GameStore
+	memberships ports.MembershipStore
+	logger      *slog.Logger
+}
+
+// Dependencies groups the collaborators used by Service.
+type Dependencies struct {
+	// Games supplies the per-status indexes that drive both the public
+	// list and the unrestricted admin list.
+	Games ports.GameStore
+
+	// Memberships is consulted only for user actors to enumerate the
+	// private games the caller belongs to.
+	Memberships ports.MembershipStore
+
+	// Logger records structured diagnostics. Defaults to slog.Default
+	// when nil.
+	Logger *slog.Logger
+}
+
+// NewService constructs one Service with deps.
+func NewService(deps Dependencies) (*Service, error) {
+	switch {
+	case deps.Games == nil:
+		return nil, errors.New("new list games service: nil game store")
+	case deps.Memberships == nil:
+		return nil, errors.New("new list games service: nil membership store")
+	}
+	logger := deps.Logger
+	if logger == nil {
+		logger = slog.Default()
+	}
+	return &Service{
+		games:       deps.Games,
+		memberships: deps.Memberships,
+		logger:      logger.With("service", "lobby.listgames"),
+	}, nil
+}
+
+// Input stores the arguments required to list games for one caller.
+type Input struct {
+	// Actor identifies the caller. Admin actors receive the
+	// unrestricted list; user actors receive the public list plus
+	// their own private games.
+	Actor shared.Actor
+
+	// Page stores the pagination request derived from page_size and
+	// page_token by the transport layer.
+	Page shared.Page
+}
+
+// Output stores the page returned by Handle.
+type Output struct {
+	// Items stores the records included in the current page.
+	Items []game.Game
+
+	// NextPageToken stores the opaque continuation token. It is empty
+	// when the current page is the last one.
+	NextPageToken string
+}
+
+// Handle assembles the candidate set, sorts it deterministically, and
+// returns the requested page together with the next-page token.
+func (service *Service) Handle(ctx context.Context, input Input) (Output, error) {
+	if service == nil {
+		return Output{}, errors.New("list games: nil service")
+	}
+	if ctx == nil {
+		return Output{}, errors.New("list games: nil context")
+	}
+	if err := input.Actor.Validate(); err != nil {
+		return Output{}, fmt.Errorf("list games: actor: %w", err)
+	}
+
+	candidates, err := service.collect(ctx, input.Actor)
+	if err != nil {
+		return Output{}, fmt.Errorf("list games: %w", err)
+	}
+
+	sortRecords(candidates)
+
+	start, end, nextOffset, hasMore := shared.Window(len(candidates), input.Page)
+	out := Output{Items: append([]game.Game(nil), candidates[start:end]...)}
+	if hasMore {
+		out.NextPageToken = shared.EncodeToken(nextOffset)
+	}
+	return out, nil
+}
+
+// collect builds the deduplicated candidate set per actor class.
+func (service *Service) collect(ctx context.Context, actor shared.Actor) ([]game.Game, error) {
+	if actor.IsAdmin() {
+		return service.collectAdmin(ctx)
+	}
+	return service.collectUser(ctx, actor.UserID)
+}
+
+func (service *Service) collectAdmin(ctx context.Context) ([]game.Game, error) {
+	seen := make(map[common.GameID]struct{})
+	candidates := make([]game.Game, 0)
+	for _, status := range adminAllStatuses {
+		records, err := service.games.GetByStatus(ctx, status)
+		if err != nil {
+			return nil, err
+		}
+		for _, record := range records {
+			if _, dup := seen[record.GameID]; dup {
+				continue
+			}
+			seen[record.GameID] = struct{}{}
+			candidates = append(candidates, record)
+		}
+	}
+	return candidates, nil
+}
+
+func (service *Service) collectUser(ctx context.Context, userID string) ([]game.Game, error) {
+	seen := make(map[common.GameID]struct{})
+	candidates := make([]game.Game, 0)
+
+	for _, status := range publicVisibleStatuses {
+		records, err := service.games.GetByStatus(ctx, status)
+		if err != nil {
+			return nil, err
+		}
+		for _, record := range records {
+			if record.GameType != game.GameTypePublic {
+				continue
+			}
+			if _, dup := seen[record.GameID]; dup {
+				continue
+			}
+			seen[record.GameID] = struct{}{}
+			candidates = append(candidates, record)
+		}
+	}
+
+	memberships, err := service.memberships.GetByUser(ctx, userID)
+	if err != nil {
+		return nil, err
+	}
+	for _, mb := range memberships {
+		if _, dup := seen[mb.GameID]; dup {
+			continue
+		}
+		record, err := service.games.Get(ctx, mb.GameID)
+		if err != nil {
+			if errors.Is(err, game.ErrNotFound) {
+				service.logger.WarnContext(ctx, "membership references missing game",
+					"user_id", userID,
+					"game_id", mb.GameID.String(),
+				)
+				continue
+			}
+			return nil, err
+		}
+		if record.GameType != game.GameTypePrivate {
+			continue
+		}
+		if _, excluded := privateMembershipExcludedStatuses[record.Status]; excluded {
+			continue
+		}
+		seen[record.GameID] = struct{}{}
+		candidates = append(candidates, record)
+	}
+
+	return candidates, nil
+}
+
+// statusGroup returns the bucket index used to order records per
+// README §«Public game list»: enrollment_open and ready_to_start come
+// first, then running, then finished. Other statuses surface only on
+// the admin or user-private paths and are appended afterwards in a
+// stable order so `next_page_token` is deterministic.
+func statusGroup(status game.Status) int {
+	switch status {
+	case game.StatusEnrollmentOpen, game.StatusReadyToStart:
+		return 0
+	case game.StatusRunning:
+		return 1
+	case game.StatusFinished:
+		return 2
+	case game.StatusPaused:
+		return 3
+	case game.StatusStarting:
+		return 4
+	case game.StatusStartFailed:
+		return 5
+	case game.StatusDraft:
+		return 6
+	case game.StatusCancelled:
+		return 7
+	default:
+		return 8
+	}
+}
+
+// sortRecords sorts the candidate set per the documented ordering. The
+// secondary key is CreatedAt descending («most recent first within each
+// group»), and the tertiary key is GameID ascending for stable output
+// when two records share the same group and CreatedAt.
+func sortRecords(items []game.Game) {
+	sort.Slice(items, func(i, j int) bool {
+		gi, gj := statusGroup(items[i].Status), statusGroup(items[j].Status)
+		if gi != gj {
+			return gi < gj
+		}
+		if !items[i].CreatedAt.Equal(items[j].CreatedAt) {
+			return items[i].CreatedAt.After(items[j].CreatedAt)
+		}
+		return items[i].GameID < items[j].GameID
+	})
+}

lobby/internal/service/listgames/service_test.go

@@ -0,0 +1,302 @@
+package listgames_test
+
+import (
+	"context"
+	"io"
+	"log/slog"
+	"testing"
+	"time"
+
+	"galaxy/lobby/internal/adapters/gamestub"
+	"galaxy/lobby/internal/adapters/membershipstub"
+	"galaxy/lobby/internal/domain/common"
+	"galaxy/lobby/internal/domain/game"
+	"galaxy/lobby/internal/domain/membership"
+	"galaxy/lobby/internal/service/listgames"
+	"galaxy/lobby/internal/service/shared"
+
+	"github.com/stretchr/testify/require"
+)
+
+func silentLogger() *slog.Logger {
+	return slog.New(slog.NewTextHandler(io.Discard, nil))
+}
+
+type fixture struct {
+	games       *gamestub.Store
+	memberships *membershipstub.Store
+	svc         *listgames.Service
+}
+
+func newFixture(t *testing.T) *fixture {
+	t.Helper()
+	games := gamestub.NewStore()
+	memberships := membershipstub.NewStore()
+	svc, err := listgames.NewService(listgames.Dependencies{
+		Games:       games,
+		Memberships: memberships,
+		Logger:      silentLogger(),
+	})
+	require.NoError(t, err)
+	return &fixture{games: games, memberships: memberships, svc: svc}
+}
+
+func seedGameAt(
+	t *testing.T,
+	store *gamestub.Store,
+	id common.GameID,
+	gameType game.GameType,
+	ownerUserID string,
+	status game.Status,
+	createdAt time.Time,
+) game.Game {
+	t.Helper()
+	record, err := game.New(game.NewGameInput{
+		GameID:              id,
+		GameName:            "Seed",
+		GameType:            gameType,
+		OwnerUserID:         ownerUserID,
+		MinPlayers:          2,
+		MaxPlayers:          4,
+		StartGapHours:       4,
+		StartGapPlayers:     1,
+		EnrollmentEndsAt:    createdAt.Add(24 * time.Hour),
+		TurnSchedule:        "0 */6 * * *",
+		TargetEngineVersion: "1.0.0",
+		Now:                 createdAt,
+	})
+	require.NoError(t, err)
+	if status != game.StatusDraft {
+		record.Status = status
+		record.UpdatedAt = createdAt.Add(time.Minute)
+	}
+	require.NoError(t, store.Save(context.Background(), record))
+	return record
+}
+
+func seedActiveMembership(
+	t *testing.T,
+	store *membershipstub.Store,
+	gameID common.GameID,
+	userID string,
+	now time.Time,
+) {
+	t.Helper()
+	record, err := membership.New(membership.NewMembershipInput{
+		MembershipID: common.MembershipID("membership-" + userID + "-" + gameID.String()),
+		GameID:       gameID,
+		UserID:       userID,
+		RaceName:     "Race-" + userID,
+		CanonicalKey: "race-" + userID,
+		Now:          now,
+	})
+	require.NoError(t, err)
+	require.NoError(t, store.Save(context.Background(), record))
+}
+
+func TestHandlePublicListExcludesDraftAndCancelled(t *testing.T) {
+	t.Parallel()
+	fix := newFixture(t)
+	now := time.Date(2025, 6, 1, 12, 0, 0, 0, time.UTC)
+
+	included := []game.Status{
+		game.StatusEnrollmentOpen, game.StatusReadyToStart,
+		game.StatusRunning, game.StatusFinished,
+	}
+	excluded := []game.Status{
+		game.StatusDraft, game.StatusCancelled, game.StatusPaused,
+		game.StatusStarting, game.StatusStartFailed,
+	}
+	for i, status := range included {
+		id := common.GameID("game-public-incl-" + string(status))
+		seedGameAt(t, fix.games, id, game.GameTypePublic, "", status, now.Add(time.Duration(i)*time.Minute))
+	}
+	for i, status := range excluded {
+		id := common.GameID("game-public-excl-" + string(status))
+		seedGameAt(t, fix.games, id, game.GameTypePublic, "", status, now.Add(time.Duration(i)*time.Minute))
+	}
+
+	out, err := fix.svc.Handle(context.Background(), listgames.Input{
+		Actor: shared.NewUserActor("user-stranger"),
+	})
+	require.NoError(t, err)
+	require.Len(t, out.Items, len(included))
+	for _, item := range out.Items {
+		require.Equal(t, game.GameTypePublic, item.GameType)
+		require.Contains(t, included, item.Status)
+	}
+	require.Empty(t, out.NextPageToken)
+}
+
+func TestHandlePublicListExcludesPrivateForStranger(t *testing.T) {
+	t.Parallel()
+	fix := newFixture(t)
+	now := time.Date(2025, 6, 1, 12, 0, 0, 0, time.UTC)
+	seedGameAt(t, fix.games, "game-private-1", game.GameTypePrivate, "user-owner",
+		game.StatusEnrollmentOpen, now)
+
+	out, err := fix.svc.Handle(context.Background(), listgames.Input{
+		Actor: shared.NewUserActor("user-stranger"),
+	})
+	require.NoError(t, err)
+	require.Empty(t, out.Items)
+}
+
+func TestHandleUserSeesOwnPrivateGames(t *testing.T) {
+	t.Parallel()
+	fix := newFixture(t)
+	now := time.Date(2025, 6, 1, 12, 0, 0, 0, time.UTC)
+	publicID := common.GameID("game-public-1")
+	seedGameAt(t, fix.games, publicID, game.GameTypePublic, "", game.StatusEnrollmentOpen, now)
+	privateID := common.GameID("game-private-mine")
+	seedGameAt(t, fix.games, privateID, game.GameTypePrivate, "user-owner", game.StatusRunning, now.Add(time.Minute))
+	seedActiveMembership(t, fix.memberships, privateID, "user-member", now)
+
+	out, err := fix.svc.Handle(context.Background(), listgames.Input{
+		Actor: shared.NewUserActor("user-member"),
+	})
+	require.NoError(t, err)
+	require.Len(t, out.Items, 2)
+
+	gotIDs := []common.GameID{out.Items[0].GameID, out.Items[1].GameID}
+	require.Contains(t, gotIDs, publicID)
+	require.Contains(t, gotIDs, privateID)
+}
+
+func TestHandleDedupesPrivateAlreadyVisible(t *testing.T) {
+	// A public game where the user also has a membership must appear
+	// only once in the response.
+	t.Parallel()
+	fix := newFixture(t)
+	now := time.Date(2025, 6, 1, 12, 0, 0, 0, time.UTC)
+	id := common.GameID("game-public-dedup")
+	seedGameAt(t, fix.games, id, game.GameTypePublic, "", game.StatusRunning, now)
+	seedActiveMembership(t, fix.memberships, id, "user-1", now)
+
+	out, err := fix.svc.Handle(context.Background(), listgames.Input{
+		Actor: shared.NewUserActor("user-1"),
+	})
+	require.NoError(t, err)
+	require.Len(t, out.Items, 1)
+}
+
+func TestHandlePrivateGameDraftHidden(t *testing.T) {
+	t.Parallel()
+	fix := newFixture(t)
+	now := time.Date(2025, 6, 1, 12, 0, 0, 0, time.UTC)
+	id := common.GameID("game-private-draft")
+	seedGameAt(t, fix.games, id, game.GameTypePrivate, "user-owner", game.StatusDraft, now)
+	seedActiveMembership(t, fix.memberships, id, "user-member", now)
+
+	out, err := fix.svc.Handle(context.Background(), listgames.Input{
+		Actor: shared.NewUserActor("user-member"),
+	})
+	require.NoError(t, err)
+	require.Empty(t, out.Items)
+}
+
+func TestHandleAdminSeesAllStatuses(t *testing.T) {
+	t.Parallel()
+	fix := newFixture(t)
+	now := time.Date(2025, 6, 1, 12, 0, 0, 0, time.UTC)
+	statuses := []game.Status{
+		game.StatusDraft, game.StatusEnrollmentOpen, game.StatusReadyToStart,
+		game.StatusStarting, game.StatusStartFailed, game.StatusRunning,
+		game.StatusPaused, game.StatusFinished, game.StatusCancelled,
+	}
+	for i, status := range statuses {
+		id := common.GameID("game-admin-" + string(status))
+		seedGameAt(t, fix.games, id, game.GameTypePublic, "", status, now.Add(time.Duration(i)*time.Minute))
+	}
+
+	out, err := fix.svc.Handle(context.Background(), listgames.Input{
+		Actor: shared.NewAdminActor(),
+		Page:  shared.Page{Size: 50},
+	})
+	require.NoError(t, err)
+	require.Len(t, out.Items, len(statuses))
+}
+
+func TestHandleSortGroupAndCreatedAt(t *testing.T) {
+	t.Parallel()
+	fix := newFixture(t)
+	base := time.Date(2025, 6, 1, 12, 0, 0, 0, time.UTC)
+
+	seedGameAt(t, fix.games, "game-running-old", game.GameTypePublic, "", game.StatusRunning, base)
+	seedGameAt(t, fix.games, "game-running-new", game.GameTypePublic, "", game.StatusRunning, base.Add(2*time.Hour))
+	seedGameAt(t, fix.games, "game-finished", game.GameTypePublic, "", game.StatusFinished, base.Add(time.Hour))
+	seedGameAt(t, fix.games, "game-enroll", game.GameTypePublic, "", game.StatusEnrollmentOpen, base.Add(30*time.Minute))
+	seedGameAt(t, fix.games, "game-ready", game.GameTypePublic, "", game.StatusReadyToStart, base.Add(45*time.Minute))
+
+	out, err := fix.svc.Handle(context.Background(), listgames.Input{
+		Actor: shared.NewUserActor("user-1"),
+	})
+	require.NoError(t, err)
+	require.Len(t, out.Items, 5)
+
+	// Group 0: ready-to-start (created later) before enroll (created earlier).
+	require.Equal(t, common.GameID("game-ready"), out.Items[0].GameID)
+	require.Equal(t, common.GameID("game-enroll"), out.Items[1].GameID)
+	// Group 1: running, descending CreatedAt.
+	require.Equal(t, common.GameID("game-running-new"), out.Items[2].GameID)
+	require.Equal(t, common.GameID("game-running-old"), out.Items[3].GameID)
+	// Group 2: finished.
+	require.Equal(t, common.GameID("game-finished"), out.Items[4].GameID)
+}
+
+func TestHandlePagination(t *testing.T) {
+	t.Parallel()
+	fix := newFixture(t)
+	base := time.Date(2025, 6, 1, 12, 0, 0, 0, time.UTC)
+	for i := range 5 {
+		id := common.GameID("game-page-" + string(rune('a'+i)))
+		seedGameAt(t, fix.games, id, game.GameTypePublic, "", game.StatusRunning,
+			base.Add(time.Duration(i)*time.Minute))
+	}
+
+	first, err := fix.svc.Handle(context.Background(), listgames.Input{
+		Actor: shared.NewUserActor("user-1"),
+		Page:  shared.Page{Size: 2},
+	})
+	require.NoError(t, err)
+	require.Len(t, first.Items, 2)
+	require.NotEmpty(t, first.NextPageToken)
+
+	page2, err := shared.ParsePage("2", first.NextPageToken)
+	require.NoError(t, err)
+	second, err := fix.svc.Handle(context.Background(), listgames.Input{
+		Actor: shared.NewUserActor("user-1"),
+		Page:  page2,
+	})
+	require.NoError(t, err)
+	require.Len(t, second.Items, 2)
+	require.NotEmpty(t, second.NextPageToken)
+
+	page3, err := shared.ParsePage("2", second.NextPageToken)
+	require.NoError(t, err)
+	third, err := fix.svc.Handle(context.Background(), listgames.Input{
+		Actor: shared.NewUserActor("user-1"),
+		Page:  page3,
+	})
+	require.NoError(t, err)
+	require.Len(t, third.Items, 1)
+	require.Empty(t, third.NextPageToken)
+}
+
+func TestNewServiceRejectsMissingDeps(t *testing.T) {
+	t.Parallel()
+	cases := []struct {
+		name string
+		deps listgames.Dependencies
+	}{
+		{"nil games", listgames.Dependencies{Memberships: membershipstub.NewStore()}},
+		{"nil memberships", listgames.Dependencies{Games: gamestub.NewStore()}},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+			_, err := listgames.NewService(tc.deps)
+			require.Error(t, err)
+		})
+	}
+}