aitch

aitch is a simple, lightweight toolkit for building HTTP servers in safe, stable Rust.

It builds upon the http crate, and provides additional types for representing HTTP handlers, bodies and middlewares. It provides both hyper and tiny_http backends for running handlers, but aims to be agnostic of the HTTP server library.

It's inspired by the simplicity (and popularity) of Go's net/http package, which builds application/middlewares as a series of nested Handlers.

aitch takes advantage of Rust's type system in order to make these handlers even easier to work with, without losing the simplicity that makes them so great.

Example

extern crate aitch;
extern crate http;

use aitch::servers::hyper::Server;
use aitch::{middlewares, Responder, Result};
use http::Request;

fn handler(_: Request<()>, mut resp: http::response::Builder) -> impl Responder {
    resp.body("Hello, world!".to_owned())
}

fn main() -> Result<()> {
    let wrapped = middlewares::with_stdout_logging(handler);

    let addr = "127.0.0.1:3000".parse()?;
    println!("Listening on http://{}", addr);
    Server::new(addr, wrapped)?.run()
}

This example is provided alongside aitch. To run it, clone this repository and run:

cargo run --release --example hello-world-sync

See also these other examples in the examples/ directory of this repo:

• json.rs, which uses the optional Json<T> type to wrap structs which are automatically (de)serialized in request/response bodies.
• simple-router.rs, which uses a simple request router, modelled after net/http's ServeMux.
• shared-context.rs, which shows how to use the provided middlewares::with_context to inject a struct containing shared resources into an application's HTTP handlers.
• examples/static-files.rs, which shows how to use the provided handlers::static_files::* handlers in order to serve static assets during development.

Dependencies & Features

aitch aims provide just the types necessary to build HTTP applications with your server technology of choice. It aims to be lightweight in both dependencies and runtime cost, while still being ergonomic to use.

To function, aitch requires a small number of dependencies: http, futures and bytes.

In order to help you be productive quickly, aitch provides a number of optional features, which are currently enabled by default:

• server-hyper: Provides a Server, which can run an aitch::Handler using the hyper web server. (example)
• server-tiny-http: Provides a Server, which can run an aitch::Handler using the tiny_http web server. (example)
• json: Provides a Json<T> type, which can wrap any type T: serde::Deserialize + serde::Serialize, allowing it to be used in requests and responses: http::Request<Json<T>>/http::Response<Json<T>>. (example)
• mime_guess: Uses the mime_guess crate to guess the MIME type of responses returned by the included handlers::static_files::* handlers.

These features will probably be split out into separate crates in the near future.

Is it fast?

It's pretty fast!

When profiling the default hello-world-sync example (with logging to stdout disabled, using Hyper), with 12 threads and 100 connections, we see ~130,000 req/s on a 2015 13inch MBP:

$ wrk --latency -t12 -c100 -d10s http://localhost:3000/
Running 10s test @ http://localhost:3000/
  12 threads and 100 connections
  Thread Stats   Avg      Stdev     Max   +/- Stdev
    Latency   837.87us    1.15ms  35.88ms   94.35%
    Req/Sec    11.09k     1.55k   17.44k    75.25%
  Latency Distribution
     50%  630.00us
     75%    1.06ms
     90%    1.61ms
     99%    3.45ms
  1325352 requests in 10.02s, 135.24MB read
Requests/sec: 132296.91
Transfer/sec:     13.50MB

License

MIT