tests, docs: game engine fetch battle api

game/openapi.yaml

@@ -207,6 +207,33 @@ paths:
           $ref: "#/components/responses/ValidationError"
         "500":
           $ref: "#/components/responses/InternalError"
+  /api/v1/battle/{turn}/{uuid}:
+    get:
+      tags:
+        - PlayerActions
+      operationId: getBattle
+      summary: Fetch a single battle report
+      description: |
+        Returns the full `BattleReport` for the supplied `turn` and battle
+        identifier. The `turn` segment must be a non-negative integer; the
+        `uuid` segment must be a valid RFC 4122 UUID. Responds with
+        `404 Not Found` when no battle is stored for the supplied pair.
+      parameters:
+        - $ref: "#/components/parameters/BattleTurnParam"
+        - $ref: "#/components/parameters/BattleIDParam"
+      responses:
+        "200":
+          description: Battle report for the supplied turn and identifier.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BattleReport"
+        "400":
+          $ref: "#/components/responses/ValidationError"
+        "404":
+          description: No battle exists for the supplied turn and identifier.
+        "500":
+          $ref: "#/components/responses/InternalError"
   /api/v1/admin/turn:
     put:
       tags:
@@ -265,6 +292,22 @@ components:
         type: integer
         minimum: 0
         default: 0
+    BattleTurnParam:
+      name: turn
+      in: path
+      required: true
+      description: Turn number the battle was generated on.
+      schema:
+        type: integer
+        minimum: 0
+    BattleIDParam:
+      name: uuid
+      in: path
+      required: true
+      description: Battle identifier (RFC 4122 UUID).
+      schema:
+        type: string
+        format: uuid
   schemas:
     HealthzResponse:
       type: object
@@ -788,6 +831,124 @@ components:
         wiped:
           type: boolean
           description: True when all population was eliminated by the bombing.
+    BattleReport:
+      type: object
+      description: |
+        Full battle report. `races` and `ships` are JSON objects whose
+        keys are stringified integers used to cross-reference entries
+        from `protocol`: a `BattleActionReport` carries integer indices
+        into both maps. The serialised key is a string because JSON
+        object keys are always strings.
+      required:
+        - id
+        - planet
+        - planetName
+        - races
+        - ships
+        - protocol
+      properties:
+        id:
+          type: string
+          format: uuid
+          description: Battle identifier.
+        planet:
+          type: integer
+          minimum: 0
+          description: Planet number the battle took place on.
+        planetName:
+          type: string
+          description: Planet name at battle start.
+        races:
+          type: object
+          description: |
+            Participating races keyed by the integer index used in
+            `protocol.a` / `protocol.d`. Values are race identifiers.
+          additionalProperties:
+            type: string
+            format: uuid
+        ships:
+          type: object
+          description: |
+            Participating ship groups keyed by the integer index used
+            in `protocol.sa` / `protocol.sd`.
+          additionalProperties:
+            $ref: "#/components/schemas/BattleReportGroup"
+        protocol:
+          type: array
+          description: Ordered list of shots exchanged during the battle.
+          items:
+            $ref: "#/components/schemas/BattleActionReport"
+    BattleReportGroup:
+      type: object
+      description: One ship group participating in the battle.
+      required:
+        - race
+        - className
+        - tech
+        - num
+        - numLeft
+        - loadType
+        - loadQuantity
+        - inBattle
+      properties:
+        race:
+          type: string
+          description: Race name of the group owner.
+        className:
+          type: string
+          description: Ship class name; resolvable through `LocalShipClass` or `OtherShipClass`.
+        tech:
+          type: object
+          description: Technology levels keyed by tech type name.
+          additionalProperties:
+            type: number
+        num:
+          type: integer
+          minimum: 0
+          description: Initial number of ships in this group.
+        numLeft:
+          type: integer
+          minimum: 0
+          description: Number of ships remaining at the end of the battle.
+        loadType:
+          type: string
+          description: Type of cargo loaded.
+        loadQuantity:
+          type: number
+          description: Quantity of cargo loaded.
+        inBattle:
+          type: boolean
+          description: |
+            True when the group actually fights. False groups observe
+            the battle in peace state and never fire or take damage.
+    BattleActionReport:
+      type: object
+      description: |
+        One shot in the battle. Attacker and defender indices reference
+        `BattleReport.races`; ship-class indices reference
+        `BattleReport.ships`.
+      required:
+        - a
+        - sa
+        - d
+        - sd
+        - x
+      properties:
+        a:
+          type: integer
+          description: Index into `BattleReport.races` for the attacker.
+        sa:
+          type: integer
+          description: Index into `BattleReport.ships` for the attacker's group.
+        d:
+          type: integer
+          description: Index into `BattleReport.races` for the defender.
+        sd:
+          type: integer
+          description: Index into `BattleReport.ships` for the defender's group.
+        x:
+          type: boolean
+          description: True when the defender ship was destroyed by this shot.
     IncomingGroup:
       type: object
       description: An identified ship group inbound toward a planet of this race.