ctfy.server.models

28class AchievementCatalogEntry(CtfyModel):
29    """One badge as advertised to the frontend."""
30
31    id: str
32    name: str
33    description: str
34    icon: str
35    tier: str
36    secret: bool = False
37    # Only populated for locked entries on /me/achievements — the
38    # general catalog endpoint and unlocked entries don't carry it.
39    progress: AchievementProgress | None = None
40    # Score weight per tier (bronze=10, silver=25, gold=50, secret=100).
41    points: int = 0
42    # Number of distinct teams that have unlocked this badge.
43    earned_by_count: int = 0
44    # ``common`` | ``uncommon`` | ``rare`` | ``epic`` | ``mythic`` |
45    # ``unearned``.
46    rarity: str = "unearned"

14class AchievementProgress(CtfyModel):
15    """Quantifiable progress toward a locked badge.
16
17    ``current`` is what the team has so far, ``target`` is the
18    threshold the rule predicate checks against. Provided only when
19    the achievement has a registered progress provider (decathlete,
20    centurion, completionist, sisyphus, unicorn). Time-of-day /
21    first-blood / easter-egg badges return ``progress = null``.
22    """
23
24    current: int
25    target: int

65class AchievementSummary(CtfyModel):
66    """Aggregate roll-up for the Achievements page header."""
67
68    unlocked_count: int = 0
69    total_count: int = 0
70    score: int = 0
71    total_score: int = 0

18class Activity(CtfyModel):
19    """A single activity event in the platform log."""
20
21    id: str = ""
22    timestamp: datetime | None = None
23    event: str  # See PlatformEvent enum for valid values
24    team_id: str = ""
25    team_name: str = ""
26    challenge_id: str = ""
27    # Who triggered this event — surfaced on the public feed so admins
28    # can filter by actor and auditors can trace back. Values mirror
29    # the ActivityState fields in core.state.models.
30    actor_id: str = ""
31    actor_name: str = ""
32    actor_type: str = ""
33    # Denormalised actor avatar (GitHub/Google), surfaced on the feed so
34    # each event can render the actor's real face. Empty ⇒ the frontend
35    # renders a generated initials chip instead.
36    actor_avatar_url: str = ""
37    detail: ActivityDetail = Field(default_factory=ActivityDetail)

55class ActivityTimeseries(CtfyModel):
56    """Bucketed activity counts for the per-team activity histogram.
57
58    Same ``ts`` semantics as ``AdminTimeseries`` — oldest-first, right
59    edge anchored to "now". ``events`` is the sorted union of event
60    types that appear in any bucket, so the frontend has a stable list
61    of stack segments to render even when individual buckets are empty.
62    """
63
64    window_s: int = 0
65    bucket_s: int = 0
66    events: list[str] = Field(default_factory=list)
67    buckets: list[ActivityTimeseriesBucket] = Field(default_factory=list)

40class ActivityTimeseriesBucket(CtfyModel):
41    """One bucket of the team's activity histogram.
42
43    ``counts`` is keyed by event type (``flag_correct``, ``instance_started``,
44    …) so the frontend can stack each event as its own bar segment without
45    a follow-up shape-change to add new event types.
46
47    See :class:`AdminTimeseriesBucket` for the ``partial`` semantics.
48    """
49
50    ts: float = 0.0  # right edge, Unix seconds
51    counts: dict[str, int] = Field(default_factory=dict)
52    partial: bool = False

69class AdminChallengeLastError(CtfyModel):
70    """Most-recent error against a challenge, surfaced on the per-challenge
71    admin row so an admin can spot a broken challenge without opening
72    instance history."""
73
74    ts: float = 0.0  # stopped_at of the failing instance
75    message: str = ""
76    instance_id: str = ""

111class AdminChallengeLatencyBucket(CtfyModel):
112    """One fixed bucket of the cluster-wide launch-duration histogram.
113
114    The Challenges admin table paginates server-side, so the pooled
115    "how slow are launches overall" picture can't be re-derived in the
116    browser from one page of rows — this endpoint pools every
117    challenge's recent successful launches and bins them with the same
118    absolute edges the per-row drawer uses, so cross-page the shape
119    stays comparable.
120    """
121
122    label: str
123    count: int = 0

52class AdminChallengeQuestions(CtfyModel):
53    """Every question a challenge declares, gated ones included.
54
55    The organiser's counterpart to the catalog projection, which omits
56    gated entries (see ``projections.question_infos``). Without this an
57    organiser running an exercise has no way to answer "which milestones
58    exist, and why did this team not get credit for one" short of reading
59    ``metadata.yaml`` off disk — and the corpus is a submodule the
60    deployment mounts read-only, not something the admin console can see.
61
62    Deliberately the **same** ``QuestionPublicInfo`` rows rather than a
63    wider admin model: this route changes *who may read*, not *what is
64    said*. The groundtruth is still never projected — a static ``answer``
65    lives in metadata and a dynamic one is minted per instance, and
66    neither belongs on a page. ``AdminTeamRow`` is a separate model
67    because it adds a field the public one must not carry; there is no
68    such field here.
69    """
70
71    challenge_id: str
72    questions: list[QuestionPublicInfo] = Field(default_factory=list)
73    # How many of ``questions`` are gated behind ``requires``. Served
74    # rather than derived so a client cannot disagree with the server
75    # about what the catalog is withholding.
76    gated_count: int = 0

 79class AdminChallengeStatsRow(CtfyModel):
 80    """One row of the per-challenge admin dashboard.
 81
 82    Aggregates over ``InstanceRecord`` (lifetime) plus live ``InstanceState``
 83    (running). Launch-duration percentiles are computed only over rows with
 84    both ``requested_at`` and ``ready_at`` populated — error rows that never
 85    reached READY contribute to ``errors`` / ``error_rate`` but not to p50/p95.
 86    """
 87
 88    challenge_id: str
 89    name: str = ""
 90    difficulty: str = ""
 91    # Spec metadata folded in so the admin table no longer has to join
 92    # a second /challenges bulk fetch in the browser to show / sort /
 93    # filter by these (it paginates server-side now).
 94    category: str = ""
 95    tags: list[str] = Field(default_factory=list)
 96    question_count: int = 0
 97    launches: int = 0
 98    errors: int = 0
 99    error_rate: float = 0.0
100    avg_launch_s: float = 0.0
101    p50_launch_s: float = 0.0
102    p95_launch_s: float = 0.0
103    solve_rate: float = 0.0
104    running_count: int = 0
105    last_error: AdminChallengeLastError | None = None
106    # Newest-first launch durations, capped at 20, used for the inline
107    # sparkline. Recorded only for successful launches.
108    recent_launch_durations: list[float] = Field(default_factory=list)

225class AdminChallengeTimeseries(CtfyModel):
226    """Per-challenge bucketed health metrics for the admin drilldown.
227
228    Backs the row-level drawer on /admin/challenges that surfaces "did
229    this challenge's error rate spike at some specific time" without
230    forcing the operator to scrub through raw activity.
231    """
232
233    challenge_id: str = ""
234    window_s: int = 0
235    bucket_s: int = 0
236    buckets: list[AdminChallengeTimeseriesBucket] = Field(default_factory=list)

206class AdminChallengeTimeseriesBucket(CtfyModel):
207    """One bucket of the per-challenge health time-series.
208
209    Carries enough fields for the admin UI to render error-rate **and**
210    launch-duration trends from a single response — no need for the
211    frontend to issue three calls or do its own bucketing.
212
213    See :class:`AdminTimeseriesBucket` for the ``partial`` semantics.
214    """
215
216    ts: float = 0.0  # right edge, Unix seconds
217    launches: int = 0
218    errors: int = 0
219    error_rate: float = 0.0  # errors / launches; 0 when no launches
220    p50_launch_s: float = 0.0
221    p95_launch_s: float = 0.0
222    partial: bool = False

43class AdminFeedbackRow(CtfyModel):
44    """One row on the admin feedback audit list.
45
46    Mirrors ``SolveFeedbackState`` plus denormalised user identity for
47    triage convenience. Only ``require_admin``-gated endpoints expose
48    this shape; the public ``stats`` endpoint never includes per-user
49    fields.
50    """
51
52    user_id: str
53    user_display_name: str = ""
54    user_email: str = ""
55    challenge_id: str
56    team_id: str
57    competition_id: str
58    reaction: Reaction
59    created_at: datetime | None = None
60    updated_at: datetime | None = None

167class AdminHealthFlags(CtfyModel):
168    """Aggregated red-flag panels for the admin Overview "needs attention"
169    section. All four lists are independently populated and may be empty."""
170
171    stuck_starting: list[AdminStuckInstance] = Field(default_factory=list)
172    recent_errors: list[AdminRecentError] = Field(default_factory=list)
173    unhealthy_nodes: list[AdminUnhealthyNode] = Field(default_factory=list)
174    silent_challenges: list[AdminSilentChallenge] = Field(default_factory=list)

255class AdminOverview(CtfyModel):
256    """Single aggregate payload for the admin landing page."""
257
258    nodes: AdminOverviewCounts = Field(default_factory=AdminOverviewCounts)
259    config: DeploymentConfig = Field(default_factory=DeploymentConfig)
260    capacity: int = 0
261    running_instances: int = 0
262    teams_total: int = 0
263    solves_total: int = 0
264    solves_today: int = 0
265    # User-engagement counters — the "are people actually on the platform right
266    # now?" signal the infra/challenge/team metrics above don't answer.
267    # ``users_active_24h`` is distinct humans who triggered a write action
268    # (launch / submit / solve / join / answer) in the last 24h, not raw logins
269    # (pure browsing leaves no activity row). ``users_new_24h`` is registrations
270    # in the same window. All default to 0 so the field set stays additive.
271    users_total: int = 0
272    users_active_24h: int = 0
273    users_new_24h: int = 0

64class AdminOverviewCounts(CtfyModel):
65    total: int = 0
66    healthy: int = 0

901class AdminPatchSubmissionDetail(AdminPatchSubmissionInfo):
902    """One submission with the code it carried.
903
904    This is what keeping the bytes was *for*: a team disputes a verdict,
905    or a checker bug is found on day two, and someone has to read what
906    was actually submitted. Without a reader the stored blobs bought
907    nothing.
908    """
909
910    #: ``{path: base64(bytes)}``. Base64 rather than text because a
911    #: patch target may legitimately be binary, and decoding it into a
912    #: string would corrupt it into something that merely looks like a
913    #: bad submission.
914    files_b64: dict[str, str] = Field(default_factory=dict)
915    #: ``{path: sha256}`` — an equality match across teams, which is
916    #: what is left once uniqueness has stopped flag sharing but nothing
917    #: stops *patch* sharing.
918    digests: dict[str, str] = Field(default_factory=dict)

880class AdminPatchSubmissionInfo(PatchSubmissionInfo):
881    """One row of the organiser's defence queue.
882
883    The player's view plus the four things only an organiser asks:
884    *whose* it is, and — when a verdict is disputed — which worker
885    decided it after how many tries.
886
887    Still **without the code**, and here that is a stronger requirement
888    than on the parent: this is a competition-wide listing, so shipping
889    bodies would mean reading every stored patch of the event to render
890    a table of statuses. The bytes live on
891    :class:`AdminPatchSubmissionDetail`, one row at a time.
892    """
893
894    team_id: str = ""
895    user_id: str = ""
896    #: Which worker judged it, for correlating with that node's logs.
897    node_id: str = ""
898    attempts: int = 0

921class AdminPatchSubmissionPage(CtfyModel):
922    """A page of the defence queue, with the total behind it.
923
924    ``total`` is its own query rather than ``len(items)`` so a pager can
925    say "1-20 of 340" — and, with a ``status`` filter, it is also the
926    answer to "is the queue draining".
927    """
928
929    items: list[AdminPatchSubmissionInfo] = Field(default_factory=list)
930    total: int = 0

138class AdminRecentError(CtfyModel):
139    """An archived instance that ended in ``stop_reason="error"``."""
140
141    instance_id: str
142    challenge_id: str = ""
143    team_id: str = ""
144    node_id: str = ""
145    error: str = ""
146    stopped_at: float = 0.0

157class AdminSilentChallenge(CtfyModel):
158    """A challenge that has launches and submissions but no full solves —
159    a strong signal that the challenge or its flag is broken."""
160
161    challenge_id: str
162    name: str = ""
163    launches: int = 0
164    submissions: int = 0

18class AdminSolveCell(CtfyModel):
19    """One cell in the team × challenge solve matrix.
20
21    Unsolved cells are emitted when the team has at least one submission
22    against the challenge (``attempts > 0``) so the UI can distinguish
23    "tried and failed" from "never attempted".
24    """
25
26    team_id: str
27    challenge_id: str
28    solved: bool = False
29    solved_at: datetime | None = None
30    solve_time_s: float = 0.0
31    attempts: int = 0
32    # True when this team is the first (fastest) solver of the challenge.
33    first_blood: bool = False

50class AdminSolveMatrix(CtfyModel):
51    """Team × challenge solve matrix for the admin dashboard.
52
53    Rows (teams) and columns (challenges) pre-sorted — teams by solve count
54    desc, challenges by category → difficulty — so the frontend can render
55    the grid verbatim without re-sorting. Cells are sparse: only teams that
56    have at least attempted a challenge contribute a row there.
57    """
58
59    teams: list[AdminSolveMatrixTeam] = Field(default_factory=list)
60    challenges: list[AdminSolveMatrixChallenge] = Field(default_factory=list)
61    cells: list[AdminSolveCell] = Field(default_factory=list)

42class AdminSolveMatrixChallenge(CtfyModel):
43    challenge_id: str
44    name: str = ""
45    category: str = ""
46    difficulty: str = ""
47    solves_count: int = 0

36class AdminSolveMatrixTeam(CtfyModel):
37    team_id: str
38    name: str = ""
39    solved: int = 0

126class AdminStuckInstance(CtfyModel):
127    """A live instance stuck in STARTING for too long — likely a node-side
128    failure that didn't reconcile to ERROR cleanly."""
129
130    instance_id: str
131    challenge_id: str = ""
132    team_id: str = ""
133    node_id: str = ""
134    requested_at: float = 0.0
135    stuck_for_s: float = 0.0

614class AdminTaskInfo(CtfyModel):
615    """One background task on ``GET /admin/tasks`` / detail. A projection
616    of ``TaskState`` onto the wire (these routes are admin-only, so the
617    full ``error_detail`` traceback tail is included)."""
618
619    id: str = ""
620    kind: str = ""
621    status: str = ""
622    params: dict[str, Any] = Field(default_factory=dict)
623    result: dict[str, Any] = Field(default_factory=dict)
624    progress: float = 0.0
625    progress_message: str = ""
626    error: str = ""
627    error_detail: str = ""
628    cancel_requested: bool = False
629    created_by_user_id: str = ""
630    created_by_name: str = ""
631    created_at_ts: float = 0.0
632    started_at_ts: float = 0.0
633    finished_at_ts: float = 0.0

636class AdminTaskListResponse(CtfyModel):
637    """Paginated task list."""
638
639    items: list[AdminTaskInfo] = Field(default_factory=list)
640    total: int = 0
641    offset: int = 0
642    limit: int = 50

645class AdminTaskLogLine(CtfyModel):
646    """One verbose log line for a task (admin-only)."""
647
648    seq: int = 0
649    ts: float = 0.0
650    level: str = "info"
651    message: str = ""

654class AdminTaskLogsResponse(CtfyModel):
655    """A cursor page of task logs. ``next_after`` is the ``seq`` to pass as
656    ``?after=`` on the next poll (the last item's seq, or the request's
657    ``after`` when the page is empty — so an empty poll never rewinds the
658    cursor)."""
659
660    items: list[AdminTaskLogLine] = Field(default_factory=list)
661    next_after: int = 0

664class AdminTaskSubmitRequest(CtfyModel):
665    """Body of ``POST /admin/tasks``. ``kind`` is validated against the
666    runner's handler registry; ``params`` is the kind-specific input
667    (e.g. ``{"competition_id": ...}`` or ``{"job": "ttl_sweep"}``)."""
668
669    kind: str = ""
670    params: dict[str, Any] = Field(default_factory=dict)

281class AdminTeamRow(CtfyModel):
282    """One row of the organiser's team table.
283
284    Deliberately **not** ``TeamInfo`` plus a field. ``TeamInfo`` is the
285    public projection, and standing is not public: a disqualification
286    reaches the team and the organisers, and announcing it more widely is
287    the organiser's call — the same reasoning that keeps
288    ``team_disqualified`` off the public SSE feed. Putting
289    ``disqualified`` on the public model would publish the verdict on
290    every team page, from a route nobody had to think about.
291
292    Also **not** ``RegistrationTeamRow``: that one carries every member's
293    sealed personal details and lands an audit row for the bulk read.
294    Managing a roster does not need anybody's phone number, and paying
295    that price to render a table would make the audit trail meaningless
296    by filling it with routine work.
297    """
298
299    id: str
300    name: str
301    description: str = ""
302    competition_id: str = ""
303    captain_user_id: str = ""
304    captain_display_name: str = ""
305    member_count: int = 0
306    created_at: datetime | None = None
307    review_status: str = ""
308    disqualified: bool = False
309    disqualified_at: datetime | None = None
310    disqualification_reason: str = ""
311    members: list[TeamMemberInfo] = Field(default_factory=list)

197class AdminTimeseries(CtfyModel):
198    """24h-by-default bucketed counts driving the admin Overview pulse charts."""
199
200    metric: str = ""
201    window_s: int = 0
202    bucket_s: int = 0
203    buckets: list[AdminTimeseriesBucket] = Field(default_factory=list)

177class AdminTimeseriesBucket(CtfyModel):
178    """One bucket of an admin time-series chart.
179
180    ``ts`` is the right edge of the bucket in Unix seconds — the natural
181    point to evaluate "active right now" metrics like running_instances —
182    and the natural label to render at the right of the bucket on the
183    frontend.
184
185    ``partial=True`` marks the rightmost bucket whose right edge is
186    ``now``; it represents an in-progress window that hasn't finished
187    accumulating yet. The frontend renders these with a "live" indicator
188    (semi-transparent fill, pulsing label) to signal the value will
189    grow until the bucket's right edge passes.
190    """
191
192    ts: float = 0.0
193    value: int = 0
194    partial: bool = False

291class AdminTrafficInstanceRow(CtfyModel):
292    """One instance × team × challenge row for the admin traffic dashboard."""
293
294    instance_id: str
295    team_id: str
296    team_name: str = ""
297    challenge_id: str = ""
298    name: str = ""
299    status: str = ""
300    request_count: int = 0
301    started_at: float = 0.0
302    stopped_at: float = 0.0
303    # ``True`` if the instance is still running (request_count is approximate
304    # — refreshed only when the dashboard re-fetches).
305    live: bool = False

308class AdminTrafficSummary(CtfyModel):
309    """Top-level response for ``GET /admin/traffic/summary``."""
310
311    teams: list[AdminTrafficTeamRow] = Field(default_factory=list)
312    instances: list[AdminTrafficInstanceRow] = Field(default_factory=list)
313    total_requests: int = 0

276class AdminTrafficTeamRow(CtfyModel):
277    """Per-team aggregate row for the admin traffic dashboard.
278
279    Sums HTTP request counts across every archived instance the team has
280    ever launched, plus the live count for any instances the team is
281    still running.
282    """
283
284    team_id: str
285    team_name: str = ""
286    instance_count: int = 0
287    request_count: int = 0
288    last_activity_at: float = 0.0

149class AdminUnhealthyNode(CtfyModel):
150    node_id: str
151    display_name: str = ""
152    url: str = ""
153    last_heartbeat_ts: float = 0.0
154    downtime_s: float = 0.0