Skip to content

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, 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.
  • Dependency injection — Depends providers for simplified handlers: per-request resources with teardown after the response is sent.
  • 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.
  • Edge inference serving — the one-process shape for serving a local model: SSE token streaming over HTTP/2 beside MQTT device ingest and a $share work queue.
  • 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.