package ports

import (
	"context"
	"errors"
)

//go:generate go run go.uber.org/mock/mockgen -destination=../adapters/mocks/mock_rtmclient.go -package=mocks galaxy/gamemaster/internal/ports RTMClient

// RTMClient executes synchronous calls to Runtime Manager over the
// trusted internal REST surface documented in
// `galaxy/rtmanager/api/internal-openapi.yaml`. GM uses RTM only for
// stop and patch lifecycle actions in v1.
//
// `Restart` is reserved per `gamemaster/PLAN.md` Stage 10 («reserved;
// not in v1 feature scope») and is intentionally absent from the v1
// surface. It will be added in a later iteration if a use case
// emerges.
type RTMClient interface {
	// Stop calls POST /api/v1/internal/runtimes/{game_id}/stop with
	// body `{reason}`. Implementations wrap any non-success outcome
	// with ErrRTMUnavailable so callers can branch with errors.Is.
	Stop(ctx context.Context, gameID, reason string) error

	// Patch calls POST /api/v1/internal/runtimes/{game_id}/patch with
	// body `{image_ref}`. Implementations wrap any non-success outcome
	// with ErrRTMUnavailable so callers can branch with errors.Is.
	Patch(ctx context.Context, gameID, imageRef string) error
}

// ErrRTMUnavailable signals that a Runtime Manager call could not be
// completed because the upstream service was unreachable, returned an
// error response, or timed out.
var ErrRTMUnavailable = errors.New("runtime manager unavailable")