Guides · the ordinary things still matter
Find the thing you expected a framework to have.
Start with the name you already use—middleware, forms, sessions, migrations, caching or webhooks—and follow it to the Wreath owner that makes the behavior explicit.
HTTP application basics#
| You are looking for | Start here | Public owner |
|---|---|---|
| application, lifespan and state | configuration and lifecycle | wreath.app, wreath.state, wreath.config |
| routes and routers | build an HTTP API | wreath.router, Wreath.route, Wreath.include_router |
| path, query, header and cookie inputs | build an HTTP API | wreath.binding |
| JSON, forms and file bodies | HTTP API, browser apps, objects | wreath.binding, wreath.objects |
| validation and problem responses | build an HTTP API | wreath.binding, wreath.validation_errors, wreath.exceptions |
| response classes and streaming | application reference | wreath.response |
| dependencies | application reference | wreath.binding.Depends |
| content negotiation | protocols | wreath.negotiation |
| OpenAPI and generated clients | build an HTTP API | wreath.openapi, wreath.typegen |
| API versions and pagination | application reference | wreath.versioning, wreath.pagination |
What other frameworks call middleware#
The standard stack is first-class HTTP policy, not a list of nested callables. That page covers proxy trust, hosts, maintenance, bot traffic, rate limits, request decompression, IDs, timing, CORS, CSRF, CSP/HSTS, WebSocket origins, sessions, idempotency, cache headers, compression, concurrency and deadlines. It also shows the custom hook protocol for behavior that is genuinely application-specific.
Browser-facing applications#
| Need | Guide or reference | Owner |
|---|---|---|
| safe server-rendered HTML | browser apps and assets | wreath.templates |
| static assets, ranges and validators | browser apps and assets | wreath.staticfiles |
| URL-encoded and multipart forms | browser apps and assets | wreath.binding.Form |
| uploads and resumable objects | objects and uploads | wreath.binding.File, wreath.objects |
| cookie or server-side sessions | policy, identity | wreath.policy.sessions, wreath.session_store |
| CORS, CSRF and browser headers | policy and hardening | wreath.policy |
Identity and multi-tenancy#
Identity and users starts with authentication and denial paths. The enterprise story carries the same principal through tenant resolution, Cedar authorization, SAML, OIDC, SCIM, quotas and support operations. The identity reference contains the complete users, organisations, tokens, sessions, second-factor, privacy and tenancy APIs.
Data and background work#
| Need | Guide | Owner |
|---|---|---|
| pools, models, queries and transactions | PostgreSQL and models | wreath.postgres, wreath.orm |
| migrations and schema generation | detect through rollback | wreath.migrations, wreath.schema |
| safe raw SQL | PostgreSQL and models | wreath.sql |
| temporal and analytical queries | time-series story | wreath.temporal, wreath.series |
| objects and uploads | objects and uploads | wreath.objects |
| live sockets and rooms | realtime and durable work | wreath.websocket, wreath.rooms |
| jobs, workflows and progress | realtime and durable work | wreath.jobs, wreath.workflows, wreath.progress |
| safe large-table maintenance | chunked passes | wreath.passes |
| retries and external effects | exactly-once effects | idempotency, jobs, webhooks |
Integration and protocol boundaries#
Integration boundaries covers outbound HTTP, service clients, verified inbound webhooks, durable outbound delivery, email and notifications. Protocols covers Protobuf, gRPC and GraphQL; MCP covers tools, resources, prompts, OAuth and agent-facing authorization.
Production and proof#
Deploy Wreath is the production runbook for extras, TLS, edge topology, worker sizing, graceful shutdown, service configuration and diagnosis. Operations covers health, readiness and observability. The command-line task map connects scaffolding, migrations, preflight, capture, replay, durable work and crash evidence. Testing and evidence covers the in-process client, WebSockets, the Wreath runner, mutation confidence, recording, replay and deterministic simulation. The operations reference holds logging, metrics, telemetry, hardening and diagnostic APIs.
The version and upgrade contract states exactly which Wreath release this site documents, the supported wheel matrix and how compatibility changes before 1.0.
If a conventional term is absent from this page, the complete surface map lists every subsystem, and the generated reference imports every documentable public module during the strict build.