cratefield_core/
problems.rs

1//! The registry of every problem slug the harness can emit (architecture
2//! section 6): stable `type` URIs, statuses and descriptions. Modules add
3//! their own slugs as `const ProblemDef`s in the same shape, and every
4//! slug — core's and modules' — must be unique workspace-wide:
5//! `errors-doc` collects the definitions from source and fails CI on a
6//! slug defined twice (issue #419).
7
8use axum::http::StatusCode;
9
10/// Definition of one problem slug.
11#[derive(Debug, Clone, Copy)]
12pub struct ProblemDef {
13    /// Last path segment of the `type` URI.
14    pub slug: &'static str,
15    pub status: StatusCode,
16    /// Short, stable human title (RFC 9457 `title`).
17    pub title: &'static str,
18    /// One-line description for reviewers; not part of the response.
19    pub description: &'static str,
20}
21
22/// Every slug core emits. Keep sorted by status.
23pub struct Slugs {
24    /// 400: a request body/query did not deserialize or failed validation.
25    pub validation_failed: ProblemDef,
26    /// 400: a captcha token was missing or rejected.
27    pub captcha_failed: ProblemDef,
28    /// 400: a signed link/token is malformed, tampered or expired.
29    pub invalid_token: ProblemDef,
30    /// 400: the request named a resource outside the configured set
31    /// (e.g. an unknown waitlist product).
32    pub unknown_product: ProblemDef,
33    /// 401: a credential was presented and did not verify, or none was
34    /// presented where one is required. The one 401 for every
35    /// unauthenticated caller — the auth-client bearer check, the tables
36    /// API's access decision and the modules reusing them all answer
37    /// with it.
38    pub unauthenticated: ProblemDef,
39    /// 401: admin endpoints are disabled (`ADMIN_TOKEN` unset) or the
40    /// request carried no bearer token.
41    pub admin_unauthorized: ProblemDef,
42    /// 401: a developer API key was missing, malformed, unknown, revoked
43    /// or failed its hash check — one uniform answer for all five, so a
44    /// probe cannot tell which (issue #532).
45    pub api_key_unauthorized: ProblemDef,
46    /// 403: the presented API key is valid but lacks the scope the route
47    /// requires (issue #532).
48    pub api_key_forbidden: ProblemDef,
49    /// 403: the presented admin token is wrong.
50    pub admin_forbidden: ProblemDef,
51    /// 401: a request reached a sidecar-guarded route (`/v1/*` or
52    /// `/__surface` on a sidecar that requires it) without a valid gateway
53    /// token from the trusted host (issue #131).
54    pub sidecar_unauthorized: ProblemDef,
55    /// 503: the deployment declares production but cannot satisfy the
56    /// abuse controls its own routes declare, so the guarded routes are
57    /// refused rather than served unprotected (issue #143).
58    pub not_production_ready: ProblemDef,
59    /// 413: the request body exceeded the 64 KiB `/v1/*` limit.
60    pub request_too_large: ProblemDef,
61    /// 429: the rate limit for this IP or address was exceeded.
62    pub rate_limited: ProblemDef,
63    /// 404: no route matched.
64    pub not_found: ProblemDef,
65    /// 500: unhandled error; body carries no internals.
66    pub internal: ProblemDef,
67    /// 503: the mailer is not configured (no API key / unverified sending
68    /// domain); forms should degrade to a direct address.
69    pub mail_not_configured: ProblemDef,
70    /// 503: readiness probe failed (`/__ready`): database missing, slow or
71    /// erroring.
72    pub not_ready: ProblemDef,
73    /// 404: the request's host resolves to no tenant in the registry. A
74    /// 404 and not a 403: which hosts are tenants is not a secret worth
75    /// a distinguishable answer, and "no such tenant" is the truth
76    /// (RECONCILIATION.md §6, TENANT-ROUTING.md §3).
77    pub unknown_tenant: ProblemDef,
78    /// 503: a sidecar-mounted module could not be reached (ADR 0009). Only
79    /// that prefix fails; every in-process module keeps serving.
80    pub sidecar_unavailable: ProblemDef,
81    /// 503: a sidecar answered with a different `HARNESS_API` than this
82    /// harness speaks, so its responses cannot be trusted.
83    pub sidecar_contract_mismatch: ProblemDef,
84    /// 503: the request's tenant is in the registry but `degraded` — its
85    /// schema is behind or its database is unreachable, so serving it
86    /// would read a shape the code no longer expects
87    /// (RECONCILIATION.md §6, TENANT-ROUTING.md §3).
88    pub tenant_degraded: ProblemDef,
89}
90
91pub const SLUGS: Slugs = Slugs {
92    validation_failed: ProblemDef {
93        slug: "validation-failed",
94        status: StatusCode::BAD_REQUEST,
95        title: "Request validation failed",
96        description: "The request body or query did not deserialize into a valid request.",
97    },
98    captcha_failed: ProblemDef {
99        slug: "captcha-failed",
100        status: StatusCode::BAD_REQUEST,
101        title: "Captcha verification failed",
102        description: "The captcha token was missing or rejected; retry the challenge.",
103    },
104    invalid_token: ProblemDef {
105        slug: "invalid-token",
106        status: StatusCode::BAD_REQUEST,
107        title: "Invalid or expired token",
108        description: "A signed link or token is malformed, tampered with, or expired.",
109    },
110    unknown_product: ProblemDef {
111        slug: "unknown-product",
112        status: StatusCode::BAD_REQUEST,
113        title: "Unknown product",
114        description: "The named product is not on this waitlist.",
115    },
116    unauthenticated: ProblemDef {
117        slug: "unauthenticated",
118        status: StatusCode::UNAUTHORIZED,
119        title: "Not authenticated",
120        description: "A credential was presented and did not verify, or none was presented where one is required.",
121    },
122    admin_unauthorized: ProblemDef {
123        slug: "admin-unauthorized",
124        status: StatusCode::UNAUTHORIZED,
125        title: "Admin access unauthorized",
126        description: "Admin endpoints are disabled or the request has no bearer token.",
127    },
128    api_key_unauthorized: ProblemDef {
129        slug: "api-key-unauthorized",
130        status: StatusCode::UNAUTHORIZED,
131        title: "API key unauthorized",
132        description: "The request's API key was missing, malformed, unknown, revoked or invalid; one uniform answer for all five.",
133    },
134    api_key_forbidden: ProblemDef {
135        slug: "api-key-forbidden",
136        status: StatusCode::FORBIDDEN,
137        title: "API key lacks the required scope",
138        description: "The presented API key is valid but does not carry the scope this route requires.",
139    },
140    admin_forbidden: ProblemDef {
141        slug: "admin-forbidden",
142        status: StatusCode::FORBIDDEN,
143        title: "Admin token rejected",
144        description: "The presented admin token is wrong.",
145    },
146    sidecar_unauthorized: ProblemDef {
147        slug: "sidecar-unauthorized",
148        status: StatusCode::UNAUTHORIZED,
149        title: "Unauthorized sidecar caller",
150        description: "A request to a sidecar-guarded route could not be established as coming from the trusted gateway.",
151    },
152    not_production_ready: ProblemDef {
153        slug: "not-production-ready",
154        status: StatusCode::SERVICE_UNAVAILABLE,
155        title: "Not ready for production traffic",
156        description: "This deployment declares production but cannot satisfy the abuse controls its routes declare.",
157    },
158    request_too_large: ProblemDef {
159        slug: "request-too-large",
160        status: StatusCode::PAYLOAD_TOO_LARGE,
161        title: "Request body too large",
162        description: "The request body exceeded the 64 KiB limit for /v1 endpoints.",
163    },
164    rate_limited: ProblemDef {
165        slug: "rate-limited",
166        status: StatusCode::TOO_MANY_REQUESTS,
167        title: "Rate limit exceeded",
168        description: "Too many requests from this IP or address; retry after the pause.",
169    },
170    not_found: ProblemDef {
171        slug: "not-found",
172        status: StatusCode::NOT_FOUND,
173        title: "Not found",
174        description: "No route matched the request.",
175    },
176    unknown_tenant: ProblemDef {
177        slug: "unknown-tenant",
178        status: StatusCode::NOT_FOUND,
179        title: "Unknown tenant",
180        description: "The request's host resolves to no tenant in the registry.",
181    },
182    internal: ProblemDef {
183        slug: "internal",
184        status: StatusCode::INTERNAL_SERVER_ERROR,
185        title: "Internal error",
186        description: "Unhandled error; no internals are exposed in the body.",
187    },
188    mail_not_configured: ProblemDef {
189        slug: "mail-not-configured",
190        status: StatusCode::SERVICE_UNAVAILABLE,
191        title: "Mail is not configured",
192        description: "No sending domain is verified; use the direct address shown by the form.",
193    },
194    not_ready: ProblemDef {
195        slug: "not-ready",
196        status: StatusCode::SERVICE_UNAVAILABLE,
197        title: "Service not ready",
198        description: "Readiness probe failed: the database is missing, erroring or too slow.",
199    },
200    sidecar_unavailable: ProblemDef {
201        slug: "sidecar-unavailable",
202        status: StatusCode::SERVICE_UNAVAILABLE,
203        title: "Sidecar module unavailable",
204        description: "A sidecar-mounted module could not be reached; other modules are unaffected.",
205    },
206    sidecar_contract_mismatch: ProblemDef {
207        slug: "sidecar-contract-mismatch",
208        status: StatusCode::SERVICE_UNAVAILABLE,
209        title: "Sidecar contract mismatch",
210        description: "A sidecar answers a different HARNESS_API than this harness speaks.",
211    },
212    tenant_degraded: ProblemDef {
213        slug: "tenant-degraded",
214        status: StatusCode::SERVICE_UNAVAILABLE,
215        title: "Tenant is degraded",
216        description: "The tenant's schema is behind or its database is unreachable; its neighbours are unaffected.",
217    },
218};
219
220/// Every core slug definition, for tests and docs.
221pub fn registry() -> Vec<&'static ProblemDef> {
222    vec![
223        &SLUGS.validation_failed,
224        &SLUGS.captcha_failed,
225        &SLUGS.invalid_token,
226        &SLUGS.unknown_product,
227        &SLUGS.unauthenticated,
228        &SLUGS.admin_unauthorized,
229        &SLUGS.api_key_unauthorized,
230        &SLUGS.api_key_forbidden,
231        &SLUGS.admin_forbidden,
232        &SLUGS.sidecar_unauthorized,
233        &SLUGS.not_production_ready,
234        &SLUGS.request_too_large,
235        &SLUGS.rate_limited,
236        &SLUGS.not_found,
237        &SLUGS.unknown_tenant,
238        &SLUGS.internal,
239        &SLUGS.mail_not_configured,
240        &SLUGS.not_ready,
241        &SLUGS.sidecar_unavailable,
242        &SLUGS.sidecar_contract_mismatch,
243        &SLUGS.tenant_degraded,
244    ]
245}
cratefield_core/problems.rs

cratefield_core/
problems.rs
