ctfy.sdk.resources.reports

  1"""``client.reports`` — the engagement report a team is graded on."""
  2
  3from __future__ import annotations
  4
  5from ctfy.sdk._helpers import _raise_for_status
  6from ctfy.sdk.base import BaseHttpClient
  7from ctfy.server.models import (
  8    MyReportsResponse,
  9    ReportAttachmentInfo,
 10    ReportAttachmentsResponse,
 11    ReportInfo,
 12    ReportSaveResponse,
 13    ReportStanding,
 14    ReportVersionsResponse,
 15)
 16
 17
 18class ReportsResource:
 19    """One revisable report per (team, competition, challenge).
 20
 21    A GAUNTLET range is one estate with its own kill chain, so an event
 22    curating four of them is four engagements and four write-ups. The
 23    competition still owns the deadline; the artifact is per range.
 24
 25    ⚠️ **The last version saved is the one that gets graded**, and every
 26    version is kept for the appeal. So :meth:`save` sends the whole
 27    document each time — there is no append — and an empty one is
 28    refused rather than stored, because an accidental blank save would
 29    otherwise replace the artifact the team is scored on.
 30    """
 31
 32    def __init__(self, http: BaseHttpClient) -> None:
 33        self._http = http
 34
 35    def save(self, competition_id: str, challenge_id: str, content: str) -> ReportSaveResponse:
 36        """Save a new version; get back what it wrote and what it credited.
 37
 38        Refused outside the competition's play sessions and for a
 39        disqualified team, exactly like every other progress path — the
 40        report *is* this format's progress path.
 41
 42        ``newly_credited`` counts the sentinels quoted in **this** save
 43        that the team did not already hold, which is the whole feedback
 44        channel the format allows: enough to learn the last edit was
 45        worth something, never enough to learn how many exist.
 46        """
 47        resp = self._http.request(
 48            "PUT",
 49            f"/competitions/{competition_id}/challenges/{challenge_id}/report",
 50            json={"content": content},
 51        )
 52        _raise_for_status(resp)
 53        return ReportSaveResponse.model_validate(resp.json())
 54
 55    def mine(self, competition_id: str) -> MyReportsResponse:
 56        """Which ranges this team has written up, and how much of each.
 57
 58        Only ranges with a saved report — the ones not started are the
 59        competition's challenge list minus these, which the caller
 60        already holds.
 61        """
 62        resp = self._http.request("GET", f"/competitions/{competition_id}/reports")
 63        _raise_for_status(resp)
 64        return MyReportsResponse.model_validate(resp.json())
 65
 66    def get(self, competition_id: str, challenge_id: str) -> ReportInfo:
 67        """This team's current report on one range — the highest version.
 68
 69        **404 when nothing has been saved**, rather than an empty
 70        report: a blank body would be indistinguishable from a saved
 71        empty one, and the write path refuses those precisely so the two
 72        remain different facts.
 73        """
 74        resp = self._http.request(
 75            "GET", f"/competitions/{competition_id}/challenges/{challenge_id}/report"
 76        )
 77        _raise_for_status(resp)
 78        return ReportInfo.model_validate(resp.json())
 79
 80    def versions(self, competition_id: str, challenge_id: str) -> ReportVersionsResponse:
 81        """Every version saved for one range, newest first, with bodies."""
 82        resp = self._http.request(
 83            "GET", f"/competitions/{competition_id}/challenges/{challenge_id}/report/versions"
 84        )
 85        _raise_for_status(resp)
 86        return ReportVersionsResponse.model_validate(resp.json())
 87
 88    # -- 交卷, and asking to be judged now ---------------------------------
 89    #
 90    # ⚠️ **Two verbs, not one with a flag.** They are separately
 91    # reachable in both directions: a team may want a verdict on a draft
 92    # it fully intends to keep editing, and a team that has run out of
 93    # grading requests must still be able to hand its work in. One call
 94    # with ``finalize=True`` would make the action that must never be
 95    # refused draw on the quota that can refuse it.
 96
 97    def finalize(self, competition_id: str, challenge_id: str) -> ReportStanding:
 98        """交卷 — declare the current version this range's deliverable.
 99
100        The save route then refuses a new version until :meth:`reopen`,
101        and, quota permitting, the report is judged now rather than when
102        the quiet window elapses.
103
104        ⚠️ **Never refused for want of quota.** Past the bound this still
105        hands the report in and the ordinary quiet window grades it,
106        which it must — a finalised report cannot be saved again.
107        """
108        resp = self._http.request(
109            "POST", f"/competitions/{competition_id}/challenges/{challenge_id}/report/finalize"
110        )
111        _raise_for_status(resp)
112        return ReportStanding.model_validate(resp.json())
113
114    def reopen(self, competition_id: str, challenge_id: str) -> ReportStanding:
115        """Withdraw 交卷 so the team can save again.
116
117        Reversible while the report window is open — the window is the
118        deadline, and a hand-in nobody can take back only buys a support
119        queue against an artifact this platform lets teams revise.
120
121        ⚠️ **The spent grading request is not refunded**, which is what
122        keeps finalise → reopen → finalise from buying a model call a
123        minute.
124        """
125        resp = self._http.request(
126            "POST", f"/competitions/{competition_id}/challenges/{challenge_id}/report/reopen"
127        )
128        _raise_for_status(resp)
129        return ReportStanding.model_validate(resp.json())
130
131    def request_grading(self, competition_id: str, challenge_id: str) -> ReportStanding:
132        """Ask for the current version to be judged now, without handing in.
133
134        Costed: the grading due-list only ever holds a report's *current*
135        version, so drafting is one model call per quiet spell however
136        many times a team saves, while save-then-request is one per save.
137        ``ReportStanding.grade_requests_limit`` is the bound and **``0``
138        is unlimited**.
139
140        ⚠️ **Pressing it twice about one version is a success**, not a
141        second request — the stamp is on the version, so nothing more is
142        spent.
143        """
144        resp = self._http.request(
145            "POST", f"/competitions/{competition_id}/challenges/{challenge_id}/report/grade-now"
146        )
147        _raise_for_status(resp)
148        return ReportStanding.model_validate(resp.json())
149
150    # -- the appendix ------------------------------------------------------
151    #
152    # ⚠️ **Attachments are evidence, never the answer.** Grading reads
153    # the report *text* — the sentinel extraction is a regex over it and
154    # the narrative grader is handed its prose — so a flag legible only
155    # inside a screenshot scores nothing. Upload the screenshot *and*
156    # write the value and the finding out in the report.
157
158    def attachments(self, competition_id: str, challenge_id: str) -> ReportAttachmentsResponse:
159        """This engagement's appendix, oldest first, plus how many more it may take."""
160        resp = self._http.request(
161            "GET", f"/competitions/{competition_id}/challenges/{challenge_id}/report/attachments"
162        )
163        _raise_for_status(resp)
164        return ReportAttachmentsResponse.model_validate(resp.json())
165
166    def upload_attachment(
167        self,
168        competition_id: str,
169        challenge_id: str,
170        *,
171        content: bytes,
172        filename: str = "evidence.png",
173        content_type: str = "application/octet-stream",
174    ) -> ReportAttachmentInfo:
175        """Add one evidence file to this engagement's appendix.
176
177        The server sniffs the bytes, so ``filename`` and ``content_type``
178        fill the multipart envelope and decide nothing: real image bytes
179        get an image type and may render inline for the organiser,
180        anything else is stored opaque and served as a download.
181
182        Refused when the deployment has no object storage configured
183        (``503 storage_unavailable``) — the report itself still saves,
184        it just takes text only.
185        """
186        resp = self._http.request(
187            "POST",
188            f"/competitions/{competition_id}/challenges/{challenge_id}/report/attachments",
189            files={"file": (filename, content, content_type)},
190        )
191        _raise_for_status(resp)
192        return ReportAttachmentInfo.model_validate(resp.json())
193
194    def attachment_bytes(self, competition_id: str, challenge_id: str, attachment_id: str) -> bytes:
195        """Fetch one of this team's own attachments.
196
197        Streamed through the platform rather than from a bucket URL, so
198        the object store needs no public-read policy.
199        """
200        resp = self._http.request(
201            "GET",
202            f"/competitions/{competition_id}/challenges/{challenge_id}"
203            f"/report/attachments/{attachment_id}",
204        )
205        _raise_for_status(resp)
206        return resp.content
207
208    def delete_attachment(
209        self, competition_id: str, challenge_id: str, attachment_id: str
210    ) -> ReportAttachmentsResponse:
211        """Remove one attachment. Returns the appendix as it now stands.
212
213        A hard delete: the reason a team removes a file is that it should
214        not have been uploaded, and keeping the bytes would answer that
215        request with a lie.
216        """
217        resp = self._http.request(
218            "DELETE",
219            f"/competitions/{competition_id}/challenges/{challenge_id}"
220            f"/report/attachments/{attachment_id}",
221        )
222        _raise_for_status(resp)
223        return ReportAttachmentsResponse.model_validate(resp.json())