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[]` not in `attachments[].path` |
22//! | `attachment_path_invalid`| 422 | duplicate, `..`, or absolute `attachments[].path` |
23//! | `metric_id_invalid` | 422 | `results[].metric` not of the form `{ns}/{name}` |
24//! | `type_mismatch` | 422 | query: operator applied to a path of another type |
25//! | `not_indexed` | 422 | query: operator needs an index the path does not have |
26//! | `unknown_path` | 422 | query: path not in the schema |
27//! | `attachment_missing` | 409 | `attachments[].sha256` not uploaded and confirmed |
28//! | `label_in_use` | 409 | `@{label}` already names another version |
29//! | `namespace_in_use` | 409 | the organisation slug is already a user or an organisation |
30//! | `registry_entry_exists` | 409 | that registry address is taken; entries are immutable |
31//!
32//! Other statuses carry no body of this shape: `404` for anything the caller
33//! may not know exists (including private records), `403` for a token
34//! without the scope, `401` for no or an invalid token, `400` for a body that
35//! is not JSON.
36//!
37//! Codes are added, never renamed or reused. A client switching on `code`
38//! must treat an unknown code as a generic 422.
39
40use schemars::JsonSchema;
41use serde::{Deserialize, Serialize};
42
43/// The closed set of error codes.
44#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, JsonSchema)]
45#[serde(rename_all = "snake_case")]
46pub enum ErrorCode {
47 /// JSON Schema violation: unknown key, wrong type, missing required key.
48 Schema,
49 /// An integer outside ±2^53.
50 NumberTooLarge,
51 /// `results` is non-empty but `counts` is absent.
52 CountsMissing,
53 /// `counts.attempted < completed + failed + skipped + errored`.
54 CountsInconsistent,
55 /// A `samples_ref`, `calls` or `artifacts[]` entry names no `attachments[].path`.
56 AttachmentRefUnknown,
57 /// An `attachments[].path` is duplicated, absolute, or contains `..`.
58 AttachmentPathInvalid,
59 /// A `results[].metric` is not of the form `{ns}/{name}`.
60 MetricIdInvalid,
61 /// Query: operator applied to a path of another type.
62 TypeMismatch,
63 /// Query: operator needs an index the path does not have.
64 NotIndexed,
65 /// Query: path not in the schema.
66 UnknownPath,
67 /// An `attachments[].sha256` has not been uploaded and confirmed.
68 AttachmentMissing,
69 /// The requested `@{label}` already names another version.
70 LabelInUse,
71 /// The requested organisation slug is already a user or an organisation.
72 NamespaceInUse,
73 /// A registry entry already exists at that address. Entries are
74 /// immutable, so a correction is a new version.
75 RegistryEntryExists,
76}
77
78impl ErrorCode {
79 /// The HTTP status this code is returned with.
80 pub const fn status(self) -> u16 {
81 match self {
82 ErrorCode::AttachmentMissing
83 | ErrorCode::LabelInUse
84 | ErrorCode::NamespaceInUse
85 | ErrorCode::RegistryEntryExists => 409,
86 _ => 422,
87 }
88 }
89}
90
91/// One rejection.
92#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
93#[serde(deny_unknown_fields)]
94pub struct ErrorEntry {
95 /// Location in the submitted document, JSON-pointer-like (`results[0].metric`).
96 pub path: String,
97 /// The code.
98 pub code: ErrorCode,
99 /// Prose for a human. Not part of the contract.
100 #[serde(default, skip_serializing_if = "Option::is_none")]
101 pub hint: Option<String>,
102}
103
104/// The body of every `422` and `409` response.
105#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
106#[serde(deny_unknown_fields)]
107pub struct ErrorEnvelope {
108 /// Every rejection found, in document order.
109 pub errors: Vec<ErrorEntry>,
110}