freastal

A fast WSGI/ASGI server for Python, built as a C extension on top of libuv and picohttpparser. Optional TLS 1.3 via picotls.

Freastal (IPA: /ˈfʲɾʲasˠtəl/) is Irish Gaelic for "service."

Performance

Regenerate with bench/compare/run.sh, which runs every server in a Linux container under identical conditions and writes this table plus a JSON record. See bench/compare/README.md for the method.

500B response

12KB response

How to read this. between is the spread across the three interleaved rounds, within is wrk's own per-thread variation inside a run. Both are published because a median over scattered samples looks more precise than it is. At one worker every row above is cleanly separated. At four workers the middle of the pack is not: freastal ASGI, bjoern, and both TLS variants all land within a few percent of each other at 500B, and their per-round ranges overlap, so treat their ordering as unresolved rather than as shown.

These are comparative figures on one host over loopback, not absolute capacity. wrk saturates the server rather than holding a fixed rate, so the latency columns are queueing latencies under overload.

The application sets Content-Length explicitly and uvicorn is installed with its [standard] extras (uvloop + httptools). Both matter: without the header bjoern falls back to chunked encoding and collapses to ~1k rps, and without the extras uvicorn runs on plain asyncio and h11 at roughly a third of its real throughput. Benchmarking either misconfiguration would flatter freastal by a large factor.

Installation

Pre-built wheels for Linux (x86_64, aarch64) and macOS (arm64, x86_64) are available on PyPI:

pip install freastal

Building from source requires libuv ≥ 1.44, a C compiler, and (optionally) OpenSSL for TLS support. See Building from source.

Usage

WSGI

import freastal

def app(environ, start_response):
    body = b"Hello, world!"
    start_response("200 OK", [("Content-Type", "text/plain")])
    return [body]

freastal.serve(app, host="0.0.0.0", port=8000, workers=4)

ASGI

import freastal

async def app(scope, receive, send):
    await send({"type": "http.response.start", "status": 200,
                "headers": [[b"content-type", b"text/plain"]]})
    await send({"type": "http.response.body", "body": b"Hello, world!"})

freastal.serve_asgi(app, host="0.0.0.0", port=8000, workers=4)

TLS 1.3

freastal.serve(app, host="0.0.0.0", port=8000, workers=4,
               certfile="/path/to/cert.pem", keyfile="/path/to/key.pem")

TLS requires OpenSSL headers at build time. Wheels published to PyPI include TLS support.

Workers

workers=N starts N server processes. The listening socket is bound once, in the parent, and handed to every worker, so a bind failure is reported once from serve() rather than N times inside the workers.

Two things follow from that:

• The app must be picklable — in practice a module-level callable. The spawn start method (macOS's default, and what forkserver does too, which becomes Linux's default in 3.14) re-imports the child rather than inheriting it, so the app travels to the worker as a pickled argument.
• reuse_port is a tri-state. Unset (the default) enables SO_REUSEPORT only where it earns its keep: more than one worker, on a kernel that load-balances the group. True demands it and raises where it cannot be honoured. False never uses it, and the workers share one accept queue instead — which works everywhere.

SO_REUSEPORT load-balances TCP listeners on Linux, FreeBSD, DragonFly and Solaris. macOS accepts the option and then delivers every connection to a single socket in the group, which is why libuv refuses UV_TCP_REUSEPORT there and why reuse_port=True is an error rather than a no-op. Session resumption. Session tickets are on: a returning client skips the certificate signature, the most expensive part of the handshake. Tickets are good for 2 hours, and the key that seals them is rotated hourly and kept for three rotations, so a compromise of the server process exposes at most the last 3 hours of tickets rather than every ticket since boot. Resumption always re-runs (EC)DHE, so a stolen ticket key does not decrypt recorded traffic.

0-RTT early data is deliberately not enabled and is not configurable: early data is replayable by design, and a general-purpose WSGI/ASGI server cannot know whether an application's handlers are idempotent.

The ticket key is per worker process. With workers > 1 behind SO_REUSEPORT the kernel picks the worker, so a resuming client hits the one that issued its ticket roughly 1/workers of the time and otherwise falls back to a full handshake — the same handshake it would have done anyway. Sharing one key across workers needs an operator-supplied key rotated out of band; freastal has no interface for that yet.

Architecture

• libuv — cross-platform event loop; io_uring-ready on Linux (libuv ≥ 1.45 batches syscalls automatically)
• picohttpparser — SSE4.2/NEON SIMD HTTP/1.1 parser from the h2o project; vendored
• picotls — TLS 1.3 library from the h2o project; vendored, gated by FREASTAL_TLS. The vendored tree is upstream at a pinned commit plus the patches in vendor/patches/, rebuilt by scripts/vendor_picotls.sh
• Single uv_write per response — headers and body sent together, no extra copy
• HTTP/1.1 keep-alive: connections re-armed in-place without close/reopen; TCP_NODELAY set on every accepted socket
• Slab allocator for per-connection state — no per-request malloc on the hot path
• Pre-interned Python strings for all WSGI/ASGI environ keys
• GIL released for the duration of the libuv event loop; acquired only when calling the WSGI/ASGI application and touching Python response objects
• SO_REUSEPORT (UV_TCP_REUSEPORT) for kernel-level load balancing across worker processes, where the kernel supports it

Multi-process model: workers=N starts N independent OS processes, each with its own libuv loop and Python interpreter (and therefore its own GIL). Where SO_REUSEPORT load-balances, each worker gets its own accept queue; elsewhere the workers share the single listening socket the parent bound. See Workers.

ASGI event loop bridge (libuv ↔ asyncio):

freastal runs asyncio inside the libuv event loop rather than the other way around. A uv_check_t steps asyncio after each I/O poll; a uv_poll_t on asyncio's selector fd wakes libuv when external async I/O (database calls, aiohttp, etc.) completes.

Building from source

# macOS
brew install libuv openssl@3
pip install freastal --no-binary freastal

# Debian/Ubuntu
apt-get install libuv1-dev libssl-dev
pip install freastal --no-binary freastal

picohttpparser and picotls are vendored — no extra steps required.

Requirements

• Python ≥ 3.10
• Linux or macOS
• libuv ≥ 1.44 (shared library, found via pkg-config or standard include paths)
• OpenSSL (optional, for TLS 1.3)

License

MIT