Module rustful::context

Handler context and request body reading extensions.

#Context

The Context contains all the input data for the request handlers, as well as some utilities. This is where request data, like headers, client address and the request body can be retrieved from and it can safely be picked apart, since its ownership is transferred to the handler.

##Accessing Headers

The headers are stored in the headers field. See the Headers struct for more information about how to access them.

use rustful::{Context, Response};
use rustful::header::UserAgent;

fn my_handler(context: Context, response: Response) {
    if let Some(&UserAgent(ref user_agent)) = context.headers.get() {
        response.send(format!("got user agent string \"{}\"", user_agent));
    } else {
        response.send("no user agent string provided");
    }
}

##Path Variables

A router may collect variable data from paths (for example id in /products/:id). The values from these variables can be accessed through the variables field.

use rustful::{Context, Response};

fn my_handler(context: Context, response: Response) {
    if let Some(id) = context.variables.get("id") {
        response.send(format!("asking for product with id \"{}\"", id));
    } else {
        //This will usually not happen, unless the handler is also
        //assigned to a path without the `id` variable
        response.send("no id provided");
    }
}

##Other URL Parts

• Query variables (http://example.com?a=b&c=d) can be found in the query field and they are accessed in exactly the same fashion as path variables are used.

• The fragment (http://example.com#foo) is also parsed and can be accessed through fragment as an optional String.

##Global Data

There is also infrastructure for globally accessible data, that can be accessed through the global field. This is meant to provide a place for things like database connections or cached data that should be available to all handlers. The storage space itself is immutable when the server has started, so the only way to change it is through some kind of inner mutability.

#[macro_use] extern crate log;
use rustful::{Context, Response};
use rustful::StatusCode::InternalServerError;

fn my_handler(context: Context, mut response: Response) {
    if let Some(some_wise_words) = context.global.get::<&str>() {
        response.send(format!("food for thought: {}", some_wise_words));
    } else {
        error!("there should be a string literal in `global`");
        response.set_status(InternalServerError);
    }
}

##Request Body

The body will not be read in advance, unlike the other parts of the request. It is instead available as a BodyReader in the field body, through which it can be read and parsed as various data formats, like JSON and query strings. The documentation for BodyReader gives more examples.

use std::io::{BufReader, BufRead};
use rustful::{Context, Response};

fn my_handler(context: Context, response: Response) {
    let mut numbered_lines = BufReader::new(context.body).lines().enumerate();
    let mut writer = response.into_chunked();

    while let Some((line_no, Ok(line))) = numbered_lines.next() {
        writer.send(format!("{}: {}", line_no + 1, line));
    }
}

Modules

body	Anything related to reading the request body.
hypermedia	Anything related to hypermedia and hyperlinks.

Structs

Buffer	A byte buffer for more efficient MaybeUtf8 manipulation.
Context	A container for handler input, like request data and utilities.
Parameters	An extended HashMap with extra functionality for value parsing.

Enums

MaybeUtf8	String data that may or may not be UTF-8 encoded.
UriPath	A URI Path that can be a path or an asterisk (*).

Type Definitions

MaybeUtf8Owned	An owned string that may be UTF-8 encoded.
MaybeUtf8Slice	A slice of a string that may be UTF-8 encoded.