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
}