Roa is an async web framework inspired by koajs, lightweight but powerful.
A Roa application is a structure composing and executing middlewares and an endpoint in a stack-like manner.
The obligatory hello world application:
```rust,no_run use roa::App; use roa::preload::*; use log::info; use std::error::Error as StdError;
async fn main() -> Result<(), Box
An endpoint is a request handler.
There are some build-in endpoints in roa.
Functional endpoint
A normal functional endpoint is an async function with signature:
async fn(&mut Context) -> Result.
```rust use roa::{App, Context, Result};
async fn endpoint(ctx: &mut Context) -> Result { Ok(()) }
let app = App::new().end(endpoint); ```
Ok endpoint
() is an endpoint always return Ok(())
rust
let app = roa::App::new().end(());
Status endpoint
Status is an endpoint always return Err(Status)
rust
use roa::{App, status};
use roa::http::StatusCode;
let app = App::new().end(status!(StatusCode::BAD_REQUEST));
String endpoint
Write string to body.
```rust use roa::App;
let app = App::new().end("Hello, world"); // static slice let app = App::new().end("Hello, world".to_owned()); // string ```
Redirect endpoint
Redirect to an uri.
```rust use roa::App; use roa::http::Uri;
let app = App::new().end("/target".parse::
Like koajs, middleware suspends and passes control to "downstream" by invoking next.await.
Then control flows back "upstream" when next.await returns.
The following example responds with "Hello World", however first the request flows through the x-response-time and logging middleware to mark when the request started, then continue to yield control through the endpoint. When a middleware invokes next the function suspends and passes control to the next middleware or endpoint. After the endpoint is called, the stack will unwind and each middleware is resumed to perform its upstream behaviour.
```rust,no_run use roa::{App, Context, Next}; use roa::preload::*; use log::info; use std::error::Error as StdError; use std::time::Instant;
async fn main() -> Result<(), Box
async fn logger(ctx: &mut Context, next: Next<'>) -> roa::Result {
next.await?;
let rt = ctx.load::
async fn xresponsetime(ctx: &mut Context, next: Next<'>) -> roa::Result { let start = Instant::now(); next.await?; let ms = start.elapsed().asmillis(); ctx.store("x-response-time", format!("{}ms", ms)); Ok(()) }
```
You can catch or straightly throw a status returned by next.
```rust,norun use roa::{App, Context, Next, status}; use roa::preload::*; use roa::http::StatusCode; use asyncstd::task::spawn; use log::info;
async fn main() -> Result<(), Box
async fn catch(ctx: &mut Context, next: Next<'>) -> roa::Result { // catch if let Err(status) = next.await { // teapot is ok if status.statuscode != StatusCode::IMA_TEAPOT { return Err(status); } } Ok(()) }
async fn notcatch(ctx: &mut Context, next: Next<'>) -> roa::Result { next.await?; // just throw unreachable!() } ```
App has an statushandler to handle status thrown by the top middleware. This is the statushandler:
rust,no_run
use roa::{Context, Status};
pub fn status_handler<S>(ctx: &mut Context<S>, status: Status) {
ctx.resp.status = status.status_code;
if status.expose {
ctx.resp.write(status.message);
} else {
log::error!("{}", status);
}
}
Roa provides a configurable and nestable router.
```rust,norun use roa::preload::*; use roa::router::{Router, get}; use roa::{App, Context}; use asyncstd::task::spawn; use log::info;
async fn main() -> Result<(), Box
Ok(())
}
async fn end(ctx: &mut Context) -> roa::Result { // get "/user/1", then id == 1. let id: u64 = ctx.must_param("id")?.parse()?; // do something Ok(()) } ```
Roa provides a middleware query_parser.
```rust,norun use roa::preload::*; use roa::query::queryparser; use roa::{App, Context}; use async_std::task::spawn; use log::info;
async fn must(ctx: &mut Context) -> roa::Result { // request "/?id=1", then id == 1. let id: u64 = ctx.must_query("id")?.parse()?; Ok(()) }
async fn main() -> Result<(), Box
Ok(())
}
```