7 releases
0.1.6 | Sep 23, 2024 |
---|---|
0.1.5 | Sep 12, 2024 |
0.1.4 | May 16, 2024 |
0.1.1 | Apr 23, 2024 |
0.1.0 | Mar 30, 2024 |
#98 in HTTP server
6,169 downloads per month
Used in 8 crates
(2 directly)
105KB
2K
SLoC
This package is for giving utils for web servers supporting the following web frameworks:
- actix
- rocket
- axum
- hyper
These will help the developer use these tools outside of the box to have uniform runtime states, config handles, and error handling for api endpoints. This will enable developers to fuse servers together to call endpoints via memory.
Error handling
This package has errors that can be imported with the following statement:
use nanoservices_utils::errors::{NanoServiceError, NanoServiceErrorStatus};
The NanoServiceError
is the error struct that handles the message and the error status of the error. To construct an error, you can use the following:
let error = NanoServiceError::new(
"could not find the item".to_string(),
NanoServiceErrorStatus::NotFound,
)
The NanoServiceErrorStatus
will convert to a HTTP response code that corresponds with the message. Without any feature selection, the error will just be an error. However, if you select one or more of the following features:
- axum
- actix
- rocket
- hyper
The error will be able to be converted to that framework's HTTP response. This means that your library can return NanoServiceError
structs for errors and these errors will be able to convert into HTTP responses for those webframeworks.
You can also map any expression returning a Result
to return a NanoServiceError
on error with the code below:
use nanoservices_utils::safe_eject;
let some_outcome = safe_eject!(some_function());
To see how error handling works for web frameworks, lets look at the following example where we have a function that will not allow a number more than 10 with the following code:
use nanoservice_utils::errors::{NanoServiceError, NanoServiceErrorStatus};
pub fn check(number: i32) -> Result<i32, NanoServiceError> {
if number > 10 {
return Err(NanoServiceError::new(
"number is too large".to_string(),
NanoServiceErrorStatus::BadRequest,
));
}
Ok(number)
}
We can then call this function and exploit the ?
operator to return a HTTP response automatically if an error is thrown with the following frameworks:
Actix
use actix_web::{HttpResponse, web};
use nanoservices_utils::errors::NanoServiceError;
use serde::Deserialize;
#[derive(Deserialize)]
pub struct Number {
number: i32,
}
pub async fn some_api_endpoint(body: web::Json<Number>) -> Result<HttpResponse, NanoServiceError> {
let number = check(body.number)?;
// can do something else here
Ok(HttpResponse::Ok().json(number))
}
Axum
use axum::{
extract::Json,
http::StatusCode,
response::IntoResponse,
};
use nanoservices_utils::errors::NanoServiceError;
use serde::Deserialize;
#[derive(Deserialize)]
pub struct Number {
number: i32,
}
pub async fn some_api_endpoint(Json(body): Json<Number>) -> Result<impl IntoResponse, NanoServiceError> {
let number = check(body.number)?;
// can do something else here
Ok((StatusCode::OK, axum::Json(number)))
}
Rocket
use rocket::serde::json::Json;
use nanoservices_utils::errors::NanoServiceError;
use rocket::http::Status;
use serde::Deserialize;
#[derive(Deserialize)]
#[serde(crate = "rocket::serde")] // Specify that Rocket's `serde` should be used
pub struct Number {
number: i32,
}
#[post("/some/api/endpoint", format = "json", data = "<body>")]
pub async fn some_api_endpoint(body: Json<Number>) -> Result<Json<i32>, (Status, String)> {
let number = check(body.number)?;
// can do something else here
Ok(Json(number))
}
Beta Utils
I'm currently supporting the following utils:
- JWT
- Config
- error handling for server endpoints
- runtime state
but these are not polished
Dependencies
~2–36MB
~591K SLoC