Guide

The Guide covers everything you'd build a BlackBull app with — routing, middleware, request/response handling, WebSockets, HTTP/2, error handling, configuration, and more.

If you're new, read Getting Started first — it covers installation and the shape of a minimal app.

Topics

• Routing — @app.route, path parameters (string, regex, typed), route groups, WebSocket route registration.
• Middleware — writing middleware, @as_middleware, attaching to routes, built-in middleware (websocket, Compression, Session, Cache, CORS, StaticFiles), common recipes.
• Error handling — @app.on_error, the DEV-mode traceback page, PROD-mode terse responses.
• Requests and responses — reading the body and headers, cookies, query parameters, forms; Response / JSONResponse / StreamingResponse; detecting client disconnection.
• WebSockets — the WebSocket route, the websocket middleware, permessage-deflate, RFC 8441 (WebSocket over HTTP/2), subprotocols, fragmented messages.
• HTTP/2 — ALPN, priority hints, http.response.push, flow control, h2c.
• Events — @app.on (observation) and @app.intercept (interception) for lifecycle hooks.
• Logging — access log, framework log, @log decorator, forwarding logs to a remote server.
• Static files — app.static, in-memory cache, range requests, production passthrough.
• Configuration — environment variables, TOML config file, CLI flags, precedence.
• OpenAPI — app.enable_openapi, Swagger UI, dataclass schemas, body deserialization.
• Testing — BlackBull's clients on an ephemeral port, httpx.ASGITransport, direct handler tests.

Deploying

Once you have something working, the Deployment chapter covers running it under multiple workers, behind nginx, with TLS, on an AF_UNIX socket, with systemd socket activation, and with hot-reload during development.

Reference

• Environment variables — the full BB_* table.
• API reference (auto-generated from source) — see the API section in the navigation.