# omnium
A set of extensions for building web applications on axum.
**Unstable:** This crate is not ready for use. The author is building out these extensions to iterate on a proof of concept, and the surface may change frequently.
## api
The `api::responses` module provides a set of response conventions for axum handlers, implementing axum's `IntoResponse` trait for typical use cases.
A handler returns `JsonResult` or `TypedJsonResult<T>`, where `JsonResult` can be used for type-erased responses and `TypedJsonResult<T>` can be used for consistently-typed responses.
The `Ok(...)` arm on these types can be used regardless of status code, to return custom responses:
```rs
// ...
use omnium::api::{JsonResult, JsonResponse};
async fn handler() -> JsonResult {
let result = try_do_or_err().await;
match result {
Ok => JsonResponse::of_status(StatusCode::ACCEPTED).into()
Err => JsonResponse::of_status(StatusCode::CONFLICT).into()
}
}
```
Response conventions are provided through the `JsonResponse<T>` struct, which implements `Into<JsonResult>` and `Into<TypedJsonResult<T>>`, as well as axum's `IntoResponse`.
A handler can return a JSON response for any serializable body, with a default `OK` status:
```rs
async fn handler() -> JsonResult {
JsonResponse::of_json(body).into()
}
```
Another status code can be set on the response:
```rs
async fn handler() -> JsonResult {
JsonResponse::of_json(body).with_status(StatusCode::IM_A_TEAPOT).into()
}
```
A handler can return a simple `JsonStatusBody` status response, implicitly deriving the response body as appropriate for the status:
```rs
async fn handler() -> JsonResult {
JsonResponse::of_status(StatusCode::OK).into()
}
```
An additional detail message can be added to the `JsonStatusBody`:
```rs
async fn handler() -> JsonResult {
JsonResponse::of_status(StatusCode::OK).with_detail("Additional detail").into()
}
```
The default `JsonResult` erases the response payload type. If you are returning a consistent type on response, you can return a `TypedJsonResult<T>`:
```rs
async fn handler() -> TypedJsonResult<JsonStatusBody> {
JsonResponse::of_status(StatusCode::OK).with_detail("Additional detail").into()
}
```
The `Err` arm is available on both `JsonResult` and `TypedJsonResult<T>` to handle status responses. For example, when using `TypedJsonResult<T>` for the happy path, you may choose to return status responses to communicate other results to the caller, whether for an error, informational result, or other case:
```rs
async fn handler() -> TypedJsonResult<JsonStatusBody> {
Err(JsonResponse::of_status(StatusCode::OK).with_detail("Additional detail"))
}
```
Finally, the `Err` arm is used to automatically handle internal server errors. A handler can return `Err(Into<anyhow::Error>)`, which will be rendered as an `INTERNAL_SERVER_ERROR` response.
```rs
async fn handler() -> JsonResult {
let success = try_do_or_err().await?;
// ...
}
```
With this convention, unhandled errors have built-in `IntoResponse` rendering and other errors must be rendered explicitly by a handler. When the handler returns an internal error in this way, the error details are not visible to the caller.
## security
The `security` module provides JWT-based authentication middleware, with utilities for a cookie-based credential exchange or the `authorization` header for browser-based or programmatic authentication.
Create a service secret:
```rs
let service_secret = create_service_secret();
```
Configure authentication middleware:
```rs
#[derive(Clone)]
struct AppUser {}
struct AppState {
pub service_secret: ServiceSecret,
}
impl SessionManager<AppUser> for Arc<AppState> {
async fn get_service_secret(&self) -> anyhow::Result<&ServiceSecret> {
// Return secret from application secret manager:
Ok(&self.service_secret)
}
async fn get_user(&self, _user_id: String) -> anyhow::Result<Option<AppUser>> {
// Return user from application database:
Ok(Some(AppUser {}))
}
fn extract_credential(&self, request: &Request, _cookies: &CookieJar) -> Option<Credential> {
// Extract credential from request:
Credential::from_authorization_header(&request)
}
}
```
Attach authentication middleware:
```rs
fn app(state: Arc<AppState>) -> Router {
Router::new()
.route("/api/user", get(|| async { "Hello, user!" }))
.layer(from_fn_with_state(
state.clone(),
authenticate::<AppUser, Arc<AppState>>,
))
.with_state(state)
}
```
Create the user session:
```rs
create_session(
"some-user-id",
&EncodingKey::from_secret(state.service_secret.value.as_bytes()),
Duration::from_secs(60),
);
```
With `Credential::from_authorization_header`, a client may pass the session as the `authorization` header. With `Credential::from_cookie`, a client may pass the session as the `__Host-omn-sess` cookie. For a simple, user-facing web application, you can set the `__Host-omn-sess` cookie when the user signs in, in order to authenticate requests to the service running on the same origin. If the application shares a session across multiple services on different origins, it can expose the session for use by the client in the `authorization` header for programmatic, cross-origin requests. You can plug in your own handling for extracting credentials from requests with a custom `extract_credential` handler.
Requests from an unauthenticated user will reject with a 401 response.
For an authenticated user, the user object from `user_lookup` can be retrieved from request state to avoid redundant lookup in handlers:
```rs
pub async fn handler(
Extension(caller): Extension<AppUser>,
) {
println!("Caller is: {}", caller);
}
```
Because a variety of data may need to be passed and verified between an application and its users, `encode_claims` and `decode_claims` may also be used for other purposes other than authentication. Note that claims are signed but not encrypted.
In addition to claims-based utilities, this crate wraps `aes_gcm` to provide utilties `encrypt_string_aes256_gcm` and `decrypt_string_aes256_gcm`. A secret created by `create_service_secret` can also be used with these encryption utilities.