[−][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 containing a middleware group which composes and executes middleware functions in a stack-like manner.
The obligatory hello world application:
use roa_core::App; let mut app = App::new(()); app.end(|mut ctx| async move { ctx.resp_mut().write_str("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 middleware. When a middleware invokes next.await
the function suspends and passes control to the next middleware defined. After there are no more
middleware to execute downstream, the stack will unwind and each middleware is resumed to perform
its upstream behaviour.
use roa_core::App; use std::time::Instant; use log::info; let mut app = App::new(()); app.gate_fn(|_ctx, next| async move { let inbound = Instant::now(); next.await?; info!("time elapsed: {} ms", inbound.elapsed().as_millis()); Ok(()) }); app.end(|mut ctx| async move { ctx.resp_mut().write_str("Hello, World"); Ok(()) });
Error Handling
You can catch or straightly throw an Error returned by next.
use roa_core::{App, throw}; use roa_core::http::StatusCode; let mut app = App::new(()); app.gate_fn(|ctx, next| async move { // catch if let Err(err) = next.await { // teapot is ok if err.status_code != StatusCode::IM_A_TEAPOT { return Err(err) } } Ok(()) }); app.gate_fn(|ctx, next| async move { next.await?; // just throw unreachable!() }); app.end(|_ctx| async move { throw!(StatusCode::IM_A_TEAPOT, "I'm a teapot!") });
error_handler
App has an error_handler to handle Error
thrown by the top middleware.
This is the error_handler:
use roa_core::{Context, Error, Result, ErrorKind, State}; pub async fn error_handler<S: State>(mut context: Context<S>, err: Error) -> Result { context.resp_mut().status = err.status_code; if err.expose { context.resp_mut().write_str(&err.message); } if err.kind == ErrorKind::ServerError { Err(err) } else { Ok(()) } }
The Error thrown by this error_handler will be handled by hyper.
HTTP Server.
Use roa_core::Server to construct a http server. Please refer to crate 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. |
Context | A structure to share request, response and other data between middlewares. |
Error | The |
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. |
SyncContext | Sync parts of Context. |
Variable | A wrapper of Arc |
Enums
ErrorKind | Kind of Error. |
Traits
Accept | Asynchronously accept incoming connections. |
Middleware | Middleware |
Spawn | Executor constraint. |
State | The |
Functions
join | Join two middleware. |
join_all | Join all middlewares in a vector. |
last | The last. |
Type Definitions
BlockingObj | Blocking task Object |
FutureObj | Future Object |
Next | Type of the second parameter in a middleware. |
Result | Type alias for |
ResultFuture | Type alias for |
Attribute Macros
async_trait |