Request Handlers

A request handler is an async function that accepts zero or more parameters that can be extracted from a request (i.e., impl FromRequest) and returns a type that can be converted into an HttpResponse (i.e., impl Responder).

Request handling happens in two stages. First the handler object is called, returning any object that implements the Responder trait. Then, respond_to() is called on the returned object, converting itself to a HttpResponse.

By default ntex provides Responder implementations for some standard types, such as &'static str, String, Bytes, Option<T>, Result<T, E>, etc.

Handlers registered with to() only use extractors. Handlers registered with to_with_state() also receive a reference to the application state and the request state as their first two arguments:

async fn index(state: &AppState, _: (), req: HttpRequest) -> String {
    format!("Hello {}!", state.app_name)
}

The request state starts as (). Filters can change its type, for example to the authenticated user, and the handler's second argument must match it. See the state/web-state example.

For a complete list of implementations, check the Responder documentation.

Examples of valid handlers:

async fn index(_req: HttpRequest) -> &'static str {
    "Hello world!"
}

async fn index(_req: HttpRequest) -> String {
    "Hello world!".to_owned()
}

You can also change the signature to return impl Responder which works well if more complex types are involved.

async fn index(_req: HttpRequest) -> impl Responder {
    ntex::util::Bytes::from_static(b"Hello world!")
}

Handlers that return an error type must use a Result, where the error implements WebResponseError:

async fn index(_req: HttpRequest) -> Result<String, std::io::Error> {
    Ok(std::fs::read_to_string("index.html")?)
}

Streaming response body

Response body can be generated asynchronously. In this case, body must implement the stream trait Stream<Item = Result<Bytes, E>>, where E implements std::error::Error, i.e.:

Different return types (Either)

Sometimes, you need to return different types of responses. For example, you can error check and return errors, return async responses, or any result that requires two different types.

For this case, the Either type can be used. Either allows combining two different responder types into a single type.