local-dev: boot-time dev sandbox provisions a runnable game on up

Adds backend/internal/devsandbox: an idempotent boot-time hook that, when BACKEND_DEV_SANDBOX_EMAIL is set, ensures (1) the configured engine_version row, (2) the real dev user, (3) PlayerCount-1 deterministic dummy users, (4) a private "Dev Sandbox" game with a year-out turn schedule, (5) memberships for every participant via the new lobby.Service.InsertMembershipDirect helper, (6) a drive of the lifecycle to running. Re-running on a populated DB is a no-op; partial states from earlier crashes are recovered. tools/local-dev gains the matching env vars in .env, surfaces them in compose, and acquires a `make build-engine` target that builds galaxy-engine:local-dev from game/Dockerfile (a prerequisite of `up`/`rebuild`). The compose game-state mount is changed from a named volume to a host bind on /tmp/galaxy-game-state so backend's bind-mount source for spawned engine containers resolves on the docker daemon. After `make -C tools/local-dev up`, login as dev@local.test with the dev code 123456 and the Dev Sandbox already shows up in My Games. Per-user behaviour for the same email survives a backend restart. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-08 15:51:09 +02:00
parent 73fb0ae968
commit e63748c344
9 changed files with 559 additions and 8 deletions
@@ -24,6 +24,7 @@ import (
 	"galaxy/backend/internal/app"
 	"galaxy/backend/internal/auth"
 	"galaxy/backend/internal/config"
+	"galaxy/backend/internal/devsandbox"
 	"galaxy/backend/internal/dockerclient"
 	"galaxy/backend/internal/engineclient"
 	"galaxy/backend/internal/geo"
@@ -265,6 +266,14 @@ func run(ctx context.Context) (err error) {
 	)
 	runtimeGateway.svc = runtimeSvc

+	if err := devsandbox.Bootstrap(ctx, devsandbox.Deps{
+		Users:          userSvc,
+		Lobby:          lobbySvc,
+		EngineVersions: engineVersionSvc,
+	}, cfg.DevSandbox, logger); err != nil {
+		return fmt.Errorf("dev sandbox bootstrap: %w", err)
+	}
+
 	notifStore := notification.NewStore(db)
 	notifSvc := notification.NewService(notification.Deps{
 		Store:    notifStore,
@@ -95,6 +95,11 @@ const (
 	envNotificationAdminEmail = "BACKEND_NOTIFICATION_ADMIN_EMAIL"
 	envNotificationWorkerInterval = "BACKEND_NOTIFICATION_WORKER_INTERVAL"
 	envNotificationMaxAttempts = "BACKEND_NOTIFICATION_MAX_ATTEMPTS"
+
+	envDevSandboxEmail = "BACKEND_DEV_SANDBOX_EMAIL"
+	envDevSandboxEngineImage = "BACKEND_DEV_SANDBOX_ENGINE_IMAGE"
+	envDevSandboxEngineVersion = "BACKEND_DEV_SANDBOX_ENGINE_VERSION"
+	envDevSandboxPlayerCount = "BACKEND_DEV_SANDBOX_PLAYER_COUNT"
 )

 // Default values applied when an environment variable is absent.
@@ -157,6 +162,9 @@ const (

 	defaultNotificationWorkerInterval = 5 * time.Second
 	defaultNotificationMaxAttempts = 8
+
+	defaultDevSandboxEngineVersion = "0.1.0"
+	defaultDevSandboxPlayerCount = 20
 )

 // Allowed values for the closed-set string options.
@@ -193,12 +201,29 @@ type Config struct {
 	Engine EngineConfig
 	Runtime RuntimeConfig
 	Notification NotificationConfig
+	DevSandbox DevSandboxConfig

 	// FreshnessWindow mirrors the gateway freshness window and is used by the
 	// push server to bound the cursor TTL.
 	FreshnessWindow time.Duration
 }

+// DevSandboxConfig configures the boot-time bootstrap implemented in
+// `backend/internal/devsandbox`. When Email is empty the bootstrap
+// is a no-op, which is the production posture. When Email is set —
+// from `BACKEND_DEV_SANDBOX_EMAIL` in the `tools/local-dev` stack —
+// the bootstrap idempotently provisions a real user, the configured
+// number of dummy participants, a private "Dev Sandbox" game, the
+// matching memberships, and drives the lifecycle to `running`. The
+// engine image and engine version refer to a row that the bootstrap
+// also seeds in `engine_versions`.
+type DevSandboxConfig struct {
+	Email string
+	EngineImage string
+	EngineVersion string
+	PlayerCount int
+}
+
 // LoggingConfig stores the parameters used by the structured logger.
 type LoggingConfig struct {
 	// Level is the zap level name (e.g. "debug", "info", "warn", "error").
@@ -469,6 +494,10 @@ func DefaultConfig() Config {
 			WorkerInterval: defaultNotificationWorkerInterval,
 			MaxAttempts: defaultNotificationMaxAttempts,
 		},
+		DevSandbox: DevSandboxConfig{
+			EngineVersion: defaultDevSandboxEngineVersion,
+			PlayerCount: defaultDevSandboxPlayerCount,
+		},
 		Runtime: RuntimeConfig{
 			WorkerPoolSize: defaultRuntimeWorkerPoolSize,
 			JobQueueSize: defaultRuntimeJobQueueSize,
@@ -628,6 +657,13 @@ func LoadFromEnv() (Config, error) {
 		return Config{}, err
 	}

+	cfg.DevSandbox.Email = strings.TrimSpace(loadString(envDevSandboxEmail, cfg.DevSandbox.Email))
+	cfg.DevSandbox.EngineImage = strings.TrimSpace(loadString(envDevSandboxEngineImage, cfg.DevSandbox.EngineImage))
+	cfg.DevSandbox.EngineVersion = strings.TrimSpace(loadString(envDevSandboxEngineVersion, cfg.DevSandbox.EngineVersion))
+	if cfg.DevSandbox.PlayerCount, err = loadInt(envDevSandboxPlayerCount, cfg.DevSandbox.PlayerCount); err != nil {
+		return Config{}, err
+	}
+
 	if err := cfg.Validate(); err != nil {
 		return Config{}, err
 	}
@@ -823,6 +859,21 @@ func (c Config) Validate() error {
 		}
 	}

+	if email := strings.TrimSpace(c.DevSandbox.Email); email != "" {
+		if _, err := netmail.ParseAddress(email); err != nil {
+			return fmt.Errorf("%s must be a valid RFC 5322 address: %w", envDevSandboxEmail, err)
+		}
+		if strings.TrimSpace(c.DevSandbox.EngineImage) == "" {
+			return fmt.Errorf("%s must not be empty when %s is set", envDevSandboxEngineImage, envDevSandboxEmail)
+		}
+		if strings.TrimSpace(c.DevSandbox.EngineVersion) == "" {
+			return fmt.Errorf("%s must not be empty when %s is set", envDevSandboxEngineVersion, envDevSandboxEmail)
+		}
+		if c.DevSandbox.PlayerCount <= 0 {
+			return fmt.Errorf("%s must be positive when %s is set", envDevSandboxPlayerCount, envDevSandboxEmail)
+		}
+	}
+
 	return nil
 }

@@ -0,0 +1,232 @@
+// Package devsandbox provisions a ready-to-play game on backend boot
+// for the `tools/local-dev` stack.
+//
+// Bootstrap is invoked from `backend/cmd/backend/main.go` after the
+// admin bootstrap and before the HTTP listener starts. It reads
+// `cfg.DevSandbox`; when `Email` is empty (the production posture)
+// the function logs "skipped" and returns nil. When set, it
+// idempotently:
+//
+//   1. registers the configured engine version and image;
+//   2. find-or-creates the real dev user with the configured email;
+//   3. find-or-creates `cfg.PlayerCount - 1` deterministic dummy
+//      users so the engine's minimum-players constraint is met;
+//   4. find-or-creates a private "Dev Sandbox" game owned by the
+//      real user with min/max_players = cfg.PlayerCount and a
+//      year-out turn schedule (effectively frozen at turn 1);
+//   5. inserts memberships for all participants bypassing the
+//      application/approval flow;
+//   6. drives the lifecycle to `running` (or as far as possible if
+//      the runtime is busy).
+//
+// The function is a no-op on subsequent boots once the game is
+// running; partial states from earlier crashes are recovered.
+package devsandbox
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"time"
+
+	"galaxy/backend/internal/config"
+	"galaxy/backend/internal/lobby"
+	"galaxy/backend/internal/runtime"
+
+	"github.com/google/uuid"
+	"go.uber.org/zap"
+)
+
+// SandboxGameName is the display name used to identify the
+// auto-provisioned game on subsequent reboots. The combination of
+// game_name and owner_user_id is unique enough in practice — only
+// the dev sandbox bootstrap creates a game owned by the configured
+// real user with this exact name.
+const SandboxGameName = "Dev Sandbox"
+
+// SandboxTurnSchedule keeps the game on turn 1 by scheduling the
+// next turn a year out. The runtime scheduler still parses this and
+// will tick once a year — long enough to never interfere with
+// solo UI development.
+const SandboxTurnSchedule = "0 0 1 1 *"
+
+// UserEnsurer matches `auth.UserEnsurer`. We define a local
+// interface to avoid importing the auth package and circular
+// dependencies — the production wiring passes the same `*user.Service`
+// instance used by auth.
+type UserEnsurer interface {
+	EnsureByEmail(ctx context.Context, email, preferredLanguage, timeZone, declaredCountry string) (uuid.UUID, error)
+}
+
+// Deps aggregates the collaborators Bootstrap needs.
+type Deps struct {
+	Users          UserEnsurer
+	Lobby          *lobby.Service
+	EngineVersions *runtime.EngineVersionService
+}
+
+// Bootstrap runs the seven-step provisioning flow described on the
+// package doc comment. Errors are returned to the caller; the boot
+// path in `cmd/backend/main.go` aborts startup if Bootstrap fails so
+// a misconfigured dev environment surfaces immediately rather than
+// silently leaving the lobby empty.
+func Bootstrap(ctx context.Context, deps Deps, cfg config.DevSandboxConfig, logger *zap.Logger) error {
+	if logger == nil {
+		logger = zap.NewNop()
+	}
+	logger = logger.Named("dev_sandbox")
+
+	if cfg.Email == "" {
+		logger.Info("skipped (no email)")
+		return nil
+	}
+	if deps.Users == nil || deps.Lobby == nil || deps.EngineVersions == nil {
+		return errors.New("dev_sandbox: deps.Users, deps.Lobby and deps.EngineVersions are required")
+	}
+	if cfg.PlayerCount <= 0 {
+		return fmt.Errorf("dev_sandbox: PlayerCount must be positive, got %d", cfg.PlayerCount)
+	}
+
+	if err := ensureEngineVersion(ctx, deps.EngineVersions, cfg, logger); err != nil {
+		return err
+	}
+
+	realID, err := deps.Users.EnsureByEmail(ctx, cfg.Email, "en", "UTC", "")
+	if err != nil {
+		return fmt.Errorf("dev_sandbox: ensure real user: %w", err)
+	}
+
+	dummyIDs := make([]uuid.UUID, 0, cfg.PlayerCount-1)
+	for i := 1; i < cfg.PlayerCount; i++ {
+		email := fmt.Sprintf("dev-dummy-%02d@local.test", i)
+		id, err := deps.Users.EnsureByEmail(ctx, email, "en", "UTC", "")
+		if err != nil {
+			return fmt.Errorf("dev_sandbox: ensure dummy %d: %w", i, err)
+		}
+		dummyIDs = append(dummyIDs, id)
+	}
+
+	game, err := findOrCreateSandboxGame(ctx, deps.Lobby, realID, cfg)
+	if err != nil {
+		return err
+	}
+
+	game, err = ensureMembershipsAndDrive(ctx, deps.Lobby, game, realID, dummyIDs, logger)
+	if err != nil {
+		return err
+	}
+
+	logger.Info("bootstrap complete",
+		zap.String("user_id", realID.String()),
+		zap.String("game_id", game.GameID.String()),
+		zap.String("status", game.Status),
+	)
+	return nil
+}
+
+func ensureEngineVersion(ctx context.Context, svc *runtime.EngineVersionService, cfg config.DevSandboxConfig, logger *zap.Logger) error {
+	_, err := svc.Register(ctx, runtime.RegisterInput{
+		Version:  cfg.EngineVersion,
+		ImageRef: cfg.EngineImage,
+	})
+	switch {
+	case err == nil:
+		logger.Info("engine version registered",
+			zap.String("version", cfg.EngineVersion),
+			zap.String("image", cfg.EngineImage),
+		)
+		return nil
+	case errors.Is(err, runtime.ErrEngineVersionTaken):
+		logger.Debug("engine version already registered",
+			zap.String("version", cfg.EngineVersion),
+		)
+		return nil
+	default:
+		return fmt.Errorf("dev_sandbox: register engine version: %w", err)
+	}
+}
+
+func findOrCreateSandboxGame(ctx context.Context, svc *lobby.Service, ownerID uuid.UUID, cfg config.DevSandboxConfig) (lobby.GameRecord, error) {
+	games, err := svc.ListMyGames(ctx, ownerID)
+	if err != nil {
+		return lobby.GameRecord{}, fmt.Errorf("dev_sandbox: list my games: %w", err)
+	}
+	for _, g := range games {
+		if g.GameName == SandboxGameName && g.OwnerUserID != nil && *g.OwnerUserID == ownerID {
+			return g, nil
+		}
+	}
+	rec, err := svc.CreateGame(ctx, lobby.CreateGameInput{
+		OwnerUserID:         &ownerID,
+		Visibility:          lobby.VisibilityPrivate,
+		GameName:            SandboxGameName,
+		Description:         "Auto-provisioned by backend/internal/devsandbox for solo UI development.",
+		MinPlayers:          int32(cfg.PlayerCount),
+		MaxPlayers:          int32(cfg.PlayerCount),
+		StartGapHours:       0,
+		StartGapPlayers:     0,
+		EnrollmentEndsAt:    time.Now().Add(365 * 24 * time.Hour),
+		TurnSchedule:        SandboxTurnSchedule,
+		TargetEngineVersion: cfg.EngineVersion,
+	})
+	if err != nil {
+		return lobby.GameRecord{}, fmt.Errorf("dev_sandbox: create game: %w", err)
+	}
+	return rec, nil
+}
+
+func ensureMembershipsAndDrive(ctx context.Context, svc *lobby.Service, game lobby.GameRecord, realID uuid.UUID, dummyIDs []uuid.UUID, logger *zap.Logger) (lobby.GameRecord, error) {
+	caller := realID
+	if game.Status == lobby.GameStatusDraft {
+		next, err := svc.OpenEnrollment(ctx, &caller, false, game.GameID)
+		if err != nil {
+			return game, fmt.Errorf("dev_sandbox: open enrollment: %w", err)
+		}
+		game = next
+	}
+
+	if game.Status == lobby.GameStatusEnrollmentOpen {
+		users := append([]uuid.UUID{realID}, dummyIDs...)
+		for i, uid := range users {
+			raceName := fmt.Sprintf("Sandbox-%02d", i+1)
+			if _, err := svc.InsertMembershipDirect(ctx, lobby.InsertMembershipDirectInput{
+				GameID:   game.GameID,
+				UserID:   uid,
+				RaceName: raceName,
+			}); err != nil {
+				return game, fmt.Errorf("dev_sandbox: insert membership %d: %w", i+1, err)
+			}
+		}
+		next, err := svc.ReadyToStart(ctx, &caller, false, game.GameID)
+		if err != nil {
+			return game, fmt.Errorf("dev_sandbox: ready to start: %w", err)
+		}
+		game = next
+	}
+
+	if game.Status == lobby.GameStatusReadyToStart {
+		next, err := svc.Start(ctx, &caller, false, game.GameID)
+		if err != nil {
+			return game, fmt.Errorf("dev_sandbox: start: %w", err)
+		}
+		game = next
+	}
+
+	if game.Status == lobby.GameStatusStartFailed {
+		next, err := svc.RetryStart(ctx, &caller, false, game.GameID)
+		if err != nil {
+			logger.Warn("retry start failed", zap.Error(err))
+			return game, nil
+		}
+		game = next
+		if game.Status == lobby.GameStatusReadyToStart {
+			next, err := svc.Start(ctx, &caller, false, game.GameID)
+			if err != nil {
+				return game, fmt.Errorf("dev_sandbox: start after retry: %w", err)
+			}
+			game = next
+		}
+	}
+
+	return game, nil
+}
@@ -0,0 +1,86 @@
+package devsandbox
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"galaxy/backend/internal/config"
+
+	"github.com/google/uuid"
+	"go.uber.org/zap"
+)
+
+// TestBootstrapSkippedWhenEmailEmpty exercises the no-op branch: with
+// the production posture (Email == "") Bootstrap must return without
+// touching any dependency. The fact that Users/Lobby/EngineVersions
+// are nil here doubles as a check that the early-return runs first.
+func TestBootstrapSkippedWhenEmailEmpty(t *testing.T) {
+	err := Bootstrap(
+		context.Background(),
+		Deps{},
+		config.DevSandboxConfig{},
+		zap.NewNop(),
+	)
+	if err != nil {
+		t.Fatalf("expected nil error on empty email, got: %v", err)
+	}
+}
+
+// TestBootstrapRejectsZeroPlayerCount confirms the validation
+// short-circuits the flow before any DB call when PlayerCount is
+// non-positive but Email is set. The error path is fast and never
+// dereferences the (still-nil) Users/Lobby deps.
+func TestBootstrapRejectsZeroPlayerCount(t *testing.T) {
+	err := Bootstrap(
+		context.Background(),
+		Deps{Users: stubEnsurer{}, Lobby: nil, EngineVersions: nil},
+		config.DevSandboxConfig{
+			Email:         "dev@local.test",
+			EngineImage:   "galaxy-engine:local-dev",
+			EngineVersion: "0.0.0-local-dev",
+			PlayerCount:   0,
+		},
+		zap.NewNop(),
+	)
+	if err == nil {
+		t.Fatal("expected error on zero PlayerCount, got nil")
+	}
+}
+
+// TestBootstrapRejectsMissingDeps checks that a misconfigured wiring
+// (Email set but one of the required services nil) fails fast rather
+// than panicking when the bootstrap reaches its first service call.
+func TestBootstrapRejectsMissingDeps(t *testing.T) {
+	err := Bootstrap(
+		context.Background(),
+		Deps{Users: stubEnsurer{}, Lobby: nil, EngineVersions: nil},
+		config.DevSandboxConfig{
+			Email:         "dev@local.test",
+			EngineImage:   "galaxy-engine:local-dev",
+			EngineVersion: "0.0.0-local-dev",
+			PlayerCount:   20,
+		},
+		zap.NewNop(),
+	)
+	if err == nil {
+		t.Fatal("expected error on missing deps, got nil")
+	}
+	if !errors.Is(err, errMissingDepsSentinel) && err.Error() == "" {
+		// The exact wording is not part of the contract; this branch
+		// only asserts the error is non-nil and human-readable.
+		t.Fatalf("error has empty message: %v", err)
+	}
+}
+
+// errMissingDepsSentinel exists so the assertion above can compile;
+// the real error is constructed via errors.New inside Bootstrap and
+// is intentionally not exported. The test only needs to confirm the
+// returned error has a message.
+var errMissingDepsSentinel = errors.New("sentinel")
+
+type stubEnsurer struct{}
+
+func (stubEnsurer) EnsureByEmail(_ context.Context, _, _, _, _ string) (uuid.UUID, error) {
+	return uuid.UUID{}, nil
+}
@@ -0,0 +1,96 @@
+package lobby
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/google/uuid"
+)
+
+// InsertMembershipDirectInput is the parameter struct for
+// Service.InsertMembershipDirect.
+type InsertMembershipDirectInput struct {
+	GameID   uuid.UUID
+	UserID   uuid.UUID
+	RaceName string
+}
+
+// InsertMembershipDirect grants a membership to userID inside gameID
+// bypassing the application/approval flow. It performs the same DB
+// writes as ApproveApplication: the per-game race-name reservation
+// row plus the membership row, and refreshes the in-memory caches.
+//
+// The method is intended for boot-time provisioning by
+// `backend/internal/devsandbox` and similar trusted callers. It is
+// not exposed through any HTTP handler. The caller must guarantee
+// game.Status == GameStatusEnrollmentOpen — the function returns
+// ErrConflict otherwise — and that the race-name policy and
+// canonical-key invariants are honoured (the implementation reuses
+// the lobby's own Policy and assertRaceNameAvailable so a duplicate
+// or unsuitable name still fails).
+//
+// Idempotency: if a membership for (GameID, UserID) already exists
+// the function returns the existing row without modifying state.
+// This makes the helper safe to call on every backend boot from
+// devsandbox.Bootstrap.
+func (s *Service) InsertMembershipDirect(ctx context.Context, in InsertMembershipDirectInput) (Membership, error) {
+	displayName, err := ValidateDisplayName(in.RaceName)
+	if err != nil {
+		return Membership{}, err
+	}
+	game, err := s.GetGame(ctx, in.GameID)
+	if err != nil {
+		return Membership{}, err
+	}
+	if game.Status != GameStatusEnrollmentOpen {
+		return Membership{}, fmt.Errorf("%w: game status is %q, want enrollment_open", ErrConflict, game.Status)
+	}
+	canonical, err := s.deps.Policy.Canonical(displayName)
+	if err != nil {
+		return Membership{}, err
+	}
+	existing, err := s.deps.Store.ListMembershipsForGame(ctx, in.GameID)
+	if err != nil {
+		return Membership{}, err
+	}
+	for _, m := range existing {
+		if m.UserID == in.UserID && m.Status == MembershipStatusActive {
+			return m, nil
+		}
+	}
+	if err := s.assertRaceNameAvailable(ctx, canonical, in.UserID, in.GameID); err != nil {
+		return Membership{}, err
+	}
+	now := s.deps.Now().UTC()
+	if _, err := s.deps.Store.InsertRaceName(ctx, raceNameInsert{
+		Name:        displayName,
+		Canonical:   canonical,
+		Status:      RaceNameStatusReservation,
+		OwnerUserID: in.UserID,
+		GameID:      in.GameID,
+		ReservedAt:  &now,
+	}); err != nil {
+		return Membership{}, err
+	}
+	membership, err := s.deps.Store.InsertMembership(ctx, membershipInsert{
+		MembershipID: uuid.New(),
+		GameID:       in.GameID,
+		UserID:       in.UserID,
+		RaceName:     displayName,
+		CanonicalKey: canonical,
+	})
+	if err != nil {
+		_ = s.deps.Store.DeleteRaceName(ctx, canonical, in.GameID)
+		return Membership{}, err
+	}
+	s.deps.Cache.PutMembership(membership)
+	s.deps.Cache.PutRaceName(RaceNameEntry{
+		Name:        displayName,
+		Canonical:   canonical,
+		Status:      RaceNameStatusReservation,
+		OwnerUserID: in.UserID,
+		GameID:      in.GameID,
+		ReservedAt:  &now,
+	})
+	return membership, nil
+}