4 releases (2 breaking)
0.3.0 | Dec 30, 2020 |
---|---|
0.2.1 | May 27, 2020 |
0.2.0 | May 20, 2020 |
0.1.0 | May 11, 2020 |
#1002 in HTTP server
140KB
3K
SLoC
tophat
A small, pragmatic, and flexible async HTTP server library. Currently in beta.
Cargo.toml:
tophat = "0.3.0"
The goal is to be low-level and small enough to work with different async runtimes and not dictate user architecture, while having enough convenience functions to still easily build a REST api. More library than framework.
Also, this:
async fn handler<W>(_req: Request, resp_wtr: ResponseWriter<W>) -> Result<ResponseWritten, Glitch>
where W: AsyncRead + AsyncWrite + Clone + Send + Sync + Unpin + 'static,
{
// Default `send` is 200 OK
let done = resp_wtr.send()?;
// Do things here after resp is written, if you like
Ok(done)
}
instead of:
async fn handler(req:Request) -> Result<Response, Error> {
Ok(Response::empty())
}
Don't be scared away by the generics and trait bounds! They won't bite! (probably)
Features
- HTTP/1.1
- Works with any tcp stream that implements
futures::{AsyncRead, AsyncWrite}
. - All dependencies are async-ecosystem independent.
- Not meant to be a framework; minimal abstraction.
- #[deny(unsafe_code)]
- Fast enough.
- Router
features = ["router"]
, very minimal. - Cors
features = ["cors"]
. - Identity
features = ["identity"]
. - "Middleware" capabilities by using functions in front of router.
- Convenient error/response handling using
Glitch
andGlitchExt
, to conveniently chain onto bothResult
andOption
. - Extensive examples.
- A minimal client (not under active development)
Correct handling of the HTTP protocol is a priority.
Example
Using smol
as the async runtime. Example is single-threaded, see smol
docs for how to make a multi-threaded executor.
use smol::{Async, Task};
use std::net::TcpListener;
use async_dup::Arc;
use tophat::server::accept;
fn main() -> Result<(), Box<dyn std::error::Error>> {
let listener = Async::<TcpListener>::bind("127.0.0.1:9999")?;
smol::run(async {
loop {
let (stream, _) = listener.accept().await?;
let stream = Arc::new(stream);
let task = Task::spawn(async move {
let serve = accept(stream, |_req, resp_wtr| async {
resp_wtr.send().await
}).await;
if let Err(err) = serve {
eprintln!("Error: {}", err);
}
});
task.detach();
}
})
}
Philosophy
I wouldn't consider this a batteries-included framework which tries to make every step easy. There are conveniences, but overall tophat is pretty minimal. For those who don't like boilerplate, another framework would probably work better. Users of tophat need to be familiar async runtimes, setting up a TCP stream, Arc
, traits, generics, etc. Tophat won't hold your hand.
In exchange, tophat provides more transparency and more control. Tophat won't dictate how to structure your app, it should play nicely with your architecture.
And if you want to know what tophat is doing under the hood, the code is meant to be simple and straightforward (Hopefully this also leads to better compile times!).
Inspiration
I was inspired to write tophat because:
- I wanted to have an async https server which was not tied to an async ecosystem and
- I saw this github issue on using a
ResponseWriter
instead of returningResponse
: https://github.com/hyperium/hyper/issues/2181
Thanks
Especially to async-h1, whose eye for structure and design I appreciate, and whose code base tophat is built from. And to hyper, whose devotion to performance and correctness is inspiring, and whose basic http libraries tophat has incorporated.
License
Licensed under either of
- Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Dependencies
~2.4–7MB
~132K SLoC