Ilia Denisov
969c0480ba
Engine wire change: Report.battle switched from []uuid.UUID to
[]BattleSummary{id, planet, shots} so the map can place battle
markers without N extra fetches. FBS schema + generated Go/TS
regenerated; transcoder + report controller updated; openapi
adds the BattleSummary schema with a freeze test.
Backend gateway forwards engine GET /api/v1/battle/:turn/:uuid as
/api/v1/user/games/{game_id}/battles/{turn}/{battle_id} (handler
plus engineclient.FetchBattle, contract test stub, openapi spec).
UI:
- BattleViewer (lib/battle-player/) is a logically isolated SVG
radial scene that consumes a BattleReport prop. Planet at the
centre, races on the outer ring at equal angular spacing, race
clusters by (race, className) with <class>:<numLeft> labels;
observer groups (inBattle: false) are not drawn; eliminated
races drop out and survivors re-distribute on the next frame.
- Shot line per frame: red on destroyed, green otherwise; erased
on the next frame. Playback controls: play/pause + step ± +
rewind + 1x/2x/4x speed (400/200/100 ms per frame).
- Page wrapper (lib/active-view/battle.svelte) loads BattleReport
via api/battle-fetch.ts; synthetic-gameId prefix routes to a
fixture loader, otherwise REST through the gateway. Always-
visible <ol> text protocol satisfies the accessibility ask.
- section-battles.svelte links every battle UUID into the viewer.
- map/battle-markers.ts: yellow X cross of 2 LinePrim through the
corners of the planet's circumscribed square (stroke width
clamps from 1 px at 1 shot to 5 px at 100+ shots); bombing
marker is a stroke-only ring (yellow when damaged, red when
wiped). Wired into state-binding.ts; click handler dispatches
battle clicks to the viewer and bombing clicks to the matching
Reports row.
- i18n keys for the viewer in en + ru.
Docs: ui/docs/battle-viewer-ux.md, FUNCTIONAL.md §6.5 + ru
mirror, ui/PLAN.md Phase 27 decisions + deferred TODOs (push
event, richer class visuals, animated re-distribution).
Tests: Vitest unit (radial layout + timeline frame builder +
marker stroke formula + marker primitives), Playwright e2e for
the viewer (Reports link → viewer, playback step, not-found),
backend engineclient FetchBattle (200 / 404 / bad input), engine
openapi freezes (BattleReport, BattleReportGroup,
BattleActionReport, BattleSummary, Report.battle items).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
360 lines
12 KiB
Go
360 lines
12 KiB
Go
package server
|
|
|
|
import (
|
|
"context"
|
|
"encoding/json"
|
|
"errors"
|
|
"io"
|
|
"net/http"
|
|
"strconv"
|
|
|
|
"galaxy/backend/internal/engineclient"
|
|
"galaxy/backend/internal/runtime"
|
|
"galaxy/backend/internal/server/handlers"
|
|
"galaxy/backend/internal/server/httperr"
|
|
"galaxy/backend/internal/server/middleware/userid"
|
|
"galaxy/backend/internal/telemetry"
|
|
gamerest "galaxy/model/rest"
|
|
|
|
"github.com/gin-gonic/gin"
|
|
"go.uber.org/zap"
|
|
)
|
|
|
|
// UserGamesHandlers groups the engine-proxy handlers under
|
|
// `/api/v1/user/games/{game_id}/*`. The wiring connects them through
|
|
// `engineclient` against running engine containers.
|
|
type UserGamesHandlers struct {
|
|
runtime *runtime.Service
|
|
engine *engineclient.Client
|
|
logger *zap.Logger
|
|
}
|
|
|
|
// NewUserGamesHandlers constructs the handler set. When runtime or
|
|
// engine is nil, every handler returns 501 so the contract test still
|
|
// passes against a partially-wired router.
|
|
func NewUserGamesHandlers(rt *runtime.Service, engine *engineclient.Client, logger *zap.Logger) *UserGamesHandlers {
|
|
if logger == nil {
|
|
logger = zap.NewNop()
|
|
}
|
|
return &UserGamesHandlers{runtime: rt, engine: engine, logger: logger.Named("http.user.games")}
|
|
}
|
|
|
|
// Commands handles POST /api/v1/user/games/{game_id}/commands.
|
|
func (h *UserGamesHandlers) Commands() gin.HandlerFunc {
|
|
if h == nil || h.runtime == nil || h.engine == nil {
|
|
return handlers.NotImplemented("userGamesCommands")
|
|
}
|
|
return func(c *gin.Context) {
|
|
gameID, ok := parseGameIDParam(c)
|
|
if !ok {
|
|
return
|
|
}
|
|
userID, ok := userid.FromContext(c.Request.Context())
|
|
if !ok {
|
|
httperr.Abort(c, http.StatusBadRequest, httperr.CodeInvalidRequest, "user id missing")
|
|
return
|
|
}
|
|
body, err := io.ReadAll(c.Request.Body)
|
|
if err != nil {
|
|
httperr.Abort(c, http.StatusBadRequest, httperr.CodeInvalidRequest, "request body could not be read")
|
|
return
|
|
}
|
|
ctx := c.Request.Context()
|
|
if err := h.runtime.CheckOrdersAccept(ctx, gameID); err != nil {
|
|
respondGameProxyError(c, h.logger, "user games commands", ctx, err)
|
|
return
|
|
}
|
|
mapping, err := h.runtime.ResolvePlayerMapping(ctx, gameID, userID)
|
|
if err != nil {
|
|
respondGameProxyError(c, h.logger, "user games commands", ctx, err)
|
|
return
|
|
}
|
|
endpoint, err := h.runtime.EngineEndpoint(ctx, gameID)
|
|
if err != nil {
|
|
respondGameProxyError(c, h.logger, "user games commands", ctx, err)
|
|
return
|
|
}
|
|
payload, err := rebindActor(body, mapping.RaceName)
|
|
if err != nil {
|
|
httperr.Abort(c, http.StatusBadRequest, httperr.CodeInvalidRequest, "request body must be a JSON object")
|
|
return
|
|
}
|
|
resp, err := h.engine.ExecuteCommands(ctx, endpoint, payload)
|
|
if err != nil {
|
|
respondEngineProxyError(c, h.logger, "user games commands", ctx, resp, err)
|
|
return
|
|
}
|
|
c.Data(http.StatusOK, "application/json", resp)
|
|
}
|
|
}
|
|
|
|
// Orders handles POST /api/v1/user/games/{game_id}/orders.
|
|
func (h *UserGamesHandlers) Orders() gin.HandlerFunc {
|
|
if h == nil || h.runtime == nil || h.engine == nil {
|
|
return handlers.NotImplemented("userGamesOrders")
|
|
}
|
|
return func(c *gin.Context) {
|
|
gameID, ok := parseGameIDParam(c)
|
|
if !ok {
|
|
return
|
|
}
|
|
userID, ok := userid.FromContext(c.Request.Context())
|
|
if !ok {
|
|
httperr.Abort(c, http.StatusBadRequest, httperr.CodeInvalidRequest, "user id missing")
|
|
return
|
|
}
|
|
body, err := io.ReadAll(c.Request.Body)
|
|
if err != nil {
|
|
httperr.Abort(c, http.StatusBadRequest, httperr.CodeInvalidRequest, "request body could not be read")
|
|
return
|
|
}
|
|
ctx := c.Request.Context()
|
|
if err := h.runtime.CheckOrdersAccept(ctx, gameID); err != nil {
|
|
respondGameProxyError(c, h.logger, "user games orders", ctx, err)
|
|
return
|
|
}
|
|
mapping, err := h.runtime.ResolvePlayerMapping(ctx, gameID, userID)
|
|
if err != nil {
|
|
respondGameProxyError(c, h.logger, "user games orders", ctx, err)
|
|
return
|
|
}
|
|
endpoint, err := h.runtime.EngineEndpoint(ctx, gameID)
|
|
if err != nil {
|
|
respondGameProxyError(c, h.logger, "user games orders", ctx, err)
|
|
return
|
|
}
|
|
// Engine binds the order body into `gamerest.Command{Actor,
|
|
// Commands}` and rejects an empty actor with `notblank`, so
|
|
// backend rebinds the actor from the runtime player mapping
|
|
// before forwarding — the same rule as for the command
|
|
// handler. Per ARCHITECTURE.md §9 backend is the only caller
|
|
// of the engine, so the body never carries a client-supplied
|
|
// actor.
|
|
payload, err := rebindActor(body, mapping.RaceName)
|
|
if err != nil {
|
|
httperr.Abort(c, http.StatusBadRequest, httperr.CodeInvalidRequest, "request body must be a JSON object")
|
|
return
|
|
}
|
|
resp, err := h.engine.PutOrders(ctx, endpoint, payload)
|
|
if err != nil {
|
|
respondEngineProxyError(c, h.logger, "user games orders", ctx, resp, err)
|
|
return
|
|
}
|
|
c.Data(http.StatusOK, "application/json", resp)
|
|
}
|
|
}
|
|
|
|
// GetOrders handles GET /api/v1/user/games/{game_id}/orders?turn=N.
|
|
// Forwards to the engine's `GET /api/v1/order` with the player rebound
|
|
// from the runtime mapping. The query parameter `turn` is required
|
|
// and must be a non-negative integer; the engine itself enforces the
|
|
// same rule, but rejecting up-front saves a network hop.
|
|
//
|
|
// On `204 No Content` the handler answers `204` so the gateway can
|
|
// translate the FBS envelope to `found = false`. On `200` the
|
|
// engine's body is forwarded verbatim — the gateway re-encodes the
|
|
// JSON `UserGamesOrder` shape into FlatBuffers.
|
|
func (h *UserGamesHandlers) GetOrders() gin.HandlerFunc {
|
|
if h == nil || h.runtime == nil || h.engine == nil {
|
|
return handlers.NotImplemented("userGamesGetOrders")
|
|
}
|
|
return func(c *gin.Context) {
|
|
gameID, ok := parseGameIDParam(c)
|
|
if !ok {
|
|
return
|
|
}
|
|
turnRaw := c.Query("turn")
|
|
if turnRaw == "" {
|
|
httperr.Abort(c, http.StatusBadRequest, httperr.CodeInvalidRequest, "turn is required")
|
|
return
|
|
}
|
|
turn, err := strconv.Atoi(turnRaw)
|
|
if err != nil || turn < 0 {
|
|
httperr.Abort(c, http.StatusBadRequest, httperr.CodeInvalidRequest, "turn must be a non-negative integer")
|
|
return
|
|
}
|
|
userID, ok := userid.FromContext(c.Request.Context())
|
|
if !ok {
|
|
httperr.Abort(c, http.StatusBadRequest, httperr.CodeInvalidRequest, "user id missing")
|
|
return
|
|
}
|
|
ctx := c.Request.Context()
|
|
mapping, err := h.runtime.ResolvePlayerMapping(ctx, gameID, userID)
|
|
if err != nil {
|
|
respondGameProxyError(c, h.logger, "user games get orders", ctx, err)
|
|
return
|
|
}
|
|
endpoint, err := h.runtime.EngineEndpoint(ctx, gameID)
|
|
if err != nil {
|
|
respondGameProxyError(c, h.logger, "user games get orders", ctx, err)
|
|
return
|
|
}
|
|
body, status, err := h.engine.GetOrder(ctx, endpoint, mapping.RaceName, turn)
|
|
if err != nil {
|
|
respondEngineProxyError(c, h.logger, "user games get orders", ctx, body, err)
|
|
return
|
|
}
|
|
if status == http.StatusNoContent {
|
|
c.Status(http.StatusNoContent)
|
|
return
|
|
}
|
|
c.Data(http.StatusOK, "application/json", body)
|
|
}
|
|
}
|
|
|
|
// Report handles GET /api/v1/user/games/{game_id}/reports/{turn}.
|
|
func (h *UserGamesHandlers) Report() gin.HandlerFunc {
|
|
if h == nil || h.runtime == nil || h.engine == nil {
|
|
return handlers.NotImplemented("userGamesReport")
|
|
}
|
|
return func(c *gin.Context) {
|
|
gameID, ok := parseGameIDParam(c)
|
|
if !ok {
|
|
return
|
|
}
|
|
turnRaw := c.Param("turn")
|
|
turn, err := strconv.Atoi(turnRaw)
|
|
if err != nil || turn < 0 {
|
|
httperr.Abort(c, http.StatusBadRequest, httperr.CodeInvalidRequest, "turn must be a non-negative integer")
|
|
return
|
|
}
|
|
userID, ok := userid.FromContext(c.Request.Context())
|
|
if !ok {
|
|
httperr.Abort(c, http.StatusBadRequest, httperr.CodeInvalidRequest, "user id missing")
|
|
return
|
|
}
|
|
ctx := c.Request.Context()
|
|
mapping, err := h.runtime.ResolvePlayerMapping(ctx, gameID, userID)
|
|
if err != nil {
|
|
respondGameProxyError(c, h.logger, "user games report", ctx, err)
|
|
return
|
|
}
|
|
endpoint, err := h.runtime.EngineEndpoint(ctx, gameID)
|
|
if err != nil {
|
|
respondGameProxyError(c, h.logger, "user games report", ctx, err)
|
|
return
|
|
}
|
|
body, err := h.engine.GetReport(ctx, endpoint, mapping.RaceName, turn)
|
|
if err != nil {
|
|
respondEngineProxyError(c, h.logger, "user games report", ctx, body, err)
|
|
return
|
|
}
|
|
c.Data(http.StatusOK, "application/json", body)
|
|
}
|
|
}
|
|
|
|
// Battle handles GET /api/v1/user/games/{game_id}/battles/{turn}/{battle_id}.
|
|
// Forwards to the engine's `GET /api/v1/battle/:turn/:uuid`. Path
|
|
// parameters are validated up-front to save a network hop. 404 from
|
|
// the engine is forwarded as 404. The recipient race is resolved
|
|
// from the runtime mapping but not forwarded — engine returns the
|
|
// battle by id, visibility is enforced by the engine state.
|
|
func (h *UserGamesHandlers) Battle() gin.HandlerFunc {
|
|
if h == nil || h.runtime == nil || h.engine == nil {
|
|
return handlers.NotImplemented("userGamesBattle")
|
|
}
|
|
return func(c *gin.Context) {
|
|
gameID, ok := parseGameIDParam(c)
|
|
if !ok {
|
|
return
|
|
}
|
|
turnRaw := c.Param("turn")
|
|
turn, err := strconv.Atoi(turnRaw)
|
|
if err != nil || turn < 0 {
|
|
httperr.Abort(c, http.StatusBadRequest, httperr.CodeInvalidRequest, "turn must be a non-negative integer")
|
|
return
|
|
}
|
|
battleID := c.Param("battle_id")
|
|
if battleID == "" {
|
|
httperr.Abort(c, http.StatusBadRequest, httperr.CodeInvalidRequest, "battle id is required")
|
|
return
|
|
}
|
|
userID, ok := userid.FromContext(c.Request.Context())
|
|
if !ok {
|
|
httperr.Abort(c, http.StatusBadRequest, httperr.CodeInvalidRequest, "user id missing")
|
|
return
|
|
}
|
|
ctx := c.Request.Context()
|
|
if _, err := h.runtime.ResolvePlayerMapping(ctx, gameID, userID); err != nil {
|
|
respondGameProxyError(c, h.logger, "user games battle", ctx, err)
|
|
return
|
|
}
|
|
endpoint, err := h.runtime.EngineEndpoint(ctx, gameID)
|
|
if err != nil {
|
|
respondGameProxyError(c, h.logger, "user games battle", ctx, err)
|
|
return
|
|
}
|
|
body, status, err := h.engine.FetchBattle(ctx, endpoint, turn, battleID)
|
|
if err != nil {
|
|
respondEngineProxyError(c, h.logger, "user games battle", ctx, body, err)
|
|
return
|
|
}
|
|
if status == http.StatusNotFound {
|
|
httperr.Abort(c, http.StatusNotFound, httperr.CodeNotFound, "battle not found")
|
|
return
|
|
}
|
|
c.Data(http.StatusOK, "application/json", body)
|
|
}
|
|
}
|
|
|
|
// rebindActor decodes a JSON object from raw, sets `actor` to
|
|
// raceName, and re-encodes. Backend never trusts the actor field
|
|
// supplied by the client (per ARCHITECTURE.md §9).
|
|
func rebindActor(raw []byte, raceName string) (json.RawMessage, error) {
|
|
if len(raw) == 0 {
|
|
// Empty body — synthesise a minimal envelope so the engine
|
|
// receives a well-formed request.
|
|
return json.Marshal(gamerest.Command{Actor: raceName})
|
|
}
|
|
var generic map[string]json.RawMessage
|
|
if err := json.Unmarshal(raw, &generic); err != nil {
|
|
return nil, err
|
|
}
|
|
actor, _ := json.Marshal(raceName)
|
|
generic["actor"] = actor
|
|
return json.Marshal(generic)
|
|
}
|
|
|
|
func respondGameProxyError(c *gin.Context, logger *zap.Logger, op string, ctx context.Context, err error) {
|
|
switch {
|
|
case errors.Is(err, runtime.ErrNotFound):
|
|
httperr.Abort(c, http.StatusNotFound, httperr.CodeNotFound, "no runtime mapping for this user/game")
|
|
case errors.Is(err, runtime.ErrTurnAlreadyClosed):
|
|
httperr.Abort(c, http.StatusConflict, httperr.CodeTurnAlreadyClosed,
|
|
"turn already closed; orders are not accepted while the engine is producing")
|
|
case errors.Is(err, runtime.ErrGamePaused):
|
|
httperr.Abort(c, http.StatusConflict, httperr.CodeGamePaused,
|
|
"game is paused; orders are not accepted until it resumes")
|
|
case errors.Is(err, runtime.ErrConflict):
|
|
httperr.Abort(c, http.StatusConflict, httperr.CodeConflict, err.Error())
|
|
default:
|
|
logger.Error(op+" failed",
|
|
append(telemetry.TraceFieldsFromContext(ctx), zap.Error(err))...,
|
|
)
|
|
httperr.Abort(c, http.StatusInternalServerError, httperr.CodeInternalError, "internal error")
|
|
}
|
|
}
|
|
|
|
func respondEngineProxyError(c *gin.Context, logger *zap.Logger, op string, ctx context.Context, body []byte, err error) {
|
|
switch {
|
|
case errors.Is(err, engineclient.ErrEngineValidation):
|
|
if len(body) > 0 {
|
|
c.Data(http.StatusBadRequest, "application/json", body)
|
|
return
|
|
}
|
|
httperr.Abort(c, http.StatusBadRequest, httperr.CodeInvalidRequest, err.Error())
|
|
case errors.Is(err, engineclient.ErrEngineUnreachable):
|
|
httperr.Abort(c, http.StatusServiceUnavailable, httperr.CodeServiceUnavailable, "engine is unreachable")
|
|
case errors.Is(err, engineclient.ErrEngineProtocolViolation):
|
|
logger.Error(op+" engine protocol violation",
|
|
append(telemetry.TraceFieldsFromContext(ctx), zap.Error(err))...,
|
|
)
|
|
httperr.Abort(c, http.StatusBadGateway, httperr.CodeInternalError, "engine response was malformed")
|
|
default:
|
|
logger.Error(op+" failed",
|
|
append(telemetry.TraceFieldsFromContext(ctx), zap.Error(err))...,
|
|
)
|
|
httperr.Abort(c, http.StatusInternalServerError, httperr.CodeInternalError, "internal error")
|
|
}
|
|
}
|