[][src]Crate roa_core

Build status codecov Rust Docs Crate version Download Version License: MIT

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 Err(Error).

Structs

AddrStream

A transport returned yieled by AddrIncoming.

App

The Application of roa.

Context

A structure to share request, response and other data between middlewares.

Error

The Error of roa.

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 State trait, should be replace with trait alias. The App::state will be cloned when a request inbounds.

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 StdResult<R, Error>.

ResultFuture

Type alias for Pin<Box<dyn 'a + Future<Output = Result<R>>>>.

Attribute Macros

async_trait