feat: gamemaster

gamemaster/internal/domain/engineversion/model.go

@@ -0,0 +1,121 @@
+// Package engineversion defines the engine version registry domain
+// model owned by Game Master.
+//
+// The registry mirrors the durable shape of the `engine_versions`
+// PostgreSQL table (see
+// `galaxy/gamemaster/internal/adapters/postgres/migrations/00001_init.sql`)
+// and the user-visible status enum frozen in
+// `galaxy/gamemaster/api/internal-openapi.yaml`.
+//
+// `Options` is intentionally kept opaque ([]byte holding raw JSON) so
+// the v1 service does not impose a Go-side schema on the engine-owned
+// document. Schema-aware handling lands when an engine version actually
+// requires it; until then the registry is a pass-through store.
+package engineversion
+
+import (
+	"errors"
+	"fmt"
+	"strings"
+	"time"
+)
+
+// Status identifies one engine-version registry state.
+type Status string
+
+const (
+	// StatusActive marks a version as deployable. Lobby's start flow
+	// resolves image refs only against active versions.
+	StatusActive Status = "active"
+
+	// StatusDeprecated marks a version as no longer offered for new
+	// starts. Already-running games on a deprecated version are
+	// unaffected; the runtime stays bound to the version it started on.
+	StatusDeprecated Status = "deprecated"
+)
+
+// IsKnown reports whether status belongs to the frozen engine-version
+// status vocabulary.
+func (status Status) IsKnown() bool {
+	switch status {
+	case StatusActive, StatusDeprecated:
+		return true
+	default:
+		return false
+	}
+}
+
+// AllStatuses returns the frozen list of every engine-version status
+// value. The slice order is stable across calls.
+func AllStatuses() []Status {
+	return []Status{StatusActive, StatusDeprecated}
+}
+
+// EngineVersion stores one row of the `engine_versions` registry table.
+// Options carries the raw `jsonb` document verbatim so the registry
+// stays decoupled from any engine-side schema.
+type EngineVersion struct {
+	// Version stores the canonical semver string (primary key).
+	Version string
+
+	// ImageRef stores the Docker reference of the engine image.
+	ImageRef string
+
+	// Options stores the engine-side options document as raw JSON. Empty
+	// is treated as `{}` by adapters that hydrate the column.
+	Options []byte
+
+	// Status reports whether the version is deployable (`active`) or
+	// no longer offered for new starts (`deprecated`).
+	Status Status
+
+	// CreatedAt stores the wall-clock at which the row was created.
+	CreatedAt time.Time
+
+	// UpdatedAt stores the wall-clock of the most recent mutation.
+	UpdatedAt time.Time
+}
+
+// Validate reports whether record satisfies the engine-version
+// invariants implied by `engine_versions_status_chk` and the README
+// §Engine Version Registry surface.
+func (record EngineVersion) Validate() error {
+	if strings.TrimSpace(record.Version) == "" {
+		return fmt.Errorf("version must not be empty")
+	}
+	if strings.TrimSpace(record.ImageRef) == "" {
+		return fmt.Errorf("image ref must not be empty")
+	}
+	if !record.Status.IsKnown() {
+		return fmt.Errorf("status %q is unsupported", record.Status)
+	}
+	if record.CreatedAt.IsZero() {
+		return fmt.Errorf("created at must not be zero")
+	}
+	if record.UpdatedAt.IsZero() {
+		return fmt.Errorf("updated at must not be zero")
+	}
+	if record.UpdatedAt.Before(record.CreatedAt) {
+		return fmt.Errorf("updated at must not be before created at")
+	}
+	return nil
+}
+
+// ErrNotFound reports that an engine-version lookup failed because no
+// matching row exists.
+var ErrNotFound = errors.New("engine version not found")
+
+// ErrInUse reports that a hard-delete or deprecate operation was
+// rejected because the version is still referenced by a non-finished
+// runtime record.
+var ErrInUse = errors.New("engine version in use")
+
+// ErrConflict reports that an engine-version mutation could not be
+// applied because a row with the same primary key already exists.
+// Adapters surface a PostgreSQL unique-violation through this sentinel
+// so the service layer maps it to a `conflict` REST envelope.
+var ErrConflict = errors.New("engine version already exists")
+
+// ErrInvalidSemver reports that a semver string did not parse against
+// `golang.org/x/mod/semver`'s grammar.
+var ErrInvalidSemver = errors.New("invalid semver")