How-to Guides

Status: Draft; implementation checked against the development source on 2026-09-08.

Task-focused recipes for the capabilities genro-asgi grows on top of the core. For troubleshooting and common choices, see the FAQ.

Each one assumes you have read Getting started and Core concepts.

The guides

  • Authentication — configure basic / bearer / JWT backends and API keys, protect routes with auth_rule, and work with the Avatar identity.

  • Sessions — arm the session subsystem, use the memory store and shutdown snapshot, control the session cookie, and attach an avatar at login.

  • OpenAPI & Swagger — turn @route methods into an OpenAPI 3.1 schema and a Swagger UI under the _meta prefix, direct or mounted.

  • MCP — expose routes as tools an AI agent can call over MCP Streamable HTTP, standalone or side-by-side with REST.

  • Background tasks — arm the task backbone, fire off fire-and-forget work, schedule interval/cron jobs, and manage them over HTTP.

  • Streaming & SSE — return chunked bodies with StreamingResponse and Server-Sent Events with SseStream.

  • Middleware — the built-in chain, its order and defaults, how to arm each stage, and how to register a custom middleware.

  • Configuration — write the recipe a server reads itself from, keep secrets out of it with resolvers, and read values back through the server and its applications.

  • The genro-asgi command — boot a server from a config.py or a single application, manage the named ones with apps/stop/remove, and reload on source changes.

  • Requests and errors — body decoding, uploads, validation and status codes.

  • Mounting applications — prefixes, root dispatch and hosted ASGI applications.

  • Lifecycle — startup hooks, admission state and bounded shutdown.

  • WebSockets — WSX messages, handshake rules and the raw socket seam.

  • Multiworker SPA — package boundary, hosted applications and global store.

How each guide is structured

Capability recipes use the following sections where applicable:

  1. What it does — the capability in one or two sentences.

  2. When to use it — the situation that calls for it.

  3. Setup — the constructor kwargs or base class you need in place.

  4. Minimal snippet — the smallest copy-pasteable example that works.

  5. How to verify it — a concrete check (a curl, a request, an observed effect) that proves it is working.

  6. Gotchas — the sharp edges worth knowing before you hit them.