feat: gamemaster
This commit is contained in:
Ilia Denisov
@@ -0,0 +1,317 @@
|
||||
// Package adminbanish implements the admin banish service-layer
|
||||
// orchestrator owned by Game Master. It is driven by Game Lobby (and,
|
||||
// in a later iteration, Admin Service) through
|
||||
// `POST /api/v1/internal/games/{game_id}/race/{race_name}/banish` after
|
||||
// a permanent membership removal at the platform level. The flow
|
||||
// resolves the race against the installed roster, calls the engine
|
||||
// `/admin/race/banish` endpoint, and writes one operation_log row.
|
||||
//
|
||||
// Lifecycle and failure-mode semantics follow `gamemaster/README.md
|
||||
// §Lifecycles → Banish`. Design rationale (no runtime status check,
|
||||
// missing race surfaces as `forbidden`) is captured in
|
||||
// `gamemaster/docs/stage17-admin-operations.md`.
|
||||
package adminbanish
|
||||
|
||||
import (
|
||||
"context"
|
||||
"errors"
|
||||
"fmt"
|
||||
"log/slog"
|
||||
"strings"
|
||||
"time"
|
||||
|
||||
"galaxy/gamemaster/internal/domain/operation"
|
||||
"galaxy/gamemaster/internal/domain/playermapping"
|
||||
"galaxy/gamemaster/internal/domain/runtime"
|
||||
"galaxy/gamemaster/internal/logging"
|
||||
"galaxy/gamemaster/internal/ports"
|
||||
"galaxy/gamemaster/internal/telemetry"
|
||||
)
|
||||
|
||||
// Input stores the per-call arguments for one admin banish operation.
|
||||
type Input struct {
|
||||
// GameID identifies the runtime the race belongs to.
|
||||
GameID string
|
||||
|
||||
// RaceName stores the platform race name to banish.
|
||||
RaceName string
|
||||
|
||||
// OpSource classifies how the request entered Game Master. Used to
|
||||
// stamp `operation_log.op_source`. Defaults to `lobby_internal`
|
||||
// when missing or unrecognised — Lobby is the only v1 caller.
|
||||
OpSource operation.OpSource
|
||||
|
||||
// SourceRef stores the optional opaque per-source reference (REST
|
||||
// request id). Empty when the caller does not provide one.
|
||||
SourceRef string
|
||||
}
|
||||
|
||||
// Validate reports whether input carries the structural invariants the
|
||||
// service requires before any store is touched.
|
||||
func (input Input) Validate() error {
|
||||
if strings.TrimSpace(input.GameID) == "" {
|
||||
return fmt.Errorf("game id must not be empty")
|
||||
}
|
||||
if strings.TrimSpace(input.RaceName) == "" {
|
||||
return fmt.Errorf("race name must not be empty")
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// Result stores the deterministic outcome of one Handle call. Business
|
||||
// outcomes flow through Result; the Go-level error return is reserved
|
||||
// for non-business failures (nil context, nil receiver).
|
||||
type Result struct {
|
||||
// Outcome reports whether the operation completed (success) or
|
||||
// produced a stable failure code.
|
||||
Outcome operation.Outcome
|
||||
|
||||
// ErrorCode stores the stable error code on failure. Empty on
|
||||
// success.
|
||||
ErrorCode string
|
||||
|
||||
// ErrorMessage stores the operator-readable detail on failure.
|
||||
// Empty on success.
|
||||
ErrorMessage string
|
||||
}
|
||||
|
||||
// IsSuccess reports whether the result represents a successful
|
||||
// operation.
|
||||
func (result Result) IsSuccess() bool {
|
||||
return result.Outcome == operation.OutcomeSuccess
|
||||
}
|
||||
|
||||
// Dependencies groups the collaborators required by Service.
|
||||
type Dependencies struct {
|
||||
// RuntimeRecords supplies the engine endpoint used for the engine
|
||||
// call.
|
||||
RuntimeRecords ports.RuntimeRecordStore
|
||||
|
||||
// PlayerMappings resolves the race against the installed roster.
|
||||
PlayerMappings ports.PlayerMappingStore
|
||||
|
||||
// OperationLogs records the audit entry.
|
||||
OperationLogs ports.OperationLogStore
|
||||
|
||||
// Engine drives the `/admin/race/banish` call.
|
||||
Engine ports.EngineClient
|
||||
|
||||
// Telemetry is required: every banish call ends with a
|
||||
// `gamemaster.banish.outcomes` counter sample.
|
||||
Telemetry *telemetry.Runtime
|
||||
|
||||
// Logger records structured service-level events. Defaults to
|
||||
// `slog.Default()` when nil.
|
||||
Logger *slog.Logger
|
||||
|
||||
// Clock supplies the wall-clock used for operation timestamps.
|
||||
// Defaults to `time.Now` when nil.
|
||||
Clock func() time.Time
|
||||
}
|
||||
|
||||
// Service executes the admin banish lifecycle operation.
|
||||
type Service struct {
|
||||
runtimeRecords ports.RuntimeRecordStore
|
||||
playerMappings ports.PlayerMappingStore
|
||||
operationLogs ports.OperationLogStore
|
||||
engine ports.EngineClient
|
||||
|
||||
telemetry *telemetry.Runtime
|
||||
logger *slog.Logger
|
||||
clock func() time.Time
|
||||
}
|
||||
|
||||
// NewService constructs one Service from deps.
|
||||
func NewService(deps Dependencies) (*Service, error) {
|
||||
switch {
|
||||
case deps.RuntimeRecords == nil:
|
||||
return nil, errors.New("new admin banish service: nil runtime records")
|
||||
case deps.PlayerMappings == nil:
|
||||
return nil, errors.New("new admin banish service: nil player mappings")
|
||||
case deps.OperationLogs == nil:
|
||||
return nil, errors.New("new admin banish service: nil operation logs")
|
||||
case deps.Engine == nil:
|
||||
return nil, errors.New("new admin banish service: nil engine client")
|
||||
case deps.Telemetry == nil:
|
||||
return nil, errors.New("new admin banish service: nil telemetry runtime")
|
||||
}
|
||||
|
||||
clock := deps.Clock
|
||||
if clock == nil {
|
||||
clock = time.Now
|
||||
}
|
||||
logger := deps.Logger
|
||||
if logger == nil {
|
||||
logger = slog.Default()
|
||||
}
|
||||
logger = logger.With("service", "gamemaster.adminbanish")
|
||||
|
||||
return &Service{
|
||||
runtimeRecords: deps.RuntimeRecords,
|
||||
playerMappings: deps.PlayerMappings,
|
||||
operationLogs: deps.OperationLogs,
|
||||
engine: deps.Engine,
|
||||
telemetry: deps.Telemetry,
|
||||
logger: logger,
|
||||
clock: clock,
|
||||
}, nil
|
||||
}
|
||||
|
||||
// Handle executes one admin banish operation end-to-end. The Go-level
|
||||
// error return is reserved for non-business failures (nil context, nil
|
||||
// receiver). Every business outcome flows through Result.
|
||||
func (service *Service) Handle(ctx context.Context, input Input) (Result, error) {
|
||||
if service == nil {
|
||||
return Result{}, errors.New("admin banish: nil service")
|
||||
}
|
||||
if ctx == nil {
|
||||
return Result{}, errors.New("admin banish: nil context")
|
||||
}
|
||||
|
||||
opStartedAt := service.clock().UTC()
|
||||
|
||||
if err := input.Validate(); err != nil {
|
||||
return service.recordFailure(ctx, opStartedAt, input,
|
||||
ErrorCodeInvalidRequest, err.Error()), nil
|
||||
}
|
||||
|
||||
record, err := service.runtimeRecords.Get(ctx, input.GameID)
|
||||
switch {
|
||||
case errors.Is(err, runtime.ErrNotFound):
|
||||
return service.recordFailure(ctx, opStartedAt, input,
|
||||
ErrorCodeRuntimeNotFound, "runtime record does not exist"), nil
|
||||
case err != nil:
|
||||
return service.recordFailure(ctx, opStartedAt, input,
|
||||
ErrorCodeServiceUnavailable, fmt.Sprintf("get runtime record: %s", err.Error())), nil
|
||||
}
|
||||
|
||||
if _, err := service.playerMappings.GetByRace(ctx, input.GameID, input.RaceName); err != nil {
|
||||
switch {
|
||||
case errors.Is(err, playermapping.ErrNotFound):
|
||||
return service.recordFailure(ctx, opStartedAt, input,
|
||||
ErrorCodeForbidden, fmt.Sprintf("race %q not in roster", input.RaceName)), nil
|
||||
default:
|
||||
return service.recordFailure(ctx, opStartedAt, input,
|
||||
ErrorCodeServiceUnavailable, fmt.Sprintf("get player mapping by race: %s", err.Error())), nil
|
||||
}
|
||||
}
|
||||
|
||||
if err := service.engine.BanishRace(ctx, record.EngineEndpoint, input.RaceName); err != nil {
|
||||
errorCode := classifyEngineError(err)
|
||||
return service.recordFailure(ctx, opStartedAt, input,
|
||||
errorCode, fmt.Sprintf("engine banish: %s", err.Error())), nil
|
||||
}
|
||||
|
||||
service.appendSuccessLog(ctx, opStartedAt, input)
|
||||
service.telemetry.RecordBanishOutcome(ctx, string(operation.OutcomeSuccess), "")
|
||||
|
||||
logArgs := []any{
|
||||
"game_id", input.GameID,
|
||||
"race_name", input.RaceName,
|
||||
"op_source", string(fallbackOpSource(input.OpSource)),
|
||||
}
|
||||
logArgs = append(logArgs, logging.ContextAttrs(ctx)...)
|
||||
service.logger.InfoContext(ctx, "race banished", logArgs...)
|
||||
|
||||
return Result{Outcome: operation.OutcomeSuccess}, nil
|
||||
}
|
||||
|
||||
// recordFailure assembles the failure Result, appends the
|
||||
// operation_log failure entry, emits telemetry, and returns the
|
||||
// structured outcome.
|
||||
func (service *Service) recordFailure(ctx context.Context, opStartedAt time.Time, input Input, errorCode string, errorMessage string) Result {
|
||||
service.appendFailureLog(ctx, opStartedAt, input, errorCode, errorMessage)
|
||||
service.telemetry.RecordBanishOutcome(ctx, string(operation.OutcomeFailure), errorCode)
|
||||
|
||||
logArgs := []any{
|
||||
"game_id", input.GameID,
|
||||
"race_name", input.RaceName,
|
||||
"op_source", string(input.OpSource),
|
||||
"error_code", errorCode,
|
||||
"error_message", errorMessage,
|
||||
}
|
||||
logArgs = append(logArgs, logging.ContextAttrs(ctx)...)
|
||||
service.logger.WarnContext(ctx, "admin banish rejected", logArgs...)
|
||||
|
||||
return Result{
|
||||
Outcome: operation.OutcomeFailure,
|
||||
ErrorCode: errorCode,
|
||||
ErrorMessage: errorMessage,
|
||||
}
|
||||
}
|
||||
|
||||
// classifyEngineError maps the engine port sentinels to the
|
||||
// admin-banish stable error codes.
|
||||
func classifyEngineError(err error) string {
|
||||
switch {
|
||||
case errors.Is(err, ports.ErrEngineValidation):
|
||||
return ErrorCodeEngineValidationError
|
||||
case errors.Is(err, ports.ErrEngineProtocolViolation):
|
||||
return ErrorCodeEngineProtocolViolation
|
||||
case errors.Is(err, ports.ErrEngineUnreachable):
|
||||
return ErrorCodeEngineUnreachable
|
||||
default:
|
||||
return ErrorCodeEngineUnreachable
|
||||
}
|
||||
}
|
||||
|
||||
// appendSuccessLog records the success operation_log entry.
|
||||
func (service *Service) appendSuccessLog(ctx context.Context, opStartedAt time.Time, input Input) {
|
||||
finishedAt := service.clock().UTC()
|
||||
service.bestEffortAppend(ctx, operation.OperationEntry{
|
||||
GameID: input.GameID,
|
||||
OpKind: operation.OpKindBanish,
|
||||
OpSource: fallbackOpSource(input.OpSource),
|
||||
SourceRef: input.SourceRef,
|
||||
Outcome: operation.OutcomeSuccess,
|
||||
StartedAt: opStartedAt,
|
||||
FinishedAt: &finishedAt,
|
||||
})
|
||||
}
|
||||
|
||||
// appendFailureLog records the failure operation_log entry. Skipped
|
||||
// when the input game id is empty so the entry validator does not
|
||||
// reject an audit row that adds no value.
|
||||
func (service *Service) appendFailureLog(ctx context.Context, opStartedAt time.Time, input Input, errorCode string, errorMessage string) {
|
||||
if strings.TrimSpace(input.GameID) == "" {
|
||||
return
|
||||
}
|
||||
finishedAt := service.clock().UTC()
|
||||
service.bestEffortAppend(ctx, operation.OperationEntry{
|
||||
GameID: input.GameID,
|
||||
OpKind: operation.OpKindBanish,
|
||||
OpSource: fallbackOpSource(input.OpSource),
|
||||
SourceRef: input.SourceRef,
|
||||
Outcome: operation.OutcomeFailure,
|
||||
ErrorCode: errorCode,
|
||||
ErrorMessage: errorMessage,
|
||||
StartedAt: opStartedAt,
|
||||
FinishedAt: &finishedAt,
|
||||
})
|
||||
}
|
||||
|
||||
// bestEffortAppend writes one operation_log entry. A failure is logged
|
||||
// and discarded; the engine state and runtime row are the source of
|
||||
// truth.
|
||||
func (service *Service) bestEffortAppend(ctx context.Context, entry operation.OperationEntry) {
|
||||
if _, err := service.operationLogs.Append(ctx, entry); err != nil {
|
||||
service.logger.ErrorContext(ctx, "append operation log",
|
||||
"game_id", entry.GameID,
|
||||
"op_kind", string(entry.OpKind),
|
||||
"outcome", string(entry.Outcome),
|
||||
"error_code", entry.ErrorCode,
|
||||
"err", err.Error(),
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
// fallbackOpSource defaults to `lobby_internal` when the caller did
|
||||
// not supply a known op source. Lobby is the only v1 banish caller; an
|
||||
// `admin_rest` source is preserved when explicitly set so future Admin
|
||||
// Service traffic is identifiable.
|
||||
func fallbackOpSource(source operation.OpSource) operation.OpSource {
|
||||
if source.IsKnown() {
|
||||
return source
|
||||
}
|
||||
return operation.OpSourceLobbyInternal
|
||||
}
|
||||
Reference in New Issue
Block a user