Rouille Web Framework

The multipart crate provides client- and server-side abstractions for handling HTTP file uploads using Content-Type: multipart/form-data.

Key details:

• API Style: It uses a synchronous API. For asynchronous (futures-based) support, use the multipart-async crate.
• Maintenance Status: Passive maintenance (as of June 2020). Bug reports are addressed as time permits, but no new features are being added to the existing API.
• Minimum Rust Version: 1.36.0

Rouille is a synchronous micro-web-framework. Unlike many modern frameworks that use asynchronous I/O, green threads, or coroutines, Rouille uses a dedicated thread for each incoming request.

It does not use a middleware pattern. Instead of registering a chain of middleware functions, you handle the entire request lifecycle linearly within the server closure. This design is intended to be intuitive for Rust developers and avoids the complexity of middleware chains. Because it is synchronous, it is designed to work easily with any third-party library (like databases or templating engines) without requiring specific 'glue code' or asynchronous wrappers.

Direct integration is not provided for Rocket because Rocket handles multipart/form-data internally. However, you can still use multipart on a Rocket server by following the pattern shown in the project's examples.

See examples/rocket.rs for a concrete implementation example.

The multipart crate provides abstractions for HTTP multipart/form-data requests with the following feature flags:

• client: Client-side abstractions for generating multipart requests.
• server: Server-side abstractions for parsing multipart requests.
• mock: Mock implementations of core client and server traits for debugging or non-standard use.
• hyper: Integration with the Hyper HTTP library (requires client or server features).
• iron: Integration with the Iron web application framework.
• nickel: Integration with the Nickel web application framework.
• tiny_http: Integration with the tiny_http crate.

The LimitBehavior enum defines how the Intercept middleware reacts when a request exceeds the configured file_size_limit or file_count_limit:

• LimitBehavior::ThrowError: The middleware will stop processing and return an IronError. This is the default behavior.
• LimitBehavior::Continue: The middleware will attempt to continue processing.
  • For size limits: The offending file will be truncated in the resulting Entries.
  • For count limits: The request will be completed with the files received up to the limit.

#[derive(Clone, Copy, Debug, repr(u32))]
pub enum LimitBehavior {
    ThrowError,
    Continue,
}

Errors occurring during the lazy construction or transmission of a multipart request are wrapped in LazyError. This error type provides context about which field caused the failure.

Error Structure

• field_name: An Option<Cow<'a, str>>. If Some, it contains the name of the field that caused the error (e.g., a file that failed to open). If None, the error occurred during stream initialization or finalization.
• error: The underlying error (typically std::io::Error).

LazyError implements std::error::Error and can be converted into a std::io::Error via Into.

The easiest way to get started with Rouille is using the start_server function. It listens on the specified address and executes the provided closure for every incoming request. The closure receives a &Request and must return a Response.

Important Requirements:

• The handler closure must capture its environment by value (use the move keyword).
• The handler must be thread-safe (Send and Sync). If you need to access shared state, use a Mutex or Atomic type.
• If the handler panics, Rouille will automatically send a 500 Internal Server Error response to the client.

use rouille::Request;
use rouille::Response;

rouille::start_server("0.0.0.0:80", move |request| {
    Response::text("hello world")
});

The StateMachine provides a low-level way to parse WebSocket frames from a stream of bytes. It handles partial data, buffering headers, and decoding masked payloads.

Workflow:

1. Initialize a new state machine using StateMachine::new().
2. Whenever new data is received from the socket, call StateMachine::feed(&[u8]).
3. Iterate over the returned ElementsIter to process the decoded Element objects.
4. If you encounter Element::Error, you must immediately terminate the connection.

Glossary:

• A WebSocket stream consists of multiple messages.
• Each message consists of one or more frames.
• Frames can be received progressively; StateMachine::feed handles the accumulation of bytes across multiple calls.

This example demonstrates how to use multipart with the Iron web application framework by utilizing multipart's support for the iron::Request type. Note that the iron feature must be enabled.

$ cargo run --features iron --example iron

This example demonstrates how to use multipart with Hyper's newer Client API by leveraging the lazy-writing capabilities provided by multipart::client::lazy.

$ cargo run --example hyper_reqbuilder