kasl_server/
error.rs

1//! One error shape for the whole API.
2//!
3//! kasl agents parse what comes back, so a failure has to be as predictable as
4//! a success: always JSON, always the same field. A handler returning a bare
5//! status leaves the agent guessing whether to retry, fix its payload, or tell
6//! the employee something is wrong.
7
8use axum::{
9    Json,
10    http::StatusCode,
11    response::{IntoResponse, Response},
12};
13use serde_json::json;
14
15/// A failed request, with the status the client should act on.
16#[derive(Debug)]
17pub struct ApiError {
18    status: StatusCode,
19    message: String,
20}
21
22impl ApiError {
23    pub fn new(status: StatusCode, message: impl Into<String>) -> Self {
24        Self {
25            status,
26            message: message.into(),
27        }
28    }
29
30    /// The payload was understood but is not acceptable - the agent must fix
31    /// it rather than retry.
32    pub fn bad_request(message: impl Into<String>) -> Self {
33        Self::new(StatusCode::BAD_REQUEST, message)
34    }
35
36    /// Whose fault this was. A batch reads it to tell a day it should give up
37    /// on from one it should send again later.
38    pub fn status(&self) -> StatusCode {
39        self.status
40    }
41}
42
43impl std::fmt::Display for ApiError {
44    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
45        f.write_str(&self.message)
46    }
47}
48
49impl IntoResponse for ApiError {
50    fn into_response(self) -> Response {
51        // Server-side faults are logged in full and reported in outline: an
52        // agent has no use for a database error, and the message could carry
53        // details of someone else's data.
54        if self.status.is_server_error() {
55            tracing::error!(status = %self.status, error = %self.message, "request failed");
56            return (self.status, Json(json!({ "error": "internal server error" }))).into_response();
57        }
58
59        (self.status, Json(json!({ "error": self.message }))).into_response()
60    }
61}
62
63impl From<sqlx::Error> for ApiError {
64    fn from(error: sqlx::Error) -> Self {
65        Self::new(StatusCode::INTERNAL_SERVER_ERROR, error.to_string())
66    }
67}
68
69#[cfg(test)]
70mod tests {
71    use super::*;
72    use axum::body::to_bytes;
73
74    async fn body_of(error: ApiError) -> serde_json::Value {
75        let response = error.into_response();
76        let bytes = to_bytes(response.into_body(), usize::MAX).await.unwrap();
77        serde_json::from_slice(&bytes).unwrap()
78    }
79
80    #[tokio::test]
81    async fn client_errors_explain_themselves() {
82        let body = body_of(ApiError::bad_request("date is not a calendar date")).await;
83        assert_eq!(body["error"], "date is not a calendar date");
84    }
85
86    #[tokio::test]
87    async fn server_errors_do_not_leak_their_cause() {
88        let body = body_of(ApiError::new(StatusCode::INTERNAL_SERVER_ERROR, "relation \"users\" does not exist")).await;
89        assert_eq!(body["error"], "internal server error", "internals must not reach the client");
90    }
91
92    #[test]
93    fn the_status_survives_into_the_response() {
94        let response = ApiError::new(StatusCode::UNAUTHORIZED, "nope").into_response();
95        assert_eq!(response.status(), StatusCode::UNAUTHORIZED);
96    }
97}
kasl_server/error.rs

kasl_server/
error.rs
