Ferrum

An Extensible, Concurrent Web Framework for Rust.

Ferrum is a fork of the Iron.

Hello World Example

extern crate ferrum;

use ferrum::*;

fn main() {
    Ferrum::new(|_: &mut Request| {
        Ok(Response::new().with_content("Hello world!", mime::TEXT_PLAIN))
    }).http("localhost:3000").unwrap();
}

Response Timer Example

extern crate time;
extern crate ferrum;

use ferrum::*;
use time::precise_time_ns;

struct ResponseTime;

impl typemap::Key for ResponseTime {
    type Value = u64;
}

impl BeforeMiddleware for ResponseTime {
    fn before(&self, request: &mut Request) -> FerrumResult<()> {
        request.extensions.insert::<ResponseTime>(precise_time_ns());
        Ok(())
    }
}

impl AfterMiddleware for ResponseTime {
    fn after(&self, request: &mut Request, response: Response) -> FerrumResult<Response> {
        let delta = precise_time_ns() - *request.extensions.get::<ResponseTime>().unwrap();
        println!("Request took: {} ms", (delta as f64) / 1000000.0);
        Ok(response)
    }
}

fn hello_world(_: &mut Request) -> FerrumResult<Response> {
    Ok(Response::new().with_content("Hello World", mime::TEXT_PLAIN))
}

fn main() {
    let mut chain = Chain::new(hello_world);
    chain.link_before(ResponseTime);
    chain.link_after(ResponseTime);
    Ferrum::new(chain).http("localhost:3000").unwrap();
}

Overview

Ferrum is a high level web framework built in and for Rust, built on hyper. Ferrum is designed to take advantage of Rust's greatest features - its excellent type system and its principled approach to ownership in both single threaded and multi threaded contexts.

Ferrum is highly concurrent and can scale horizontally on more machines behind a load balancer or by running more threads on a more powerful machine. Ferrum avoids the bottlenecks encountered in highly concurrent code by avoiding shared writes and locking in the core framework.

Philosophy

Ferrum is meant to be as extensible and pluggable as possible; Ferrum's core is concentrated and avoids unnecessary features by leaving them to middleware and plugins.

Middleware and Plugins are the main ways to extend Ferrum with new functionality. Most extensions that would be provided by middleware in other web frameworks are instead addressed by the much simpler Plugin system.

Plugins allow for lazily-evaluated, automatically cached extensions to Requests and Responses, perfect for parsing, accessing, and otherwise lazily manipulating an http connection.

Middleware are only used when it is necessary to modify the control flow of a Request flow, hijack the entire handling of a Request, check an incoming Request, or to do final post-processing. This covers areas such as routing, mounting, static asset serving, final template rendering, authentication, and logging.

Ferrum comes with only basic functionality for setting the status, body, and various headers, and the infrastructure for creating plugins and middleware. No plugins or middleware are bundled with Ferrum.

Underlying HTTP Implementation

Ferrum is based on and uses hyper as its HTTP implementation, and lifts several types from it, including its header representation, status, and other core HTTP types. It is usually unnecessary to use hyper, futures and mime directly when using Ferrum, since Ferrum provides a facade over those core facilities, but it is sometimes necessary to depend on it as well.

Installation

If you're using Cargo, just add Ferrum to your Cargo.toml:

[dependencies.ferrum]
version = "*"

Examples

Check out the examples directory!

You can run an individual example using cargo run --example example-name. Note that for benchmarking you should make sure to use the --release flag, which will cause cargo to compile the entire toolchain with optimizations. Without --release you will get truly sad numbers.

License

MIT