Module rustful::handler

Request handlers and routers.

Building Routers

Rustful provides a tree structured all-round router called DefaultRouter, but any other type of router can be used, as long as it implements the HandleRequest trait. Implementing the Build trait will also make it compatible with router builders:

extern crate rustful;
use rustful::DefaultRouter;

let mut router = DefaultRouter::<ExampleHandler>::new();
router.build().many(|mut node| {
    node.then().on_get(show_welcome);
    node.path("about").then().on_get(about_us);
    node.path("users").many(|mut node| {
        node.then().on_get(list_users);
        node.path(":id").then().on_get(show_user);
    });
    node.path("products").many(|mut node| {
        node.then().on_get(list_products);
        node.path(":id").then().on_get(show_product);
    });
    node.path("*").then().on_get(show_error);
});

#Variables

Routes in the TreeRouter may contain variables, that are useful for capturing parts of the requested path as input to the handler. The syntax for a variable is simply an indicator character (: or *) followed by a label. Variables without labels are also valid, but their values will be discarded.

##Variable Segments (:label)

A variable segment will match a single arbitrary segment. They are probably the most commonly used variables and may, for example, be used to select a blog post: "posts/:year/:month/:day/:title_slug".

pattern = "a/:v/b"
"a/c/b" -> v = "c"
"a/c/d/b" -> no match
"a/b" -> no match
"a/c/b/d" -> no match

##Variable Sequences (*label)

A variable sequence is similar to a variable segment, but with the difference that it may consume multiple segments until the rest of the path gives a match. An example use case is a route for downloadable files that may be arranged in arbitrary directories: "downloads/*file_path".

pattern = "a/*v/b"
"a/c/b" -> v = "c"
"a/c/d/b" -> v = "c/d"
"a/b" -> no match
"a/c/b/d" -> no match

pattern = "a/b/*v"
"a/b/c" -> v = "c"
"a/b/c/d" -> v = "c/d"
"a/b" -> no match

Router Composition

The default router is actually a composition of three routers: TreeRouter, MethodRouter and Variables. They come together as the type DefaultRouter<T>, so no need to write it all out in most of the cases.

There may, however, be cases where you want something else. What if you don't care about the HTTP method? Maybe your handler takes care of that internally. Sure, no problem:

use rustful::handler::{Variables, TreeRouter};

let my_router = TreeRouter::<Option<Variables<ExampleHandler>>>::new();

And what about those route variables? Not using them at all? Well, just remove them too, if you don't want them:

use rustful::handler::TreeRouter;

let my_router = TreeRouter::<Option<ExampleHandler>>::new();

You can simply recombine and reorder the router types however you want, or why not make your own router?

Re-exports

pub use self::tree_router::TreeRouter;

pub use self::method_router::MethodRouter;

pub use self::or_else::OrElse;

pub use self::status_router::StatusRouter;

Modules

method_router	A router that selects a handler from an HTTP method.
or_else	A router that selects a secondary handler on error.
routing	Routing related traits and types.
status_router	A router that selects an item from an HTTP status code.
tree_router	A tree shaped router that selects handlers using paths.

Structs

ContentFactory	An adapter for simple content creation handlers.
Environment	A request environment, containing the context, response and route state.
VariableNames	Context type for storing path variable names.
Variables	Assigns names to route variables.

Traits

ApplyContext	Apply a BuilderContext in various ways.
Build	A trait for handlers that can be build, using a chainable API.
CreateContent	A simplified handler that returns the response content.
FromHandler	Create a handler from another handler.
HandleRequest	A low level request handler.
Handler	A trait for request handlers.
Merge	A trait for handlers that can be merged.

Type Definitions

BuilderContext	A collection of information that can be passed to child handlers while building a handler.
DefaultRouter	Alias for TreeRouter<MethodRouter<Variables<T>>>.