Crate iron

The main crate for Iron.

Overview

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

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

Hello World

extern crate iron;

use iron::prelude::*;
use iron::status;

fn main() {
    Iron::new(|_: &mut Request| {
        Ok(Response::with((status::Ok, "Hello World!")))
    }).http("localhost:3000").unwrap();
}

Design Philosophy

Iron is meant to be as extensible and pluggable as possible; Iron’s core is concentrated and avoids unnecessary features by leaving them to middleware, plugins, and modifiers.

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

Modifiers allow external code to manipulate Requests and Response in an ergonomic fashion, allowing third-party extensions to get the same treatment as modifiers defined in Iron itself. 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.

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

Re-exports

• pub use request::Request;
• pub use request::Url;
• pub use response::Response;
• pub use middleware::BeforeMiddleware;
• pub use middleware::AfterMiddleware;
• pub use middleware::AroundMiddleware;
• pub use middleware::Handler;
• pub use middleware::Chain;
• pub use error::IronError;

Modules

• error
  Iron’s error type and associated utilities.
• headers
  Headers container, and common header fields.
• method
  HTTP Methods
• middleware
  This module contains Iron’s middleware and handler system, the fundamental building blocks for handling HTTP requests and generating responses.
• mime
  Re-exporting the mime crate, for convenience.
• modifier
  Re-exports from the Modifier crate.
• modifiers
  This module defines a series of convenience modifiers for changing Responses.
• prelude
  A module meant to be glob imported when using Iron.
• request
  Iron’s HTTP Request representation and associated methods.
• response
  Iron’s HTTP Response representation and associated methods.
• status
  Status Codes
• typemap
  Re-exports from the TypeMap crate.
• url
  Re-exports from the url crate.

Macros

• headers
• iexpect
  Unwrap the given Option or return a Ok(Response::new()) with the given modifier. The default modifier is status::BadRequest.
• itry
  Like try!(), but wraps the error value in IronError. To be used in request handlers.

Structs

• Headers
  A map of header fields on requests and responses.
• Iron
  The primary entrance point to Iron, a struct to instantiate a new server.
• Listening
  A listening server, which can later be closed.
• Protocol
  Protocol used to serve content.
• Timeouts
  A settings struct containing a set of timeouts which can be applied to a server.
• TypeMap
  A map keyed by types.

Traits

• Error
  Error is a trait representing the basic expectations for error values, i.e., values of type E in Result<T, E>.
• Plugin
  An interface for plugins that cache values between calls.
• Set
  A trait providing the set and set_mut methods for all types.

Type Aliases

• IronResult
  The Result alias used throughout Iron and in clients of Iron.