ctfy.sdk

 55class AdminClient:
 56    """Admin / operator surface, grouped into resource namespaces.
 57
 58    Namespaces: :attr:`users`, :attr:`competitions`, :attr:`announcements`,
 59    :attr:`achievements`, :attr:`challenges`, :attr:`instances`,
 60    :attr:`records`, :attr:`nodes`, :attr:`observability`, :attr:`settings`,
 61    :attr:`competition_admins`.
 62    """
 63
 64    def __init__(self, http: BaseHttpClient) -> None:
 65        #: Shared transport (the parent PlatformClient when reached via
 66        #: ``client.admin``, or an owned client when built via ``connect``).
 67        self._http = http
 68
 69    @classmethod
 70    def connect(
 71        cls,
 72        server_url: str,
 73        token: str = "",
 74        *,
 75        max_retries: int = 3,
 76        timeout: int = DEFAULT_CLIENT_TIMEOUT,
 77    ) -> AdminClient:
 78        """Build an ``AdminClient`` that owns its own transport.
 79
 80        For operator tooling that doesn't already hold a
 81        :class:`PlatformClient`. The returned client is a context manager
 82        that closes its transport on exit.
 83        """
 84        base = server_url.rstrip("/")
 85        http = BaseHttpClient(f"{base}/api/v1", token, timeout=timeout, max_retries=max_retries)
 86        return cls(http)
 87
 88    @cached_property
 89    def users(self) -> AdminUsersResource:
 90        return AdminUsersResource(self._http)
 91
 92    @cached_property
 93    def competitions(self) -> AdminCompetitionsResource:
 94        return AdminCompetitionsResource(self._http)
 95
 96    @cached_property
 97    def announcements(self) -> AdminAnnouncementsResource:
 98        return AdminAnnouncementsResource(self._http)
 99
100    @cached_property
101    def achievements(self) -> AdminAchievementsResource:
102        return AdminAchievementsResource(self._http)
103
104    @cached_property
105    def challenges(self) -> AdminChallengesResource:
106        return AdminChallengesResource(self._http)
107
108    @cached_property
109    def instances(self) -> AdminInstancesResource:
110        return AdminInstancesResource(self._http)
111
112    @cached_property
113    def records(self) -> AdminRecordsResource:
114        return AdminRecordsResource(self._http)
115
116    @cached_property
117    def nodes(self) -> AdminNodesResource:
118        return AdminNodesResource(self._http)
119
120    @cached_property
121    def observability(self) -> AdminObservabilityResource:
122        return AdminObservabilityResource(self._http)
123
124    @cached_property
125    def settings(self) -> AdminSettingsResource:
126        return AdminSettingsResource(self._http)
127
128    @cached_property
129    def competition_admins(self) -> AdminCompetitionAdminsResource:
130        return AdminCompetitionAdminsResource(self._http)
131
132    def close(self) -> None:
133        """Close the underlying transport.
134
135        Only call this on a standalone client built via :meth:`connect`;
136        when reached via ``PlatformClient.admin`` the transport is shared
137        with — and closed by — the parent player client.
138        """
139        self._http.close()
140
141    def __enter__(self) -> Self:
142        return self
143
144    def __exit__(
145        self,
146        exc_type: type[BaseException] | None,
147        exc: BaseException | None,
148        tb: TracebackType | None,
149    ) -> None:
150        self.close()

 48class NodeClient(BaseHttpClient):
 49    """Thin sync HTTP client; one instance per node URL."""
 50
 51    def __init__(
 52        self,
 53        node_url: str,
 54        token: str,
 55        *,
 56        timeout: int = DEFAULT_CLIENT_TIMEOUT,
 57    ) -> None:
 58        super().__init__(f"{node_url.rstrip('/')}/api/v1", token, timeout=timeout)
 59
 60    # -- lifecycle ----------------------------------------------------------
 61
 62    def start_instance(
 63        self,
 64        *,
 65        challenge_id: str,
 66        instance_id: str,
 67        ttl: int,
 68        answers: dict[str, str],
 69        proxy_output_dir: str | None = None,
 70    ) -> dict[str, Any]:
 71        resp = self.request(
 72            "POST",
 73            "/instances",
 74            json={
 75                "challenge_id": challenge_id,
 76                "instance_id": instance_id,
 77                "ttl": ttl,
 78                "answers": answers,
 79                "proxy_output_dir": proxy_output_dir,
 80            },
 81        )
 82        _raise_for_node_status(resp)
 83        body: dict[str, Any] = resp.json()
 84        return body
 85
 86    def stop_instance(self, instance_id: str) -> None:
 87        resp = self.request("DELETE", f"/instances/{instance_id}")
 88        resp.raise_for_status()
 89
 90    def stop_all(self) -> None:
 91        resp = self.request("POST", "/admin/stop-all")
 92        resp.raise_for_status()
 93
 94    def rescan_challenges(self) -> dict[str, Any]:
 95        """Tell the node to drop its spec cache and re-scan challenges_dir.
 96
 97        Returns ``{total, added, removed}`` so the platform can report
 98        the per-node outcome of a cluster-wide rescan."""
 99        resp = self.request("POST", "/admin/rescan-challenges")
100        resp.raise_for_status()
101        body: dict[str, Any] = resp.json()
102        return body
103
104    # -- admin pre-build (image cache warming) ------------------------------
105
106    def build_challenge(self, challenge_id: str) -> dict[str, Any]:
107        """Ask the node to pre-build images for *challenge_id*.
108
109        Fires-and-returns: the node persists ``status="building"`` and
110        spawns a daemon thread; the body returned here is that initial
111        state row. Polling :meth:`get_build_state` is how the platform
112        learns when it lands on ``built`` / ``failed``.
113        """
114        resp = self.request("POST", f"/admin/challenges/{challenge_id}/build")
115        _raise_for_node_status(resp)
116        body: dict[str, Any] = resp.json()
117        return body
118
119    def build_all_challenges(self) -> dict[str, Any]:
120        """Queue background pre-build for every spec the node knows about.
121
122        Returns ``{queued, skipped_built, skipped_in_progress}`` so the
123        platform can report per-node what got picked up. Sequential
124        on the node side — no fan-out across the corpus.
125        """
126        resp = self.request("POST", "/admin/challenges/build-all")
127        _raise_for_node_status(resp)
128        body: dict[str, Any] = resp.json()
129        return body
130
131    def get_build_state(self) -> dict[str, Any]:
132        """Fetch every per-challenge build-state row on this node.
133
134        Returns ``{"rows": [{challenge_id, status, built_at, error}, …]}``.
135        ``status`` is one of ``unbuilt`` / ``building`` / ``built`` /
136        ``failed``; ``unbuilt`` placeholders are synthesised for specs
137        the node has seen but never been asked to build.
138        """
139        resp = self.request("GET", "/admin/challenges/build-state")
140        _raise_for_node_status(resp)
141        body: dict[str, Any] = resp.json()
142        return body
143
144    # -- status / health ----------------------------------------------------
145
146    def get_status(self, instance_id: str) -> dict[str, Any]:
147        resp = self.request("GET", f"/instances/{instance_id}/status")
148        resp.raise_for_status()
149        body: dict[str, Any] = resp.json()
150        return body
151
152    def check_health(self, instance_id: str) -> bool:
153        resp = self.request("GET", f"/instances/{instance_id}/health")
154        resp.raise_for_status()
155        return bool(resp.json().get("is_healthy"))
156
157    def node_health(self) -> dict[str, Any]:
158        """Liveness + ``{running, capacity}`` for heartbeat."""
159        resp = self.request("GET", "/health")
160        resp.raise_for_status()
161        body: dict[str, Any] = resp.json()
162        return body
163
164    # -- traffic / runtime --------------------------------------------------
165
166    def get_traffic(self, instance_id: str) -> dict[str, Any]:
167        """Fetch mitmproxy flow data; file lives on the node's FS."""
168        resp = self.request("GET", f"/instances/{instance_id}/traffic")
169        resp.raise_for_status()
170        body: dict[str, Any] = resp.json()
171        return body
172
173    def list_containers(self, instance_id: str) -> list[dict[str, Any]]:
174        """Enumerate every container in an instance's compose project.
175
176        Backs the admin-shell feature: the platform forwards a
177        ``GET /admin/instances/{id}/containers`` to the assigned node,
178        which returns one row per container (challenge services and
179        platform-injected sidecars alike). The WebSocket reverse-proxy
180        is opened separately and does not go through ``NodeClient``.
181        """
182        resp = self.request("GET", f"/instances/{instance_id}/containers")
183        _raise_for_node_status(resp)
184        body: list[dict[str, Any]] = resp.json()
185        return body
186
187    def get_container_logs(self, instance_id: str) -> str:
188        """Fetch combined container stdout/stderr for archival."""
189        resp = self.request("GET", f"/instances/{instance_id}/container-logs")
190        resp.raise_for_status()
191        return str(resp.json().get("logs") or "")
192
193    def get_pcap(self, instance_id: str) -> bytes:
194        """Fetch the raw tcpdump capture for *instance_id*.
195
196        Returns an empty ``bytes`` when no capture exists (sidecar
197        disabled, instance never reached the running state, etc.) so
198        callers can persist conditionally without try/except.
199        """
200        resp = self.request("GET", f"/instances/{instance_id}/pcap")
201        if resp.status_code == 404:
202            return b""
203        resp.raise_for_status()
204        return resp.content
205
206    def get_agent_runtime(self, instance_id: str) -> dict[str, Any]:
207        """Provider-agnostic runtime hints for attaching an agent (proxy URL,
208        CA PEM, optional Docker-specific names). Replaces the old
209        sandbox-network shape."""
210        resp = self.request("GET", f"/instances/{instance_id}/agent-runtime")
211        resp.raise_for_status()
212        body: dict[str, Any] = resp.json()
213        return body
214
215    # -- per-instance rendered attachments ---------------------------------
216
217    def list_instance_attachments(self, instance_id: str) -> dict[str, Any]:
218        """List per-instance attachments rendered into the node's workdir.
219
220        Returns the raw JSON dict — caller projects through
221        :class:`AttachmentList` for typing. Used by the platform's
222        per-instance attachment endpoint to surface team-specific
223        rendered file listings."""
224        resp = self.request("GET", f"/instances/{instance_id}/attachments")
225        resp.raise_for_status()
226        body: dict[str, Any] = resp.json()
227        return body
228
229    def get_openvpn_config(self, instance_id: str) -> bytes:
230        """Fetch the per-instance OpenVPN client config from the node.
231
232        The node reads ``/etc/openvpn/client.ovpn`` out of the instance's
233        ``openvpn`` service container (generated on first boot by the
234        ``ctfy/openvpn-base`` image's bootstrap). Returns the body
235        verbatim — the platform-side route adds the
236        ``Content-Disposition`` header before re-emitting to the player.
237
238        Raises ``httpx.HTTPStatusError`` on non-2xx — the platform's
239        proxy route catches 404 and re-emits to the player, anything
240        else is treated as a 502.
241        """
242        resp = self.request("GET", f"/instances/{instance_id}/openvpn-config")
243        resp.raise_for_status()
244        return resp.content
245
246    def download_instance_attachment(self, instance_id: str, filename: str) -> tuple[bytes, str]:
247        """Download one per-instance attachment as ``(bytes, content_type)``.
248
249        Buffers the whole body — attachments are bounded (typical case
250        is a 10 KB binary or a small text file). For huge captures the
251        caller should hand the player a CDN URL instead.
252
253        Raises ``httpx.HTTPStatusError`` on non-2xx — the platform's
254        proxy route catches 404 and re-emits to the player, anything
255        else is a 502."""
256        resp = self.request(
257            "GET",
258            f"/instances/{instance_id}/attachments/{filename}",
259        )
260        resp.raise_for_status()
261        return resp.content, resp.headers.get("content-type", "application/octet-stream")

 77class PlatformClient(BaseHttpClient):
 78    """Player-facing HTTP client for the ctfy platform.
 79
 80    Methods are grouped into resource namespaces (``client.teams.list()``, …)
 81    plus a per-competition scope via ``client.competition(id)``. The admin
 82    surface is a separate :class:`~ctfy.sdk.admin.AdminClient` reached via
 83    :attr:`admin`. Used by the CLI, the SDK, the MCP server, and external callers.
 84    """
 85
 86    def __init__(
 87        self,
 88        server_url: str,
 89        token: str = "",
 90        max_retries: int = 3,
 91        timeout: int = DEFAULT_CLIENT_TIMEOUT,
 92    ):
 93        self._url = server_url.rstrip("/")
 94        super().__init__(f"{self._url}/api/v1", token, timeout=timeout, max_retries=max_retries)
 95
 96    # -- resource namespaces ------------------------------------------------
 97
 98    @cached_property
 99    def teams(self) -> TeamsResource:
100        """Public team discovery + profile reads."""
101        return TeamsResource(self)
102
103    @cached_property
104    def users(self) -> UsersResource:
105        """Public per-user profile reads."""
106        return UsersResource(self)
107
108    @cached_property
109    def me(self) -> MeResource:
110        """The calling user's profile, inbox, account, and progress."""
111        return MeResource(self)
112
113    @cached_property
114    def auth(self) -> AuthResource:
115        """Password auth, OAuth identities, API tokens, sign-in discovery."""
116        return AuthResource(self)
117
118    @cached_property
119    def achievements(self) -> AchievementsResource:
120        """Public badge catalog, recent-unlock feed, easter eggs."""
121        return AchievementsResource(self)
122
123    @cached_property
124    def challenges(self) -> ChallengesResource:
125        """Global challenge catalog, attachments, facets, feedback chips."""
126        return ChallengesResource(self)
127
128    @cached_property
129    def competitions(self) -> CompetitionsResource:
130        """Discover competitions (``list`` / ``get``). To act within one, use
131        :meth:`competition`."""
132        return CompetitionsResource(self)
133
134    def competition(self, competition_id: str) -> Competition:
135        """Scope to one competition. The inherently competition-scoped
136        operations — register, your team (captain tooling + invites +
137        join-requests), the comp's challenges, team search, and standings —
138        hang off the returned :class:`~ctfy.sdk.competition.Competition`
139        handle, so ``competition_id`` is named once instead of on every call.
140        (Instance lifecycle and answer submission stay on :attr:`instances` /
141        :attr:`submissions`, keyed by ``instance_id``.)"""
142        return Competition(self, competition_id)
143
144    @cached_property
145    def instances(self) -> InstancesResource:
146        """Launch / control / inspect challenge instances by instance id
147        (the competition is inferred server-side)."""
148        return InstancesResource(self)
149
150    @cached_property
151    def submissions(self) -> SubmissionsResource:
152        """Submit / verify answers + list submissions (by instance id), plus
153        the instance-less QA challenges."""
154        return SubmissionsResource(self)
155
156    @cached_property
157    def scoreboard(self) -> ScoreboardResource:
158        """Global standings, per-challenge stats, persisted snapshots."""
159        return ScoreboardResource(self)
160
161    @cached_property
162    def activities(self) -> ActivitiesResource:
163        """Platform activity log + histogram."""
164        return ActivitiesResource(self)
165
166    @cached_property
167    def nodes(self) -> NodesResource:
168        """Public worker-node list (operator node mgmt is on ``admin.nodes``)."""
169        return NodesResource(self)
170
171    @cached_property
172    def admin(self) -> AdminClient:
173        """Admin / operator surface (separate, role-gated server-side).
174
175        Shares this client's transport. See :class:`~ctfy.sdk.admin.AdminClient`.
176        """
177        return AdminClient(self)
178
179    # -- top-level convenience: server status / realtime / version ----------
180
181    def health(self) -> HealthResponse:
182        resp = self.request("GET", "/health")
183        _raise_for_status(resp)
184        return HealthResponse.model_validate(resp.json())
185
186    def get_meta(self) -> MetaResponse:
187        """Server identity + challenge repo SHA + build version.
188        Admin tokens additionally see cluster capacity + team / solve
189        counts in the same payload."""
190        resp = self.request("GET", "/meta")
191        _raise_for_status(resp)
192        return MetaResponse.model_validate(resp.json())
193
194    def cluster_info(self) -> ClusterInfo:
195        """Aggregate worker-node capacity / utilisation (the public
196        capacity banner; no per-node detail)."""
197        resp = self.request("GET", "/cluster-info")
198        _raise_for_status(resp)
199        return ClusterInfo.model_validate(resp.json())
200
201    def check_server_compatibility(self, *, health: HealthResponse | None = None) -> VersionCheck:
202        """Compare this client's ``ctfy`` version against the server's.
203
204        Uses the cheap unauthenticated ``/health`` probe (pass an
205        already-fetched :class:`HealthResponse` to avoid a second round
206        trip). Pure classification — never prints, never raises on a
207        mismatch, never mutates anything. The caller (CLI, MCP, harness)
208        decides what to do with :class:`~ctfy.core.version.VersionCheck`
209        (typically: print ``.message`` to stderr when not ``.quiet``).
210
211        A server too old to report its version yields
212        :attr:`Compatibility.UNKNOWN` (``health.version == ""``), which
213        is ``.quiet`` — so this stays silent against legacy servers
214        rather than crying wolf.
215        """
216        h = health if health is not None else self.health()
217        return check_compatibility(package_version(), h.version)
218
219    def events(self, *, auto_reconnect: bool = True) -> EventStream:
220        """Open the platform SSE event stream.
221
222        Yields ``{"event": <name>, "data": <dict>}`` for each frame.
223        Filters: team-scoped events for every team the caller's user is
224        on (across every per-comp competition), plus all global events;
225        admin tokens additionally see admin-only frames.
226
227        Usage::
228
229            with client.events() as stream:
230                for event in stream:
231                    if event["event"] == "solve":
232                        ...
233
234        Auto-reconnects on transient network errors with exponential
235        backoff (1s → 30s capped). Set ``auto_reconnect=False`` to make
236        the iterator raise instead.
237        """
238        token = self._token
239
240        def _factory() -> httpx.Client:
241            # New client per session so a reconnect after a stale
242            # connection drops fresh sockets, not warmed-over ones.
243            return httpx.Client(base_url=self._base_url, timeout=None)
244
245        return EventStream(
246            client_factory=_factory,
247            path="/events",
248            token=token,
249            auto_reconnect=auto_reconnect,
250        )