ctfy.sdk.admin_resources.awd

  1"""``client.admin.awd`` — configuring a classic-AWD match."""
  2
  3from __future__ import annotations
  4
  5from datetime import datetime
  6
  7from ctfy.sdk._helpers import _raise_for_status
  8from ctfy.sdk.base import BaseHttpClient
  9from ctfy.server.models import AdminTaskInfo, AwdMatchInfo, AwdProvisionPlanInfo
 10
 11
 12class AdminAwdResource:
 13    """The organiser's half of a match: cadence, gamebox, budgets.
 14
 15    ⚠️ **The round number is derived from the clock, not stored**, so
 16    ``starts_at`` / ``tick_seconds`` / ``challenge_id`` are frozen once
 17    the match has started — editing one would retroactively renumber
 18    every round already settled and published. :meth:`configure`
 19    answers 409 ``awd_match_locked`` naming the fields, rather than
 20    silently accepting a write that breaks the board.
 21
 22    There is deliberately no way to set ``last_tick_done``: it is the
 23    tick loop's bookmark, and moving it makes the loop re-settle rounds
 24    the board has already published.
 25    """
 26
 27    def __init__(self, http: BaseHttpClient) -> None:
 28        self._http = http
 29
 30    def get(self, competition_id: str) -> AwdMatchInfo:
 31        """This competition's match. 404 if it runs none.
 32
 33        ``current_tick`` and ``started`` are computed per read — asking
 34        again a round later gives a different answer with no write in
 35        between, which is the point.
 36        """
 37        resp = self._http.request("GET", f"/admin/competitions/{competition_id}/awd/match")
 38        _raise_for_status(resp)
 39        return AwdMatchInfo.model_validate(resp.json())
 40
 41    def configure(
 42        self,
 43        competition_id: str,
 44        *,
 45        tick_seconds: int,
 46        tick_count: int,
 47        challenge_id: str = "",
 48        starts_at: datetime | None = None,
 49        per_tick_budget: int | None = None,
 50        total_budget: int | None = None,
 51    ) -> AwdMatchInfo:
 52        """Create the match, or edit it. Idempotent on the competition.
 53
 54        ``challenge_id`` may be left empty while the match is being put
 55        together — provisioning is what refuses without a gamebox, and
 56        it refuses at the point an organiser can still act on it.
 57        """
 58        body: dict[str, object] = {
 59            "challenge_id": challenge_id,
 60            "starts_at": starts_at.isoformat() if starts_at else None,
 61            "tick_seconds": tick_seconds,
 62            "tick_count": tick_count,
 63            "per_tick_budget": per_tick_budget,
 64            "total_budget": total_budget,
 65        }
 66        resp = self._http.request(
 67            "PUT", f"/admin/competitions/{competition_id}/awd/match", json=body
 68        )
 69        _raise_for_status(resp)
 70        return AwdMatchInfo.model_validate(resp.json())
 71
 72    def delete(self, competition_id: str) -> None:
 73        """Remove a match that never started and holds no boxes.
 74
 75        Refused once the first round has opened — its scores are
 76        published and keyed by round, so the configuration they belong
 77        to has to stay. Lowering ``tick_count`` is how a running match
 78        is ended.
 79        """
 80        resp = self._http.request("DELETE", f"/admin/competitions/{competition_id}/awd/match")
 81        _raise_for_status(resp)
 82
 83    def plan(self, competition_id: str) -> AwdProvisionPlanInfo:
 84        """What opening the arena would do, without doing it.
 85
 86        409 ``awd_provision_refused`` when the match cannot be
 87        provisioned at all — no gamebox, no teams, or a match that has
 88        already started (§4.5 fixes the box supply at kickoff).
 89        """
 90        resp = self._http.request("GET", f"/admin/competitions/{competition_id}/awd/plan")
 91        _raise_for_status(resp)
 92        return AwdProvisionPlanInfo.model_validate(resp.json())
 93
 94    def provision(self, competition_id: str) -> AdminTaskInfo:
 95        """Start a gamebox for every team that lacks one.
 96
 97        Returns the **task**, not the boxes: a fleet launch is minutes
 98        of work at event scale. Poll ``client.admin.tasks.get(id)`` (or
 99        ``.logs``, which names every team that failed) for the outcome.
100        Idempotent — re-running skips the teams already holding a box.
101        """
102        resp = self._http.request("POST", f"/admin/competitions/{competition_id}/awd/provision")
103        _raise_for_status(resp)
104        return AdminTaskInfo.model_validate(resp.json())
105
106    def teardown(self, competition_id: str) -> AdminTaskInfo:
107        """Stop every arena box of this match. Also a task.
108
109        Only this competition's ``lease="match"`` boxes: a player's own
110        on-demand instance is not part of the match, and no node is
111        wiped wholesale — the arena shares hosts with every other event
112        on the platform.
113        """
114        resp = self._http.request("DELETE", f"/admin/competitions/{competition_id}/awd/boxes")
115        _raise_for_status(resp)
116        return AdminTaskInfo.model_validate(resp.json())