joist 1.0.0

A backend framework for Rust: routing, middleware, JSON, config and plugins, with no third-party dependencies.
Documentation
  • Coverage
  • 39.15%
    83 out of 212 items documented2 out of 142 items with examples
  • Size
  • Source code size: 189.8 kB This is the summed size of all the files inside the crates.io package for this release.
  • Documentation size: 1.9 MB This is the summed size of all files generated by rustdoc for all configured targets
  • Ø build duration
  • this release: 5s Average build duration of successful builds.
  • all releases: 6s Average build duration of successful builds in releases after 2024-10-23.
  • Links
  • Homepage
  • Repository
  • crates.io
  • Dependencies
  • Versions
  • Owners
  • martin-k-m

joist

A backend framework for Rust, with no third-party dependencies.

CI crates.io docs.rs Rust License Dependencies

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();
}
cargo add joist

or by hand:

[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.

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:

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 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

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

Document What it covers
docs/getting-started.md Build a service from nothing
docs/routing.md Patterns, matching order, parameters
docs/middleware.md Hooks, ordering, writing your own
docs/architecture.md How it works and why
docs/roadmap.md What is not built yet

Development

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.

License

Apache-2.0