joist
A backend framework for Rust, with no third-party dependencies.
use ;
or by hand:
[]
= "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:
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 ;
;
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
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.