ctfy.sdk.resources.authoring

  1"""``client.authoring`` — uploading a challenge you wrote.
  2
  3For the competition format where entrants set challenges for each other.
  4The upload is a ``.tar.gz`` of one benchmark directory, exactly the
  5shape ``tar czf mine.tgz mychallenge/`` produces — the wrapping
  6directory is stripped server-side, so an author never has to know
  7whether to include it.
  8
  9⚠️ The server records the upload ``pending`` and does not judge it: a
 10verdict means running the audit and a smoke test on a worker, which
 11takes minutes. ``review_status`` on the returned row is what to poll.
 12"""
 13
 14from __future__ import annotations
 15
 16from ctfy.challenge.benchmark import ChallengeCategory
 17from ctfy.challenge.scaffold import Stack
 18from ctfy.core.enums import (
 19    AuthoredAiAssistanceState,
 20    AuthoredCredit,
 21    AuthoredDestination,
 22    AuthoredLicenseState,
 23    AuthoredProvenanceState,
 24)
 25from ctfy.sdk._helpers import _raise_for_status
 26from ctfy.sdk.base import BaseHttpClient
 27from ctfy.server.models import (
 28    AuthoredAuditReport,
 29    AuthoredChallengeInfo,
 30    AuthoredChallengeRow,
 31    AuthoredRevisionInfo,
 32    AuthoringReceptionInfo,
 33    AuthoringTemplateManifest,
 34)
 35
 36
 37class AuthoringResource:
 38    """Upload and list the calling team's authored challenges."""
 39
 40    def __init__(self, http: BaseHttpClient) -> None:
 41        self._http = http
 42
 43    def upload(
 44        self,
 45        competition_id: str,
 46        *,
 47        slug: str,
 48        archive: bytes,
 49        filename: str = "challenge.tar.gz",
 50        license: AuthoredLicenseState = "",
 51        provenance: AuthoredProvenanceState = "",
 52        source_url: str = "",
 53        ai_assisted: AuthoredAiAssistanceState = "",
 54        eval_use: bool = False,
 55        credit: AuthoredCredit = "anonymous",
 56        accepted_terms_version: str = "",
 57        destination: AuthoredDestination = "public",
 58    ) -> AuthoredChallengeInfo:
 59        """Upload one challenge tree.
 60
 61        ``slug`` is your own label for the upload, never its id: the
 62        platform mints the benchmark id (``AUTHORED-<hex>``) and answers
 63        with it on the returned row. The label is normalised and refused
 64        rather than sanitised if it cannot be one.
 65
 66        Re-uploading the same slug replaces the tree **while it is still
 67        pending**; once an operator has ruled on it the id is fixed. An
 68        approved upload then takes a revision (:meth:`revise`); a rejected
 69        one is kept as it is, and a new version goes under a new name.
 70
 71        The contributor agreement: when the competition names one
 72        (``authoring_terms_version`` / ``authoring_terms_url`` on its
 73        detail), pass that version as ``accepted_terms_version`` and
 74        answer ``license``, ``provenance`` (with ``source_url`` for a
 75        ``port``) and ``ai_assisted``. ``eval_use`` and ``credit`` are
 76        grants, refused unless given.
 77
 78        ``destination`` is where it goes once published (plan P3.4): the
 79        public catalog, or ``eval_only`` — the evaluation pool, kept out of
 80        every public listing and launched only through a competition that
 81        is not public and curates it. The pool takes an original challenge
 82        (``provenance="original"``) whose author granted ``eval_use``;
 83        AI-assisted is allowed, and marked on the evaluation board.
 84
 85        The account must hold a verified email address, on every
 86        deployment: an unproved one is refused
 87        ``authoring_requires_verified_email`` before the archive is read.
 88
 89        ``auto_smoke`` on the returned row says whether the deployment is
 90        smoking the upload on an isolated worker (``queued`` — the verdict
 91        lands on the listing's ``smoke_verdict``) and, if not, why:
 92        ``budget_spent`` carries when the next run is free. ``None`` is a
 93        server that did not say, never *not smoked*.
 94
 95        ⚠️ **Only what you name is sent.** An absent declaration is
 96        *nobody said* on the platform, and putting ``license=`` or
 97        ``eval_use=false`` on the wire for a caller that chose neither
 98        would send a value nobody picked.
 99        """
100        declared: dict[str, str] = {
101            name: value
102            for name, value in (
103                ("license", license),
104                ("provenance", provenance),
105                ("source_url", source_url),
106                ("ai_assisted", ai_assisted),
107                ("accepted_terms_version", accepted_terms_version),
108            )
109            if value
110        }
111        if eval_use:
112            declared["eval_use"] = "true"
113        if credit != "anonymous":
114            declared["credit"] = credit
115        if destination != "public":
116            declared["destination"] = destination
117        resp = self._http.request(
118            "POST",
119            f"/competitions/{competition_id}/authored-challenges",
120            data={"slug": slug, **declared},
121            files={"file": (filename, archive, "application/gzip")},
122        )
123        _raise_for_status(resp)
124        return AuthoredChallengeInfo.model_validate(resp.json())
125
126    def revise(
127        self,
128        competition_id: str,
129        challenge_id: str,
130        *,
131        archive: bytes,
132        filename: str = "challenge.tar.gz",
133    ) -> AuthoredRevisionInfo:
134        """Propose a new tree for one of your **approved** uploads (plan P3.1).
135
136        Any of the upload's recorded authors may. The revision is reviewed
137        as a diff against the live version and a platform admin applies
138        it; until then players keep the live one, and boxes already
139        running keep it until they expire. A second proposal replaces the
140        first, whatever its verdict — the listing's ``revision`` says
141        where the current one stands.
142
143        Refused ``authored_revision_drops_questions`` when the tree drops a
144        question the live version has (solves are recorded against them),
145        ``authored_revision_unchanged`` for an identical tree, and
146        ``authored_challenge_not_revisable`` for an upload that is not
147        approved. The event's authoring window does not apply: a revision
148        maintains a challenge that outlives its event.
149        """
150        resp = self._http.request(
151            "POST",
152            f"/competitions/{competition_id}/authored-challenges/{challenge_id}/revisions",
153            files={"file": (filename, archive, "application/gzip")},
154        )
155        _raise_for_status(resp)
156        return AuthoredRevisionInfo.model_validate(resp.json())
157
158    def template(
159        self,
160        *,
161        category: ChallengeCategory = ChallengeCategory.WEB,
162        stack: Stack | None = None,
163        competition_id: str = "",
164    ) -> bytes:
165        """A starter challenge tree as ``.tar.gz`` bytes.
166
167        The same tree ``ctfy authoring init`` writes and the authoring
168        page downloads — all three call the server's own
169        ``scaffold_authored``, so a template fixed on one path cannot be
170        stale on another.
171
172        ⚠️ **Bytes, not a model.** The route answers an archive; parsing
173        it here would mean this library deciding where an author's
174        files land, which is `_pack`'s job in the opposite direction and
175        the caller's here.
176
177        ⚠️ ``stack`` belongs to ``web`` alone — the server refuses the
178        pair on any other category and refuses ``web`` without one —
179        and it is **omitted** rather than sent empty, since the query
180        parameter is an enum and ``""`` is not a member.
181
182        ⚠️ ``competition_id`` is optional because the template contains
183        nothing an event owns, but it is *accepted*: ``authoring`` is a
184        competition-scoped category, so a ``selected`` fine-grained
185        token names its event here as it does on the upload.
186        """
187        params: dict[str, str] = {"category": category.value}
188        if stack is not None:
189            params["stack"] = stack.value
190        if competition_id:
191            params["competition_id"] = competition_id
192        resp = self._http.request("GET", "/authoring/template", params=params)
193        _raise_for_status(resp)
194        return bytes(resp.content)
195
196    def audit(self, competition_id: str, challenge_id: str) -> AuthoredAuditReport:
197        """What the challenge audit says about one of your uploads.
198
199        A defect list you can fix and re-upload against, without waiting
200        for a reviewer to read the tree and write the same findings out
201        by hand.
202
203        ⚠️ ``outcome`` is the field to read first: ``ok`` means the
204        audit ran and ``errors`` / ``warnings`` are its verdict, while
205        ``timed_out`` and ``failed`` mean it could not say — an empty
206        ``findings`` list is not by itself a clean bill.
207        """
208        resp = self._http.request(
209            "GET",
210            f"/competitions/{competition_id}/authored-challenges/{challenge_id}/audit",
211        )
212        _raise_for_status(resp)
213        return AuthoredAuditReport.model_validate(resp.json())
214
215    def template_manifest(
216        self,
217        *,
218        category: ChallengeCategory = ChallengeCategory.WEB,
219        stack: Stack | None = None,
220        competition_id: str = "",
221    ) -> AuthoringTemplateManifest:
222        """What :meth:`template` would hand over, without downloading it.
223
224        The same tree, described rather than packed — so a caller can
225        show an author the files before spending the transfer, and the
226        two answers cannot disagree because the server builds one tree
227        for both routes.
228
229        ⚠️ The pairing rules are :meth:`template`'s, verbatim, and are
230        not restated here: the server refuses the same shapes with the
231        same message, which is what makes one refusal a menu rather
232        than three.
233        """
234        params: dict[str, str] = {"category": category.value}
235        if stack is not None:
236            params["stack"] = stack.value
237        if competition_id:
238            params["competition_id"] = competition_id
239        resp = self._http.request("GET", "/authoring/template/manifest", params=params)
240        _raise_for_status(resp)
241        return AuthoringTemplateManifest.model_validate(resp.json())
242
243    def list(self, competition_id: str) -> list[AuthoredChallengeRow]:
244        """The calling team's own uploads for one competition.
245
246        ⚠️ The team's, never the event's: before the release point a
247        list of everybody's challenge names is a preview of what the
248        field will have to solve.
249
250        ⚠️ **:class:`AuthoredChallengeRow`, never the ``Info`` the
251        upload answers with, and the difference is invisible without
252        this line.** That model adds ``files`` — the tree's paths — with
253        a ``default_factory``, so validating a listing row against it
254        *succeeds* and hands every caller ``files == []``: not a missing
255        field but a **claim that the upload has no files**, which is the
256        one sentence the two-model split exists to stop. Two live
257        readers would have said it — ``ctfy authoring list --json``
258        emits the key, and the MCP tool hands it to an agent —
259        and `test_sdk_openapi_parity` cannot see it, because that guard
260        asks whether a route is *reached* and never whether the answer
261        is *understood*.
262        """
263        resp = self._http.request("GET", f"/competitions/{competition_id}/authored-challenges")
264        _raise_for_status(resp)
265        return [AuthoredChallengeRow.model_validate(row) for row in resp.json()]
266
267    def reception(self, competition_id: str) -> AuthoringReceptionInfo:
268        """How this event's field fared against the challenges you wrote.
269
270        The other half of the board's authoring column: that one says
271        *how much*, this says which of your challenges earned it and how
272        close each landed to the band the curve pays for.
273
274        ⚠️ Read ``state`` per row before the numbers. ``priced`` is the
275        only one with a rate; ``not_curated`` means the organiser has
276        not put that challenge in this event's set, and ``no_field``
277        that your division is too small to produce a rate at all. Both
278        render as a blank cell and only one of them is about the
279        challenge.
280
281        ⚠️ ``scored`` is ``False`` on every competition not running
282        ``peer_authoring``, with no rows — not an error, just an event
283        that does not pay for authoring.
284        """
285        resp = self._http.request("GET", f"/competitions/{competition_id}/authoring/reception")
286        _raise_for_status(resp)
287        return AuthoringReceptionInfo.model_validate(resp.json())