# joist
**A backend framework for Rust, with no third-party dependencies.**
[](https://github.com/martin-k-m/joist/actions/workflows/ci.yml)
[](https://crates.io/crates/joist)
[](https://docs.rs/joist)
[](https://www.rust-lang.org)
[](LICENSE)
[](Cargo.toml)
```rust
use joist::{Response, Router, Server};
fn main() {
let mut router = Router::new();
router.get("/hello/:name", |req| {
Response::text(format!("hello {}", req.param("name").unwrap_or("world")))
});
Server::new(router).bind("127.0.0.1:8080").unwrap().wait();
}
```
```sh
cargo add joist
```
or by hand:
```toml
[dependencies]
joist = "0.1"
```
That is the whole dependency tree. `cargo build` on a clean machine downloads
nothing, `cargo audit` has one crate to look at, and no upstream release can
break your build.
API documentation is on [docs.rs](https://docs.rs/joist).
To try it without a Rust toolchain, the `hello` example is published as an
image. It is a demo of the framework, not the library itself:
```sh
docker run --rm -p 8080:8080 ghcr.io/martin-k-m/joist
curl localhost:8080/hello/martin
```
## What is in 0.1
| **Routing** | Path parameters (`:id`), wildcards (`*rest`), automatic `405` with `Allow`, `HEAD` served by the `GET` route |
| **Middleware** | `before`/`after` hooks, short-circuiting, with a request logger and CORS included |
| **JSON** | Parse and serialise, with sorted keys so responses are byte-stable and exact integers so ids survive the trip |
| **Requests** | Percent-decoded paths, query parameters, size-capped bodies, keep-alive, and a constructor so a handler can be unit-tested without a socket |
| **Config** | Environment and file, normalised so `APP_DATABASE_URL` and `database.url` are one setting |
| **Plugins** | Bundle routes for reuse |
| **Server** | Threaded HTTP/1.1, graceful shutdown, panic isolation |
## What is not
WebSockets, authentication, database migrations, background jobs, queues,
caching and observability are on the roadmap and **not implemented**. They are
listed in [docs/roadmap.md](docs/roadmap.md) rather than shipped as stubs,
because a function that returns success without doing anything is worse than an
absent one.
## Threads, not async
Joist serves each connection on a worker thread from a fixed pool.
That is a real ceiling. A few thousand idle connections cost a few thousand
threads, where an async runtime would cost almost nothing. If you are building
something that holds many mostly-idle connections, use a framework built on
`tokio` instead. This is not the tool for that.
What it buys: handlers are ordinary functions, there is no colouring, no
executor to reason about, stack traces mean what they say, and the whole
framework is about a thousand lines you can read in an afternoon.
## Middleware
```rust
use joist::{Middleware, Request, Response, Status};
struct RequireToken;
impl Middleware for RequireToken {
fn before(&self, req: &mut Request) -> Option<Response> {
match req.headers.get("Authorization") {
Some(_) => None,
None => Some(Response::error(Status::UNAUTHORIZED, "missing token")),
}
}
}
```
`before` hooks run in registration order, and returning a response skips the
remaining hooks and the handler. `after` hooks run in reverse order and always
run, so a logger still records a request that authentication rejected.
These are hooks rather than an onion of `next()` calls. The onion is more
general, since it lets one middleware hold state across the handler, which is
how request timing is normally done. Hooks cannot. In exchange the ordering is
obvious and writing one does not involve lifetimes. To wrap, wrap the handler.
## Safety and limits
Requests are capped before a handler sees them: 8 KB per line, 100 header
fields, and a body limit that defaults to 2 MB (`max_body_bytes`). A handler
that panics returns `500` and the worker keeps serving. Handlers cannot override
`Content-Length`, `Connection` or `Transfer-Encoding`, since those are decided
from the actual body.
`chunked` request bodies are **not** implemented and return `501` rather than
being misread as content. Joist speaks no TLS: terminate it at a reverse proxy.
## Documentation
| [docs/getting-started.md](docs/getting-started.md) | Build a service from nothing |
| [docs/routing.md](docs/routing.md) | Patterns, matching order, parameters |
| [docs/middleware.md](docs/middleware.md) | Hooks, ordering, writing your own |
| [docs/architecture.md](docs/architecture.md) | How it works and why |
| [docs/roadmap.md](docs/roadmap.md) | What is not built yet |
## Development
```sh
cargo test # unit and end-to-end tests
cargo clippy --all-targets -- -D warnings
cargo fmt --all -- --check
cargo run --example hello
```
The end-to-end tests bind real sockets on port 0 and speak raw HTTP, so what is
verified is the bytes on the wire rather than an internal call.
Your own handlers do not need a socket. A handler is an ordinary function, and
`Request::new(Method::Get, "/users/42").with_param("id", "42")` builds the
argument to call it with. See
[docs/getting-started.md](docs/getting-started.md#testing-a-handler).
## License
[Apache-2.0](LICENSE)