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.
  • Async client — choosing between Client, HTTP1Client and HTTP2Client; what a connection owns; what a call raises; what the BB_CLIENT_* defaults leave open.

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.