feat: runtime manager

rtmanager/internal/service/stopruntime/stopreason.go

@@ -0,0 +1,82 @@
+package stopruntime
+
+import "fmt"
+
+// StopReason classifies why a caller is asking Runtime Manager to stop a
+// game container. The enum is part of the `runtime:stop_jobs` envelope
+// produced by Game Lobby and the body of the `POST
+// /api/v1/internal/runtimes/{game_id}/stop` REST endpoint, and mirrors
+// the AsyncAPI contract frozen in
+// `rtmanager/api/runtime-jobs-asyncapi.yaml`.
+//
+// The vocabulary is shared with `lobby/internal/ports/runtimemanager.go`;
+// the two declarations stay byte-identical and adding a new value
+// requires a coordinated contract bump on both sides.
+type StopReason string
+
+// StopReason enum values. Adding a new value is a contract change that
+// touches the AsyncAPI spec, the Lobby producer, and every Runtime
+// Manager consumer.
+const (
+	// StopReasonOrphanCleanup releases a container whose post-start
+	// metadata persistence failed in Lobby.
+	StopReasonOrphanCleanup StopReason = "orphan_cleanup"
+
+	// StopReasonCancelled covers user-lifecycle cascade and explicit
+	// cancel paths for in-flight games.
+	StopReasonCancelled StopReason = "cancelled"
+
+	// StopReasonFinished is reserved for engine-driven game finish flows.
+	StopReasonFinished StopReason = "finished"
+
+	// StopReasonAdminRequest is reserved for admin-initiated stop paths.
+	StopReasonAdminRequest StopReason = "admin_request"
+
+	// StopReasonTimeout is reserved for timeout-driven stop paths.
+	StopReasonTimeout StopReason = "timeout"
+)
+
+// IsKnown reports whether reason belongs to the frozen stop-reason
+// vocabulary.
+func (reason StopReason) IsKnown() bool {
+	switch reason {
+	case StopReasonOrphanCleanup,
+		StopReasonCancelled,
+		StopReasonFinished,
+		StopReasonAdminRequest,
+		StopReasonTimeout:
+		return true
+	default:
+		return false
+	}
+}
+
+// AllStopReasons returns the frozen list of every stop-reason value. The
+// slice order is stable across calls and matches the AsyncAPI enum order.
+func AllStopReasons() []StopReason {
+	return []StopReason{
+		StopReasonOrphanCleanup,
+		StopReasonCancelled,
+		StopReasonFinished,
+		StopReasonAdminRequest,
+		StopReasonTimeout,
+	}
+}
+
+// String returns reason as its stored enum value. Useful in log fields
+// and telemetry attributes.
+func (reason StopReason) String() string {
+	return string(reason)
+}
+
+// Validate reports whether reason carries one of the five values fixed
+// by the AsyncAPI contract.
+func (reason StopReason) Validate() error {
+	if reason == "" {
+		return fmt.Errorf("stop reason must not be empty")
+	}
+	if !reason.IsKnown() {
+		return fmt.Errorf("stop reason %q is unsupported", reason)
+	}
+	return nil
+}