[−][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;
let app = App::new().end("Hello, World");

Endpoint

An endpoint is a request handler.

There are some build-in endpoints in roa_core.

Functional endpoint

A normal functional endpoint is an async function with signature: async fn(&mut Context) -> Result.

use roa_core::{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(())
```
let app = roa_core::App::new().end(());
```

Status endpoint

Status is an endpoint always return Err(Status)

use roa_core::{App, status};
use roa_core::http::StatusCode;
let app = App::new().end(status!(StatusCode::BAD_REQUEST));

String endpoint

Write string to body.

use roa_core::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.

use roa_core::App;
use roa_core::http::Uri;

let app = App::new().end("/target".parse::<Uri>().unwrap());

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 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("Hello, World");

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 a 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);
    }
}

status	Construct a `Status`.
throw	Throw an `Err(Status)`.

Structs

AddrStream	A transport returned yieled by `AddrIncoming`.
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 `Status` of roa.
Variable	A wrapper of Arc.

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

Type Definitions

Next	Type of the second parameter in a middleware, an alias for `&mut (dyn Unpin + Future<Output = Result>)`
Result	Type alias for `StdResult`.

Attribute Macros

async_trait