http_kit/
error.rs

1//! Error types and utilities.
2//!
3//! This module provides the core error handling infrastructure. The main types are:
4//!
5//! - [`Error`] - The main error type used throughout HTTP operations
6//! - [`Result`] - A specialized Result type alias for HTTP operations
7//! - [`ResultExt`] - Extension trait that adds HTTP status code handling
8//!
9//! The error types integrate with standard Rust error handling while adding HTTP-specific
10//! functionality like status codes.
11//!
12//! # Examples
13//!
14//! ```rust
15//! use http_kit::{Error, Result, ResultExt};
16//! use http::StatusCode;
17//!
18//! // Create an error with a status code
19//! let err = Error::msg("not found").set_status(StatusCode::NOT_FOUND);
20//!
21//! // Add status code to existing Result
22//! let result: Result<()> = Ok::<(), std::convert::Infallible>(()).status(StatusCode::OK);
23//! ```
24//!
25use alloc::boxed::Box;
26use alloc::string::String;
27use core::convert::Infallible;
28use core::fmt;
29use http::StatusCode;
30
31/// A concrete error type for HTTP operations.
32#[derive(Debug)]
33pub struct Error {
34    inner: Box<dyn core::error::Error + Send + Sync>,
35    status: StatusCode,
36}
37
38impl Error {
39    /// Create a new error from a message.
40    pub fn msg(msg: impl Into<String>) -> Self {
41        Self {
42            inner: msg.into().into(),
43            status: StatusCode::INTERNAL_SERVER_ERROR,
44        }
45    }
46
47    /// Create a new error from any standard error type.
48    pub fn new(e: impl Into<Box<dyn core::error::Error + Send + Sync>>) -> Self {
49        Self {
50            inner: e.into(),
51            status: StatusCode::INTERNAL_SERVER_ERROR,
52        }
53    }
54
55    /// Set the HTTP status code for this error.
56    pub fn set_status(mut self, status: StatusCode) -> Self {
57        self.status = status;
58        self
59    }
60}
61
62impl fmt::Display for Error {
63    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
64        write!(f, "{}", self.inner)
65    }
66}
67
68impl core::error::Error for Error {
69    fn source(&self) -> Option<&(dyn core::error::Error + 'static)> {
70        Some(self.inner.as_ref())
71    }
72}
73
74/// Trait for errors that have an associated HTTP status code.
75///
76/// This trait extends the standard `Error` trait to include a method for retrieving
77/// the HTTP status code associated with the error.
78pub trait HttpError: core::error::Error + Send + Sync + 'static {
79    /// Returns the HTTP status code associated with this error.
80    ///
81    /// # Examples
82    ///
83    /// ```rust
84    /// use http_kit::{HttpError,StatusCode};
85    /// use thiserror::Error;
86    ///
87    /// #[derive(Debug, Error)]
88    /// #[error("My error occurred")]
89    /// struct MyError;
90    ///
91    /// impl HttpError for MyError {
92    ///     fn status(&self) -> StatusCode {
93    ///         StatusCode::INTERNAL_SERVER_ERROR
94    ///     }
95    /// }
96    /// let err = MyError;
97    /// assert_eq!(err.status(), StatusCode::INTERNAL_SERVER_ERROR);
98    /// assert_eq!(err.to_string(), "My error occurred");
99    /// ```
100    ///
101    /// Alternatively, you can use the [`http_error!`](crate::http_error!) macro to build
102    /// zero-sized types that already implement `HttpError` with a fixed status code:
103    ///
104    /// ```rust
105    /// use http_kit::{http_error, StatusCode, HttpError};
106    ///
107    /// http_error!(pub BadGateway, StatusCode::BAD_GATEWAY, "upstream failed");
108    /// let err = BadGateway::new();
109    /// assert_eq!(err.status(), StatusCode::BAD_GATEWAY);
110    /// ```
111    fn status(&self) -> StatusCode {
112        StatusCode::INTERNAL_SERVER_ERROR
113    }
114}
115
116impl HttpError for Error {
117    fn status(&self) -> StatusCode {
118        self.status
119    }
120}
121
122/// A specialized Result type for HTTP operations.
123pub type Result<T, E = Error> = core::result::Result<T, E>;
124
125/// Extension trait for adding status codes to Results.
126pub trait ResultExt<T> {
127    /// Map the error variant to an [`Error`] with the given status code.
128    fn status(self, status: StatusCode) -> Result<T, Error>;
129}
130
131impl<T, E> ResultExt<T> for core::result::Result<T, E>
132where
133    E: Into<Box<dyn core::error::Error + Send + Sync>>,
134{
135    fn status(self, status: StatusCode) -> Result<T, Error> {
136        self.map_err(|e| Error::new(e).set_status(status))
137    }
138}
139
140/// A boxed HTTP error trait object.
141///
142/// > Unlike `Box<dyn std::error::Error>`, this type carries HTTP status code information, and implements the `HttpError` trait.
143pub type BoxHttpError = Box<dyn HttpError>;
144
145impl From<crate::BodyError> for Error {
146    fn from(e: crate::BodyError) -> Self {
147        Error::new(e)
148    }
149}
150
151#[cfg(feature = "json")]
152impl From<serde_json::Error> for Error {
153    fn from(e: serde_json::Error) -> Self {
154        Error::new(e)
155    }
156}
157
158impl core::error::Error for BoxHttpError {}
159impl HttpError for BoxHttpError {
160    fn status(&self) -> StatusCode {
161        (**self).status()
162    }
163}
164
165impl HttpError for Infallible {
166    fn status(&self) -> StatusCode {
167        unreachable!("Infallible can never be instantiated")
168    }
169}
http_kit/error.rs

http_kit/
error.rs
