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.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_PLATFORM_TIMEOUT
 44from ctfy.core.unavailable import UNAVAILABLE_BUDGET_S
 45from ctfy.core.version import VersionCheck, check_compatibility, package_version
 46from ctfy.sdk._helpers import (
 47    InstanceReadyResult,
 48    _raise_for_status,
 49)
 50from ctfy.sdk._helpers import (
 51    _extract_items as _extract_items,
 52)
 53from ctfy.sdk._helpers import (
 54    _poll_instance_ready as _poll_instance_ready,
 55)
 56from ctfy.sdk.admin import AdminClient
 57from ctfy.sdk.base import BaseHttpClient
 58from ctfy.sdk.competition import Competition
 59from ctfy.sdk.events import EventStream
 60from ctfy.sdk.resources.achievements import AchievementsResource
 61from ctfy.sdk.resources.activities import ActivitiesResource
 62from ctfy.sdk.resources.auth import AuthResource
 63from ctfy.sdk.resources.authoring import AuthoringResource
 64from ctfy.sdk.resources.awd import AwdResource
 65from ctfy.sdk.resources.challenges import ChallengesResource
 66from ctfy.sdk.resources.changelog import ChangelogResource
 67from ctfy.sdk.resources.competitions import CompetitionsResource
 68from ctfy.sdk.resources.eval import EvalResource, RegistryResource
 69from ctfy.sdk.resources.hints import HintsResource
 70from ctfy.sdk.resources.instances import InstancesResource
 71from ctfy.sdk.resources.me import MeResource
 72from ctfy.sdk.resources.messages import MessagesResource
 73from ctfy.sdk.resources.nodes import NodesResource
 74from ctfy.sdk.resources.registration import RegistrationResource
 75from ctfy.sdk.resources.reports import ReportsResource
 76from ctfy.sdk.resources.search import SearchResource
 77from ctfy.sdk.resources.series import SeriesResource
 78from ctfy.sdk.resources.site import SiteResource
 79from ctfy.sdk.resources.submissions import PatchesResource, SubmissionsResource
 80from ctfy.sdk.resources.suites import SuitesResource
 81from ctfy.sdk.resources.tasks import TasksResource
 82from ctfy.sdk.resources.teams import TeamsResource
 83from ctfy.sdk.resources.users import UsersResource
 84from ctfy.sdk.resources.vendor import VendorResource
 85from ctfy.server.models import (
 86    ClusterInfo,
 87    HealthResponse,
 88    LandingResponse,
 89    MetaResponse,
 90    PublicStatsResponse,
 91)
 92
 93__all__ = ["InstanceReadyResult", "PlatformClient"]
 94
 95
 96class PlatformClient(BaseHttpClient):
 97    """Player-facing HTTP client for the ctfy platform.
 98
 99    Methods are grouped into resource namespaces (``client.teams.list()``, …)
100    plus a per-competition scope via ``client.competition(id)``. The admin
101    surface is a separate :class:`~ctfy.sdk.admin.AdminClient` reached via
102    :attr:`admin`. Used by the CLI, the SDK, the MCP server, and external callers.
103    """
104
105    def __init__(
106        self,
107        server_url: str,
108        token: str = "",
109        max_retries: int = 2,
110        timeout: int = DEFAULT_PLATFORM_TIMEOUT,
111        transport: httpx.BaseTransport | None = None,
112        unavailable_budget_s: float = UNAVAILABLE_BUDGET_S,
113    ):
114        """``unavailable_budget_s``: how long one call waits out a ``503`` +
115        ``Retry-After`` (#3312: a redeploy is a wait, not a failed tool
116        call). ``0`` never waits — the platform's own MCP endpoint calling
117        itself, whose tool thread holds one of the pool's slots (#3504)."""
118        self._url = server_url.rstrip("/")
119        super().__init__(
120            f"{self._url}/api/v1",
121            token,
122            timeout=timeout,
123            max_retries=max_retries,
124            transport=transport,
125            unavailable_budget_s=unavailable_budget_s,
126        )
127
128    @property
129    def server_url(self) -> str:
130        """The platform root, without the ``/api/v1`` suffix.
131
132        Exposed for callers that must build a non-``/api/v1`` URL of
133        their own — today the shell WebSocket, whose ticket carries a
134        platform-relative path the client has to absolutise against the
135        scheme and host *it* reached us on.
136        """
137        return self._url
138
139    # -- resource namespaces ------------------------------------------------
140
141    @cached_property
142    def registration(self) -> RegistrationResource:
143        """The caller's own per-competition registration + team logo."""
144        return RegistrationResource(self)
145
146    @property
147    def authoring(self) -> AuthoringResource:
148        """Upload a challenge your team wrote, for a peer-authored event."""
149        return AuthoringResource(self)
150
151    @cached_property
152    def teams(self) -> TeamsResource:
153        """Public team discovery + profile reads."""
154        return TeamsResource(self)
155
156    @cached_property
157    def users(self) -> UsersResource:
158        """Public per-user profile reads."""
159        return UsersResource(self)
160
161    @cached_property
162    def me(self) -> MeResource:
163        """The calling user's profile, inbox, account, and progress."""
164        return MeResource(self)
165
166    @cached_property
167    def messages(self) -> MessagesResource:
168        """Site messages and the inbox stream (#2073)."""
169        return MessagesResource(self)
170
171    @cached_property
172    def auth(self) -> AuthResource:
173        """Password auth, OAuth identities, API tokens, sign-in discovery."""
174        return AuthResource(self)
175
176    @cached_property
177    def achievements(self) -> AchievementsResource:
178        """Public badge catalog, recent-unlock feed, easter eggs."""
179        return AchievementsResource(self)
180
181    @cached_property
182    def challenges(self) -> ChallengesResource:
183        """Global challenge catalog, attachments, facets, feedback chips."""
184        return ChallengesResource(self)
185
186    @cached_property
187    def site(self) -> SiteResource:
188        """The operator's site pages and their Contact form (#3414)."""
189        return SiteResource(self)
190
191    @cached_property
192    def hints(self) -> HintsResource:
193        """A challenge's hint tiers in a competition: read, and open (#2101)."""
194        return HintsResource(self)
195
196    @cached_property
197    def changelog(self) -> ChangelogResource:
198        """Public "What's New" feed, plus this account's seen marker."""
199        return ChangelogResource(self)
200
201    @cached_property
202    def competitions(self) -> CompetitionsResource:
203        """Discover competitions (``list`` / ``get``). To act within one, use
204        :meth:`competition`."""
205        return CompetitionsResource(self)
206
207    def competition(self, competition_id: str) -> Competition:
208        """Scope to one competition. The inherently competition-scoped
209        operations — register, your team (captain tooling + invites +
210        join-requests), the comp's challenges, team search, and standings —
211        hang off the returned :class:`~ctfy.sdk.competition.Competition`
212        handle, so ``competition_id`` is named once instead of on every call.
213        (Instance lifecycle and answer submission stay on :attr:`instances` /
214        :attr:`submissions`, keyed by ``instance_id``.)"""
215        return Competition(self, competition_id)
216
217    @cached_property
218    def series(self) -> SeriesResource:
219        """A recurring contest's ladder (public), not its schedule —
220        configuring a series is ``client.admin.series``."""
221        return SeriesResource(self)
222
223    @property
224    def suites(self) -> SuitesResource:
225        """The benchmark suites -- public challenge sets anybody practises or
226        evaluates against at any time (#2097). Playing one is
227        ``client.competition(id)``, like any competition."""
228        return SuitesResource(self)
229
230    @cached_property
231    def eval(self) -> EvalResource:
232        """Public model-evaluation leaderboard (ranking + dimensional breakdowns)."""
233        return EvalResource(self)
234
235    @property
236    def registry(self) -> RegistryResource:
237        """The container registry's token endpoint (docker follows it itself)."""
238        return RegistryResource(self)
239
240    @cached_property
241    def vendor(self) -> VendorResource:
242        """Vendor tenancy — the calling vendor's own models / runs (``pv_`` bearer)."""
243        return VendorResource(self)
244
245    @cached_property
246    def instances(self) -> InstancesResource:
247        """Launch / control / inspect challenge instances by instance id
248        (the competition is inferred server-side)."""
249        return InstancesResource(self)
250
251    @cached_property
252    def submissions(self) -> SubmissionsResource:
253        """Submit / verify answers + list submissions (by instance id), plus
254        the instance-less QA challenges."""
255        return SubmissionsResource(self)
256
257    @cached_property
258    def patches(self) -> PatchesResource:
259        """AWD+ defence: submit a patch, then watch for its verdict."""
260        return PatchesResource(self)
261
262    @cached_property
263    def awd(self) -> AwdResource:
264        """Classic AWD: submit a round's captured flags in one batch."""
265        return AwdResource(self)
266
267    @cached_property
268    def reports(self) -> ReportsResource:
269        """The engagement report: save a version, read the current one."""
270        return ReportsResource(self)
271
272    @cached_property
273    def search(self) -> SearchResource:
274        """Global search: competitions, challenges and teams by name."""
275        return SearchResource(self)
276
277    @cached_property
278    def tasks(self) -> TasksResource:
279        """The background tasks you may see: when each waited, ran and ended."""
280        return TasksResource(self)
281
282    @cached_property
283    def activities(self) -> ActivitiesResource:
284        """Platform activity log + histogram."""
285        return ActivitiesResource(self)
286
287    @cached_property
288    def nodes(self) -> NodesResource:
289        """Public worker-node list (operator node mgmt is on ``admin.nodes``)."""
290        return NodesResource(self)
291
292    @cached_property
293    def admin(self) -> AdminClient:
294        """Admin / operator surface (separate, role-gated server-side).
295
296        Shares this client's transport. See :class:`~ctfy.sdk.admin.AdminClient`.
297        """
298        return AdminClient(self)
299
300    # -- top-level convenience: server status / realtime / version ----------
301
302    def health(self) -> HealthResponse:
303        resp = self.request("GET", "/health")
304        _raise_for_status(resp)
305        return HealthResponse.model_validate(resp.json())
306
307    def get_meta(self) -> MetaResponse:
308        """Server identity + challenge repo SHA + build version.
309        Admin tokens additionally see cluster capacity + team / solve
310        counts in the same payload."""
311        resp = self.request("GET", "/meta")
312        _raise_for_status(resp)
313        return MetaResponse.model_validate(resp.json())
314
315    def get_landing(self) -> LandingResponse:
316        """What the public home page shows: the featured event (``None``
317        when nothing featured may be shown) and the catalog by domain."""
318        resp = self.request("GET", "/landing")
319        _raise_for_status(resp)
320        return LandingResponse.model_validate(resp.json())
321
322    def get_public_stats(self) -> PublicStatsResponse:
323        """The home page's live eval numbers and rounded platform scale
324        (#3413). Public and the same for every caller."""
325        resp = self.request("GET", "/stats/public")
326        _raise_for_status(resp)
327        return PublicStatsResponse.model_validate(resp.json())
328
329    def cluster_info(self) -> ClusterInfo:
330        """Aggregate worker-node capacity / utilisation (the public
331        capacity banner; no per-node detail)."""
332        resp = self.request("GET", "/cluster-info")
333        _raise_for_status(resp)
334        return ClusterInfo.model_validate(resp.json())
335
336    def check_server_compatibility(self, *, health: HealthResponse | None = None) -> VersionCheck:
337        """Compare this client's ``ctfy`` version against the server's.
338
339        Uses the cheap unauthenticated ``/health`` probe (pass an
340        already-fetched :class:`HealthResponse` to avoid a second round
341        trip). Pure classification — never prints, never raises on a
342        mismatch, never mutates anything. The caller (CLI, MCP, harness)
343        decides what to do with :class:`~ctfy.core.version.VersionCheck`
344        (typically: print ``.message`` to stderr when not ``.quiet``).
345
346        A server too old to report its version yields
347        :attr:`Compatibility.UNKNOWN` (``health.version == ""``), which
348        is ``.quiet`` — so this stays silent against legacy servers
349        rather than crying wolf.
350        """
351        h = health if health is not None else self.health()
352        return check_compatibility(package_version(), h.version)
353
354    def events(self, *, auto_reconnect: bool = True) -> EventStream:
355        """Open the platform SSE event stream.
356
357        Yields ``{"event": <name>, "data": <dict>}`` for each frame.
358        Filters: team-scoped events for every team the caller's user is
359        on (across every per-comp competition), plus all global events;
360        admin tokens additionally see admin-only frames.
361
362        Usage::
363
364            with client.events() as stream:
365                for event in stream:
366                    if event["event"] == "solve":
367                        ...
368
369        Auto-reconnects on transient network errors with exponential
370        backoff (1s → 30s capped). Set ``auto_reconnect=False`` to make
371        the iterator raise instead.
372        """
373        token = self._token
374
375        def _factory() -> httpx.Client:
376            # New client per session so a reconnect after a stale
377            # connection drops fresh sockets, not warmed-over ones.
378            return httpx.Client(base_url=self._base_url, timeout=None)
379
380        return EventStream(
381            client_factory=_factory,
382            path="/events",
383            token=token,
384            auto_reconnect=auto_reconnect,
385        )