feat: game lobby service

2026-04-25 23:20:55 +02:00
parent 32dc29359a
commit 48b0056b49
336 changed files with 57074 additions and 1418 deletions
@@ -0,0 +1,187 @@
+// Package startgame implements the `lobby.game.start` message type. It
+// validates the actor authorization, transitions the game from
+// `ready_to_start` to `starting` via a CAS update, and publishes the
+// start job to Runtime Manager. The remainder of the start sequence
+// (Runtime Manager result + Game Master registration) lives in the
+// runtimejobresult worker.
+package startgame
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"log/slog"
+	"time"
+
+	"galaxy/lobby/internal/domain/common"
+	"galaxy/lobby/internal/domain/game"
+	"galaxy/lobby/internal/logging"
+	"galaxy/lobby/internal/ports"
+	"galaxy/lobby/internal/service/shared"
+	"galaxy/lobby/internal/telemetry"
+)
+
+// Service executes the start-game use case.
+type Service struct {
+	games          ports.GameStore
+	runtimeManager ports.RuntimeManager
+	clock          func() time.Time
+	logger         *slog.Logger
+	telemetry      *telemetry.Runtime
+}
+
+// Dependencies groups the collaborators used by Service.
+type Dependencies struct {
+	// Games mediates the CAS status transition and the result read.
+	Games ports.GameStore
+
+	// RuntimeManager publishes the start job after the CAS succeeds.
+	RuntimeManager ports.RuntimeManager
+
+	// Clock supplies the wall-clock used for UpdatedAt. Defaults to
+	// time.Now when nil.
+	Clock func() time.Time
+
+	// Logger records structured service-level events. Defaults to
+	// slog.Default when nil.
+	Logger *slog.Logger
+
+	// Telemetry records the `lobby.game.transitions` counter on each
+	// successful start. Optional; nil disables metric emission.
+	Telemetry *telemetry.Runtime
+}
+
+// NewService constructs one Service with deps.
+func NewService(deps Dependencies) (*Service, error) {
+	switch {
+	case deps.Games == nil:
+		return nil, errors.New("new start game service: nil game store")
+	case deps.RuntimeManager == nil:
+		return nil, errors.New("new start game service: nil runtime manager")
+	}
+
+	clock := deps.Clock
+	if clock == nil {
+		clock = time.Now
+	}
+	logger := deps.Logger
+	if logger == nil {
+		logger = slog.Default()
+	}
+
+	return &Service{
+		games:          deps.Games,
+		runtimeManager: deps.RuntimeManager,
+		clock:          clock,
+		logger:         logger.With("service", "lobby.startgame"),
+		telemetry:      deps.Telemetry,
+	}, nil
+}
+
+// Input stores the arguments required to start one game.
+type Input struct {
+	// Actor identifies the caller.
+	Actor shared.Actor
+
+	// GameID identifies the target game record.
+	GameID common.GameID
+}
+
+// Handle authorizes the actor, asserts the game is in `ready_to_start`,
+// transitions it to `starting`, and publishes the start job to Runtime
+// Manager. The CAS guarantees that two concurrent start commands cannot
+// both succeed.
+//
+// On Runtime Manager publish failure the game record stays in
+// `starting`; the caller is informed through the returned error. The
+// next start attempt will be rejected with game.ErrConflict because the
+// status is no longer `ready_to_start`. The runtimejobresult worker
+// resolves the situation when (or if) a job result later arrives;
+// otherwise an admin must intervene through tooling. This
+// trade-off is documented in the decision record.
+func (service *Service) Handle(ctx context.Context, input Input) (game.Game, error) {
+	if service == nil {
+		return game.Game{}, errors.New("start game: nil service")
+	}
+	if ctx == nil {
+		return game.Game{}, errors.New("start game: nil context")
+	}
+	if err := input.Actor.Validate(); err != nil {
+		return game.Game{}, fmt.Errorf("start game: actor: %w", err)
+	}
+	if err := input.GameID.Validate(); err != nil {
+		return game.Game{}, fmt.Errorf("start game: %w", err)
+	}
+
+	record, err := service.games.Get(ctx, input.GameID)
+	if err != nil {
+		return game.Game{}, fmt.Errorf("start game: %w", err)
+	}
+	if err := authorize(input.Actor, record); err != nil {
+		return game.Game{}, err
+	}
+	if record.Status != game.StatusReadyToStart {
+		return game.Game{}, fmt.Errorf(
+			"start game: status %q is not %q: %w",
+			record.Status, game.StatusReadyToStart, game.ErrConflict,
+		)
+	}
+
+	at := service.clock().UTC()
+	if err := service.games.UpdateStatus(ctx, ports.UpdateStatusInput{
+		GameID:       input.GameID,
+		ExpectedFrom: game.StatusReadyToStart,
+		To:           game.StatusStarting,
+		Trigger:      game.TriggerCommand,
+		At:           at,
+	}); err != nil {
+		return game.Game{}, fmt.Errorf("start game: %w", err)
+	}
+
+	service.telemetry.RecordGameTransition(ctx,
+		string(game.StatusReadyToStart),
+		string(game.StatusStarting),
+		string(game.TriggerCommand),
+	)
+
+	if err := service.runtimeManager.PublishStartJob(ctx, input.GameID.String()); err != nil {
+		// Status is already `starting` and the domain forbids a direct
+		// rollback to `ready_to_start`. We surface the publish error to
+		// the caller; the game stays in `starting` until either a
+		// runtime job result arrives (worker handles the outcome) or an
+		// admin intervenes manually.
+		service.logger.ErrorContext(ctx, "publish runtime start job",
+			"game_id", input.GameID.String(),
+			"err", err.Error(),
+		)
+		return game.Game{}, fmt.Errorf("start game: %w", errors.Join(shared.ErrServiceUnavailable, err))
+	}
+
+	updated, err := service.games.Get(ctx, input.GameID)
+	if err != nil {
+		return game.Game{}, fmt.Errorf("start game: %w", err)
+	}
+
+	logArgs := []any{
+		"game_id", updated.GameID.String(),
+		"from_status", string(game.StatusReadyToStart),
+		"to_status", string(updated.Status),
+		"trigger", string(game.TriggerCommand),
+		"actor_kind", string(input.Actor.Kind),
+	}
+	logArgs = append(logArgs, logging.ContextAttrs(ctx)...)
+	service.logger.InfoContext(ctx, "game start job published", logArgs...)
+	return updated, nil
+}
+
+// authorize enforces admin OR private-owner access to the record.
+func authorize(actor shared.Actor, record game.Game) error {
+	if actor.IsAdmin() {
+		return nil
+	}
+	if record.GameType == game.GameTypePrivate && actor.UserID == record.OwnerUserID {
+		return nil
+	}
+	return fmt.Errorf("%w: actor is not authorized to start game %q",
+		shared.ErrForbidden, record.GameID.String())
+}
@@ -0,0 +1,209 @@
+package startgame_test
+
+import (
+	"context"
+	"errors"
+	"io"
+	"log/slog"
+	"testing"
+	"time"
+
+	"galaxy/lobby/internal/adapters/gamestub"
+	"galaxy/lobby/internal/adapters/runtimemanagerstub"
+	"galaxy/lobby/internal/domain/common"
+	"galaxy/lobby/internal/domain/game"
+	"galaxy/lobby/internal/ports"
+	"galaxy/lobby/internal/service/shared"
+	"galaxy/lobby/internal/service/startgame"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func silentLogger() *slog.Logger {
+	return slog.New(slog.NewTextHandler(io.Discard, nil))
+}
+
+func fixedClock(at time.Time) func() time.Time {
+	return func() time.Time { return at }
+}
+
+func newReadyGame(t *testing.T, gameType game.GameType, ownerID string) (game.Game, time.Time) {
+	t.Helper()
+	now := time.Date(2026, 4, 25, 12, 0, 0, 0, time.UTC)
+	record, err := game.New(game.NewGameInput{
+		GameID:              common.GameID("game-1"),
+		GameName:            "test game",
+		GameType:            gameType,
+		OwnerUserID:         ownerID,
+		MinPlayers:          4,
+		MaxPlayers:          8,
+		StartGapHours:       12,
+		StartGapPlayers:     2,
+		EnrollmentEndsAt:    now.Add(24 * time.Hour),
+		TurnSchedule:        "0 18 * * *",
+		TargetEngineVersion: "v1.0.0",
+		Now:                 now,
+	})
+	require.NoError(t, err)
+	record.Status = game.StatusReadyToStart
+	return record, now
+}
+
+type fixture struct {
+	games   *gamestub.Store
+	runtime *runtimemanagerstub.Publisher
+	service *startgame.Service
+	now     time.Time
+}
+
+func newFixture(t *testing.T, record game.Game, now time.Time) *fixture {
+	t.Helper()
+	games := gamestub.NewStore()
+	require.NoError(t, games.Save(context.Background(), record))
+	runtime := runtimemanagerstub.NewPublisher()
+	service, err := startgame.NewService(startgame.Dependencies{
+		Games:          games,
+		RuntimeManager: runtime,
+		Clock:          fixedClock(now.Add(time.Hour)),
+		Logger:         silentLogger(),
+	})
+	require.NoError(t, err)
+	return &fixture{games: games, runtime: runtime, service: service, now: now}
+}
+
+func TestNewServiceRejectsMissingDeps(t *testing.T) {
+	_, err := startgame.NewService(startgame.Dependencies{
+		RuntimeManager: runtimemanagerstub.NewPublisher(),
+	})
+	require.Error(t, err)
+
+	_, err = startgame.NewService(startgame.Dependencies{
+		Games: gamestub.NewStore(),
+	})
+	require.Error(t, err)
+}
+
+func TestStartGamePublicAdminHappyPath(t *testing.T) {
+	record, now := newReadyGame(t, game.GameTypePublic, "")
+	f := newFixture(t, record, now)
+
+	updated, err := f.service.Handle(context.Background(), startgame.Input{
+		Actor:  shared.NewAdminActor(),
+		GameID: record.GameID,
+	})
+	require.NoError(t, err)
+	assert.Equal(t, game.StatusStarting, updated.Status)
+	assert.Equal(t, []string{record.GameID.String()}, f.runtime.StartJobs())
+	assert.Empty(t, f.runtime.StopJobs())
+}
+
+func TestStartGamePrivateOwnerHappyPath(t *testing.T) {
+	record, now := newReadyGame(t, game.GameTypePrivate, "user-owner")
+	f := newFixture(t, record, now)
+
+	updated, err := f.service.Handle(context.Background(), startgame.Input{
+		Actor:  shared.NewUserActor("user-owner"),
+		GameID: record.GameID,
+	})
+	require.NoError(t, err)
+	assert.Equal(t, game.StatusStarting, updated.Status)
+	assert.Equal(t, []string{record.GameID.String()}, f.runtime.StartJobs())
+}
+
+func TestStartGameRejectsNonOwnerUser(t *testing.T) {
+	record, now := newReadyGame(t, game.GameTypePrivate, "user-owner")
+	f := newFixture(t, record, now)
+
+	_, err := f.service.Handle(context.Background(), startgame.Input{
+		Actor:  shared.NewUserActor("user-other"),
+		GameID: record.GameID,
+	})
+	require.ErrorIs(t, err, shared.ErrForbidden)
+	assert.Empty(t, f.runtime.StartJobs(), "no start job published on forbidden")
+
+	stored, err := f.games.Get(context.Background(), record.GameID)
+	require.NoError(t, err)
+	assert.Equal(t, game.StatusReadyToStart, stored.Status, "status must remain ready_to_start")
+}
+
+func TestStartGameRejectsPublicUserActor(t *testing.T) {
+	record, now := newReadyGame(t, game.GameTypePublic, "")
+	f := newFixture(t, record, now)
+
+	_, err := f.service.Handle(context.Background(), startgame.Input{
+		Actor:  shared.NewUserActor("user-1"),
+		GameID: record.GameID,
+	})
+	require.ErrorIs(t, err, shared.ErrForbidden)
+}
+
+func TestStartGameRejectsWrongStatus(t *testing.T) {
+	record, now := newReadyGame(t, game.GameTypePublic, "")
+	record.Status = game.StatusEnrollmentOpen
+	f := newFixture(t, record, now)
+
+	_, err := f.service.Handle(context.Background(), startgame.Input{
+		Actor:  shared.NewAdminActor(),
+		GameID: record.GameID,
+	})
+	require.ErrorIs(t, err, game.ErrConflict)
+	assert.Empty(t, f.runtime.StartJobs())
+}
+
+func TestStartGameRejectsCASLossOnRecentTransition(t *testing.T) {
+	record, now := newReadyGame(t, game.GameTypePublic, "")
+	f := newFixture(t, record, now)
+
+	// Concurrent start: simulate someone moved status to starting.
+	require.NoError(t, f.games.UpdateStatus(context.Background(), ports.UpdateStatusInput{
+		GameID:       record.GameID,
+		ExpectedFrom: game.StatusReadyToStart,
+		To:           game.StatusStarting,
+		Trigger:      game.TriggerCommand,
+		At:           now.Add(time.Minute),
+	}))
+
+	_, err := f.service.Handle(context.Background(), startgame.Input{
+		Actor:  shared.NewAdminActor(),
+		GameID: record.GameID,
+	})
+	require.ErrorIs(t, err, game.ErrConflict)
+	assert.Empty(t, f.runtime.StartJobs())
+}
+
+func TestStartGamePublishFailureSurfacesUnavailable(t *testing.T) {
+	record, now := newReadyGame(t, game.GameTypePublic, "")
+	f := newFixture(t, record, now)
+	f.runtime.SetStartError(errors.New("redis down"))
+
+	_, err := f.service.Handle(context.Background(), startgame.Input{
+		Actor:  shared.NewAdminActor(),
+		GameID: record.GameID,
+	})
+	require.Error(t, err)
+	assert.ErrorIs(t, err, shared.ErrServiceUnavailable)
+
+	stored, err := f.games.Get(context.Background(), record.GameID)
+	require.NoError(t, err)
+	assert.Equal(t, game.StatusStarting, stored.Status,
+		"status remains starting; runtime worker resolves orphan via job result")
+}
+
+func TestStartGameRejectsMissingRecord(t *testing.T) {
+	games := gamestub.NewStore()
+	runtime := runtimemanagerstub.NewPublisher()
+	service, err := startgame.NewService(startgame.Dependencies{
+		Games:          games,
+		RuntimeManager: runtime,
+		Clock:          fixedClock(time.Now().UTC()),
+		Logger:         silentLogger(),
+	})
+	require.NoError(t, err)
+
+	_, err = service.Handle(context.Background(), startgame.Input{
+		Actor:  shared.NewAdminActor(),
+		GameID: common.GameID("game-missing"),
+	})
+	require.ErrorIs(t, err, game.ErrNotFound)
+}