Replace HTTP/2 server push with dependency injection in backlog

HTTP/2 server push was removed from the spec and dropped by browsers.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.claude/commands/release.md

@@ -0,0 +1,42 @@
+Release a new version of responder to PyPI and GitHub.
+
+Usage: /release <version> (e.g. /release 3.6.0)
+
+If no version is provided, ask the user what version to release.
+
+## Steps
+
+1. **Verify clean state**: Run `git status` and ensure the working tree is clean. If not, stop and ask the user.
+
+2. **Run tests**: Run `uv run pytest -x --no-header -q`. If any fail, stop and report.
+
+3. **Bump version**: Update `responder/__version__.py` to the new version.
+
+4. **Update changelog**:
+   - Run `git log --oneline $(git describe --tags --abbrev=0)..HEAD` to get commits since last release.
+   - Add a new section in `CHANGELOG.md` under `## [Unreleased]` with the date, categorized into Added/Changed/Fixed/Removed.
+   - Update the compare links at the bottom of the file.
+
+5. **Lock deps**: Run `uv lock`.
+
+6. **Commit**: Stage `responder/__version__.py`, `CHANGELOG.md`, and `uv.lock`. Commit with message `Bump version to X.Y.Z and update changelog`.
+
+7. **Push and tag**:
+   ```
+   git push
+   git tag vX.Y.Z
+   git push origin vX.Y.Z
+   ```
+
+8. **GitHub release**: Create a release with `gh release create` including highlights and a link to the full changelog.
+
+9. **Build and publish**:
+   ```
+   uv build
+   uvx twine upload dist/responder-X.Y.Z*
+   ```
+   Note: This requires a PyPI token. If twine fails due to auth, tell the user to set `TWINE_USERNAME=__token__` and `TWINE_PASSWORD` and re-run, or run `! uvx twine upload dist/responder-X.Y.Z*` interactively.
+
+10. **Update GitHub release**: Edit the release to add a link to the PyPI page: `https://pypi.org/project/responder/X.Y.Z/`
+
+11. **Report**: Print a summary with links to the GitHub release and PyPI page.

.gitignore

@@ -8,6 +8,7 @@
 .DS_Store
 coverage.xml
 .coverage*
+*.lock
 
 __pycache__
 tests/__pycache__

CHANGELOG.md

@@ -5,8 +5,6 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and
 this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
-
 ## [v3.5.0] - 2026-03-24
 
 ### Added
@@ -14,7 +12,6 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 - CI validation for Python 3.14, 3.14 free-threaded, and PyPy 3.11
 - Marimo notebook mounting docs and example
 - Type annotations for `routes.py`
-- `uv.lock` for reproducible installs
 
 ### Changed
 
@@ -462,7 +459,6 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 - Conception!
 
-[unreleased]: https://github.com/kennethreitz/responder/compare/v3.5.0..HEAD
 [v3.5.0]: https://github.com/kennethreitz/responder/compare/v3.4.0..v3.5.0
 [v3.4.0]: https://github.com/kennethreitz/responder/compare/v3.3.0..v3.4.0
 [v3.3.0]: https://github.com/kennethreitz/responder/compare/v3.2.0..v3.3.0

CLAUDE.md

@@ -0,0 +1,44 @@
+# Responder
+
+A familiar HTTP Service Framework for Python, by Kenneth Reitz.
+
+## Commands
+
+- **Tests**: `uv run pytest` (runs full suite with coverage)
+- **Single test**: `uv run pytest tests/test_responder.py::test_name -xvs`
+- **Lint**: `uv run ruff check .`
+- **Type check**: `uv run mypy`
+- **Build docs**: `cd docs && uv run make html`
+- **Build package**: `uv build`
+- **Lock deps**: `uv lock`
+
+## Architecture
+
+- `responder/api.py` — Main `API` class, the entry point for all apps
+- `responder/routes.py` — `Router`, `Route`, `WebSocketRoute` dispatch
+- `responder/models.py` — `Request` and `Response` wrappers around Starlette
+- `responder/ext/` — Extensions: CLI, GraphQL, OpenAPI, rate limiting
+- `responder/background.py` — Background task queue
+- `responder/formats.py` — Content negotiation (JSON, YAML, msgpack)
+- `responder/__version__.py` — Single source of truth for version string
+
+## Conventions
+
+- Python 3.10+ only. Use `from __future__ import annotations` where present.
+- Use `inspect.iscoroutinefunction` (not `asyncio.iscoroutinefunction`).
+- Tests use `api.requests` (Starlette TestClient) with `allowed_hosts=[";"]` or `["localhost"]`.
+- Werkzeug 3.1.7+ rejects invalid Host headers — use `localhost` when mounting WSGI apps in tests.
+- Version is in `responder/__version__.py`, bump it there.
+- Changelog follows [Keep a Changelog](https://keepachangelog.com/) format in `CHANGELOG.md`.
+- Compare links at the bottom of CHANGELOG.md must be updated when adding a release.
+- All deps managed via `uv`. Lock file (`uv.lock`) is not committed.
+
+## Release Process
+
+1. Bump version in `responder/__version__.py`
+2. Add changelog entry in `CHANGELOG.md` (update compare links too)
+3. `uv lock` to refresh the lock file
+4. Commit: `Bump version to X.Y.Z and update changelog`
+5. `git tag vX.Y.Z && git push && git push origin vX.Y.Z`
+6. `gh release create vX.Y.Z --title "vX.Y.Z" --notes "..."`
+7. `uv build && uvx twine upload dist/responder-X.Y.Z*`

docs/source/_templates/sidebarintro.html

@@ -5,6 +5,8 @@
 </p>
 <p>
   <strong>Responder</strong> — a familiar HTTP service framework for Python.
+  <br />
+  <small>v{{ version }}</small>
 </p>
 <h3>Useful Links</h3>
 <ul>

docs/source/api.rst

@@ -12,6 +12,20 @@ The central object of every Responder application. It holds your routes,
 middleware, templates, and configuration. Create one at the top of your
 module and use it to define your entire web service.
 
+Quick example::
+
+    import responder
+
+    api = responder.API(
+        title="My Service",           # OpenAPI title
+        version="1.0",                # OpenAPI version
+        openapi="3.0.2",              # enable OpenAPI
+        docs_route="/docs",           # Swagger UI at /docs
+        cors=True,                    # enable CORS
+        secret_key="change-me",       # session signing key
+        allowed_hosts=["example.com"],
+    )
+
 .. module:: responder
 
 .. autoclass:: API
@@ -28,6 +42,27 @@ parameters, the request body, cookies, and more.
 Most properties are synchronous, but reading the body requires ``await``
 because it involves I/O.
 
+Common patterns::
+
+    # Headers (case-insensitive)
+    token = req.headers.get("Authorization")
+
+    # Query parameters: /search?q=python&page=2
+    query = req.params["q"]
+
+    # JSON body
+    data = await req.media()
+
+    # Form data
+    form = await req.media("form")
+
+    # File uploads
+    files = await req.media("files")
+
+    # Client info
+    ip, port = req.client
+    is_https = req.is_secure
+
 .. autoclass:: Request
     :inherited-members:
 
@@ -39,6 +74,19 @@ The response object is passed into every view as the second argument.
 Mutate it to control what gets sent back to the client — the body,
 status code, headers, and cookies.
 
+Common patterns::
+
+    resp.text = "plain text"            # text/plain
+    resp.html = "<h1>Hello</h1>"        # text/html
+    resp.media = {"key": "value"}       # application/json
+    resp.content = b"raw bytes"         # application/octet-stream
+    resp.file("path/to/file.pdf")       # auto content-type
+    resp.stream_file("large/export.csv") # streamed
+
+    resp.status_code = 201
+    resp.headers["X-Custom"] = "value"
+    resp.cookies["session"] = "abc123"
+
 .. autoclass:: Response
     :inherited-members:
 
@@ -47,7 +95,13 @@ Route Groups
 ------------
 
 Group related routes under a shared URL prefix — useful for API versioning
-and organizing large applications.
+and organizing large applications::
+
+    v1 = api.group("/v1")
+
+    @v1.route("/users")
+    def list_users(req, resp):
+        resp.media = []
 
 .. autoclass:: responder.api.RouteGroup
     :members:
@@ -57,7 +111,19 @@ Background Queue
 ----------------
 
 Run tasks in background threads without blocking the response. Available
-as ``api.background``.
+as ``api.background``::
+
+    @api.route("/submit")
+    async def submit(req, resp):
+        data = await req.media()
+
+        @api.background.task
+        def process(data):
+            # runs in a thread pool
+            ...
+
+        process(data)
+        resp.media = {"status": "accepted"}
 
 .. autoclass:: responder.background.BackgroundQueue
     :members:
@@ -67,6 +133,8 @@ Query Dict
 ----------
 
 A dictionary subclass for query string parameters with multi-value support.
+Behaves like a normal dict for single values, but supports ``getlist()``
+for parameters that appear multiple times (e.g. ``?tag=a&tag=b``).
 
 .. autoclass:: responder.models.QueryDict
     :members:
@@ -76,7 +144,15 @@ Rate Limiter
 ------------
 
 In-memory token bucket rate limiter. Limits requests per client IP address
-and returns ``429 Too Many Requests`` when exceeded.
+and returns ``429 Too Many Requests`` when exceeded::
+
+    from responder.ext.ratelimit import RateLimiter
+
+    limiter = RateLimiter(requests=100, period=60)  # 100 req/min
+    limiter.install(api)
+
+Response headers: ``X-RateLimit-Limit``, ``X-RateLimit-Remaining``,
+and ``Retry-After`` (when limited).
 
 .. autoclass:: responder.ext.ratelimit.RateLimiter
     :members:
@@ -86,7 +162,14 @@ Status Code Helpers
 -------------------
 
 Convenience functions for checking which category a status code falls
-into. Useful in middleware and after-request hooks.
+into. Useful in middleware and after-request hooks::
+
+    from responder.status_codes import is_200, is_400, is_500
+
+    @api.after_request()
+    def log_errors(req, resp):
+        if is_400(resp.status_code) or is_500(resp.status_code):
+            print(f"Error: {req.method} {req.url.path} -> {resp.status_code}")
 
 .. autofunction:: responder.status_codes.is_100
 

docs/source/backlog.md

@@ -1,7 +1,8 @@
 # Backlog
 
 ## Future Ideas
-- Consider adding `after_request` hooks (complement to `before_request`)
-- Explore WebSocket before_request short-circuit support
-- Add rate limiting middleware
-- Consider async template rendering by default
+- WebSocket before_request short-circuit support (reject before accept)
+- Per-route rate limiting (different limits for different endpoints)
+- Built-in structured logging with request context
+- OpenAPI 3.1 support
+- Dependency injection for route handlers

docs/source/cli.rst

@@ -71,6 +71,25 @@ For URLs, use a fragment::
     $ responder run https://example.com/app.py#service
 
 
+Environment Variables
+---------------------
+
+Responder automatically reads the ``PORT`` environment variable at
+runtime:
+
+- ``PORT`` — bind to ``0.0.0.0`` on this port (cloud platform convention)
+
+When ``PORT`` is set, the server binds to all interfaces automatically.
+This is how cloud platforms like Fly.io, Railway, and Heroku inject the
+listen port.
+
+For other settings like ``SECRET_KEY``, read them in your application
+code and pass them to ``responder.API()``::
+
+    import os
+    api = responder.API(secret_key=os.environ["SECRET_KEY"])
+
+
 Building Frontend Assets
 -------------------------
 

docs/source/deployment.rst

@@ -30,8 +30,9 @@ Here's a minimal Dockerfile::
 
     FROM python:3.13-slim
     WORKDIR /app
+    COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
     COPY . .
-    RUN pip install responder
+    RUN uv pip install --system responder
     ENV PORT=80
     EXPOSE 80
     CMD ["python", "api.py"]
@@ -42,9 +43,10 @@ Build and run::
     $ docker run -p 8000:80 myapi
 
 The ``python:3.13-slim`` image is about 150MB — small enough for fast
-deploys but includes everything you need. For even smaller images, you
-can use ``python:3.13-alpine``, though some packages may need extra
-build dependencies.
+deploys but includes everything you need. Using ``uv`` for installs
+is significantly faster than pip. For even smaller images, you can use
+``python:3.13-alpine``, though some packages may need extra build
+dependencies.
 
 
 Cloud Platforms
@@ -67,6 +69,27 @@ The pattern is always the same: deploy your code, set the start command
 to ``python api.py``, and the platform handles the rest.
 
 
+Health Check Endpoint
+---------------------
+
+Every production deployment needs a health check — a lightweight endpoint
+that monitoring tools, load balancers, and orchestrators can poll to verify
+your service is running::
+
+    @api.route("/health")
+    def health(req, resp):
+        resp.media = {"status": "healthy"}
+
+Keep it simple. Don't query the database or do expensive work — the health
+check should return instantly. Cloud platforms, Docker, and Kubernetes all
+look for an HTTP 200 to confirm your service is alive.
+
+For Docker, add a ``HEALTHCHECK`` instruction::
+
+    HEALTHCHECK --interval=30s --timeout=3s \
+        CMD curl -f http://localhost/health || exit 1
+
+
 Uvicorn Directly
 ----------------
 
@@ -82,6 +105,45 @@ Uvicorn supports many options — SSL certificates, access logging, graceful
 shutdown timeouts, and more. See the
 `uvicorn documentation <https://www.uvicorn.org/deployment/>`_ for details.
 
+For platforms like Heroku or Railway that use a ``Procfile``::
+
+    web: uvicorn api:api --host 0.0.0.0 --port $PORT --workers 4
+
+
+Docker Compose
+--------------
+
+For local development with databases and other services, Docker Compose
+ties everything together::
+
+    # docker-compose.yml
+    services:
+      api:
+        build: .
+        ports:
+          - "5042:80"
+        environment:
+          - PORT=80
+          - DATABASE_URL=postgresql+asyncpg://user:pass@db/myapp
+          - SECRET_KEY=dev-secret
+        depends_on:
+          - db
+
+      db:
+        image: docker.io/postgres:16-alpine
+        environment:
+          POSTGRES_USER: user
+          POSTGRES_PASSWORD: pass
+          POSTGRES_DB: myapp
+        volumes:
+          - pgdata:/var/lib/postgresql/data
+
+    volumes:
+      pgdata:
+
+Run with ``docker compose up``. The API waits for ``db`` to start, then
+connects using the ``DATABASE_URL`` environment variable.
+
 
 Reverse Proxy
 -------------
@@ -95,9 +157,31 @@ front of your application for:
 - **Static asset serving** — offload static files to the proxy
 - **Rate limiting** — at the infrastructure level
 
+A minimal Caddy config that handles HTTPS automatically::
+
+    # Caddyfile
+    example.com {
+        reverse_proxy localhost:5042
+    }
+
 Responder's ``TrustedHostMiddleware`` and ``HTTPSRedirectMiddleware`` work
 correctly behind proxies that set standard forwarding headers
 (``X-Forwarded-For``, ``X-Forwarded-Proto``).
 
 That said, uvicorn is production-ready on its own. Many applications run
 uvicorn directly without a reverse proxy and do just fine.
+
+
+Production Checklist
+--------------------
+
+Before going live:
+
+- **Set a secret key** — ``SECRET_KEY`` env var, never the default
+- **Disable debug mode** — ``DEBUG=false`` or omit it entirely
+- **Set allowed hosts** — restrict to your actual domain names
+- **Use multiple workers** — ``--workers 4`` or more, depending on CPU cores
+- **Add a health check** — ``/health`` endpoint for monitoring
+- **Enable HTTPS** — via your proxy, cloud platform, or uvicorn's ``--ssl-*`` flags
+- **Set up logging** — uvicorn logs requests by default; pipe them to your log aggregator
+- **Pin your dependencies** — use a lock file or pinned requirements for reproducible deploys

docs/source/index.rst

@@ -59,21 +59,25 @@ What You Get
 
 One ``pip install``, batteries included:
 
+- Pydantic request validation and response serialization.
 - Mount Flask, Django, or any WSGI/ASGI app at a subroute.
 - Gzip compression, HSTS, CORS, and trusted host validation.
-- Before-request hooks that can short-circuit for auth guards.
+- Before-request and after-request hooks for auth and logging.
 - A test client for fast, in-process testing with pytest.
 - Route parameters with f-string syntax and type convertors.
 - Lifespan context managers for startup and shutdown logic.
 - Custom exception handlers for clean error responses.
 - `GraphQL`_ with Graphene and a built-in GraphiQL IDE.
+- Server-Sent Events for real-time streaming.
 - File serving with automatic content-type detection.
 - Sync and async views — ``async`` is always optional.
 - Class-based views with ``on_get``, ``on_post``, ``on_request``.
+- Built-in rate limiting with ``X-RateLimit`` headers.
+- Content negotiation: JSON, YAML, and MessagePack.
 - A pleasant API with a single import statement.
 - OpenAPI schema generation with Swagger UI.
 - A production `uvicorn`_ server, ready to deploy.
-- HTTP method filtering for REST APIs.
+- Route groups for API versioning.
 - Signed cookie-based sessions.
 - Background tasks in a thread pool.
 - WebSocket support.

docs/source/quickstart.rst

@@ -376,3 +376,9 @@ jump into the tutorials:
 - :doc:`tutorial-rest` — build a full CRUD API with validation
 - :doc:`tutorial-sqlalchemy` — connect to a database
 - :doc:`tutorial-auth` — add authentication
+- :doc:`tutorial-websockets` — real-time communication
+- :doc:`tutorial-middleware` — hooks and middleware
+- :doc:`tutorial-flask` — migrating from Flask
+- :doc:`guide-config` — environment variables and secrets
+- :doc:`deployment` — Docker, cloud platforms, and production
+- :doc:`testing` — writing tests with pytest

docs/source/sandbox.md

@@ -2,35 +2,61 @@
 # Development Sandbox
 
 ## Setup
-Set up a development sandbox.
 
-Acquire sources and create virtualenv.
+Clone the repo and install all dependencies:
 ```shell
 git clone https://github.com/kennethreitz/responder.git
 cd responder
-uv venv
-```
-
-Install project in editable mode, including
-all development tools.
-```shell
+uv venv && source .venv/bin/activate
 uv pip install --upgrade --editable '.[develop,docs,release,test]'
 ```
 
-## Operations
-Run tests.
+## Running Tests
 ```shell
-source .venv/bin/activate
-pytest
+pytest                                  # full suite with coverage
+pytest tests/test_responder.py -xvs     # single file, stop on first failure
+pytest -k "test_mount"                  # run tests matching a pattern
 ```
 
-Format code.
+## Code Formatting
 ```shell
-ruff format .
-ruff check --fix .
+ruff format .        # auto-format
+ruff check --fix .   # lint and auto-fix
 ```
 
-Documentation authoring.
+## Type Checking
 ```shell
-sphinx-autobuild --open-browser --watch docs/source docs/source docs/build
+mypy
+```
+
+## Documentation
+
+Live-reloading doc server (opens in browser):
+```shell
+cd docs
+sphinx-autobuild --open-browser --watch source source build
+```
+
+Or build once:
+```shell
+cd docs
+make html
+# open build/html/index.html
+```
+
+## Project Layout
+
+```
+responder/
+├── responder/          # main package
+│   ├── api.py          # API class — the entry point
+│   ├── routes.py       # Router, Route, WebSocketRoute
+│   ├── models.py       # Request and Response wrappers
+│   ├── ext/            # extensions (CLI, GraphQL, OpenAPI, rate limiting)
+│   ├── background.py   # background task queue
+│   └── formats.py      # content negotiation (JSON, YAML, msgpack)
+├── tests/              # pytest test suite
+├── examples/           # runnable example apps
+├── docs/source/        # Sphinx documentation
+└── pyproject.toml      # project metadata and tool config
 ```

docs/source/testing.rst

@@ -269,6 +269,57 @@ just like in production. You can verify their effects on the response::
         assert r.headers["X-Served-By"] == "responder"
 
 
+Testing Rate Limiting
+---------------------
+
+Rate limiters are just hooks — they run automatically during tests.
+Verify the headers and the 429 response::
+
+    from responder.ext.ratelimit import RateLimiter
+
+    def test_rate_limiting():
+        api = responder.API(allowed_hosts=["localhost"])
+        limiter = RateLimiter(requests=2, period=60)
+        limiter.install(api)
+
+        @api.route("/")
+        def view(req, resp):
+            resp.text = "ok"
+
+        # First two requests succeed
+        for _ in range(2):
+            r = api.requests.get("http://localhost/")
+            assert r.status_code == 200
+            assert "X-RateLimit-Remaining" in r.headers
+
+        # Third request is rate limited
+        r = api.requests.get("http://localhost/")
+        assert r.status_code == 429
+
+
+Testing Mounted Apps
+--------------------
+
+When testing WSGI apps mounted at a subroute, use ``localhost`` as the
+host to avoid Werkzeug's trusted host validation::
+
+    from flask import Flask
+
+    def test_flask_mount():
+        api = responder.API(allowed_hosts=["localhost"])
+
+        flask_app = Flask(__name__)
+        @flask_app.route("/")
+        def hello():
+            return "Hello from Flask!"
+
+        api.mount("/flask", flask_app)
+
+        r = api.requests.get("http://localhost/flask")
+        assert r.status_code == 200
+        assert "Hello from Flask" in r.text
+
+
 Tips
 ----
 
@@ -284,3 +335,6 @@ Tips
 
 - **Test the contract, not the implementation.** Assert on status codes,
   response bodies, and headers — not on internal state.
+
+- **Use ``localhost`` for mounted WSGI apps.** Werkzeug 3.1.7+ validates
+  the ``Host`` header, so avoid synthetic hosts like ``;`` in tests.

docs/source/tour.rst

@@ -596,6 +596,73 @@ can pace themselves.
 The rate limiter is per-client, keyed by IP address.
 
 
+Pydantic Validation
+-------------------
+
+`Pydantic <https://docs.pydantic.dev/>`_ models integrate directly with
+Responder's routing. Set ``request_model`` to validate incoming data and
+``response_model`` to control the shape of outgoing data::
+
+    from pydantic import BaseModel
+
+    class ItemIn(BaseModel):
+        name: str
+        price: float
+
+    class ItemOut(BaseModel):
+        id: int
+        name: str
+        price: float
+
+    @api.route("/items", methods=["POST"],
+               request_model=ItemIn, response_model=ItemOut)
+    async def create_item(req, resp):
+        data = await req.media()
+        resp.media = {"id": 1, **data}
+
+When ``request_model`` is set:
+
+- Valid requests are parsed and the data is available via ``await req.media()``
+- Invalid requests get an automatic ``422 Unprocessable Entity`` response
+  with detailed error messages — you don't write any validation code
+
+When ``response_model`` is set:
+
+- The response is serialized through the model before being sent
+- Extra fields are stripped automatically
+- Type coercion happens at the boundary
+
+This is the recommended way to build validated REST APIs with Responder.
+See the :doc:`tutorial-rest` for a complete walkthrough.
+
+
+Content Negotiation
+-------------------
+
+Responder automatically negotiates the response format based on the
+client's ``Accept`` header. Set ``resp.media`` to a Python object and
+the right thing happens:
+
+- ``Accept: application/json`` (default) → JSON
+- ``Accept: application/x-yaml`` → YAML
+- ``Accept: application/x-msgpack`` → MessagePack
+
+This means a single endpoint serves multiple formats without any
+conditional logic in your code::
+
+    @api.route("/data")
+    def data(req, resp):
+        resp.media = {"key": "value"}
+
+Clients get the format they ask for::
+
+    $ curl http://localhost:5042/data
+    {"key": "value"}
+
+    $ curl -H "Accept: application/x-yaml" http://localhost:5042/data
+    key: value
+
+
 MessagePack
 -----------
 
@@ -608,6 +675,10 @@ Responder supports MessagePack alongside JSON and YAML::
     # Decode a MessagePack request body
     data = await req.media("msgpack")
 
-Content negotiation works too — clients can send
+    # Respond with MessagePack
+    resp.media = {"result": [1, 2, 3]}
+
+Content negotiation works automatically — clients can send
 ``Accept: application/x-msgpack`` to receive MessagePack responses
-instead of JSON.
+instead of JSON. You can also explicitly decode MessagePack request
+bodies by passing ``"msgpack"`` to ``req.media()``.

docs/source/tutorial-auth.rst

@@ -46,14 +46,14 @@ Install PyJWT::
 Create a helper to encode and decode tokens::
 
     import jwt
-    from datetime import datetime, timedelta
+    from datetime import datetime, timedelta, timezone
 
     SECRET = "your-secret-key"
 
     def create_token(user_id: int) -> str:
         payload = {
             "sub": user_id,
-            "exp": datetime.utcnow() + timedelta(hours=24),
+            "exp": datetime.now(timezone.utc) + timedelta(hours=24),
         }
         return jwt.encode(payload, SECRET, algorithm="HS256")
 
@@ -189,3 +189,56 @@ Remember to set a proper secret key::
 The session data is signed (not encrypted) — users can read it but
 can't tamper with it. Don't store sensitive data like passwords in
 sessions.
+
+
+Role-Based Access Control
+--------------------------
+
+For APIs where different users have different permissions, embed the
+role in the token and check it in route-specific guards::
+
+    def create_token(user_id: int, role: str = "user") -> str:
+        payload = {
+            "sub": user_id,
+            "role": role,
+            "exp": datetime.now(timezone.utc) + timedelta(hours=24),
+        }
+        return jwt.encode(payload, SECRET, algorithm="HS256")
+
+Create a helper that checks for a specific role::
+
+    def require_role(*roles):
+        """Before-request hook factory that restricts by role."""
+        def check(req, resp):
+            user_role = getattr(req.state, "role", None)
+            if user_role not in roles:
+                resp.status_code = 403
+                resp.media = {"error": "Insufficient permissions"}
+        return check
+
+Use it on specific routes::
+
+    @api.route("/admin/users", before_request=require_role("admin"))
+    def list_all_users(req, resp):
+        resp.media = {"users": [...]}
+
+And store the role during token verification::
+
+    # In your auth_guard:
+    req.state.user_id = payload["sub"]
+    req.state.role = payload.get("role", "user")
+
+
+Choosing an Auth Strategy
+--------------------------
+
+- **API keys** — simplest. Good for server-to-server, CLI tools, and
+  internal services. No expiration unless you build it.
+- **JWT tokens** — standard for SPAs and mobile apps. Stateless, so
+  they scale well. Downside: you can't revoke them without a blocklist.
+- **Sessions** — best for traditional web apps with HTML forms. The
+  browser manages cookies automatically. Stateful — the server controls
+  the session lifecycle.
+
+Start with API keys for internal tools, JWT for public APIs, and
+sessions for web apps with login pages.

docs/source/tutorial-middleware.rst

@@ -117,6 +117,47 @@ the existing stack. Keep this in mind for ordering dependencies — if
 middleware A depends on middleware B having run first, add B before A.
 
 
+Writing Pure ASGI Middleware
+----------------------------
+
+For maximum performance and control, you can write middleware as a plain
+ASGI application. This bypasses Starlette's ``BaseHTTPMiddleware``
+abstraction — it's faster and gives you direct access to the ASGI
+protocol::
+
+    class SecurityHeadersMiddleware:
+        def __init__(self, app):
+            self.app = app
+
+        async def __call__(self, scope, receive, send):
+            if scope["type"] != "http":
+                await self.app(scope, receive, send)
+                return
+
+            async def send_with_headers(message):
+                if message["type"] == "http.response.start":
+                    extra = [
+                        (b"x-content-type-options", b"nosniff"),
+                        (b"x-frame-options", b"DENY"),
+                        (b"referrer-policy", b"strict-origin-when-cross-origin"),
+                    ]
+                    message["headers"] = list(message["headers"]) + extra
+                await send(message)
+
+            await self.app(scope, receive, send_with_headers)
+
+    api.add_middleware(SecurityHeadersMiddleware)
+
+This is the same pattern used internally by Starlette and uvicorn. The
+middleware receives the ASGI ``scope``, ``receive``, and ``send`` callables,
+and wraps ``send`` to inject headers into the response.
+
+For most cases, ``BaseHTTPMiddleware`` is simpler and perfectly fine.
+Use the pure ASGI approach when you need to handle WebSocket connections,
+streaming responses, or want to avoid the overhead of request/response
+object creation.
+
+
 When to Use What
 -----------------
 

docs/source/tutorial-sqlalchemy.rst

@@ -28,8 +28,8 @@ SQLAlchemy models map Python classes to database tables. Each attribute
 becomes a column::
 
     # models.py
-    from sqlalchemy import Column, Integer, String
-    from sqlalchemy.orm import DeclarativeBase
+    from sqlalchemy import String
+    from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
 
     class Base(DeclarativeBase):
         pass
@@ -37,15 +37,16 @@ becomes a column::
     class Book(Base):
         __tablename__ = "books"
 
-        id = Column(Integer, primary_key=True, autoincrement=True)
-        title = Column(String, nullable=False)
-        author = Column(String, nullable=False)
-        year = Column(Integer, nullable=False)
-        isbn = Column(String, nullable=True)
+        id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
+        title: Mapped[str] = mapped_column(String, nullable=False)
+        author: Mapped[str] = mapped_column(String, nullable=False)
+        year: Mapped[int] = mapped_column(nullable=False)
+        isbn: Mapped[str | None] = mapped_column(String, nullable=True)
 
-``DeclarativeBase`` is SQLAlchemy's modern base class (SQLAlchemy 2.0+).
-Each model class corresponds to a table, and each ``Column`` corresponds
-to a column in that table.
+This uses SQLAlchemy 2.0's ``Mapped`` type annotations and
+``mapped_column()``, which give you type checker support and cleaner
+syntax than the older ``Column()`` style. Each model class corresponds
+to a table, and each ``mapped_column()`` corresponds to a column.
 
 
 Database Setup

docs/source/tutorial-websockets.rst

@@ -58,6 +58,8 @@ A chat room needs to broadcast messages to all connected clients. We keep
 a set of active connections and iterate through them when someone sends
 a message::
 
+    from starlette.websockets import WebSocketDisconnect
+
     connected = set()
 
     @api.route("/chat", websocket=True)
@@ -70,13 +72,15 @@ a message::
                 # Broadcast to all connected clients
                 for client in connected:
                     await client.send_text(message)
-        except Exception:
+        except WebSocketDisconnect:
             pass
         finally:
             connected.discard(ws)
 
 The ``try/finally`` block ensures we remove disconnected clients from
-the set, even if the connection drops unexpectedly.
+the set, even if the connection drops unexpectedly. Catching
+``WebSocketDisconnect`` specifically (rather than bare ``Exception``)
+makes the intent clear and avoids swallowing real bugs.
 
 
 Data Formats
@@ -154,6 +158,40 @@ WebSocket before-request hooks receive the ``ws`` object and must call
 ``await ws.accept()`` if they want the connection to proceed.
 
 
+Connection Lifecycle
+--------------------
+
+WebSocket connections go through several states:
+
+1. **Connecting** — the client sends an upgrade request
+2. **Open** — after ``await ws.accept()``, both sides can send messages
+3. **Closing** — either side initiates a close handshake
+4. **Closed** — the connection is fully terminated
+
+When a client disconnects (closes the tab, loses network), the next
+``await ws.receive_text()`` raises ``WebSocketDisconnect``. Always
+handle this — otherwise your server accumulates dead connections::
+
+    from starlette.websockets import WebSocketDisconnect
+
+    @api.route("/ws", websocket=True)
+    async def handler(ws):
+        await ws.accept()
+        try:
+            while True:
+                data = await ws.receive_text()
+                await ws.send_text(f"Got: {data}")
+        except WebSocketDisconnect:
+            print("Client disconnected")
+
+You can also close connections from the server side::
+
+    await ws.close(code=1000)  # 1000 = normal closure
+
+Common close codes: ``1000`` (normal), ``1001`` (going away),
+``1008`` (policy violation), ``1011`` (server error).
+
+
 Testing WebSockets
 ------------------
 
@@ -169,3 +207,13 @@ Use Starlette's ``TestClient`` for WebSocket tests::
 
 The ``websocket_connect`` context manager handles the connection
 lifecycle — it connects on enter and disconnects on exit.
+
+You can also test that connections are properly rejected::
+
+    from starlette.websockets import WebSocketDisconnect
+
+    def test_websocket_404():
+        client = TestClient(api)
+        with pytest.raises(WebSocketDisconnect):
+            with client.websocket_connect("/nonexistent"):
+                pass