chumicro-http-server

A non-blocking HTTP/1.1 server with @route — serve requests while your LED keeps blinking.

Routing with @server.route (method dispatch, path parameters), bounded multi-connection, per-tick byte budgets, and a streaming request parser — all without blocking your main loop. Serves TLS on every supported board pair except CircuitPython on RP2040 (CYW43 substrate limitation; documented inline). Self-contained — no chumicro-requests dependency on the device.

Part of the ChuMicro family — small, focused Python libraries for microcontrollers and laptops. Browse all libraries.

Install

# CircuitPython (after `circup bundle-add ChuMicro/ChuMicro-Bundle-Experimental`)
circup install chumicro_http_server

# MicroPython
mpremote mip install github:ChuMicro/ChuMicro-Bundle-Experimental/chumicro_http_server

# CPython
pip install chumicro-http-server-experimental

For bundle setup, pre-compiled .mpy bundles, the experimental channel, and details on PyPI naming, see the chumicro INSTALL guide.

Quick example

from chumicro_http_server import HttpServer, build_response
from chumicro_sockets import listener
from chumicro_timing import ticks_ms

server = HttpServer(
    transport_factory=lambda: listener(host="0.0.0.0", port=8080),
)

@server.route("/")
def index(request):
    return build_response(200, html="<h1>Hello from a Pi Pico W</h1>")

@server.route("/sensor", methods=["POST"])
def sensor(request):
    payload = request.json()
    return build_response(201, json={"ok": True})

@server.route("/widgets/<id>")
def widget(request):
    return build_response(200, json={"id": request.path_params["id"]})

while True:
    if server.check(ticks_ms()):
        server.handle(ticks_ms())

What's included

Each request is served on a fresh accepted socket and Connection: close is added to every response — HTTP/1.1 keep-alive and connection pooling are not supported. Chunked request bodies are not supported either; use Content-Length.

Need to return a body bigger than the heap — a log dump, a file, a long export? Return a streaming response from the opt-in chumicro_http_server.streaming submodule and the server drains it from a fill-a-buffer source one small window at a time, choosing Content-Length or chunked framing for you:

from chumicro_http_server.streaming import build_streaming_response, SOURCE_EOF

@server.route("/log")
def log_dump(request):
    def source(buffer):
        n = read_next_block_into(buffer)   # your storage read; 0 <= n <= len(buffer)
        return n if n else SOURCE_EOF      # -1 signals end of body
    return build_streaming_response(200, source=source)

See the user guide for the source contract, framing rules, fairness, and staging-window sizing.

Where this fits

Depends on chumicro-sockets (TCP listener) and chumicro-timing (ticks). Pairs with chumicro-websockets for combined HTTP + WS deployments. Self-contained otherwise — the shared HTTP/1.1 primitives (case-insensitive header dict, charset parsing) are inlined locally, so a server-only board never ships chumicro-requests.

Platform support

Works on CPython, MicroPython, and CircuitPython. Pure Python — no native extensions.

TLS server (HTTPS)

chumicro-http-server itself is transport-agnostic — pass a TLS-wrapped listener from chumicro_sockets.ssl_context_with_cert_and_key_paths into transport_factory and the same HttpServer runs HTTPS. Live verification across the supported board matrix:

Why the CP-on-rp2 row? The CYW43 stack's TLS server path raises OSError(32) mid-handshake and wedges the chip's station state until a USB power-cycle. No upstream fix is in flight; for HTTPS server work on rp2, use MicroPython.

The TLS handshake is synchronous inside wrap_socket(..., server_side=True): the listener stalls until it completes — single-digit to tens of milliseconds on the supported board class with a local TLS client, longer on a slow uplink as TLS rounds-trip. Once the handshake completes, the per-connection state machine resumes its runner-shaped, LED-blink-friendly progression.

Examples

Wiring wifi credentials for examples and functional tests

The hardware-prefixed examples + real-network suites in functional_tests/test_real_*.py need wifi credentials. See docs/wiring-wifi-credentials.md for the workspace-based and raw single-file paths. The library itself never reads TOML — it takes a transport_factory and goes; config wiring is application-layer.

Contributing

Working on chumicro-http-server itself? Clone the mono-repo if you haven't already — the rest of the workflow assumes you're inside that workspace.

pip install -e .[test]
pytest tests/                  # host-side tests
pytest functional_tests/       # on-device tests (needs a board registered in devices.yml)

Register a board before running functional tests: chumicro-workspace add-device <id> --address <port>.

Docs

📖 Stable docs · Experimental docs

Find this library

• PyPI: chumicro-http-server
• Bundle: ChuMicro-Bundle (CircuitPython & MicroPython)
• Experimental bundle: ChuMicro-Bundle-Experimental
• Source: libraries/http_server

License

MIT