ctfy.sdk.client

  1"""Platform HTTP client — the player-facing client for the ctfy platform.
  2
  3This is the client agents and players reach for. It drives the platform's
  4``/api/v1/*`` REST API with typed Pydantic returns and auto-retry on transient
  5errors. Operations split into two tiers:
  6
  7* **Global / account** namespaces on the client itself —
  8  :attr:`~PlatformClient.auth`, :attr:`~PlatformClient.me`,
  9  :attr:`~PlatformClient.users`, :attr:`~PlatformClient.teams`,
 10  :attr:`~PlatformClient.challenges` (global catalog),
 11  :attr:`~PlatformClient.instances`, :attr:`~PlatformClient.submissions`,
 12  :attr:`~PlatformClient.achievements`, :attr:`~PlatformClient.activities`,
 13  :attr:`~PlatformClient.scoreboard`, :attr:`~PlatformClient.nodes`, and
 14  :attr:`~PlatformClient.competitions` (discovery).
 15* **A competition scope** — :meth:`competition` returns a
 16  :class:`~ctfy.sdk.competition.Competition` handle for the operations that are
 17  inherently competition-scoped (register, your team, the comp's challenges,
 18  team search, standings), so ``competition_id`` is named once. Instance
 19  lifecycle and answer submission stay flat (keyed by ``instance_id``)::
 20
 21      from ctfy.sdk import PlatformClient
 22
 23      client = PlatformClient("http://localhost:8100", token="pf_xxx")
 24      comp = client.competition(client.competitions.list(phase="running")[0].id)
 25      comp.register(mode="solo")
 26      ready = client.instances.start(comp.challenges()[0].id, competition_id=comp.id)
 27      result = client.submissions.submit(ready.id, "FLAG{...}")
 28      board = comp.scoreboard()
 29
 30The admin / operator surface is a separate
 31:class:`~ctfy.sdk.admin.AdminClient`, reached via :attr:`admin`. A few
 32server-status / realtime / version helpers stay top-level on the client:
 33:meth:`health`, :meth:`get_meta`, :meth:`cluster_info`, :meth:`events`,
 34:meth:`check_server_compatibility`.
 35"""
 36
 37from __future__ import annotations
 38
 39from functools import cached_property
 40
 41import httpx
 42
 43from ctfy.core.constants import DEFAULT_CLIENT_TIMEOUT
 44from ctfy.core.version import VersionCheck, check_compatibility, package_version
 45from ctfy.sdk._helpers import (
 46    InstanceReadyResult,
 47    _raise_for_status,
 48)
 49from ctfy.sdk._helpers import (
 50    _extract_items as _extract_items,
 51)
 52from ctfy.sdk._helpers import (
 53    _poll_instance_ready as _poll_instance_ready,
 54)
 55from ctfy.sdk.admin import AdminClient
 56from ctfy.sdk.base import BaseHttpClient
 57from ctfy.sdk.competition import Competition
 58from ctfy.sdk.events import EventStream
 59from ctfy.sdk.resources.achievements import AchievementsResource
 60from ctfy.sdk.resources.activities import ActivitiesResource
 61from ctfy.sdk.resources.auth import AuthResource
 62from ctfy.sdk.resources.awd import AwdResource
 63from ctfy.sdk.resources.challenges import ChallengesResource
 64from ctfy.sdk.resources.competitions import CompetitionsResource
 65from ctfy.sdk.resources.eval import EvalResource
 66from ctfy.sdk.resources.instances import InstancesResource
 67from ctfy.sdk.resources.me import MeResource
 68from ctfy.sdk.resources.nodes import NodesResource
 69from ctfy.sdk.resources.registration import RegistrationResource
 70from ctfy.sdk.resources.scoreboard import ScoreboardResource
 71from ctfy.sdk.resources.series import SeriesResource
 72from ctfy.sdk.resources.submissions import PatchesResource, SubmissionsResource
 73from ctfy.sdk.resources.teams import TeamsResource
 74from ctfy.sdk.resources.users import UsersResource
 75from ctfy.sdk.resources.vendor import VendorResource
 76from ctfy.server.models import ClusterInfo, HealthResponse, MetaResponse
 77
 78__all__ = ["InstanceReadyResult", "PlatformClient"]
 79
 80
 81class PlatformClient(BaseHttpClient):
 82    """Player-facing HTTP client for the ctfy platform.
 83
 84    Methods are grouped into resource namespaces (``client.teams.list()``, …)
 85    plus a per-competition scope via ``client.competition(id)``. The admin
 86    surface is a separate :class:`~ctfy.sdk.admin.AdminClient` reached via
 87    :attr:`admin`. Used by the CLI, the SDK, the MCP server, and external callers.
 88    """
 89
 90    def __init__(
 91        self,
 92        server_url: str,
 93        token: str = "",
 94        max_retries: int = 3,
 95        timeout: int = DEFAULT_CLIENT_TIMEOUT,
 96    ):
 97        self._url = server_url.rstrip("/")
 98        super().__init__(f"{self._url}/api/v1", token, timeout=timeout, max_retries=max_retries)
 99
100    @property
101    def server_url(self) -> str:
102        """The platform root, without the ``/api/v1`` suffix.
103
104        Exposed for callers that must build a non-``/api/v1`` URL of
105        their own — today the shell WebSocket, whose ticket carries a
106        platform-relative path the client has to absolutise against the
107        scheme and host *it* reached us on.
108        """
109        return self._url
110
111    # -- resource namespaces ------------------------------------------------
112
113    @cached_property
114    def registration(self) -> RegistrationResource:
115        """The caller's own per-competition registration + team logo."""
116        return RegistrationResource(self)
117
118    @cached_property
119    def teams(self) -> TeamsResource:
120        """Public team discovery + profile reads."""
121        return TeamsResource(self)
122
123    @cached_property
124    def users(self) -> UsersResource:
125        """Public per-user profile reads."""
126        return UsersResource(self)
127
128    @cached_property
129    def me(self) -> MeResource:
130        """The calling user's profile, inbox, account, and progress."""
131        return MeResource(self)
132
133    @cached_property
134    def auth(self) -> AuthResource:
135        """Password auth, OAuth identities, API tokens, sign-in discovery."""
136        return AuthResource(self)
137
138    @cached_property
139    def achievements(self) -> AchievementsResource:
140        """Public badge catalog, recent-unlock feed, easter eggs."""
141        return AchievementsResource(self)
142
143    @cached_property
144    def challenges(self) -> ChallengesResource:
145        """Global challenge catalog, attachments, facets, feedback chips."""
146        return ChallengesResource(self)
147
148    @cached_property
149    def competitions(self) -> CompetitionsResource:
150        """Discover competitions (``list`` / ``get``). To act within one, use
151        :meth:`competition`."""
152        return CompetitionsResource(self)
153
154    def competition(self, competition_id: str) -> Competition:
155        """Scope to one competition. The inherently competition-scoped
156        operations — register, your team (captain tooling + invites +
157        join-requests), the comp's challenges, team search, and standings —
158        hang off the returned :class:`~ctfy.sdk.competition.Competition`
159        handle, so ``competition_id`` is named once instead of on every call.
160        (Instance lifecycle and answer submission stay on :attr:`instances` /
161        :attr:`submissions`, keyed by ``instance_id``.)"""
162        return Competition(self, competition_id)
163
164    @cached_property
165    def series(self) -> SeriesResource:
166        """A recurring contest's ladder (public), not its schedule —
167        configuring a series is ``client.admin.series``."""
168        return SeriesResource(self)
169
170    @cached_property
171    def eval(self) -> EvalResource:
172        """Public model-evaluation leaderboard (ranking + dimensional breakdowns)."""
173        return EvalResource(self)
174
175    @cached_property
176    def vendor(self) -> VendorResource:
177        """Vendor tenancy — the calling vendor's own models / runs (``pv_`` bearer)."""
178        return VendorResource(self)
179
180    @cached_property
181    def instances(self) -> InstancesResource:
182        """Launch / control / inspect challenge instances by instance id
183        (the competition is inferred server-side)."""
184        return InstancesResource(self)
185
186    @cached_property
187    def submissions(self) -> SubmissionsResource:
188        """Submit / verify answers + list submissions (by instance id), plus
189        the instance-less QA challenges."""
190        return SubmissionsResource(self)
191
192    @cached_property
193    def patches(self) -> PatchesResource:
194        """AWD+ defence: submit a patch, then watch for its verdict."""
195        return PatchesResource(self)
196
197    @cached_property
198    def awd(self) -> AwdResource:
199        """Classic AWD: submit a round's captured flags in one batch."""
200        return AwdResource(self)
201
202    @cached_property
203    def scoreboard(self) -> ScoreboardResource:
204        """Global standings, per-challenge stats, persisted snapshots."""
205        return ScoreboardResource(self)
206
207    @cached_property
208    def activities(self) -> ActivitiesResource:
209        """Platform activity log + histogram."""
210        return ActivitiesResource(self)
211
212    @cached_property
213    def nodes(self) -> NodesResource:
214        """Public worker-node list (operator node mgmt is on ``admin.nodes``)."""
215        return NodesResource(self)
216
217    @cached_property
218    def admin(self) -> AdminClient:
219        """Admin / operator surface (separate, role-gated server-side).
220
221        Shares this client's transport. See :class:`~ctfy.sdk.admin.AdminClient`.
222        """
223        return AdminClient(self)
224
225    # -- top-level convenience: server status / realtime / version ----------
226
227    def health(self) -> HealthResponse:
228        resp = self.request("GET", "/health")
229        _raise_for_status(resp)
230        return HealthResponse.model_validate(resp.json())
231
232    def get_meta(self) -> MetaResponse:
233        """Server identity + challenge repo SHA + build version.
234        Admin tokens additionally see cluster capacity + team / solve
235        counts in the same payload."""
236        resp = self.request("GET", "/meta")
237        _raise_for_status(resp)
238        return MetaResponse.model_validate(resp.json())
239
240    def cluster_info(self) -> ClusterInfo:
241        """Aggregate worker-node capacity / utilisation (the public
242        capacity banner; no per-node detail)."""
243        resp = self.request("GET", "/cluster-info")
244        _raise_for_status(resp)
245        return ClusterInfo.model_validate(resp.json())
246
247    def check_server_compatibility(self, *, health: HealthResponse | None = None) -> VersionCheck:
248        """Compare this client's ``ctfy`` version against the server's.
249
250        Uses the cheap unauthenticated ``/health`` probe (pass an
251        already-fetched :class:`HealthResponse` to avoid a second round
252        trip). Pure classification — never prints, never raises on a
253        mismatch, never mutates anything. The caller (CLI, MCP, harness)
254        decides what to do with :class:`~ctfy.core.version.VersionCheck`
255        (typically: print ``.message`` to stderr when not ``.quiet``).
256
257        A server too old to report its version yields
258        :attr:`Compatibility.UNKNOWN` (``health.version == ""``), which
259        is ``.quiet`` — so this stays silent against legacy servers
260        rather than crying wolf.
261        """
262        h = health if health is not None else self.health()
263        return check_compatibility(package_version(), h.version)
264
265    def events(self, *, auto_reconnect: bool = True) -> EventStream:
266        """Open the platform SSE event stream.
267
268        Yields ``{"event": <name>, "data": <dict>}`` for each frame.
269        Filters: team-scoped events for every team the caller's user is
270        on (across every per-comp competition), plus all global events;
271        admin tokens additionally see admin-only frames.
272
273        Usage::
274
275            with client.events() as stream:
276                for event in stream:
277                    if event["event"] == "solve":
278                        ...
279
280        Auto-reconnects on transient network errors with exponential
281        backoff (1s → 30s capped). Set ``auto_reconnect=False`` to make
282        the iterator raise instead.
283        """
284        token = self._token
285
286        def _factory() -> httpx.Client:
287            # New client per session so a reconnect after a stale
288            # connection drops fresh sockets, not warmed-over ones.
289            return httpx.Client(base_url=self._base_url, timeout=None)
290
291        return EventStream(
292            client_factory=_factory,
293            path="/events",
294            token=token,
295            auto_reconnect=auto_reconnect,
296        )