Lean synchronous web framework for latency critical applications
Verstappen is a synchronous HTTP/1.1 server for Linux, built to answer small requests with as little CPU as possible: one epoll reactor per CPU, each pinned to it, handlers that run inline on the reactor that read the request, and no allocation per request.
dotnet add package Verstappen
using Verstappen;
var app = new Max();
app.Get("/", static _ => { });
app.Get("/user/:id", static ctx => ctx.Write(ctx.RouteValue(0)));
app.Post("/user", static _ => { });
app.Run(3000);- Reactors. One thread per CPU the process may use (a container's cpuset counts), each pinned to its CPU, each with its own epoll set. A request is read, parsed, routed, handled and answered inside the event that brought it; the answers to a batch of pipelined requests leave in one send.
- Connections. By default the first reactor accepts and hands each connection to the reactors in
turn, so they share the load evenly.
ReusePort(a listener per reactor) andExclusive(one listener in every epoll set) are the alternatives. - Memory. Each connection has two native buffers, each with a head and a tail. The kernel writes at the ingress's tail, so a request that arrives in pieces is never copied, and requests are taken from its head; between reads the connection keeps where its current request stands (still reading the head, or reading the body of a head already parsed). Answers are written at the egress's tail and sent from its head, one send per batch; what a full socket does not take stays between the two. The 200 with an empty body is built once and copied.
- Syscalls. One recv and one send per request: sockets are edge-triggered, a short read means the socket is drained, and EPOLLOUT is registered once, so no epoll_ctl ever follows the accept. The calls on the request path skip the GC transition.
A handler is a RequestHandler: void (Context context). It runs on the reactor, so it must not
block: the reactor serves nothing else while it runs. The context is reused for every request on
that reactor, and the spans it hands out point into the reactor's buffers; copy what has to be kept.
| Request | Response |
|---|---|
Method, Path, Query, Body |
Status (200 unless set) |
RouteValue(index), RouteValue(name) |
Write(bytes), Write(text) |
TryGetHeader(name, out value) |
SetHeader(name, value), SetContentType(value) |
CloseConnection() |
Routes are path segments: literals, or parameters as :name or {name}. A literal wins over a
parameter in the same place, and the match backs off to the parameter when the literal leads
nowhere. A HEAD request runs the GET route without sending its body. An unknown path is 404, a known
path with another method 405 with an Allow header, an unknown method 501.
Requests are parsed by Glyph11's hardened parser,
in place: a native buffer goes to it as ReadOnlyMemory<byte> through an UnmanagedMemoryManager,
and the parsed request's fields are slices of that memory (Context.Request). Whatever it rejects
is answered with its status (400, 431, 505) and the connection closed: smuggling shapes, bare CR/LF,
obs-fold, invalid tokens or field values, dot segments, CONNECT, a missing or repeated Host
(HTTP/1.0 included). Chunked bodies are checked and decoded by Glyph11 too.
Verstappen adds keep-alive (HTTP/1.1, and HTTP/1.0 that asks for it), pipelining,
Expect: 100-continue and absolute-form targets. There is no Date header: the benchmark does not
ask for one, though RFC 9110 does. Limits: 16 KiB of request line and headers (431) and 1 MiB of
body (413), both in ServerOptions. A response body can be written as spans, or through the
context as an IBufferWriter<byte> over its native buffer, so a serializer such as
Utf8JsonWriter writes into it directly.
ServerOptions sets them in code; the environment overrides them when the server starts.
| Option | Environment | Default |
|---|---|---|
Reactors |
VERSTAPPEN_REACTORS |
one per allowed CPU |
Pin |
VERSTAPPEN_PIN |
on |
Accept |
VERSTAPPEN_ACCEPT (roundrobin, reuseport, exclusive) |
roundrobin |
SpinMicroseconds |
VERSTAPPEN_SPIN_US |
0 |
ServerHeader, MaxHeaderBytes, MaxBodyBytes, Backlog, MaxEvents |
none, 16 KiB, 1 MiB, 4096, 256 |
VERSTAPPEN_STATS=1 prints, once a second per reactor, its requests, waits, events and requests per
wait, and how often its thread slept.
Linux only. MIT.