chumicro-http-server-experimental 0.18.0

Non-blocking HTTP/1.1 server for CircuitPython, MicroPython, and CPython.

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

Symbol	Purpose
HttpServer	Runner-shaped HTTP/1.1 server; check(now_ms) / handle(now_ms).
Request	Per-request value object: method, path, query, headers, body, json(), text().
Response	Outbound response: status_code, reason, headers, body.
build_response(status, *, body, json, text, html, headers)	Convenience builder with sensible Content-Type defaults.
streaming.build_streaming_response(status, *, source, content_length, headers)	Opt-in chumicro_http_server.streaming submodule — serve a body larger than the heap from a fill-a-buffer source(buffer) -> int (Content-Length or chunked framing, fixed staging window).
RequestParser	Streaming request parser (request line + headers + Content-Length body).
parse_query / split_target	URL helpers.
ServerError + subclasses	Typed exception hierarchy, independent of chumicro_requests so the server can ship without the client library.

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:

Runtime + board	TLS server status	Notes
CircuitPython on ESP32-S2 (Lolin S2)	✅ Works	Bench-tested ~5 KB context (RSA-2048); each connection adds tens of KB during handshake — leave headroom.
CircuitPython on rp2 (Pi Pico W / Pi Pico 2 W)	❌ Refused (UnsupportedSSLConfigError)	chumicro_sockets.listener(tls=True) raises up-front; the underlying CYW43 TLS path raises OSError(32) mid-handshake AND wedges the chip's station-mode state. Use ESP32-family or MicroPython on rp2.
MicroPython on ESP32-S2	✅ Works	Hardware-accelerated handshake; ~1 KB heap.
MicroPython on rp2 (Pi Pico W)	✅ Works (RSA-2048 only)	DER-encoded key; ~25 KB handshake heap; ECC keys fail at context build.

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

Example	What it shows
simple_server.py	Single-board HTTP server with GET /, GET /api/uptime, POST /api/echo routes. Drive it with curl from your laptop. Cross-runtime (CP + MP) — runtime marker on the file gates hardware-only deploys. For a two-physical-board demo see the workspace template's two_board_handshake/ example.

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