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`)
circup install chumicro_http_server

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

# CPython
pip install chumicro-http-server

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

The hardware examples need wifi credentials to join your network. The library itself never reads TOML. It takes a transport_factory and goes, so bringing wifi up and handing the server a connected transport is application-layer work.

Contributing

Issues, bug reports, and pull requests are welcome, and so is "I ran it on this board and here's what happened", some of the most useful feedback a hardware project can get. Development happens in the ChuMicro repository, whose contributing guide covers setup and the test workflow.

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