Runtime and Build
wisp::main!() is wisp::app!() plus a main that calls wisp::run::<App>(). Write your own main if the app sets things up first. wisp::serve::<App>(addr) is the async form for apps that own their runtime. Base path, slots, fonts and layers: Parity features.
Server
wisp::run::<App>() serves on $HOST:$PORT (default 3000) with one worker per CPU (WISP_THREADS). Each worker is a single-threaded tokio runtime with its own I/O driver, and a connection stays on one worker. There is no work stealing, so a handler that blocks its thread stalls that thread's connections. Dev builds log any handler that holds a thread for 100 ms or more.
- SIGTERM or Ctrl+C stops accepting, answers requests under way with
connection: close, and closes idle connections. The server returns afterWISP_DRAINseconds (10 by default) or at a second signal. WithWISP_STOP_DELAYset, it first waits that many seconds while/_wisp/healthanswers 503. See Environment variables. - Under
wisp devthe app exits when the CLI's stdin pipe closes, so a killedwisp devnever leaves an app on the port. - A panic in a handler is a 500 for that request. The connection survives.
- TLS and compression belong to the proxy or CDN (Caddy, nginx, Cloudflare). Or run Wisp as a tower service under hyper or axum: Testing and mixing with Rust code.
Settings
All settings are environment variables. A set but invalid value stops the server with a message. The full list is in Environment variables.
| Setting | What it does |
|---|---|
PORT, HOST | listen address (defaults: port 3000, host 127.0.0.1 in dev and 0.0.0.0 otherwise) |
WISP_DEV | dev mode: on in debug builds, off in release |
WISP_THREADS | worker threads, one per CPU |
WISP_BODY_LIMIT | largest request body (512KB or 10MB, default 1 MB) |
WISP_SECRET | signs cookies, at least 32 characters |
WISP_SECRET_OLD | the previous secret, for rotation |
ORIGIN | the site's address, for a proxy that does not pass Host |
WISP_CLIENT_IP_HEADER | header the proxy puts the client address in, for cx.client_ip(). The last address counts, the one your proxy added. A visitor can forge the first |
WISP_ONION | on, off or auto: serve as a Tor onion service |
WISP_MAX_CONNS | open connections before new ones get a 503. Unset: on Linux the open-file limit less 1024, within a quarter of memory (cgroup memory.max in a container) at 16 KiB each. Unset elsewhere: 10000. 0 for no cap |
WISP_IO | Linux: epoll instead of io_uring. uring fails at start where it cannot run |
Behind a proxy, the server checks form posts against Host, X-Forwarded-Host or ORIGIN, and cx.client_ip() trusts only the header WISP_CLIENT_IP_HEADER names. Behind a Tor onion service every visitor is the Tor daemon, 127.0.0.1 when it runs on the same host. RATE_LIMIT and cx.limit count by cx.visitor() instead. Behind Tor, this is a signed ticket cookie that each visitor carries. The whole site's allowance sits on top. A client that never returns its cookie shares one limit with all such clients. Limit by account or your own key with RateLimit::check(key) (cx.login already does). To count each Tor circuit on its own, set HiddenServiceExportCircuitID haproxy in torrc, put HAProxy in front (bind 127.0.0.1:8080 accept-proxy, option forwardfor) and set WISP_CLIENT_IP_HEADER=x-forwarded-for. This needs WISP_ONION=off. With on, or with an onion ORIGIN or SITE_URL, Wisp ignores WISP_CLIENT_IP_HEADER and logs that it does. With auto, a client address that differs from the peer ends the onion rules for that request. A client can open more circuits, so this stops a runaway browser, not a flood.
I/O Drivers
io_uring (Linux 6.1+, crates/wisp/src/uring.rs) is the default where it works. Each worker has its own ring and its own SO_REUSEPORT listener, and one io_uring_enter per turn submits every response. At start, a throwaway ring proves it works. It receives and sends. Three test requests over TCP must each finish by eventfd wakes within 500 ms. One request can try again. Then a request of 160 KiB must finish within 1 s. Its receive pauses on a full inbox and starts again, its echo needs more than one send, and the ring closes the connection (OP_CLOSE). No new way starts its proof after 2 s. With WISP_IO not set, the workers serve on epoll at once and the proof runs on a thread of its own. When it passes, each worker takes its listener out of its epoll (it does not close it, so no waiting connection is lost) and gives it to its ring. A worker whose ring then cannot start keeps its listener on epoll, and the server writes wisp: io: epoll (io_uring stopped working: ...) once. The epoll driver clears O_NONBLOCK before it gives the listener. If that fails, the worker keeps the listener on epoll, and the server writes wisp: io: epoll (the listener stays O_NONBLOCK: ...) once. The connections that epoll has stay on epoll until they end.
With WISP_IO=uring the start waits for the proof. With no loopback there is no proof. With DEFER_TASKRUN on Linux 6.18.54.1-microsoft-standard-WSL2 and Ubuntu 7.0.0-42-generic, the eventfd of a ring stops waking for new connections. The check fails there, and the workers use a ring without DEFER_TASKRUN. The kernel source may explain it. io_eventfd_do_signal (io_uring/eventfd.c:42 at tags v6.18 and v7.0) does not clear IO_EVENTFD_OP_SIGNAL_BIT. Linux commit 04fe9aeb4f3c adds the clear. The order is: buffer ring with DEFER_TASKRUN, buffer ring without it, PROVIDE_BUFFERS with it, PROVIDE_BUFFERS without it, epoll. The speed without DEFER_TASKRUN is not measured. One stderr line (wisp: io: ...) says which driver runs. The driver itself answers a request whose handler never waits, without the scheduler, as on epoll. epoll already did this. It does not change. Where the kernel refuses buffer rings (Ubuntu 24.04's 6.8), the driver falls back to PROVIDE_BUFFERS. A page head and a body of 16 KiB or more go in one send: one sendmsg on epoll, one OP_SENDMSG on io_uring. At start a test send checks OP_SENDMSG. When it fails, the head and the body go in two sends, and the stderr line adds , no OP_SENDMSG (<cause>).
epoll (crates/wisp/src/epoll.rs) runs where io_uring cannot run (before 6.1, a seccomp profile such as Docker's default, the io_uring_disabled sysctl), or with WISP_IO=epoll. The driver answers a request whose handler never waits, without the scheduler. An async fn before in hooks.rs takes that path away from every route, so keep it sync.
Connections and Limits
An idle keep-alive connection gives its read and write buffers back to the thread's pool. On io_uring the kernel receives into the worker's own buffers. A worker gets 28 buffers. It gets a quarter more (at least 16) whenever a receive finds none, up to 256 with a buffer ring and 4096 without. A write buffer of 16 KB or less stays with the connection for its next response. A larger one goes to the worker's spares (64 at most). The spares shrink to the size of the response that last used them. The worker frees a spare once no send took it for a second. On Linux with glibc, the clock thread trims the heap (malloc_trim) when a worker frees buffers that it kept. It also trims after a worker that had at least 170 connections open has none open for 2 s.
| Limit | Value |
|---|---|
| Headers | 16 KB, 100 headers |
| Too large a head | over 16 KB or 100 headers: 431. A request line over 16 KB with no line end: 414 |
| HTTP version | HTTP/2.0, HTTP/1.2 and the like: 505 (the server speaks 1.0 and 1.1) |
| JSON body | 200 000 values (keys counted) and 128 levels deep, else 400 |
| Body | 1 MB (WISP_BODY_LIMIT or a route's BODY_LIMIT), checked against Content-Length first |
| Receive | 10 s for the head, then 10 s per part of the body. After the first 10 s, a body must average 1024 bytes a second (MIN_BODY_RATE, crates/wisp/src/policy.rs:19) |
| Keep-alive idle | 60 s |
| Client taking a response | 30 s |
| Out of descriptors | accepting pauses 50 ms at a time |
- HTTP/1.1 without
Host, or with two, is 400. The server parses chunked bodies strictly (other codings are 501,Content-LengthwithTransfer-Encodingis 400). - With
WISP_ALLOWED_HOSTSset, a request with anotherHost, or with none (HTTP/1.0), is a 421. It holds on the native server and on thenode,deno,bunandcloudflaretargets. Oncloudflare, the files ofstatic/come from Cloudflare and skip the check. Thepages,vercel,netlifyandazurehosts also serve those files before the app. Not tested on those hosts. - The server gzips embedded files (
wisp.js,live.js, CSS,static/) once, with Huffman codes made for each file, off the request path. - The build makes Brotli copies of embedded text and prerendered pages and embeds them as
.br. It useswisp-buildand thebrotlicrate (quality 11, a build dependency only). The request path readsaccept-encodingonly for an asset that has a copy, and sends the copy as is.
HTTP/2
The h2 feature compiles in h2c with prior knowledge (src/h2.rs, own HPACK, no new dependency). A request over HTTP/1 pays nothing, with the feature on or off. There is no Upgrade: h2c, no ALPN and no server TLS.
- Limits: 100 concurrent streams, 16 KiB header lists, the route's body limit (413).
- A reset, CONTINUATION or HPACK flood ends the connection with GOAWAY
ENHANCE_YOUR_CALM. - WebSockets use extended CONNECT (RFC 8441). A plain GET to a WebSocket route is a 426.
One Request Entry Point
The built-in server is one front end. Everything else calls the same code, parser and limits (Testing and mixing with Rust code, Deploying):
| Entry | What it is |
|---|---|
wisp::prepare::<A>() | runs init |
wisp::handle::<A>(Request) -> Reply | answers one request in process |
wisp::test::client::<A>() | handle with cookies, for tests |
wisp::test::browser::<A>() (feature browser) | the server on a free port, driven in headless Chrome or Edge |
wisp::tower::service::<A>() (feature tower) | a tower::Service |
wisp build --static | runs handle for each page and writes files |
wisp build --target | compiles the same code to WebAssembly (crates/wisp/src/edge.rs) with a small JS bridge |
The App Trait
Generated code implements one trait:
pub trait App: 'static {
fn init() -> impl Future<Output = Result<()>>;
fn handle(
route: Option<usize>,
cx: &mut Cx,
out: &mut Out,
) -> impl Future<Output = Result<()>> + Send;
// + static tables: shell, assets, templates (dev)
}
handle calls before, then is one match over the route id, so the compiler monomorphizes the whole server with the app. It has no handler trait objects.
Templates need less Rust:
Datafields are in scope:${count}for${data.count}.class:won=${data.won}toggles a class on the server.<a ${href}>ishref=${href}.- An
Optionattribute (aria-current=${current}) drops out whenNone. #[derive(Json)]gives JSON without serde: return the value, orResponse::json_of(&value).
Hooks in the Request Flow
before runs first, then the route's guards, load and render, then html on the finished text/html body, then after. before returns Result<Option<Response>>. Ok(Some(response)) answers at once, and Ok(Some(Response::rewrite("/x"))) routes again to /x. See Parity features.
What wisp build Does
wisp_build::run() in the app's build.rs:
- Walks
src/routes, builds the route table and rejects conflicts. - Parses every
.wispfile into a node list. Errors arefile:line:col: msg. - Scans
+page.rs,+layout.rs,+server.rs, the blocks' items,src/hooks.rsandsrc/NAME.rsforfn load,#[action]functions, HTTP-method functions, hooks andconst BODY_LIMIT, and reads each signature. - Writes
$OUT_DIR/wisp.rs: a module per user file, a render function per template, the router and the asset tables. Each block line carries a// file.wisp:linecomment, whichwisp devuses to retell rustc's errors against the file.
Release builds embed static/ and the built CSS with a content hash, served Cache-Control: immutable under ?v=hash URLs. A file whose path has a segment that starts with . is not embedded, except under a top-level .well-known.
- Baked pages. A page that is the same for every request (no load, statements or
+page.js, literal holes and props) is onestaticin the binary. Answering is two copies and the date, and a matchingif-none-matchis a 304 without hashing. Hooks still run first. - Folded text. In release, adjacent text and literal holes become one
push_str, escaped at build time. - Router. The router matches a path with no parameter whole, by length then bytes.
Is This Page Useful?