ctfy.sdk.admin_resources.challenges

  1"""``client.admin.challenges`` — catalog rescan, pre-build, stats, feedback audit."""
  2
  3from __future__ import annotations
  4
  5from typing import Any
  6
  7from ctfy.sdk._helpers import _extract_items, _raise_for_status
  8from ctfy.sdk.base import BaseHttpClient
  9from ctfy.server.models import (
 10    AdminChallengeLatencyBucket,
 11    AdminChallengeStatsRow,
 12    AdminChallengeTimeseries,
 13    AdminFeedbackRow,
 14    ChallengeBuildKickoffResponse,
 15    ChallengeBuildStateResponse,
 16    QuestionAttemptResetInfo,
 17)
 18
 19
 20class AdminChallengesResource:
 21    """Operator challenge tooling: reload the catalog, pre-build on nodes,
 22    inspect attempt/solve stats, audit feedback, reset attempt caps."""
 23
 24    def __init__(self, http: BaseHttpClient) -> None:
 25        self._http = http
 26
 27    def rescan(self) -> dict[str, Any]:
 28        """Reload the on-disk challenge catalog without a restart.
 29
 30        Drops the platform's process-lifetime spec cache, re-scans
 31        ``challenges_dir``, and fans the rescan out to every online
 32        worker node. Returns ``{total, added, removed, nodes}`` —
 33        the platform's post-rescan counts plus the per-node fan-out
 34        outcome. Wraps ``POST /admin/challenges/rescan``."""
 35        resp = self._http.request("POST", "/admin/challenges/rescan")
 36        _raise_for_status(resp)
 37        body: dict[str, Any] = resp.json()
 38        return body
 39
 40    def build(self, challenge_id: str) -> ChallengeBuildKickoffResponse:
 41        """Kick off a single-challenge pre-build on every online node.
 42
 43        Returns the per-node kickoff outcomes. Each node spawns a
 44        background thread; poll :meth:`build_state` to watch
 45        ``building`` → ``built`` / ``failed``. Wraps
 46        ``POST /admin/challenges/{id}/build``."""
 47        resp = self._http.request("POST", f"/admin/challenges/{challenge_id}/build")
 48        _raise_for_status(resp)
 49        return ChallengeBuildKickoffResponse.model_validate(resp.json())
 50
 51    def build_all(self) -> ChallengeBuildKickoffResponse:
 52        """Kick off a bulk pre-build on every online node.
 53
 54        Each node sequentially pre-builds every spec not already in
 55        ``built`` / ``building``. Returns per-node kickoff outcomes
 56        with ``queued`` / ``skipped_built`` / ``skipped_in_progress``
 57        lists. Wraps ``POST /admin/challenges/build-all``."""
 58        resp = self._http.request("POST", "/admin/challenges/build-all")
 59        _raise_for_status(resp)
 60        return ChallengeBuildKickoffResponse.model_validate(resp.json())
 61
 62    def build_state(self) -> ChallengeBuildStateResponse:
 63        """Aggregate per-challenge build state across every online node.
 64
 65        Returns one row per known challenge with an ``aggregated``
 66        worst-case status plus the per-node breakdown for the modal
 67        drill-down. Wraps ``GET /admin/challenges/build-state``."""
 68        resp = self._http.request("GET", "/admin/challenges/build-state")
 69        _raise_for_status(resp)
 70        return ChallengeBuildStateResponse.model_validate(resp.json())
 71
 72    def stats(self, offset: int = 0, limit: int = 50) -> list[AdminChallengeStatsRow]:
 73        """Per-challenge attempt / solve / first-blood counts."""
 74        resp = self._http.request(
 75            "GET",
 76            "/admin/challenges/stats",
 77            params={"offset": offset, "limit": limit},
 78        )
 79        _raise_for_status(resp)
 80        return [AdminChallengeStatsRow.model_validate(r) for r in resp.json()["items"]]
 81
 82    def timeseries(
 83        self,
 84        challenge_id: str,
 85        *,
 86        window: int = 86400,
 87        bucket: int = 3600,
 88    ) -> AdminChallengeTimeseries:
 89        """Per-challenge timeseries for the row-level drawer on
 90        ``/admin/challenges``."""
 91        resp = self._http.request(
 92            "GET",
 93            f"/admin/challenges/{challenge_id}/timeseries",
 94            params={"window": window, "bucket": bucket},
 95        )
 96        _raise_for_status(resp)
 97        return AdminChallengeTimeseries.model_validate(resp.json())
 98
 99    def latency_histogram(self) -> list[AdminChallengeLatencyBucket]:
100        """Instance-start latency distribution across challenges (the
101        admin challenges latency chart)."""
102        resp = self._http.request("GET", "/admin/challenges/latency-histogram")
103        _raise_for_status(resp)
104        return [AdminChallengeLatencyBucket.model_validate(b) for b in resp.json()]
105
106    def feedback(self, challenge_id: str, *, competition_id: str = "") -> list[AdminFeedbackRow]:
107        """Admin audit list: every reaction row on a challenge with
108        denormalised user identity. Requires admin role."""
109        params: dict[str, Any] = {}
110        if competition_id:
111            params["competition_id"] = competition_id
112        resp = self._http.request(
113            "GET", f"/admin/challenges/{challenge_id}/feedback", params=params
114        )
115        _raise_for_status(resp)
116        return _extract_items(resp.json(), AdminFeedbackRow)
117
118    def reset_question_attempts(
119        self,
120        team_id: str,
121        challenge_id: str,
122        question_id: str,
123        *,
124        reason: str = "",
125    ) -> QuestionAttemptResetInfo:
126        """Reset the per-question wrong-attempt counter for one team.
127
128        Writes a fresh baseline timestamp; the cap counter ignores all
129        wrong submissions before the new baseline, so the team gets a
130        fresh batch of attempts on this question without any audit
131        rows being deleted. Returns the new baseline row.
132        Wraps ``POST /admin/teams/{team_id}/questions/{challenge_id}/{question_id}/reset-attempts``."""
133        resp = self._http.request(
134            "POST",
135            f"/admin/teams/{team_id}/questions/{challenge_id}/{question_id}/reset-attempts",
136            json={"reason": reason},
137        )
138        _raise_for_status(resp)
139        return QuestionAttemptResetInfo.model_validate(resp.json())