evalhub_schema/error.rs
1//! The error envelope and the closed set of error codes.
2//!
3//! Every rejection the hub makes has the same shape:
4//!
5//! ```text
6//! 422 { "errors": [ { "path": "results[0].metric", "code": "metric_id_invalid", "hint": "..." }, ... ] }
7//! ```
8//!
9//! Validation collects *all* errors before returning, so a producer fixes a
10//! record in one round trip rather than one error at a time. `path` is a
11//! JSON-pointer-like location in the submitted record; `code` is one of the
12//! variants below and is listed as an enum in the OpenAPI document; `hint`
13//! is prose for a human and is not part of the contract.
14//!
15//! | Code | Status | Meaning |
16//! | ------------------------ | ------ | -------------------------------------------------------------------- |
17//! | `schema` | 422 | JSON Schema violation (unknown key, wrong type, missing required) |
18//! | `number_too_large` | 422 | integer outside ±2^53 |
19//! | `counts_missing` | 422 | `results` non-empty but no `counts` |
20//! | `counts_inconsistent` | 422 | `attempted < completed + failed + skipped + errored` |
21//! | `attachment_ref_unknown` | 422 | `samples_ref` / `calls` / `artifacts[]` / `error.log` not in `attachments[].path` |
22//! | `attachment_path_invalid`| 422 | duplicate, `..`, or absolute `attachments[].path` |
23//! | `metric_id_invalid` | 422 | `results[].metric`, `run_results[].metric` or a run's `metrics` key not of the form `{ns}/{name}` |
24//! | `ext_key_invalid` | 422 | a key of `ext` (top-level or in a facet) not of the form `{ns}/{name}` |
25//! | `type_mismatch` | 422 | query: operator applied to a path of another type |
26//! | `not_indexed` | 422 | query: operator needs an index the path does not have |
27//! | `unknown_path` | 422 | query: path not in the schema |
28//! | `runs_moved` | 422 | an `evalhub.eval/2.0` header carries `runs`, or the body declares `evalhub.eval/1.0`; runs are written apart |
29//! | `run_status_detail` | 422 | `error` present iff `status` is `error`, `skip_reason` iff `skipped` |
30//! | `run_id_invalid` | 422 | `run_id` empty, containing `/`, or over 200 bytes |
31//! | `run_id_mismatch` | 422 | the `run_id` in the body differs from the one in the path |
32//! | `run_result_value_or_label` | 422 | a `run_results[]` element has neither `value` nor `label` |
33//! | `run_results_eval_unknown` | 422 | `run_results[].eval` is not the record of any `core/uses_eval` |
34//! | `run_unknown` | 422 | a `run_id` in the used set has no row in that Eval |
35//! | `run_not_in_used_set` | 422 | `run_results[].run_id` outside the Card's used set for its `eval` |
36//! | `too_many_run_results` | 422 | more `run_results[]` than the configured limit |
37//! | `batch_duplicate_run_id` | 422 | the same `run_id` twice in one batch |
38//! | `attachment_missing` | 409 | `attachments[].sha256` not uploaded and confirmed |
39//! | `label_in_use` | 409 | `@{label}` already names another version |
40//! | `namespace_in_use` | 409 | the organisation slug is already a user or an organisation |
41//! | `registry_entry_exists` | 409 | that registry address is taken; entries are immutable |
42//! | `run_deleted` | 409 | writing a `run_id` that was deleted; a deleted id is never reused |
43//! | `batch_too_large` | 413 | more runs in one batch than the configured count |
44//! | `body_too_large` | 413 | request body over the configured size in bytes |
45//!
46//! A `413` carries this body only with the two `413` codes above. Other
47//! statuses carry no body of this shape: `404` for anything the caller
48//! may not know exists (including private records), `403` for a token
49//! without the scope, `401` for no or an invalid token, `400` for a body that
50//! is not JSON.
51//!
52//! Codes are added, never renamed or reused. A client switching on `code`
53//! must treat an unknown code as a generic 422. The enum is
54//! `#[non_exhaustive]` for the same reason: a release may add a code, and a
55//! `match` in another crate must have a fallback arm for it.
56
57use schemars::JsonSchema;
58use serde::{Deserialize, Serialize};
59
60/// The closed set of error codes.
61#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, JsonSchema)]
62#[serde(rename_all = "snake_case")]
63#[non_exhaustive]
64pub enum ErrorCode {
65 /// JSON Schema violation: unknown key, wrong type, missing required key.
66 Schema,
67 /// An integer outside ±2^53.
68 NumberTooLarge,
69 /// `results` is non-empty but `counts` is absent.
70 CountsMissing,
71 /// `counts.attempted < completed + failed + skipped + errored`.
72 CountsInconsistent,
73 /// A `samples_ref`, `calls`, `artifacts[]` or `error.log` entry names no `attachments[].path`.
74 AttachmentRefUnknown,
75 /// An `attachments[].path` is duplicated, absolute, or contains `..`.
76 AttachmentPathInvalid,
77 /// A `results[].metric`, a `run_results[].metric` or a key of a run's
78 /// `metrics` is not of the form `{ns}/{name}`.
79 MetricIdInvalid,
80 /// A key of `ext`, at the top level of a record or a run or inside one
81 /// of its facets, is not of the form `{ns}/{name}`.
82 ExtKeyInvalid,
83 /// Query: operator applied to a path of another type.
84 TypeMismatch,
85 /// Query: operator needs an index the path does not have.
86 NotIndexed,
87 /// Query: path not in the schema.
88 UnknownPath,
89 /// An `attachments[].sha256` has not been uploaded and confirmed.
90 AttachmentMissing,
91 /// The requested `@{label}` already names another version.
92 LabelInUse,
93 /// The requested organisation slug is already a user or an organisation.
94 NamespaceInUse,
95 /// A registry entry already exists at that address. Entries are
96 /// immutable, so a correction is a new version.
97 RegistryEntryExists,
98 /// An `evalhub.eval/2.0` Eval header carries `runs`, or the body
99 /// declares `evalhub.eval/1.0` (with or without `runs`). Runs are not
100 /// part of the header; they are written one by one or in a batch.
101 RunsMoved,
102 /// A run's `status` and its detail disagree: `error` must be present
103 /// exactly when `status` is `error`, `skip_reason` exactly when it is
104 /// `skipped`.
105 RunStatusDetail,
106 /// A `run_id` is empty, contains `/`, or is longer than 200 bytes.
107 RunIdInvalid,
108 /// The `run_id` in the body differs from the one in the request path.
109 RunIdMismatch,
110 /// A `run_results[]` element has neither `value` nor `label`.
111 RunResultValueOrLabel,
112 /// A `run_results[].eval` is not the record of any of the Card's
113 /// `core/uses_eval` relations.
114 RunResultsEvalUnknown,
115 /// A `run_id` in the Card's used set has no row in that Eval (or the
116 /// Eval is one the writer may not see).
117 RunUnknown,
118 /// A `run_results[].run_id` is outside the Card's used set for its `eval`.
119 RunNotInUsedSet,
120 /// A Card version carries more `run_results[]` than the hub's configured limit.
121 TooManyRunResults,
122 /// The `run_id` names a run that was deleted. A deleted run's id is not
123 /// reused, because Cards that judged it would then point at different content.
124 RunDeleted,
125 /// The same `run_id` appears more than once in one batch.
126 BatchDuplicateRunId,
127 /// A batch carries more runs than the hub's configured count.
128 BatchTooLarge,
129 /// The request body is larger than the hub's configured size in bytes.
130 BodyTooLarge,
131}
132
133impl ErrorCode {
134 /// The HTTP status this code is returned with.
135 pub const fn status(self) -> u16 {
136 match self {
137 ErrorCode::AttachmentMissing
138 | ErrorCode::LabelInUse
139 | ErrorCode::NamespaceInUse
140 | ErrorCode::RegistryEntryExists
141 | ErrorCode::RunDeleted => 409,
142 ErrorCode::BatchTooLarge | ErrorCode::BodyTooLarge => 413,
143 _ => 422,
144 }
145 }
146}
147
148/// One rejection.
149#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
150#[serde(deny_unknown_fields)]
151pub struct ErrorEntry {
152 /// Location in the submitted document, JSON-pointer-like (`results[0].metric`).
153 pub path: String,
154 /// The code.
155 pub code: ErrorCode,
156 /// Prose for a human. Not part of the contract.
157 #[serde(default, skip_serializing_if = "Option::is_none")]
158 pub hint: Option<String>,
159}
160
161/// The body of every `422` and `409` response.
162#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
163#[serde(deny_unknown_fields)]
164pub struct ErrorEnvelope {
165 /// Every rejection found, in document order.
166 pub errors: Vec<ErrorEntry>,
167}