[−][src]Crate roa_core
Introduction
Core components of Roa framework.
If you are new to roa, please go to the documentation of roa framework.
Application
A Roa application is a structure composing and executing middlewares and an endpoint in a stack-like manner.
The obligatory hello world application:
use roa_core::{App, Context, Result, Status}; let app = App::new(()).end(end); // endpoint async fn end(ctx: &mut Context<()>) -> Result { ctx.resp.write("Hello, World"); Ok(()) }
Cascading
The following example responds with "Hello World", however, the request flows through
the logging
middleware to mark when the request started, then continue
to yield control through the response endpoint. When a middleware invokes next.await
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.
use roa_core::{App, Context, Result, Status, MiddlewareExt, Next}; use std::time::Instant; use log::info; let app = App::new(()).gate(logging).end(response); async fn response(ctx: &mut Context<()>) -> Result { ctx.resp.write("Hello, World"); Ok(()) } async fn logging(ctx: &mut Context<()>, next: Next<'_>) -> Result { let inbound = Instant::now(); next.await?; info!("time elapsed: {} ms", inbound.elapsed().as_millis()); Ok(()) }
Status Handling
You can catch or straightly throw an status returned by next.
use roa_core::{App, Context, Result, Status, MiddlewareExt, Next, throw}; use roa_core::http::StatusCode; let app = App::new(()).gate(catch).gate(gate).end(end); async fn catch(ctx: &mut Context<()>, next: Next<'_>) -> Result { // catch if let Err(status) = next.await { // teapot is ok if status.status_code != StatusCode::IM_A_TEAPOT { return Err(status); } } Ok(()) } async fn gate(ctx: &mut Context<()>, next: Next<'_>) -> Result { next.await?; // just throw unreachable!() } async fn end(ctx: &mut Context<()>) -> Result { throw!(StatusCode::IM_A_TEAPOT, "I'm a teapot!") }
status_handler
App has an status_handler to handle Status
thrown by the top middleware.
This is the status_handler:
use roa_core::{Context, Status, Result, State}; pub fn status_handler<S: State>(ctx: &mut Context<S>, status: Status) { ctx.resp.status = status.status_code; if status.expose { ctx.resp.write(status.message); } else { log::error!("{}", status); } }
HTTP Server.
Use roa_core::accept
to construct a http server.
Please refer to roa::tcp
for more information.
Re-exports
pub use http; |
Macros
throw | Throw an |
Structs
AddrStream | A transport returned yieled by |
App | The Application of roa. |
Boxed | Boxed endpoint. |
Chain | A middleware composing and executing other middlewares in a stack-like manner. |
Context | A structure to share request, response and other data between middlewares. |
Executor | A type implementing hyper::rt::Executor |
JoinHandle | A handle that awaits the result of a task. |
Request | Http request type of roa. |
Response | Http response type of roa. |
Server | A listening HTTP server that accepts connections in both HTTP1 and HTTP2 by default. |
Shared | Shared middleware. |
Status | The |
Variable | A variable. |
Enums
Body | The body of response. |
Traits
Accept | Asynchronously accept incoming connections. |
Endpoint | Endpoint |
EndpointExt | Extra methods of endpoint. |
Middleware | Middleware |
MiddlewareExt | A set of method to chain middleware/endpoint to middleware or make middleware shared. |
Spawn | Executor constraint. |
State | The |
Type Definitions
Next | Type of the second parameter in a middleware. |
Result | Type alias for |
ResultFuture | Type alias for |
Attribute Macros
async_trait |