Wisp is in pre-release, self-hosted since GitHub suspended us. Install it, or see the changelog.

Wisp

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 after WISP_DRAIN seconds (10 by default) or at a second signal. With WISP_STOP_DELAY set, it first waits that many seconds while /_wisp/health answers 503. See Environment variables.
  • Under wisp dev the app exits when the CLI's stdin pipe closes, so a killed wisp dev never 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.

SettingWhat it does
PORT, HOSTlisten address (defaults: port 3000, host 127.0.0.1 in dev and 0.0.0.0 otherwise)
WISP_DEVdev mode: on in debug builds, off in release
WISP_THREADSworker threads, one per CPU
WISP_BODY_LIMITlargest request body (512KB or 10MB, default 1 MB)
WISP_SECRETsigns cookies, at least 32 characters
WISP_SECRET_OLDthe previous secret, for rotation
ORIGINthe site's address, for a proxy that does not pass Host
WISP_CLIENT_IP_HEADERheader 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_ONIONon, off or auto: serve as a Tor onion service
WISP_MAX_CONNSopen 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_IOLinux: 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.

LimitValue
Headers16 KB, 100 headers
Too large a headover 16 KB or 100 headers: 431. A request line over 16 KB with no line end: 414
HTTP versionHTTP/2.0, HTTP/1.2 and the like: 505 (the server speaks 1.0 and 1.1)
JSON body200 000 values (keys counted) and 128 levels deep, else 400
Body1 MB (WISP_BODY_LIMIT or a route's BODY_LIMIT), checked against Content-Length first
Receive10 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 idle60 s
Client taking a response30 s
Out of descriptorsaccepting 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-Length with Transfer-Encoding is 400).
  • With WISP_ALLOWED_HOSTS set, a request with another Host, or with none (HTTP/1.0), is a 421. It holds on the native server and on the node, deno, bun and cloudflare targets. On cloudflare, the files of static/ come from Cloudflare and skip the check. The pages, vercel, netlify and azure hosts 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 uses wisp-build and the brotli crate (quality 11, a build dependency only). The request path reads accept-encoding only 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):

EntryWhat it is
wisp::prepare::<A>()runs init
wisp::handle::<A>(Request) -> Replyanswers 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 --staticruns handle for each page and writes files
wisp build --targetcompiles 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:

  • Data fields are in scope: ${count} for ${data.count}.
  • class:won=${data.won} toggles a class on the server.
  • <a ${href}> is href=${href}.
  • An Option attribute (aria-current=${current}) drops out when None.
  • #[derive(Json)] gives JSON without serde: return the value, or Response::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:

  1. Walks src/routes, builds the route table and rejects conflicts.
  2. Parses every .wisp file into a node list. Errors are file:line:col: msg.
  3. Scans +page.rs, +layout.rs, +server.rs, the blocks' items, src/hooks.rs and src/NAME.rs for fn load, #[action] functions, HTTP-method functions, hooks and const BODY_LIMIT, and reads each signature.
  4. 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:line comment, which wisp dev uses 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 one static in the binary. Answering is two copies and the date, and a matching if-none-match is 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?

View This Page's Source

Type to search every docs page and heading.