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.

.github/FUNDING.yml

@@ -0,0 +1,3 @@
+github: kennethreitz
+thanks_dev: kennethreitz
+custom: https://cash.app/$KennethReitz

.github/dependabot.yml

@@ -0,0 +1,16 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"

.github/workflows/docs.yaml

@@ -0,0 +1,53 @@
+name: "Documentation"
+
+on:
+  push:
+    branches: [ main ]
+  pull_request: ~
+  workflow_dispatch:
+
+# Cancel redundant in-progress jobs.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+
+jobs:
+
+  documentation:
+    name: "Documentation"
+    runs-on: ubuntu-latest
+    env:
+      UV_SYSTEM_PYTHON: true
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.13"
+
+    - name: Set up uv
+      uses: astral-sh/setup-uv@v5
+      with:
+        version: "latest"
+        enable-cache: true
+        cache-dependency-glob: |
+          pyproject.toml
+
+    - name: Install package and documentation dependencies
+      run: uv pip install '.[docs]'
+
+    - name: Build static HTML documentation
+      run: sphinx-build -W --keep-going docs/source docs/build
+
+    - name: Deploy to GitHub Pages
+      if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+      uses: peaceiris/actions-gh-pages@v4
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./docs/build
+        cname: responder.kennethreitz.org

.github/workflows/test.yaml

@@ -0,0 +1,58 @@
+name: "Tests"
+
+on:
+  push:
+    branches: [ main ]
+  pull_request: ~
+  workflow_dispatch:
+
+# Cancel redundant in-progress jobs.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+
+  test:
+    name: "Python ${{ matrix.python-version }}"
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: [
+          "3.10",
+          "3.11",
+          "3.12",
+          "3.13",
+          "3.14",
+          "3.14t",
+          "pypy3.11",
+        ]
+    env:
+      UV_SYSTEM_PYTHON: true
+
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-node@v4
+      with:
+        node-version: 22
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Set up uv
+      uses: astral-sh/setup-uv@v5
+      with:
+        version: "latest"
+        enable-cache: true
+        cache-suffix: ${{ matrix.python-version }}
+        cache-dependency-glob: |
+          pyproject.toml
+
+    - name: Install package
+      run: uv pip install '.[develop,test]'
+
+    - name: Run tests
+      run: pytest

.gitignore

@@ -1 +1,20 @@
+.venv*
 .vscode/
+.cache
+.idea
+.python-version
+.coverage
+.pytest_cache
+.DS_Store
+coverage.xml
+.coverage*
+*.lock
+
+__pycache__
+tests/__pycache__
+
+build
+responder.egg-info/
+dist/
+app.py
+app2.py

CHANGELOG.md

@@ -0,0 +1,511 @@
+# Changelog
+
+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).
+
+## [v3.5.0] - 2026-03-24
+
+### Added
+
+- 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`
+
+### Changed
+
+- Replaced deprecated `asyncio.iscoroutinefunction` with `inspect.iscoroutinefunction` ahead of Python 3.16 removal
+- Narrowed broad `except Exception` to specific exceptions in response model serialization and websocket chat example
+- Improved GraphQL API interface with expanded test coverage
+- Code formatting cleanup via pyproject-fmt and ruff
+- Dropped Python 3.9 from CI
+
+### Fixed
+
+- WSGI mount returning 400 when requesting the exact mount root path
+- Werkzeug 3.1.7 compatibility for trusted host validation in tests
+- `future.result` bare property access in background task test (now properly calls `future.result()`)
+- OpenAPI template packaging and static file serving
+- RST title underline warning breaking docs CI
+
+### Removed
+
+- Read the Docs configuration (docs hosted on GitHub Pages)
+
+## [v3.4.0] - 2026-03-22
+
+### Changed
+
+- Upgraded to Starlette 1.0
+- Added comprehensive docstrings across the codebase
+- Expanded API reference documentation
+
+## [v3.3.0] - 2026-03-22
+
+### Added
+
+- Full documentation rewrite: tutorials for REST APIs, SQLAlchemy, Flask migration
+- Auth, WebSocket, middleware, and configuration guides
+- Testing docs with prose, examples, and tips
+- GitHub Pages deployment for docs
+
+### Changed
+
+- Reworked homepage prose
+- Rewrote CLI and API reference docs
+
+## [v3.2.0] - 2026-03-22
+
+### Added
+
+- Pydantic auto-validation: `request_model` validates input, returns 422 on failure
+- Pydantic auto-serialization: `response_model` strips extra fields from responses
+- Server-Sent Events: `@resp.sse` for real-time streaming
+- `resp.stream_file()` for streaming large files without loading into memory
+- `@api.after_request()` hooks
+- `api.group("/prefix")` for route groups and API versioning
+- `api.graphql("/path", schema=schema)` one-liner GraphQL setup
+- `api = responder.API(request_id=True)` for automatic request ID generation
+- Built-in rate limiter: `RateLimiter(requests=100, period=60).install(api)`
+- MessagePack format support: `await req.media("msgpack")`
+- `req.is_json`, `req.path_params`, `req.client` properties
+- `api.exception_handler()` decorator for custom error handling
+- Lifespan context manager support
+- `uuid` and `path` route convertors
+- PEP 561 `py.typed` marker
+- Pydantic support for OpenAPI schema generation
+
+### Changed
+
+- Dependencies flattened: `pip install responder` gets everything
+- Core deps reduced to starlette + uvicorn
+- TestClient lazy-loaded (no httpx import in production)
+- Before-request hooks can short-circuit by setting status code
+- Removed poethepoet task runner
+
+### Fixed
+
+- Multipart parser losing headers when parts have multiple headers
+- `url_for()` with typed route params (`{id:int}`)
+- `resp.body` encoding crash on bytes content
+- GraphQL text query missing `await`
+- Streaming responses not sending Content-Type headers
+- Python 3.9 compatibility for union type syntax
+
+## [v3.0.0] - 2026-03-22
+
+### Added
+
+- Platform: Added support for Python 3.10 - Python 3.13
+- CLI: `responder run` now also accepts a filesystem path on its `<target>`
+  argument, enabling usage on single-file applications.
+- CLI: `responder run` now also accepts URLs.
+
+### Changed
+
+- Platform: Minimum Python version is now 3.9 (dropped 3.6, 3.7, 3.8)
+- Dependencies: Dramatically reduced core dependency count (10 → 5)
+  - Removed `requests`, `requests-toolbelt`, `rfc3986`, `whitenoise`
+  - Moved `apispec` and `marshmallow` to `openapi` optional extra
+  - Replaced `rfc3986` with stdlib `urllib.parse`
+  - Replaced `requests-toolbelt` multipart decoder with `python-multipart`
+  - Replaced deprecated `starlette.middleware.wsgi` with `a2wsgi`
+  - Switched from WhiteNoise to ServeStatic
+- Dependencies: Pinned `starlette[full]>=0.40` (was unpinned)
+- GraphQL: Upgraded to `graphene>=3` and `graphql-core>=3.1`
+  (from `graphene<3` and `graphql-server-core`, which is unmaintained)
+- GraphQL: Updated GraphiQL UI from 0.12.0 (2018) to 3.0.6 with React 18
+- Extensions: All of CLI-, GraphQL-, and OpenAPI-Support modules are
+  extensions now, found within the `responder.ext` module namespace.
+- Packaging: Migrated from `setup.py` to declarative `pyproject.toml`
+
+### Removed
+
+- Platform: Removed support for EOL Python 3.6, 3.7, 3.8
+- Status codes: Removed deprecated `resume_incomplete` and `resume`
+  aliases for HTTP 308 (marked for removal in 3.0)
+- CLI: `responder run --build` ceased to exist
+
+### Fixed
+
+- Routing: Fixed dispatching `static_route=None` on Windows
+- uvicorn: `--debug` now maps to uvicorn's `log_level = "debug"`
+- Tests: Fixed deprecated httpx TestClient usage
+
+## [v2.0.5] - 2019-12-15
+
+### Added
+
+- Update requirements to support python 3.8
+
+## [v2.0.4] - 2019-11-19
+
+### Fixed
+
+- Fix static app resolving
+
+## [v2.0.3] - 2019-09-20
+
+### Fixed
+
+- Fix template conflicts
+
+## [v2.0.2] - 2019-09-20
+
+### Fixed
+
+- Fix template conflicts
+
+## [v2.0.1] - 2019-09-20
+
+### Fixed
+
+- Fix template import
+
+## [v2.0.0] - 2019-09-19
+
+### Changed
+
+- Refactor Router and Schema
+
+## [v1.3.2] - 2019-08-15
+
+### Added
+
+- ASGI 3 support
+- CI tests for python 3.8-dev
+- Now requests have `state` a mapping object
+
+### Deprecated
+
+- ASGI 2
+
+## [v1.3.1] - 2019-04-28
+
+### Added
+
+- Route params Converters
+- Add search for documentation pages
+
+### Changed
+
+- Bump dependencies
+
+## [v1.3.0] - 2019-02-22
+
+### Fixed
+
+- Versioning issue
+- Multiple cookies.
+- Whitenoise returns not found.
+- Other bugfixes.
+
+### Added
+
+- Stream support via `resp.stream`.
+- Cookie directives via `resp.set_cookie`.
+- Add `resp.html` to send HTML.
+- Other improvements.
+
+## [v1.1.3] - 2019-01-12
+
+### Changed
+
+- Refactor `_route_for`
+
+### Fixed
+
+- Resolve startup/shutdwown events
+
+## [v1.2.0] - 2018-12-29
+
+### Added
+
+- Documentations
+
+### Changed
+
+- Use Starlette's LifeSpan middleware
+- Update denpendencies
+
+### Fixed
+
+- Fix route.is_class_based
+- Fix test_500
+- Typos
+
+## [v1.1.2] - 2018-11-11
+
+### Fixed
+
+- Minor fixes for Open API
+- Typos
+
+## [v1.1.1] - 2018-10-29
+
+### Changed
+
+- Run sync views in a threadpoolexecutor.
+
+## [v1.1.0] - 2018-10-27
+
+### Added
+
+- Support for `before_request`.
+
+## [v1.0.5]- 2018-10-27
+
+### Fixed
+
+- Fix sessions.
+
+## [v1.0.4] - 2018-10-27
+
+### Fixed
+
+- Potential bufix for cookies.
+
+## [v1.0.3] - 2018-10-27
+
+### Fixed
+
+- Bugfix for redirects.
+
+## [v1.0.2] - 2018-10-27
+
+### Changed
+
+- Improvement for static file hosting.
+
+## [v1.0.1] - 2018-10-26
+
+### Changed
+
+- Improve cors configuration settings.
+
+## [v1.0.0] - 2018-10-26
+
+### Changed
+
+- Move GraphQL support into a built-in plugin.
+
+## [v0.3.3] - 2018-10-25
+
+### Added
+
+- CORS support
+
+### Changed
+
+- Improved exceptions.
+
+## [v0.3.2] - 2018-10-25
+
+### Changed
+
+- Subtle improvements.
+
+## [v0.3.1] - 2018-10-24
+
+### Fixed
+
+- Packaging fix.
+
+## [v0.3.0] - 2018-10-24
+
+### Changed
+
+- Interactive Documentation endpoint.
+- Minor improvements.
+
+## [v0.2.3] - 2018-10-24
+
+### Changed
+
+- Overall improvements.
+
+## [v0.2.2] - 2018-10-23
+
+### Added
+
+- Show traceback info when background tasks raise exceptions.
+
+## [v0.2.1] - 2018-10-23
+
+### Added
+
+- api.requests.
+
+## [v0.2.0] - 2018-10-22
+
+### Added
+
+- WebSocket support.
+
+## [v0.1.6] - 2018-10-20
+
+### Added
+
+- 500 support.
+
+## [v0.1.5] - 2018-10-20
+
+### Added
+
+- File upload support
+
+### Changed
+
+- Improvements to sequential media reading.
+
+## [v0.1.4] - 2018-10-19
+
+### Fixed
+
+- Stability.
+
+## [v0.1.3] - 2018-10-18
+
+### Added
+
+- Sessions support.
+
+## [v0.1.2] - 2018-10-18
+
+### Added
+
+- Cookies support.
+
+## [v0.1.1] - 2018-10-17
+
+### Changed
+
+- Default routes.
+
+## [v0.1.0] - 2018-10-17
+
+### Added
+
+- Prototype of static application support.
+
+## [v0.0.10] - 2018-10-17
+
+### Fixed
+
+- Bugfix for async class-based views.
+
+## [v0.0.9] - 2018-10-17
+
+### Fixed
+
+- Bugfix for async class-based views.
+
+## [v0.0.8] - 2018-10-17
+
+### Added
+
+- GraphiQL Support.
+
+### Changed
+
+- Improvement to route selection.
+
+## [v0.0.7] - 2018-10-16
+
+### Changed
+
+- Immutable Request object.
+
+## [v0.0.6] - 2018-10-16
+
+### Added
+
+- Ability to mount WSGI apps.
+- Supply content-type when serving up the schema.
+
+## [v0.0.5] - 2018-10-15
+
+### Added
+
+- OpenAPI Schema support.
+- Safe load/dump yaml.
+
+## [v0.0.4] - 2018-10-15
+
+### Added
+
+- Asynchronous support for data uploads.
+
+### Fixed
+
+- Bug fixes.
+
+## [v0.0.3] - 2018-10-13
+
+### Fixed
+
+- Bug fixes.
+
+## [v0.0.2] - 2018-10-13
+
+### Changed
+
+- Switch to ASGI/Starlette.
+
+## [v0.0.1] - 2018-10-12
+
+### Added
+
+- Conception!
+
+[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
+[v3.2.0]: https://github.com/kennethreitz/responder/compare/v3.0.0..v3.2.0
+[v3.0.0]: https://github.com/kennethreitz/responder/compare/v2.0.5..v3.0.0
+[v2.0.5]: https://github.com/kennethreitz/responder/compare/v2.0.4..v2.0.5
+[v2.0.4]: https://github.com/kennethreitz/responder/compare/v2.0.3..v2.0.4
+[v2.0.3]: https://github.com/kennethreitz/responder/compare/v2.0.2..v2.0.3
+[v2.0.2]: https://github.com/kennethreitz/responder/compare/v2.0.1..v2.0.2
+[v2.0.1]: https://github.com/kennethreitz/responder/compare/v2.0.0..v2.0.1
+[v2.0.0]: https://github.com/kennethreitz/responder/compare/v1.3.2..v2.0.0
+[v1.3.2]: https://github.com/kennethreitz/responder/compare/v1.3.1..v1.3.2
+[v1.3.1]: https://github.com/kennethreitz/responder/compare/v1.3.0..v1.3.1
+[v1.3.0]: https://github.com/kennethreitz/responder/compare/v1.2.0..v1.3.0
+[v1.2.0]: https://github.com/kennethreitz/responder/compare/v1.1.3..v1.2.0
+[v1.1.3]: https://github.com/kennethreitz/responder/compare/v1.1.2..v1.1.3
+[v1.1.2]: https://github.com/kennethreitz/responder/compare/v1.1.1..v1.1.2
+[v1.1.1]: https://github.com/kennethreitz/responder/compare/v1.1.0..v1.1.1
+[v1.1.0]: https://github.com/kennethreitz/responder/compare/v1.0.5..v1.1.0
+[v1.0.5]: https://github.com/kennethreitz/responder/compare/v1.0.4..v1.0.5
+[v1.0.4]: https://github.com/kennethreitz/responder/compare/v1.0.3..v1.0.4
+[v1.0.3]: https://github.com/kennethreitz/responder/compare/v1.0.2..v1.0.3
+[v1.0.2]: https://github.com/kennethreitz/responder/compare/v1.0.1..v1.0.2
+[v1.0.1]: https://github.com/kennethreitz/responder/compare/v1.0.0..v1.0.1
+[v1.0.0]: https://github.com/kennethreitz/responder/compare/v0.3.3..v1.0.0
+[v0.3.3]: https://github.com/kennethreitz/responder/compare/v0.3.2..v0.3.3
+[v0.3.2]: https://github.com/kennethreitz/responder/compare/v0.3.1..v0.3.2
+[v0.3.1]: https://github.com/kennethreitz/responder/compare/v0.3.0..v0.3.1
+[v0.3.0]: https://github.com/kennethreitz/responder/compare/v0.2.3..v0.3.0
+[v0.2.3]: https://github.com/kennethreitz/responder/compare/v0.2.2..v0.2.3
+[v0.2.2]: https://github.com/kennethreitz/responder/compare/v0.2.1..v0.2.2
+[v0.2.1]: https://github.com/kennethreitz/responder/compare/v0.2.0..v0.2.1
+[v0.2.0]: https://github.com/kennethreitz/responder/compare/v0.1.6..v0.2.0
+[v0.1.6]: https://github.com/kennethreitz/responder/compare/v0.1.5..v0.1.6
+[v0.1.5]: https://github.com/kennethreitz/responder/compare/v0.1.4..v0.1.5
+[v0.1.4]: https://github.com/kennethreitz/responder/compare/v0.1.3..v0.1.4
+[v0.1.3]: https://github.com/kennethreitz/responder/compare/v0.1.2..v0.1.3
+[v0.1.2]: https://github.com/kennethreitz/responder/compare/v0.1.1..v0.1.2
+[v0.1.1]: https://github.com/kennethreitz/responder/compare/v0.1.0..v0.1.1
+[v0.1.0]: https://github.com/kennethreitz/responder/compare/v0.0.10..v0.1.0
+[v0.0.10]: https://github.com/kennethreitz/responder/compare/v0.0.9..v0.0.10
+[v0.0.9]: https://github.com/kennethreitz/responder/compare/v0.0.8..v0.0.9
+[v0.0.8]: https://github.com/kennethreitz/responder/compare/v0.0.7..v0.0.8
+[v0.0.7]: https://github.com/kennethreitz/responder/compare/v0.0.6..v0.0.7
+[v0.0.6]: https://github.com/kennethreitz/responder/compare/v0.0.5..v0.0.6
+[v0.0.5]: https://github.com/kennethreitz/responder/compare/v0.0.4..v0.0.5
+[v0.0.4]: https://github.com/kennethreitz/responder/compare/v0.0.3..v0.0.4
+[v0.0.3]: https://github.com/kennethreitz/responder/compare/v0.0.2..v0.0.3
+[v0.0.2]: https://github.com/kennethreitz/responder/compare/v0.0.1..v0.0.2
+[v0.0.1]: https://github.com/kennethreitz/responder/compare/v0.0.0..v0.0.1

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*`

LICENSE

@@ -0,0 +1,178 @@
+
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

Pipfile

@@ -1,24 +0,0 @@
-[[source]]
-url = "https://pypi.org/simple"
-verify_ssl = true
-name = "pypi"
-
-[packages]
-waitress = "*"
-werkzeug = "*"
-pyyaml = "*"
-requests = "*"
-requests-wsgi-adapter = "*"
-graphene = "*"
-whitenoise = "*"
-
-[dev-packages]
-pytest = "*"
-"flake8" = "*"
-black = "*"
-
-[requires]
-python_version = "3.7"
-
-[pipenv]
-allow_prereleases = true

Pipfile.lock

@@ -1,271 +0,0 @@
-{
-    "_meta": {
-        "hash": {
-            "sha256": "f6b7cc3cf0ac2760ea99bcb8d18c743eff418c6269da29823ccfdbdea19a8c1e"
-        },
-        "pipfile-spec": 6,
-        "requires": {
-            "python_version": "3.7"
-        },
-        "sources": [
-            {
-                "name": "pypi",
-                "url": "https://pypi.org/simple",
-                "verify_ssl": true
-            }
-        ]
-    },
-    "default": {
-        "aniso8601": {
-            "hashes": [
-                "sha256:7849749cf00ae0680ad2bdfe4419c7a662bef19c03691a19e008c8b9a5267802",
-                "sha256:94f90871fcd314a458a3d4eca1c84448efbd200e86f55fe4c733c7a40149ef50"
-            ],
-            "version": "==3.0.2"
-        },
-        "certifi": {
-            "hashes": [
-                "sha256:376690d6f16d32f9d1fe8932551d80b23e9d393a8578c5633a2ed39a64861638",
-                "sha256:456048c7e371c089d0a77a5212fb37a2c2dce1e24146e3b7e0261736aaeaa22a"
-            ],
-            "version": "==2018.8.24"
-        },
-        "chardet": {
-            "hashes": [
-                "sha256:84ab92ed1c4d4f16916e05906b6b75a6c0fb5db821cc65e70cbd64a3e2a5eaae",
-                "sha256:fc323ffcaeaed0e0a02bf4d117757b98aed530d9ed4531e3e15460124c106691"
-            ],
-            "version": "==3.0.4"
-        },
-        "graphene": {
-            "hashes": [
-                "sha256:b8ec446d17fa68721636eaad3d6adc1a378cb6323e219814c8f98c9928fc9642",
-                "sha256:faa26573b598b22ffd274e2fd7a4c52efa405dcca96e01a62239482246248aa3"
-            ],
-            "index": "pypi",
-            "version": "==2.1.3"
-        },
-        "graphql-core": {
-            "hashes": [
-                "sha256:889e869be5574d02af77baf1f30b5db9ca2959f1c9f5be7b2863ead5a3ec6181",
-                "sha256:9462e22e32c7f03b667373ec0a84d95fba10e8ce2ead08f29fbddc63b671b0c1"
-            ],
-            "version": "==2.1"
-        },
-        "graphql-relay": {
-            "hashes": [
-                "sha256:2716b7245d97091af21abf096fabafac576905096d21ba7118fba722596f65db"
-            ],
-            "version": "==0.4.5"
-        },
-        "idna": {
-            "hashes": [
-                "sha256:156a6814fb5ac1fc6850fb002e0852d56c0c8d2531923a51032d1b70760e186e",
-                "sha256:684a38a6f903c1d71d6d5fac066b58d7768af4de2b832e426ec79c30daa94a16"
-            ],
-            "version": "==2.7"
-        },
-        "promise": {
-            "hashes": [
-                "sha256:2ebbfc10b7abf6354403ed785fe4f04b9dfd421eb1a474ac8d187022228332af",
-                "sha256:348f5f6c3edd4fd47c9cd65aed03ac1b31136d375aa63871a57d3e444c85655c"
-            ],
-            "version": "==2.2.1"
-        },
-        "pyyaml": {
-            "hashes": [
-                "sha256:254bf6fda2b7c651837acb2c718e213df29d531eebf00edb54743d10bcb694eb",
-                "sha256:3108529b78577327d15eec243f0ff348a0640b0c3478d67ad7f5648f93bac3e2",
-                "sha256:3c17fb92c8ba2f525e4b5f7941d850e7a48c3a59b32d331e2502a3cdc6648e76",
-                "sha256:8d6d96001aa7f0a6a4a95e8143225b5d06e41b1131044913fecb8f85a125714b",
-                "sha256:c8a88edd93ee29ede719080b2be6cb2333dfee1dccba213b422a9c8e97f2967b"
-            ],
-            "index": "pypi",
-            "version": "==4.2b4"
-        },
-        "requests": {
-            "hashes": [
-                "sha256:63b52e3c866428a224f97cab011de738c36aec0185aa91cfacd418b5d58911d1",
-                "sha256:ec22d826a36ed72a7358ff3fe56cbd4ba69dd7a6718ffd450ff0e9df7a47ce6a"
-            ],
-            "index": "pypi",
-            "version": "==2.19.1"
-        },
-        "requests-wsgi-adapter": {
-            "hashes": [
-                "sha256:7080c98ae2614b8d0b7339b611d97a535470d2fb479731f7d588d5f8108ea134"
-            ],
-            "index": "pypi",
-            "version": "==0.4.0"
-        },
-        "rx": {
-            "hashes": [
-                "sha256:13a1d8d9e252625c173dc795471e614eadfe1cf40ffc684e08b8fff0d9748c23",
-                "sha256:7357592bc7e881a95e0c2013b73326f704953301ab551fbc8133a6fadab84105"
-            ],
-            "version": "==1.6.1"
-        },
-        "six": {
-            "hashes": [
-                "sha256:70e8a77beed4562e7f14fe23a786b54f6296e34344c23bc42f07b15018ff98e9",
-                "sha256:832dc0e10feb1aa2c68dcc57dbb658f1c7e65b9b61af69048abc87a2db00a0eb"
-            ],
-            "version": "==1.11.0"
-        },
-        "urllib3": {
-            "hashes": [
-                "sha256:a68ac5e15e76e7e5dd2b8f94007233e01effe3e50e8daddf69acfd81cb686baf",
-                "sha256:b5725a0bd4ba422ab0e66e89e030c806576753ea3ee08554382c14e685d117b5"
-            ],
-            "markers": "python_version < '4' and python_version != '3.3.*' and python_version != '3.2.*' and python_version != '3.0.*' and python_version != '3.1.*' and python_version >= '2.6'",
-            "version": "==1.23"
-        },
-        "waitress": {
-            "hashes": [
-                "sha256:40b0f297a7f3af61fbfbdc67e59090c70dc150a1601c39ecc9f5f1d283fb931b",
-                "sha256:d33cd3d62426c0f1b3cd84ee3d65779c7003aae3fc060dee60524d10a57f05a9"
-            ],
-            "index": "pypi",
-            "version": "==1.1.0"
-        },
-        "werkzeug": {
-            "hashes": [
-                "sha256:c3fd7a7d41976d9f44db327260e263132466836cef6f91512889ed60ad26557c",
-                "sha256:d5da73735293558eb1651ee2fddc4d0dedcfa06538b8813a2e20011583c9e49b"
-            ],
-            "index": "pypi",
-            "version": "==0.14.1"
-        },
-        "whitenoise": {
-            "hashes": [
-                "sha256:133a92ff0ab8fb9509f77d4f7d0de493eca19c6fea973f4195d4184f888f2e02",
-                "sha256:32b57d193478908a48acb66bf73e7a3c18679263e3e64bfebcfac1144a430039"
-            ],
-            "index": "pypi",
-            "version": "==4.1"
-        }
-    },
-    "develop": {
-        "appdirs": {
-            "hashes": [
-                "sha256:9e5896d1372858f8dd3344faf4e5014d21849c756c8d5701f78f8a103b372d92",
-                "sha256:d8b24664561d0d34ddfaec54636d502d7cea6e29c3eaf68f3df6180863e2166e"
-            ],
-            "version": "==1.4.3"
-        },
-        "atomicwrites": {
-            "hashes": [
-                "sha256:0312ad34fcad8fac3704d441f7b317e50af620823353ec657a53e981f92920c0",
-                "sha256:ec9ae8adaae229e4f8446952d204a3e4b5fdd2d099f9be3aaf556120135fb3ee"
-            ],
-            "markers": "python_version != '3.2.*' and python_version >= '2.7' and python_version != '3.3.*' and python_version != '3.0.*' and python_version != '3.1.*'",
-            "version": "==1.2.1"
-        },
-        "attrs": {
-            "hashes": [
-                "sha256:10cbf6e27dbce8c30807caf056c8eb50917e0eaafe86347671b57254006c3e69",
-                "sha256:ca4be454458f9dec299268d472aaa5a11f67a4ff70093396e1ceae9c76cf4bbb"
-            ],
-            "version": "==18.2.0"
-        },
-        "black": {
-            "hashes": [
-                "sha256:817243426042db1d36617910df579a54f1afd659adb96fc5032fcf4b36209739",
-                "sha256:e030a9a28f542debc08acceb273f228ac422798e5215ba2a791a6ddeaaca22a5"
-            ],
-            "index": "pypi",
-            "version": "==18.9b0"
-        },
-        "click": {
-            "hashes": [
-                "sha256:2335065e6395b9e67ca716de5f7526736bfa6ceead690adf616d925bdc622b13",
-                "sha256:5b94b49521f6456670fdb30cd82a4eca9412788a93fa6dd6df72c94d5a8ff2d7"
-            ],
-            "markers": "python_version != '3.3.*' and python_version != '3.0.*' and python_version != '3.2.*' and python_version != '3.1.*' and python_version >= '2.7'",
-            "version": "==7.0"
-        },
-        "colorama": {
-            "hashes": [
-                "sha256:463f8483208e921368c9f306094eb6f725c6ca42b0f97e313cb5d5512459feda",
-                "sha256:48eb22f4f8461b1df5734a074b57042430fb06e1d61bd1e11b078c0fe6d7a1f1"
-            ],
-            "markers": "sys_platform == 'win32'",
-            "version": "==0.3.9"
-        },
-        "flake8": {
-            "hashes": [
-                "sha256:7253265f7abd8b313e3892944044a365e3f4ac3fcdcfb4298f55ee9ddf188ba0",
-                "sha256:c7841163e2b576d435799169b78703ad6ac1bbb0f199994fc05f700b2a90ea37"
-            ],
-            "index": "pypi",
-            "version": "==3.5.0"
-        },
-        "mccabe": {
-            "hashes": [
-                "sha256:ab8a6258860da4b6677da4bd2fe5dc2c659cff31b3ee4f7f5d64e79735b80d42",
-                "sha256:dd8d182285a0fe56bace7f45b5e7d1a6ebcbf524e8f3bd87eb0f125271b8831f"
-            ],
-            "version": "==0.6.1"
-        },
-        "more-itertools": {
-            "hashes": [
-                "sha256:c187a73da93e7a8acc0001572aebc7e3c69daf7bf6881a2cea10650bd4420092",
-                "sha256:c476b5d3a34e12d40130bc2f935028b5f636df8f372dc2c1c01dc19681b2039e",
-                "sha256:fcbfeaea0be121980e15bc97b3817b5202ca73d0eae185b4550cbfce2a3ebb3d"
-            ],
-            "version": "==4.3.0"
-        },
-        "pluggy": {
-            "hashes": [
-                "sha256:6e3836e39f4d36ae72840833db137f7b7d35105079aee6ec4a62d9f80d594dd1",
-                "sha256:95eb8364a4708392bae89035f45341871286a333f749c3141c20573d2b3876e1"
-            ],
-            "markers": "python_version != '3.2.*' and python_version >= '2.7' and python_version != '3.3.*' and python_version != '3.0.*' and python_version != '3.1.*'",
-            "version": "==0.7.1"
-        },
-        "py": {
-            "hashes": [
-                "sha256:06a30435d058473046be836d3fc4f27167fd84c45b99704f2fb5509ef61f9af1",
-                "sha256:50402e9d1c9005d759426988a492e0edaadb7f4e68bcddfea586bc7432d009c6"
-            ],
-            "markers": "python_version != '3.2.*' and python_version >= '2.7' and python_version != '3.3.*' and python_version != '3.0.*' and python_version != '3.1.*'",
-            "version": "==1.6.0"
-        },
-        "pycodestyle": {
-            "hashes": [
-                "sha256:682256a5b318149ca0d2a9185d365d8864a768a28db66a84a2ea946bcc426766",
-                "sha256:6c4245ade1edfad79c3446fadfc96b0de2759662dc29d07d80a6f27ad1ca6ba9"
-            ],
-            "version": "==2.3.1"
-        },
-        "pyflakes": {
-            "hashes": [
-                "sha256:08bd6a50edf8cffa9fa09a463063c425ecaaf10d1eb0335a7e8b1401aef89e6f",
-                "sha256:8d616a382f243dbf19b54743f280b80198be0bca3a5396f1d2e1fca6223e8805"
-            ],
-            "version": "==1.6.0"
-        },
-        "pytest": {
-            "hashes": [
-                "sha256:7e258ee50338f4e46957f9e09a0f10fb1c2d05493fa901d113a8dafd0790de4e",
-                "sha256:9332147e9af2dcf46cd7ceb14d5acadb6564744ddff1fe8c17f0ce60ece7d9a2"
-            ],
-            "index": "pypi",
-            "version": "==3.8.2"
-        },
-        "six": {
-            "hashes": [
-                "sha256:70e8a77beed4562e7f14fe23a786b54f6296e34344c23bc42f07b15018ff98e9",
-                "sha256:832dc0e10feb1aa2c68dcc57dbb658f1c7e65b9b61af69048abc87a2db00a0eb"
-            ],
-            "version": "==1.11.0"
-        },
-        "toml": {
-            "hashes": [
-                "sha256:229f81c57791a41d65e399fc06bf0848bab550a9dfd5ed66df18ce5f05e73d5c",
-                "sha256:235682dd292d5899d361a811df37e04a8828a5b1da3115886b73cf81ebc9100e"
-            ],
-            "version": "==0.10.0"
-        }
-    }
-}

README.md

@@ -1,35 +1,109 @@
-# Responder: a Sorta Familar HTTP Framework for Python
+# Responder
 
-![](https://farm2.staticflickr.com/1937/30196007887_604e2f10d8_k_d.jpg)
+A familiar HTTP Service Framework for Python, powered by [Starlette](https://www.starlette.io/).
 
-I'm adept to keep the "for humans" tagline off this project, until it comes out of the prototyping phase. I'm building this to learn, and to have fun -- while, at the same time, trying to bring something new to the table.
+```python
+import responder
 
-The Python world certianly doesn't need more web frameworks. But, it does need more creativity, so I thought I'd bring some of my ideas to the table and see what I could come up with.
+api = responder.API()
 
-# The Basic Idea
+@api.route("/{greeting}")
+async def greet_world(req, resp, *, greeting):
+    resp.text = f"{greeting}, world!"
 
-The primary concept here is to bring the nicities that are brought forth from both Flask and Falcon and unify them into a single framework, along with some new ideas I have. I also wanted to take some of the API primitaves that are instilled in the Requests library and put them into a web framework. So, you'll find a lot of parallels here with Requests.
+if __name__ == "__main__":
+    api.run()
+```
 
-## Old Ideas
+    $ pip install responder
 
-- Flask-style route expression, with new capabilities -- primarily, the ability to cast a parameter to integers as well as other types that are missing from Flask, all while using Python 3.6+'s new f-string syntax.
+That's it. Supports Python 3.10+.
 
-- I love Falcon's "every request and response is passed into to each view and mutated" methodology, especially `response.media`, and have used it here. In addition to supporting JSON, I have decided to support YAML as well, as Kubernetes is slowly taking over the world, and it uses YAML for all the things. Content-negotiation and all that.
+## The Basics
 
-## New Ideas
+- `resp.text` sends back text. `resp.html` sends back HTML. `resp.content` sends back bytes.
+- `resp.media` sends back JSON (or YAML, with content negotiation).
+- `resp.file("path.pdf")` serves a file with automatic content-type detection.
+- `req.headers` is case-insensitive. `req.params` gives you query parameters.
+- Both sync and async views work — the `async` is optional.
 
-- **A built in testing client that uses the actual Requests you know and love**.
-- In addition to Falcon's `on_get`, `on_post`, etc methods, Responder features an `on_request` method, which gets called on every type of request, much like Requests.
-- WhiteNoise is built-in, for serving static files (this has yet to be built out, there's no templating or `static_url` yet)
-- Waitress (will-be) built-in as a production web server. I would have chosen Gunicorn, but it doesn't run on Windows. Plus, Waitress serves well to protect against slowloris attacks, making nginx unneccessary in production.
-- GraphQL support, via Graphene. The goal here is to eventually have an embedded version of GraphiQL exposable at any route.
+## Highlights
 
-## Future Ideas
+```python
+# Type-safe route parameters
+@api.route("/users/{user_id:int}")
+async def get_user(req, resp, *, user_id):
+    resp.media = {"id": user_id}
 
-- I want to be able to "mount" any WSGI app into a sub-route.
-- Cooke-based sessions are currently an afterthrought, as this is an API framework, but websites are APIs too.
-- Potentially support ASGI instead of WSGI. Will the tradeoffs be worth it? This is a question to ask. Procedural code works well for 90% use cases.
+# HTTP method filtering
+@api.route("/items", methods=["POST"])
+async def create_item(req, resp):
+    data = await req.media()
+    resp.media = {"created": data}
 
-# The Goal
+# Class-based views
+@api.route("/things/{id}")
+class ThingResource:
+    def on_get(self, req, resp, *, id):
+        resp.media = {"id": id}
+    def on_post(self, req, resp, *, id):
+        resp.text = "created"
 
-The primary goal here is to learn, not to get adoption. Though, who knows how these things will pan out.
+# Before-request hooks (auth, rate limiting, etc.)
+@api.route(before_request=True)
+def check_auth(req, resp):
+    if not req.headers.get("Authorization"):
+        resp.status_code = 401
+        resp.media = {"error": "unauthorized"}
+
+# Custom error handling
+@api.exception_handler(ValueError)
+async def handle_error(req, resp, exc):
+    resp.status_code = 400
+    resp.media = {"error": str(exc)}
+
+# Lifespan events
+from contextlib import asynccontextmanager
+
+@asynccontextmanager
+async def lifespan(app):
+    print("starting up")
+    yield
+    print("shutting down")
+
+api = responder.API(lifespan=lifespan)
+
+# GraphQL
+import graphene
+api.graphql("/graphql", schema=graphene.Schema(query=Query))
+
+# WebSockets
+@api.route("/ws", websocket=True)
+async def websocket(ws):
+    await ws.accept()
+    while True:
+        name = await ws.receive_text()
+        await ws.send_text(f"Hello {name}!")
+
+# Mount WSGI/ASGI apps
+from flask import Flask
+flask_app = Flask(__name__)
+api.mount("/flask", flask_app)
+
+# Background tasks
+@api.route("/work")
+def do_work(req, resp):
+    @api.background.task
+    def process():
+        import time; time.sleep(10)
+    process()
+    resp.media = {"status": "processing"}
+```
+
+Built-in OpenAPI docs, cookie-based sessions, gzip compression, static file serving, Jinja2 templates, and a production uvicorn server.
+
+Route convertors: `str`, `int`, `float`, `uuid`, `path`.
+
+## Documentation
+
+https://responder.kennethreitz.org

app.py

@@ -1,53 +0,0 @@
-import responder
-import graphene
-
-api = responder.API(static="static")
-# api.mount('/subapp', other_wsgi_app)
-
-
-@api.route("/")
-def hello(req, resp):
-    print(resp)
-    # resp.status = responder.status.ok
-    resp.media = {"hello": "world"}
-
-
-class ThingsResource:
-    def on_request(self, req, resp):
-        resp.status = responder.status.HTTP_200
-        resp.media = ["ylolo"]
-
-
-class Query(graphene.ObjectType):
-    hello = graphene.String(name=graphene.String(default_value="stranger"))
-
-    def resolve_hello(self, info, name):
-        return "Hello " + name
-
-
-schema = graphene.Schema(query=Query)
-
-
-class GraphQLResource(responder.GraphQLSchema):
-    import graphene
-
-    def on_request(self, req, resp):
-        resp.status = responder.status.HTTP_200
-        print(schema.execute("{ hello }").data)
-
-        resp.media = ["yolo"]
-
-
-# Alerntatively,
-api.add_route("/2", GraphQLResource)
-api.add_route("/graph", schema)
-
-print(
-    api.session()
-    .get(
-        "http://app/graph?query={ hello }",
-        headers={"Accept": "application/x-yaml"},
-        # data="hello",
-    )
-    .text
-)

docs/Makefile

@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+
+:end
+popd

docs/source/_templates/hacks.html

@@ -0,0 +1,21 @@
+<style type="text/css">
+  /* Make the document a little wider. */
+  div.document {
+    width: 1008px;
+  }
+
+  /* Better spacing around code blocks. */
+  div.highlight pre {
+    padding: 11px 14px;
+  }
+
+  /* Responsive layout. */
+  @media screen and (max-width: 1008px) {
+    div.sphinxsidebar {
+      display: none;
+    }
+    div.document {
+      width: 100% !important;
+    }
+  }
+</style>

docs/source/_templates/sidebarintro.html

@@ -0,0 +1,16 @@
+<p class="logo">
+  <a href="{{ pathto(master_doc) }}">
+    <img class="logo" src="{{ pathto('_static/responder.png', 1) }}" />
+  </a>
+</p>
+<p>
+  <strong>Responder</strong> — a familiar HTTP service framework for Python.
+  <br />
+  <small>v{{ version }}</small>
+</p>
+<h3>Useful Links</h3>
+<ul>
+  <li><a href="https://github.com/kennethreitz/responder">Responder @ GitHub</a></li>
+  <li><a href="https://pypi.org/project/responder/">Responder @ PyPI</a></li>
+  <li><a href="https://github.com/kennethreitz/responder/issues">Issue Tracker</a></li>
+</ul>

docs/source/api.rst

@@ -0,0 +1,182 @@
+API Reference
+=============
+
+This page documents Responder's public Python API. For usage examples
+and explanations, see the :doc:`quickstart` and :doc:`tour`.
+
+
+The API Class
+-------------
+
+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
+    :inherited-members:
+
+
+Request
+-------
+
+The request object is passed into every view as the first argument. It
+gives you access to everything the client sent — headers, query
+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:
+
+
+Response
+--------
+
+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:
+
+
+Route Groups
+------------
+
+Group related routes under a shared URL prefix — useful for API versioning
+and organizing large applications::
+
+    v1 = api.group("/v1")
+
+    @v1.route("/users")
+    def list_users(req, resp):
+        resp.media = []
+
+.. autoclass:: responder.api.RouteGroup
+    :members:
+
+
+Background Queue
+----------------
+
+Run tasks in background threads without blocking the response. Available
+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:
+
+
+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:
+
+
+Rate Limiter
+------------
+
+In-memory token bucket rate limiter. Limits requests per client IP address
+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:
+
+
+Status Code Helpers
+-------------------
+
+Convenience functions for checking which category a status code falls
+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
+
+.. autofunction:: responder.status_codes.is_200
+
+.. autofunction:: responder.status_codes.is_300
+
+.. autofunction:: responder.status_codes.is_400
+
+.. autofunction:: responder.status_codes.is_500

docs/source/backlog.md

@@ -0,0 +1,8 @@
+# Backlog
+
+## Future Ideas
+- 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/changes.md

@@ -0,0 +1 @@
+../../CHANGELOG.md

docs/source/cli.rst

@@ -0,0 +1,100 @@
+Command Line Interface
+======================
+
+Responder installs a ``responder`` command that lets you launch
+applications from the terminal. You can point it at a Python module,
+a local file, or even a URL — and it will find your ``API`` instance
+and start serving.
+
+
+Launching from a Module
+-----------------------
+
+The most common way to run a Responder application in production. Use
+Python's standard dotted module path::
+
+    $ responder run acme.app
+
+This imports ``acme.app`` and looks for an attribute called ``api``
+(a ``responder.API`` instance). It's the same import system Python
+uses everywhere — your ``PYTHONPATH`` and virtual environment are
+respected.
+
+
+Launching from a File
+---------------------
+
+During development, you often have a single file you want to run::
+
+    $ responder run helloworld.py
+
+This loads the file directly and starts the server. Quick and easy for
+prototyping and single-file applications.
+
+You can test it with a simple HTTP request::
+
+    $ curl http://127.0.0.1:5042/hello
+    hello, world!
+
+
+Launching from a URL
+--------------------
+
+Responder can fetch and run a Python file from any URL — great for
+demos, sharing examples, and running code from GitHub::
+
+    $ responder run https://github.com/kennethreitz/responder/raw/refs/heads/main/examples/helloworld.py
+
+This also works with ``github://`` URLs and any filesystem protocol
+supported by `fsspec <https://filesystem-spec.readthedocs.io/>`_::
+
+    $ responder run github://kennethreitz:responder@/examples/helloworld.py
+
+Cloud storage is supported too — Azure Blob Storage, Google Cloud
+Storage, S3, HDFS, SFTP, and more. Install ``fsspec[full]`` for all
+protocols::
+
+    $ uv pip install 'fsspec[full]'
+
+
+Custom Instance Names
+---------------------
+
+By default, Responder looks for an attribute called ``api``. If your
+application uses a different name, specify it with a colon::
+
+    $ responder run acme.app:service
+    $ responder run myapp.py:application
+
+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
+-------------------------
+
+If your project includes a JavaScript frontend with a ``package.json``,
+the ``build`` subcommand runs ``npm run build``::
+
+    $ responder build
+    $ responder build /path/to/frontend

docs/source/conf.py

@@ -0,0 +1,52 @@
+# Sphinx configuration for Responder documentation.
+
+import os
+
+project = "responder"
+copyright = "2018-2026, Kenneth Reitz"
+author = "Kenneth Reitz"
+
+here = os.path.abspath(os.path.dirname(__file__))
+about = {}
+with open(os.path.join(here, "..", "..", "responder", "__version__.py")) as f:
+    exec(f.read(), about)
+
+version = about["__version__"]
+release = about["__version__"]
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.viewcode",
+    "myst_parser",
+    "sphinx_copybutton",
+    "sphinx_design_elements",
+]
+
+templates_path = ["_templates"]
+source_suffix = {".rst": "restructuredtext"}
+master_doc = "index"
+language = "en"
+exclude_patterns = []
+
+# Theme
+html_theme = "alabaster"
+html_theme_options = {
+    "show_powered_by": False,
+    "github_user": "kennethreitz",
+    "github_repo": "responder",
+    "github_banner": False,
+    "show_related": False,
+}
+html_static_path = ["_static"]
+html_sidebars = {
+    "index": ["sidebarintro.html", "searchbox.html"],
+    "**": ["sidebarintro.html", "localtoc.html", "searchbox.html"],
+}
+
+# MyST
+myst_heading_anchors = 3
+
+# Copybutton
+copybutton_remove_prompts = True
+copybutton_prompt_text = r">>> |\.\.\. |\$ "
+copybutton_prompt_is_regexp = True

docs/source/deployment.rst

@@ -0,0 +1,187 @@
+Deployment
+==========
+
+Responder applications are standard `ASGI <https://asgi.readthedocs.io/>`_
+apps. ASGI (Asynchronous Server Gateway Interface) is the modern successor
+to WSGI — it supports async, WebSockets, and HTTP/2. This means you can
+deploy a Responder app anywhere that runs Python, using any ASGI server.
+
+
+Running Locally
+---------------
+
+During development, ``api.run()`` is all you need::
+
+    if __name__ == "__main__":
+        api.run()
+
+This starts a `uvicorn <https://www.uvicorn.org/>`_ server on
+``127.0.0.1:5042``. Uvicorn is a lightning-fast ASGI server built on
+`uvloop <https://uvloop.readthedocs.io/>`_ — it handles thousands of
+concurrent connections efficiently and protects against slowloris attacks,
+making a reverse proxy like nginx optional for many deployments.
+
+
+Docker
+------
+
+Docker is the most common way to package and deploy web applications.
+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 uv pip install --system responder
+    ENV PORT=80
+    EXPOSE 80
+    CMD ["python", "api.py"]
+
+Build and run::
+
+    $ docker build -t myapi .
+    $ 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. 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
+---------------
+
+Responder automatically honors the ``PORT`` environment variable. When
+``PORT`` is set, the server binds to ``0.0.0.0`` on that port — this is
+the convention that virtually every cloud platform uses.
+
+This means zero configuration on:
+
+- **Fly.io** — ``fly launch`` and you're done
+- **Railway** — push your code, Railway sets ``PORT``
+- **Render** — set start command to ``python api.py``
+- **Google Cloud Run** — containerize and deploy
+- **Azure Container Apps** — same pattern
+- **AWS App Runner** — and here too
+
+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
+----------------
+
+For production deployments where you want more control, bypass
+``api.run()`` and use uvicorn directly::
+
+    $ uvicorn api:api --host 0.0.0.0 --port 8000 --workers 4
+
+The ``--workers`` flag spawns multiple processes, each handling requests
+independently. A good starting point is 2-4 workers per CPU core.
+
+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
+-------------
+
+For high-traffic production deployments, you may want a reverse proxy like
+`nginx <https://nginx.org/>`_ or `Caddy <https://caddyserver.com/>`_ in
+front of your application for:
+
+- **SSL/TLS termination** — let the proxy handle HTTPS certificates
+- **Load balancing** — distribute traffic across multiple app instances
+- **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/guide-config.rst

@@ -0,0 +1,172 @@
+Configuration
+=============
+
+Every application needs different settings for different environments —
+debug mode in development, real secrets in production, different database
+URLs for testing. This guide covers how to manage configuration cleanly.
+
+
+Environment Variables
+---------------------
+
+The simplest and most universal approach. Environment variables work
+everywhere — locally, in Docker, on cloud platforms — and keep secrets
+out of your source code::
+
+    import os
+    import responder
+
+    api = responder.API(
+        debug=os.getenv("DEBUG", "false").lower() == "true",
+        secret_key=os.environ["SECRET_KEY"],
+        cors=os.getenv("CORS_ENABLED", "false").lower() == "true",
+    )
+
+Some variables Responder handles automatically:
+
+- ``PORT`` — when set, the server binds to ``0.0.0.0`` on this port
+
+Set variables in your shell::
+
+    $ export SECRET_KEY="your-secret-here"
+    $ export DEBUG=true
+    $ python app.py
+
+Or in a ``.env`` file (don't commit this to git)::
+
+    SECRET_KEY=your-secret-here
+    DEBUG=true
+
+
+Using .env Files
+----------------
+
+For local development, a ``.env`` file is convenient. Install
+``python-dotenv`` and load it at the top of your app::
+
+    $ uv pip install python-dotenv
+
+::
+
+    from dotenv import load_dotenv
+    load_dotenv()
+
+    import os
+    import responder
+
+    api = responder.API(
+        secret_key=os.environ["SECRET_KEY"],
+    )
+
+Add ``.env`` to your ``.gitignore`` — never commit secrets.
+
+
+Configuration Class Pattern
+----------------------------
+
+For larger applications, a configuration class keeps things organized::
+
+    import os
+
+    class Config:
+        SECRET_KEY = os.environ.get("SECRET_KEY", "dev-secret")
+        DEBUG = os.environ.get("DEBUG", "false").lower() == "true"
+        DATABASE_URL = os.environ.get("DATABASE_URL", "sqlite:///dev.db")
+        CORS_ORIGINS = os.environ.get("CORS_ORIGINS", "").split(",")
+
+    config = Config()
+
+    api = responder.API(
+        debug=config.DEBUG,
+        secret_key=config.SECRET_KEY,
+        cors=bool(config.CORS_ORIGINS[0]),
+        cors_params={"allow_origins": config.CORS_ORIGINS},
+    )
+
+This makes it easy to see all your settings in one place.
+
+
+Secret Key
+----------
+
+The ``secret_key`` is used to sign session cookies. If someone knows your
+secret key, they can forge session data and impersonate any user.
+
+Rules:
+
+- **Never use the default** in production
+- **Generate a random key**: ``python -c "import secrets; print(secrets.token_hex(32))"``
+- **Store it in an environment variable**, not in code
+- **Rotate it** if it's ever compromised (this invalidates all sessions)
+
+::
+
+    api = responder.API(secret_key=os.environ["SECRET_KEY"])
+
+
+Debug Mode
+----------
+
+Debug mode controls error page behavior:
+
+- **On** (``debug=True``): detailed error pages with tracebacks. Never
+  use this in production — it exposes your source code.
+- **Off** (``debug=False``): generic error pages. This is the default.
+
+::
+
+    api = responder.API(debug=True)  # development only
+
+A common pattern is to read it from the environment::
+
+    api = responder.API(debug=os.getenv("DEBUG") == "true")
+
+
+Allowed Hosts
+-------------
+
+In production, always set ``allowed_hosts`` to prevent Host header
+attacks. This should match the domain names your application serves::
+
+    api = responder.API(
+        allowed_hosts=["example.com", "www.example.com"],
+    )
+
+In development, you can use ``["*"]`` (the default) or specific local
+addresses::
+
+    api = responder.API(allowed_hosts=["localhost", "127.0.0.1"])
+
+
+Putting It All Together
+-----------------------
+
+A production-ready configuration setup::
+
+    import os
+    from dotenv import load_dotenv
+
+    load_dotenv()
+
+    import responder
+
+    api = responder.API(
+        debug=os.getenv("DEBUG", "false") == "true",
+        secret_key=os.environ["SECRET_KEY"],
+        allowed_hosts=os.getenv("ALLOWED_HOSTS", "*").split(","),
+        cors=bool(os.getenv("CORS_ORIGINS")),
+        cors_params={
+            "allow_origins": os.getenv("CORS_ORIGINS", "").split(","),
+            "allow_methods": ["GET", "POST", "PUT", "DELETE"],
+        },
+    )
+
+With a ``.env`` file for local development::
+
+    SECRET_KEY=dev-secret-do-not-use-in-prod
+    DEBUG=true
+    ALLOWED_HOSTS=localhost,127.0.0.1
+    CORS_ORIGINS=http://localhost:3000
+
+And environment variables set properly in production (via your cloud
+platform's dashboard, Docker secrets, or a secrets manager).

docs/source/index.rst

@@ -0,0 +1,134 @@
+Responder
+=========
+
+A familiar HTTP Service Framework for Python.
+
+.. code:: python
+
+   import responder
+
+   api = responder.API()
+
+   @api.route("/{greeting}")
+   async def greet_world(req, resp, *, greeting):
+       resp.text = f"{greeting}, world!"
+
+   if __name__ == '__main__':
+       api.run()
+
+Powered by `Starlette`_, `uvicorn`_, and good intentions. The ``async`` is optional.
+
+
+The Idea
+--------
+
+If you've ever used `Flask`_, the routing will look familiar. If you've
+used `Falcon`_, the request/response pattern will click immediately. And
+if you've used `Requests`_ — well, you'll feel right at home.
+
+Responder takes these ideas and brings them together. Every view receives
+a request and a response. You read from one and write to the other. No
+return values, no special response classes, no boilerplate.
+
+- ``resp.text`` sends text. ``resp.html`` sends HTML. ``resp.media`` sends JSON.
+- ``resp.file("path")`` serves a file. ``resp.content`` sends raw bytes.
+- ``req.headers`` is case-insensitive. ``req.params`` holds query parameters.
+- ``resp.status_code``, ``req.method``, ``req.url`` — the familiar ones.
+
+Set ``resp.media`` to a dict and the right thing happens. If the client
+asks for YAML, it gets YAML. Content negotiation is automatic.
+
+Responder and `FastAPI`_ are siblings — both built on Starlette, both
+born around the same time, both part of the push that made ASGI the
+future of Python web services. FastAPI went deep on type annotations
+and automatic validation. Responder went for simplicity and a mutable
+request/response pattern. Both projects are better for the other
+existing. Use whichever feels right.
+
+This is a passion project. It exists because building a web framework
+from scratch is one of the best ways to understand how the web works.
+It's a great fit for personal projects, prototyping, teaching, research,
+and anyone who values a clean API over a sprawling ecosystem. If you
+need battle-tested infrastructure at scale, FastAPI and Django will
+serve you well. If you want something small, expressive, and fun to
+work with — welcome.
+
+
+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 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.
+- Route groups for API versioning.
+- Signed cookie-based sessions.
+- Background tasks in a thread pool.
+- WebSocket support.
+
+
+Installation
+------------
+
+.. code-block:: shell
+
+    $ uv pip install responder
+
+Python 3.10 and above. That's it.
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: User Guide
+
+   quickstart
+   tour
+   deployment
+   testing
+   api
+   cli
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Tutorials
+
+   tutorial-rest
+   tutorial-sqlalchemy
+   tutorial-auth
+   tutorial-websockets
+   tutorial-middleware
+   tutorial-flask
+   guide-config
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Project
+
+   changes
+   Sandbox <sandbox>
+   backlog
+
+
+.. _Starlette: https://www.starlette.io/
+.. _uvicorn: https://www.uvicorn.org/
+.. _Flask: https://flask.palletsprojects.com/
+.. _Falcon: https://falconframework.org/
+.. _FastAPI: https://fastapi.tiangolo.com/
+.. _GraphQL: https://graphql.org/
+.. _Requests: https://requests.readthedocs.io/

docs/source/quickstart.rst

@@ -0,0 +1,384 @@
+Quick Start
+===========
+
+This guide will walk you through the basics of building a web service with
+Responder. By the end, you'll understand how HTTP requests and responses
+work, how to define routes, read data from clients, send data back, render
+HTML templates, and process work in the background.
+
+
+Create a Web Service
+--------------------
+
+Every web application starts with a single object — the application
+instance. In Responder, this is the ``API`` class. It holds your routes,
+middleware, templates, and configuration. Think of it as the central
+nervous system of your web service::
+
+    import responder
+
+    api = responder.API()
+
+That's it. One import, one line. You now have a fully functional ASGI
+application with gzip compression, static file serving, session support,
+and a production-ready server — all wired up and ready to go.
+
+
+Hello World
+-----------
+
+A web service isn't very useful until it can respond to requests. In HTTP,
+a *route* maps a URL path to a function that handles it. When a client
+(like a browser or ``curl``) sends a request to that path, your function
+runs and produces a response.
+
+Here's the simplest possible route::
+
+    @api.route("/")
+    def hello_world(req, resp):
+        resp.text = "hello, world!"
+
+Two things to notice:
+
+1. Every view function receives two arguments: ``req`` (the incoming
+   request) and ``resp`` (the outgoing response).
+2. You don't return anything. Instead, you *mutate* the response object
+   directly. This is a deliberate design choice — it keeps the API
+   consistent whether you're setting text, JSON, headers, cookies, or
+   status codes.
+
+
+Run the Server
+--------------
+
+Start your web service with a single call::
+
+    api.run()
+
+This spins up a production-grade `uvicorn <https://www.uvicorn.org/>`_
+server on port ``5042``, ready for incoming HTTP requests. Open
+``http://localhost:5042`` in your browser and you'll see your hello world
+response.
+
+You can customize the port with ``api.run(port=8000)``. The ``PORT``
+environment variable is also honored automatically — when set, Responder
+binds to ``0.0.0.0`` on that port, which is what cloud platforms expect.
+
+.. note::
+
+   Both sync and async views are supported. The ``async`` keyword is always
+   optional — use it when you need to ``await`` something, like reading a
+   request body or querying a database.
+
+
+Route Parameters
+----------------
+
+Static URLs like ``/about`` are useful, but most applications need dynamic
+routes — URLs that contain variable data, like a user ID or a product slug.
+
+In Responder, you declare route parameters using Python's f-string syntax::
+
+    @api.route("/hello/{who}")
+    def hello_to(req, resp, *, who):
+        resp.text = f"hello, {who}!"
+
+A ``GET`` request to ``/hello/world`` will respond with ``hello, world!``.
+A request to ``/hello/guido`` will respond with ``hello, guido!``.
+
+Route parameters are passed as *keyword-only* arguments (after the ``*``
+in the function signature). This is a Python feature that makes the
+interface explicit — you always know which arguments come from the URL.
+
+
+Type Convertors
+^^^^^^^^^^^^^^^
+
+By default, route parameters are strings. But often you want them as
+integers, UUIDs, or other types. Responder can convert them automatically
+using type annotations in the route pattern::
+
+    @api.route("/add/{a:int}/{b:int}")
+    async def add(req, resp, *, a, b):
+        resp.text = f"{a} + {b} = {a + b}"
+
+Here, ``a`` and ``b`` will arrive as Python ``int`` objects, not strings.
+If someone requests ``/add/3/hello``, they'll get a 404 — the route won't
+match because ``hello`` isn't a valid integer.
+
+Supported types:
+
+- ``str`` — matches any string without slashes (this is the default)
+- ``int`` — matches digits and converts to ``int``
+- ``float`` — matches decimal numbers and converts to ``float``
+- ``uuid`` — matches UUID strings like ``550e8400-e29b-41d4-a716-446655440000``
+- ``path`` — matches any string *including* slashes, useful for file paths
+  like ``/files/{filepath:path}``
+
+
+Sending Responses
+-----------------
+
+When an HTTP server receives a request, it must send back a response. Every
+HTTP response has three parts: a status code (like ``200 OK`` or ``404 Not
+Found``), headers (metadata like ``Content-Type``), and a body (the actual
+data).
+
+Responder lets you set all three by mutating the response object.
+
+**Text and HTML** — the simplest response types. ``resp.text`` sets the
+``Content-Type`` to ``text/plain``, while ``resp.html`` sets it to
+``text/html``::
+
+    resp.text = "plain text response"
+    resp.html = "<h1>HTML response</h1>"
+
+**JSON** — the lingua franca of web APIs. Set ``resp.media`` to any
+JSON-serializable Python object — a dict, a list, whatever — and Responder
+will serialize it to JSON and set the right headers::
+
+    @api.route("/hello/{who}/json")
+    def hello_json(req, resp, *, who):
+        resp.media = {"hello": who}
+
+If the client sends an ``Accept: application/x-yaml`` header, the same data
+will be returned as YAML instead. This is called *content negotiation* —
+the server and client agree on a format. It happens automatically.
+
+**Files** — serve a file from disk. Responder uses Python's ``mimetypes``
+module to figure out the ``Content-Type`` from the file extension::
+
+    resp.file("reports/annual.pdf")
+
+**Raw bytes** — for binary data like images or protocol buffers::
+
+    resp.content = b"\x89PNG\r\n..."
+
+**Status codes** — HTTP status codes tell the client what happened. ``200``
+means success, ``201`` means something was created, ``404`` means not found,
+``500`` means the server broke. Set it directly::
+
+    resp.status_code = 201
+
+**Headers** — HTTP headers carry metadata. Common ones include
+``Content-Type``, ``Cache-Control``, ``Authorization``, and custom
+application headers::
+
+    resp.headers["X-Custom"] = "value"
+
+**Redirects** — tell the client to go somewhere else::
+
+    api.redirect(resp, location="/new-url")
+
+This sends a ``301 Moved Permanently`` response by default. The client's
+browser will automatically follow the redirect.
+
+
+Reading Requests
+----------------
+
+The other half of HTTP is the request — the data the client sends to your
+server. This includes the HTTP method (GET, POST, PUT, DELETE), the URL,
+headers, query parameters, cookies, and optionally a body.
+
+Responder wraps all of this in the ``req`` object.
+
+**Method and URL** — every HTTP request has a method (what the client wants
+to do) and a URL (what resource it's about)::
+
+    req.method      # "get", "post", etc. (lowercase)
+    req.full_url    # "http://example.com/path?q=1"
+    req.url         # parsed URL object
+
+**Headers** — HTTP headers carry metadata from the client, like what
+content types it accepts, authentication tokens, and more. Responder's
+headers dict is case-insensitive, because the HTTP spec says header names
+are case-insensitive::
+
+    req.headers["Content-Type"]
+    req.headers["content-type"]  # same thing
+
+**Query parameters** — the part of the URL after the ``?``. These are
+commonly used for search, filtering, and pagination::
+
+    # GET /search?q=python&page=2
+    req.params["q"]     # "python"
+    req.params["page"]  # "2"
+
+Note that query parameters are always strings. If you need an integer,
+you'll need to convert it yourself: ``int(req.params["page"])``.
+
+**Path parameters** — the dynamic parts of the URL that matched your route
+pattern. These are also available on the request object, which is useful
+in before-request hooks where they aren't passed as function arguments::
+
+    req.path_params["user_id"]  # same as the keyword argument
+
+**Request body** — for POST, PUT, and PATCH requests, the client sends
+data in the body. Since reading the body is an I/O operation, you need to
+``await`` it::
+
+    # JSON body (the most common format for APIs)
+    data = await req.media()
+
+    # Form data (from HTML forms)
+    data = await req.media("form")
+
+    # File uploads (multipart)
+    files = await req.media("files")
+
+    # Raw bytes
+    body = await req.content
+
+    # Raw text
+    text = await req.text
+
+**Other useful properties**::
+
+    req.is_json     # True if the content type is JSON
+    req.cookies     # dict of cookies sent by the client
+    req.session     # session data (a signed, server-side dict)
+    req.client      # (host, port) tuple — the client's IP address
+    req.is_secure   # True if the request came over HTTPS
+
+
+Rendering Templates
+-------------------
+
+While APIs typically return JSON, many web applications need to render
+HTML pages. Responder includes built-in support for
+`Jinja2 <https://jinja.palletsprojects.com/>`_, one of the most popular
+templating engines in the Python ecosystem.
+
+Templates let you write HTML with placeholders that get filled in with
+dynamic data. This keeps your presentation logic (HTML) separate from
+your application logic (Python) — a pattern called
+*separation of concerns*.
+
+The simplest way to render a template is ``api.template()``. Templates
+are loaded from the ``templates/`` directory by default::
+
+    @api.route("/hello/{name}/html")
+    def hello_html(req, resp, *, name):
+        resp.html = api.template("hello.html", name=name)
+
+The template file ``templates/hello.html`` might look like::
+
+    <h1>Hello, {{ name }}!</h1>
+
+The ``{{ name }}`` part is a Jinja2 expression — it gets replaced with
+the value you passed in.
+
+You can also use the ``Templates`` class directly for more control over
+the template directory and configuration::
+
+    from responder.templates import Templates
+
+    templates = Templates(directory="my_templates")
+
+    @api.route("/page")
+    def page(req, resp):
+        resp.html = templates.render("page.html", title="Hello")
+
+For applications that need non-blocking template rendering (rare, but
+useful under extreme load), async rendering is supported::
+
+    templates = Templates(directory="templates", enable_async=True)
+    resp.html = await templates.render_async("page.html", title="Hello")
+
+And for quick one-off templates, you can render a string directly without
+a file::
+
+    resp.html = api.template_string("Hello, {{ name }}!", name="world")
+
+
+Background Tasks
+----------------
+
+Sometimes you want to accept a request, respond immediately, and do the
+actual processing later. This is a common pattern for operations that take
+a long time — sending emails, processing images, updating caches, or
+calling slow external APIs.
+
+Responder makes this easy with background tasks. Decorate any function
+with ``@api.background.task`` and it will run in a thread pool, separate
+from the request/response cycle::
+
+    @api.route("/incoming")
+    async def receive_incoming(req, resp):
+        data = await req.media()
+
+        @api.background.task
+        def process_data(data):
+            """This runs in a background thread."""
+            import time
+            time.sleep(10)  # simulate heavy work
+
+        process_data(data)
+
+        # This response is sent immediately, while process_data
+        # continues running in the background.
+        resp.media = {"status": "accepted"}
+
+The client gets an instant response — the heavy lifting happens after.
+This is the same pattern used by task queues like Celery, but much simpler
+for lightweight use cases where you don't need a full message broker.
+
+.. note::
+
+   Background tasks run in threads, not processes. They share memory with
+   your application, which makes them fast to start but means CPU-intensive
+   work will block the event loop. For heavy computation, consider a proper
+   task queue.
+
+
+Putting It All Together
+-----------------------
+
+Here's a complete, working Responder application that combines everything
+from this guide::
+
+    import responder
+
+    api = responder.API()
+
+    @api.route("/")
+    def index(req, resp):
+        resp.text = "Welcome to the API"
+
+    @api.route("/hello/{name}")
+    def greet(req, resp, *, name):
+        resp.media = {"message": f"hello, {name}!"}
+
+    @api.route("/add/{a:int}/{b:int}")
+    def add(req, resp, *, a, b):
+        resp.media = {"result": a + b}
+
+    @api.route("/echo", methods=["POST"])
+    async def echo(req, resp):
+        data = await req.media()
+        resp.media = {"received": data}
+
+    if __name__ == "__main__":
+        api.run()
+
+Save this as ``app.py``, run it with ``python app.py``, and try::
+
+    $ curl http://localhost:5042/
+    $ curl http://localhost:5042/hello/world
+    $ curl http://localhost:5042/add/3/4
+    $ curl -X POST http://localhost:5042/echo \
+        -H "Content-Type: application/json" -d '{"key": "value"}'
+
+From here, explore the :doc:`tour` for the full range of features, or
+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

@@ -0,0 +1,62 @@
+(sandbox)=
+# Development Sandbox
+
+## Setup
+
+Clone the repo and install all dependencies:
+```shell
+git clone https://github.com/kennethreitz/responder.git
+cd responder
+uv venv && source .venv/bin/activate
+uv pip install --upgrade --editable '.[develop,docs,release,test]'
+```
+
+## Running Tests
+```shell
+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
+```
+
+## Code Formatting
+```shell
+ruff format .        # auto-format
+ruff check --fix .   # lint and auto-fix
+```
+
+## Type Checking
+```shell
+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

@@ -0,0 +1,340 @@
+Testing
+=======
+
+Responder includes a built-in test client powered by Starlette's
+``TestClient``. You don't need to start a server — tests run in-process,
+making them fast and reliable. There's no separate test server to manage,
+no ports to allocate, and no race conditions to worry about. Just import
+your app and start making requests.
+
+
+Getting Started
+---------------
+
+Given a simple application in ``api.py``::
+
+    import responder
+
+    api = responder.API()
+
+    @api.route("/")
+    def hello(req, resp):
+        resp.text = "hello, world!"
+
+    if __name__ == "__main__":
+        api.run()
+
+You can test it with pytest. Every Responder ``API`` instance has a
+``requests`` property that gives you a test client — use it exactly like
+you'd use ``requests`` or ``httpx``::
+
+    # test_api.py
+    import api as service
+
+    def test_hello():
+        r = service.api.requests.get("/")
+        assert r.text == "hello, world!"
+
+Run your tests::
+
+    $ pytest
+
+That's really all there is to it. No configuration, no test server setup.
+
+
+Using Fixtures
+--------------
+
+For larger test suites, pytest fixtures keep things organized. Create a
+fixture that returns your API instance, and every test gets a fresh
+reference to it::
+
+    import pytest
+    import api as service
+
+    @pytest.fixture
+    def api():
+        return service.api
+
+    def test_hello(api):
+        r = api.requests.get("/")
+        assert r.text == "hello, world!"
+
+    def test_json(api):
+        @api.route("/data")
+        def data(req, resp):
+            resp.media = {"key": "value"}
+
+        r = api.requests.get(api.url_for(data))
+        assert r.json() == {"key": "value"}
+
+The ``api.url_for()`` method generates a URL for a given route endpoint,
+so you don't have to hard-code paths in your tests. If you rename a route
+later, your tests won't break.
+
+
+Testing JSON APIs
+-----------------
+
+Most APIs send and receive JSON. The test client makes this natural — pass
+``json=`` to send a JSON body, and call ``.json()`` on the response to
+parse it::
+
+    def test_create_item(api):
+        @api.route("/items")
+        async def create(req, resp):
+            data = await req.media()
+            resp.media = {"created": data}
+            resp.status_code = 201
+
+        r = api.requests.post(api.url_for(create), json={"name": "widget"})
+        assert r.status_code == 201
+        assert r.json() == {"created": {"name": "widget"}}
+
+You can also test content negotiation by setting the ``Accept`` header::
+
+    r = api.requests.get("/data", headers={"Accept": "application/x-yaml"})
+    assert "key: value" in r.text
+
+
+Testing Request Validation
+--------------------------
+
+If you're using Pydantic models for request validation, you can test
+that invalid inputs are properly rejected::
+
+    from pydantic import BaseModel
+
+    class Item(BaseModel):
+        name: str
+        price: float
+
+    def test_validation(api):
+        @api.route("/items", methods=["POST"], request_model=Item)
+        async def create(req, resp):
+            data = await req.media()
+            resp.media = data
+
+        # Valid request
+        r = api.requests.post("/items", json={"name": "thing", "price": 9.99})
+        assert r.status_code == 200
+
+        # Missing required field
+        r = api.requests.post("/items", json={"name": "thing"})
+        assert r.status_code == 422
+        assert "errors" in r.json()
+
+
+Testing File Uploads
+--------------------
+
+File uploads use the ``files`` parameter, just like the ``requests``
+library. Each file is a tuple of ``(filename, content, content_type)``::
+
+    def test_upload(api):
+        @api.route("/upload")
+        async def upload(req, resp):
+            files = await req.media("files")
+            resp.media = {"received": list(files.keys())}
+
+        files = {"doc": ("report.pdf", b"content", "application/pdf")}
+        r = api.requests.post(api.url_for(upload), files=files)
+        assert r.json() == {"received": ["doc"]}
+
+
+Testing Headers and Cookies
+----------------------------
+
+Check response headers and cookies just like you would with any HTTP
+client::
+
+    def test_headers(api):
+        @api.route("/")
+        def view(req, resp):
+            resp.headers["X-Custom"] = "hello"
+            resp.cookies["session"] = "abc123"
+
+        r = api.requests.get("/")
+        assert r.headers["X-Custom"] == "hello"
+        assert "session" in r.cookies
+
+
+Testing WebSockets
+------------------
+
+WebSocket tests use Starlette's ``TestClient`` directly, since WebSocket
+connections require a different protocol. The ``websocket_connect`` context
+manager gives you a connection you can send and receive on::
+
+    from starlette.testclient import TestClient
+
+    def test_websocket(api):
+        @api.route("/ws", websocket=True)
+        async def ws(ws):
+            await ws.accept()
+            name = await ws.receive_text()
+            await ws.send_text(f"hello, {name}!")
+            await ws.close()
+
+        client = TestClient(api)
+        with client.websocket_connect("/ws") as ws:
+            ws.send_text("world")
+            assert ws.receive_text() == "hello, world!"
+
+
+Testing Error Handling
+----------------------
+
+By default, the test client raises exceptions from your route handlers,
+which is usually what you want — it makes bugs obvious. But when you're
+testing error handling specifically, you want to see the error response
+instead. Disable exception propagation with ``raise_server_exceptions``::
+
+    from starlette.testclient import TestClient
+
+    def test_500(api):
+        @api.route("/fail")
+        def fail(req, resp):
+            raise ValueError("something broke")
+
+        client = TestClient(api, raise_server_exceptions=False)
+        r = client.get(api.url_for(fail))
+        assert r.status_code == 500
+
+If you've registered a custom exception handler, you can test that too::
+
+    def test_custom_error(api):
+        @api.exception_handler(ValueError)
+        async def handle(req, resp, exc):
+            resp.status_code = 400
+            resp.media = {"error": str(exc)}
+
+        @api.route("/fail")
+        def fail(req, resp):
+            raise ValueError("bad input")
+
+        client = TestClient(api, raise_server_exceptions=False)
+        r = client.get(api.url_for(fail))
+        assert r.status_code == 400
+        assert r.json() == {"error": "bad input"}
+
+
+Testing Lifespan Events
+-----------------------
+
+If your app uses startup and shutdown events (for database connections,
+caches, etc.), you need the test client to trigger them. Wrap the client
+in a ``with`` block — startup runs on enter, shutdown runs on exit::
+
+    def test_with_lifespan(api):
+        started = {"value": False}
+
+        @api.on_event("startup")
+        async def on_startup():
+            started["value"] = True
+
+        @api.route("/")
+        def check(req, resp):
+            resp.media = {"started": started["value"]}
+
+        with api.requests as session:
+            r = session.get("http://;/")
+            assert r.json() == {"started": True}
+
+Without the ``with`` block, lifespan events won't fire, which can lead to
+confusing test failures if your routes depend on startup initialization.
+
+
+Testing Before and After Hooks
+------------------------------
+
+Before-request and after-request hooks run automatically during tests,
+just like in production. You can verify their effects on the response::
+
+    def test_hooks(api):
+        @api.route(before_request=True)
+        def add_version(req, resp):
+            resp.headers["X-Version"] = "3.2"
+
+        @api.after_request()
+        def add_timing(req, resp):
+            resp.headers["X-Served-By"] = "responder"
+
+        @api.route("/")
+        def view(req, resp):
+            resp.text = "ok"
+
+        r = api.requests.get("/")
+        assert r.headers["X-Version"] == "3.2"
+        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
+----
+
+- **Keep tests fast.** The in-process test client is already fast — no
+  network overhead. Avoid ``time.sleep()`` in tests.
+
+- **One API per test** when testing configuration. If you need a specific
+  ``API()`` configuration (like ``cors=True``), create a new instance
+  in the test rather than sharing the fixture.
+
+- Use ``api.url_for()`` instead of hard-coded paths. It's a small
+  thing, but it makes refactoring painless.
+
+- **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

@@ -0,0 +1,684 @@
+Feature Tour
+============
+
+This section walks through Responder's features in depth. Each section
+explains the concept, shows working code, and explains the design choices
+behind it. If you're new to web development, this is a good place to learn
+how modern web frameworks work under the hood.
+
+
+Method Filtering
+----------------
+
+HTTP defines several *methods* (also called verbs) that describe what a
+client wants to do with a resource. The most common are:
+
+- ``GET`` — retrieve data
+- ``POST`` — create something new
+- ``PUT`` — replace something entirely
+- ``PATCH`` — update part of something
+- ``DELETE`` — remove something
+
+By default, a Responder route matches all methods. This is fine for simple
+endpoints, but REST APIs typically map different methods to different
+operations. Use the ``methods`` parameter to restrict a route::
+
+    @api.route("/items", methods=["GET"])
+    def list_items(req, resp):
+        resp.media = {"items": []}
+
+    @api.route("/items", methods=["POST"], check_existing=False)
+    async def create_item(req, resp):
+        data = await req.media()
+        resp.media = {"created": data}
+
+Note the ``check_existing=False`` — Responder normally prevents you from
+registering two routes with the same path (to catch typos). When you
+intentionally want multiple handlers for the same path with different
+methods, you need to opt in.
+
+
+Class-Based Views
+-----------------
+
+Function-based views are great for simple endpoints, but sometimes you want
+to group related HTTP methods together into a single resource. This is
+where class-based views come in — a pattern popularized by
+`Falcon <https://falconframework.org/>`_.
+
+Responder dispatches to the appropriate method handler based on the HTTP
+method::
+
+    @api.route("/{greeting}")
+    class GreetingResource:
+        def on_get(self, req, resp, *, greeting):
+            resp.text = f"{greeting}, world!"
+
+        def on_post(self, req, resp, *, greeting):
+            resp.media = {"received": greeting}
+
+        def on_request(self, req, resp, *, greeting):
+            """Called on EVERY request, before the method-specific handler."""
+            resp.headers["X-Greeting"] = greeting
+
+The ``on_request`` method is called for all HTTP methods, much like
+middleware scoped to a single route. Method-specific handlers (``on_get``,
+``on_post``, ``on_put``, ``on_delete``, etc.) are called after.
+
+No inheritance required — just define a class with the right method names.
+This is simpler than Django's ``View`` classes and more Pythonic than
+framework-specific base classes.
+
+
+Lifespan Events
+---------------
+
+Real applications need to set up resources when they start (database
+connection pools, ML models, caches) and tear them down when they stop.
+This is called the application *lifespan*.
+
+The modern approach is the *context manager* pattern, where startup and
+shutdown are two halves of the same block::
+
+    from contextlib import asynccontextmanager
+
+    @asynccontextmanager
+    async def lifespan(app):
+        # Startup — runs before the first request
+        print("connecting to database...")
+        yield
+        # Shutdown — runs after the server stops
+        print("closing connections...")
+
+    api = responder.API(lifespan=lifespan)
+
+Everything before ``yield`` runs at startup. Everything after runs at
+shutdown. If startup fails, the server won't start. If shutdown raises,
+it's logged but the server still exits.
+
+The traditional event decorator style also works::
+
+    @api.on_event("startup")
+    async def startup():
+        print("starting up")
+
+    @api.on_event("shutdown")
+    async def shutdown():
+        print("shutting down")
+
+The context manager is preferred for new code — it keeps related startup
+and shutdown logic together and makes resource cleanup more explicit.
+
+
+Serving Files
+-------------
+
+Web applications often need to serve files — downloads, reports, images.
+Responder makes this simple with ``resp.file()``, which reads a file from
+disk and sets the ``Content-Type`` header automatically using Python's
+``mimetypes`` module::
+
+    @api.route("/download")
+    def download(req, resp):
+        resp.file("reports/annual.pdf")
+
+You can override the content type if the automatic detection isn't right::
+
+    @api.route("/image")
+    def image(req, resp):
+        resp.file("photos/cat.jpg", content_type="image/jpeg")
+
+For large files, use ``resp.stream_file()`` to avoid loading the entire
+file into memory. This streams the file in chunks::
+
+    @api.route("/export")
+    def export(req, resp):
+        resp.stream_file("data/export.csv")
+
+
+Custom Error Handling
+---------------------
+
+In production, you don't want your users to see raw Python tracebacks.
+Responder lets you register custom handlers for specific exception types,
+so you can return clean, structured error responses::
+
+    @api.exception_handler(ValueError)
+    async def handle_value_error(req, resp, exc):
+        resp.status_code = 400
+        resp.media = {"error": str(exc)}
+
+Now, any route that raises a ``ValueError`` will return a clean JSON
+response with a 400 status code instead of a generic 500 error page.
+
+This is a common pattern in API development — you define your own exception
+classes for different error conditions, register handlers for each, and
+your API always returns consistent, machine-readable error responses.
+
+
+Before-Request Hooks
+--------------------
+
+Sometimes you need to run the same code before every request —
+authentication checks, request logging, adding common headers, or setting
+up per-request state. Before-request hooks let you do this without
+duplicating code in every route::
+
+    @api.route(before_request=True)
+    def add_headers(req, resp):
+        resp.headers["X-API-Version"] = "3.2"
+
+**Short-circuiting** is the really powerful part. If your hook sets
+``resp.status_code``, the route handler is skipped entirely and the
+response is sent immediately. This is the pattern for authentication::
+
+    @api.route(before_request=True)
+    def auth_check(req, resp):
+        if "Authorization" not in req.headers:
+            resp.status_code = 401
+            resp.media = {"error": "unauthorized"}
+
+If the ``Authorization`` header is missing, the client gets a 401 response
+and the actual route handler never runs. This is cleaner than adding
+auth checks to every individual route.
+
+
+After-Request Hooks
+-------------------
+
+The complement to before-request hooks. After-request hooks run after the
+route handler completes but before the response is sent. They're useful
+for logging, adding response headers, or any post-processing::
+
+    @api.after_request()
+    def log_response(req, resp):
+        print(f"{req.method} {req.full_url} -> {resp.status_code}")
+
+    @api.after_request()
+    async def add_timing(req, resp):
+        resp.headers["X-Served-By"] = "responder"
+
+
+WebSocket Support
+-----------------
+
+HTTP is a request-response protocol — the client asks, the server answers.
+But some applications need real-time, bidirectional communication: chat
+apps, live dashboards, multiplayer games, collaborative editors.
+
+`WebSockets <https://en.wikipedia.org/wiki/WebSocket>`_ solve this by
+upgrading an HTTP connection into a persistent, full-duplex channel where
+both sides can send messages at any time::
+
+    @api.route("/ws", websocket=True)
+    async def websocket(ws):
+        await ws.accept()
+        while True:
+            name = await ws.receive_text()
+            await ws.send_text(f"Hello {name}!")
+        await ws.close()
+
+You can send and receive in multiple formats:
+
+- ``send_text`` / ``receive_text`` — plain text strings
+- ``send_json`` / ``receive_json`` — JSON objects (auto-serialized)
+- ``send_bytes`` / ``receive_bytes`` — raw binary data
+
+WebSocket routes are marked with ``websocket=True`` in the route decorator.
+They receive a ``ws`` object instead of ``req`` and ``resp``.
+
+
+Server-Sent Events (SSE)
+-------------------------
+
+SSE is a simpler alternative to WebSockets for *one-way* real-time
+communication — the server pushes events to the client, but the client
+can't send messages back. This is perfect for live feeds, progress bars,
+notification streams, and AI response streaming.
+
+Unlike WebSockets, SSE works over plain HTTP, is automatically reconnected
+by the browser, and doesn't require any special client-side libraries::
+
+    @api.route("/events")
+    async def events(req, resp):
+        @resp.sse
+        async def stream():
+            for i in range(10):
+                yield {"data": f"message {i}"}
+
+On the client side, you consume SSE events with JavaScript's built-in
+``EventSource`` API::
+
+    const source = new EventSource("/events");
+    source.onmessage = (event) => {
+        console.log(event.data);
+    };
+
+Each yielded value can be a string (treated as data) or a dict with the
+standard SSE fields::
+
+    yield {"event": "update", "data": "hello", "id": "1", "retry": "5000"}
+    yield "simple string message"
+
+
+GraphQL
+-------
+
+`GraphQL <https://graphql.org/>`_ is a query language for APIs that lets
+clients request exactly the data they need — no more, no less. Instead of
+multiple REST endpoints, you define a schema and let clients query it.
+
+Responder includes built-in GraphQL support via
+`Graphene <https://graphene-python.org/>`_. Set up a full GraphQL endpoint
+with a single method call::
+
+    import graphene
+
+    class Query(graphene.ObjectType):
+        hello = graphene.String(name=graphene.String(default_value="stranger"))
+
+        def resolve_hello(self, info, name):
+            return f"Hello {name}"
+
+    api.graphql("/graphql", schema=graphene.Schema(query=Query))
+
+Visiting ``/graphql`` in a browser renders the
+`GraphiQL <https://github.com/graphql/graphiql>`_ interactive IDE, where
+you can explore your schema, write queries, and see results in real-time.
+Programmatic clients can POST JSON queries to the same endpoint.
+
+You can access the Responder request and response objects in your resolvers
+through ``info.context["request"]`` and ``info.context["response"]``.
+
+
+OpenAPI Documentation
+---------------------
+
+`OpenAPI <https://www.openapis.org/>`_ (formerly Swagger) is the industry
+standard for describing REST APIs. An OpenAPI specification lets you
+auto-generate interactive documentation, client libraries, and validation
+logic.
+
+Responder generates OpenAPI specs from your code::
+
+    api = responder.API(
+        title="Pet Store",
+        version="1.0",
+        openapi="3.0.2",
+        docs_route="/docs",
+    )
+
+This gives you:
+
+- An OpenAPI schema at ``/schema.yml``
+- Interactive Swagger UI documentation at ``/docs``
+
+There are three ways to document your endpoints.
+
+**Pydantic models** — the recommended approach. Use ``request_model`` and
+``response_model`` to annotate your routes, and Responder generates the
+schema automatically. When ``request_model`` is set, request bodies are
+also validated automatically — invalid inputs get a ``422`` response with
+detailed error messages::
+
+    from pydantic import BaseModel
+
+    class PetIn(BaseModel):
+        name: str
+        age: int = 0
+
+    class PetOut(BaseModel):
+        id: int
+        name: str
+        age: int
+
+    @api.route("/pets", methods=["POST"],
+               request_model=PetIn, response_model=PetOut)
+    async def create_pet(req, resp):
+        data = await req.media()
+        resp.media = {"id": 1, **data}
+
+When ``response_model`` is set, the response is serialized through the
+model — extra fields are stripped and types are enforced.
+
+**YAML docstrings** — for full control, embed OpenAPI YAML in the
+docstring::
+
+    @api.route("/pets")
+    def list_pets(req, resp):
+        """A list of pets.
+        ---
+        get:
+            description: Get all pets
+            responses:
+                200:
+                    description: A list of pets
+        """
+        resp.media = [{"name": "Fido"}]
+
+**Marshmallow schemas** — if you're already using marshmallow::
+
+    from marshmallow import Schema, fields
+
+    @api.schema("Pet")
+    class PetSchema(Schema):
+        name = fields.Str()
+
+All three approaches can be mixed in the same API. You can choose from
+multiple documentation themes: ``swagger_ui`` (default), ``redoc``,
+``rapidoc``, or ``elements``.
+
+
+Route Groups
+------------
+
+As your application grows, you'll want to organize routes logically.
+Route groups let you share a URL prefix across related endpoints — a
+common pattern for API versioning::
+
+    v1 = api.group("/v1")
+
+    @v1.route("/users")
+    def list_users(req, resp):
+        resp.media = []
+
+    @v1.route("/users/{user_id:int}")
+    def get_user(req, resp, *, user_id):
+        resp.media = {"id": user_id}
+
+    v2 = api.group("/v2")
+
+    @v2.route("/users")
+    def list_users_v2(req, resp):
+        resp.media = {"users": [], "total": 0}
+
+This keeps your code organized without affecting the routing logic.
+
+
+Mounting Other Apps
+-------------------
+
+Responder can mount any WSGI or ASGI application at a subroute. This is
+incredibly useful for gradual migrations — you can run Flask and Responder
+side by side, moving routes over one at a time::
+
+    from flask import Flask
+
+    flask_app = Flask(__name__)
+
+    @flask_app.route("/")
+    def hello():
+        return "Hello from Flask!"
+
+    api.mount("/flask", flask_app)
+
+Requests to ``/flask/`` will be handled by Flask. Everything else goes
+through Responder. Both WSGI and ASGI apps are supported — Responder
+wraps WSGI apps in an ASGI adapter automatically.
+
+You can also mount `marimo <https://marimo.io/>`_ notebooks as
+interactive dashboards within your API::
+
+    import marimo
+
+    server = (
+        marimo.create_asgi_app()
+        .with_app(path="", root="./notebooks/dashboard.py")
+        .with_app(path="/analysis", root="./notebooks/analysis.py")
+    )
+
+    api.mount("/notebooks", server.build())
+
+Notebooks are served at ``/notebooks/`` and ``/notebooks/analysis``,
+with full interactivity — reactive cells, widgets, plots, and all.
+
+
+Cookies
+-------
+
+`Cookies <https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies>`_ are
+small pieces of data that the server asks the browser to store and send
+back with every subsequent request. They're the foundation of sessions,
+authentication tokens, and user preferences on the web.
+
+Reading and writing cookies is straightforward::
+
+    # Read cookies from the request
+    session_id = req.cookies.get("session_id")
+
+    # Set a cookie on the response
+    resp.cookies["hello"] = "world"
+
+For production use, you'll want to set security directives. The
+``httponly`` flag prevents JavaScript from reading the cookie (defending
+against XSS attacks), and ``secure`` ensures it's only sent over HTTPS::
+
+    resp.set_cookie(
+        "token",
+        value="abc123",
+        max_age=3600,        # expires in 1 hour
+        secure=True,         # HTTPS only
+        httponly=True,        # no JavaScript access
+        path="/",
+    )
+
+
+Cookie-Based Sessions
+---------------------
+
+Sessions let you store per-user data across multiple requests. Responder's
+built-in sessions are cookie-based — the session data is serialized, signed
+with your secret key, and stored in a cookie. The signature prevents
+tampering: if someone modifies the cookie, the signature won't match and
+the data will be rejected::
+
+    @api.route("/login")
+    def login(req, resp):
+        resp.session["username"] = "alice"
+
+    @api.route("/profile")
+    def profile(req, resp):
+        resp.media = {"user": req.session.get("username")}
+
+.. warning::
+
+   Always set a secret key in production. The default key is not secret::
+
+       api = responder.API(secret_key="your-secret-key-here")
+
+
+Static Files
+------------
+
+Most web applications serve static assets — CSS stylesheets, JavaScript
+files, images, fonts. Responder serves these from the ``static/`` directory
+by default::
+
+    api = responder.API(static_dir="static", static_route="/static")
+
+Place your assets in the ``static/`` directory and they'll be served
+automatically at ``/static/style.css``, ``/static/app.js``, etc.
+
+For single-page applications (React, Vue, Angular), you can serve
+``index.html`` as the default response for all unmatched routes::
+
+    api.add_route("/", static=True)
+
+
+CORS
+----
+
+`CORS <https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS>`_ (Cross-
+Origin Resource Sharing) is a security mechanism that controls which
+websites can make requests to your API. Browsers enforce this — if your
+API is at ``api.example.com`` and your frontend is at ``app.example.com``,
+the browser will block requests unless your API explicitly allows it.
+
+Enable CORS and configure which origins are allowed::
+
+    api = responder.API(cors=True, cors_params={
+        "allow_origins": ["https://app.example.com"],
+        "allow_methods": ["GET", "POST"],
+        "allow_headers": ["*"],
+        "allow_credentials": True,
+        "max_age": 600,
+    })
+
+The default policy is restrictive — you must explicitly allow each origin.
+Using ``["*"]`` for allow_origins permits any website to call your API,
+which is fine for public APIs but not for private ones.
+
+
+HSTS
+----
+
+`HSTS <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security>`_
+(HTTP Strict Transport Security) tells browsers to always use HTTPS when
+communicating with your server. Once a browser sees the HSTS header, it
+will refuse to connect over plain HTTP, even if the user types ``http://``
+in the address bar::
+
+    api = responder.API(enable_hsts=True)
+
+
+Trusted Hosts
+-------------
+
+The ``Host`` header in an HTTP request tells the server which domain name
+the client used. Attackers can forge this header to trick your application
+into generating URLs to malicious domains (a class of attack called *Host
+header injection*).
+
+Restrict which hostnames your application accepts::
+
+    api = responder.API(allowed_hosts=["example.com", "*.example.com"])
+
+Requests with unrecognized hosts get a ``400 Bad Request``. Wildcard
+patterns are supported. By default, all hostnames are allowed.
+
+
+Request ID
+----------
+
+In distributed systems, tracing a single request across multiple services
+is essential for debugging. Request IDs are unique identifiers attached to
+each request — if something goes wrong, you can search your logs for that
+ID and find every related event.
+
+Responder can auto-generate request IDs. If the client sends an
+``X-Request-ID`` header (common in microservice architectures), it's
+forwarded. Otherwise, a new UUID is generated::
+
+    api = responder.API(request_id=True)
+
+The ID appears in the ``X-Request-ID`` response header.
+
+
+Rate Limiting
+-------------
+
+Rate limiting prevents individual clients from overwhelming your API with
+too many requests. It's essential for public APIs, and good practice even
+for internal ones.
+
+Responder includes a built-in token bucket rate limiter::
+
+    from responder.ext.ratelimit import RateLimiter
+
+    limiter = RateLimiter(requests=100, period=60)  # 100 req/min
+    limiter.install(api)
+
+When the limit is exceeded, clients receive a ``429 Too Many Requests``
+response with a ``Retry-After`` header. Every response includes
+``X-RateLimit-Limit`` and ``X-RateLimit-Remaining`` headers so clients
+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
+-----------
+
+`MessagePack <https://msgpack.org/>`_ is a binary serialization format
+that's more compact and faster to parse than JSON. It's useful for
+high-throughput APIs, IoT devices, and anywhere bandwidth matters.
+
+Responder supports MessagePack alongside JSON and YAML::
+
+    # Decode a MessagePack request body
+    data = await req.media("msgpack")
+
+    # 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. You can also explicitly decode MessagePack request
+bodies by passing ``"msgpack"`` to ``req.media()``.

docs/source/tutorial-auth.rst

@@ -0,0 +1,244 @@
+Authentication
+==============
+
+Every API that handles user data needs authentication — a way to verify
+who is making a request. This guide covers the most common patterns:
+API keys, JWT tokens, and how to build reusable auth guards with
+Responder's before-request hooks.
+
+
+API Key Authentication
+----------------------
+
+The simplest approach. The client sends a secret key in a header, and
+your server checks it against a known value. This is common for
+server-to-server communication and simple APIs::
+
+    API_KEYS = {"sk-abc123", "sk-def456"}
+
+    @api.route(before_request=True)
+    def check_api_key(req, resp):
+        key = req.headers.get("X-API-Key")
+        if key not in API_KEYS:
+            resp.status_code = 401
+            resp.media = {"error": "Invalid or missing API key"}
+
+Because the before-request hook sets ``resp.status_code``, the route
+handler is skipped entirely for unauthorized requests. The client never
+reaches your endpoint — the guard catches them first.
+
+The client sends the key like this::
+
+    $ curl -H "X-API-Key: sk-abc123" http://localhost:5042/protected
+
+
+Bearer Token Authentication
+----------------------------
+
+Bearer tokens are the standard for modern APIs. The client sends a token
+in the ``Authorization`` header, and the server validates it. The most
+common format is `JWT <https://jwt.io/>`_ (JSON Web Tokens).
+
+Install PyJWT::
+
+    $ uv pip install pyjwt
+
+Create a helper to encode and decode tokens::
+
+    import jwt
+    from datetime import datetime, timedelta, timezone
+
+    SECRET = "your-secret-key"
+
+    def create_token(user_id: int) -> str:
+        payload = {
+            "sub": user_id,
+            "exp": datetime.now(timezone.utc) + timedelta(hours=24),
+        }
+        return jwt.encode(payload, SECRET, algorithm="HS256")
+
+    def verify_token(token: str) -> dict | None:
+        try:
+            return jwt.decode(token, SECRET, algorithms=["HS256"])
+        except jwt.InvalidTokenError:
+            return None
+
+Add a login endpoint that issues tokens, and a before-request hook that
+verifies them::
+
+    @api.route("/login", methods=["POST"])
+    async def login(req, resp):
+        data = await req.media()
+        # In a real app, check credentials against a database
+        if data.get("username") == "admin" and data.get("password") == "secret":
+            token = create_token(user_id=1)
+            resp.media = {"token": token}
+        else:
+            resp.status_code = 401
+            resp.media = {"error": "Invalid credentials"}
+
+    @api.route(before_request=True)
+    def auth_guard(req, resp):
+        # Skip auth for the login endpoint itself
+        if req.url.path == "/login":
+            return
+
+        auth = req.headers.get("Authorization", "")
+        if not auth.startswith("Bearer "):
+            resp.status_code = 401
+            resp.media = {"error": "Missing bearer token"}
+            return
+
+        token = auth[7:]  # Strip "Bearer "
+        payload = verify_token(token)
+        if payload is None:
+            resp.status_code = 401
+            resp.media = {"error": "Invalid or expired token"}
+            return
+
+        # Store the authenticated user on the request state
+        req.state.user_id = payload["sub"]
+
+Now any route can access the authenticated user::
+
+    @api.route("/me")
+    def get_me(req, resp):
+        resp.media = {"user_id": req.state.user_id}
+
+The client flow:
+
+1. ``POST /login`` with credentials → receive a token
+2. Include ``Authorization: Bearer <token>`` on every subsequent request
+3. The token expires after 24 hours — the client must log in again
+
+
+Skipping Auth for Public Routes
+--------------------------------
+
+The example above skips auth for ``/login`` by checking the path. For
+more control, you can use a set of public paths::
+
+    PUBLIC_PATHS = {"/login", "/signup", "/health", "/docs", "/schema.yml"}
+
+    @api.route(before_request=True)
+    def auth_guard(req, resp):
+        if req.url.path in PUBLIC_PATHS:
+            return
+        # ... check token
+
+
+Custom Exception for Auth Errors
+---------------------------------
+
+For cleaner code, define a custom exception and register a handler::
+
+    class AuthError(Exception):
+        def __init__(self, message="Unauthorized", status_code=401):
+            self.message = message
+            self.status_code = status_code
+
+    @api.exception_handler(AuthError)
+    async def handle_auth_error(req, resp, exc):
+        resp.status_code = exc.status_code
+        resp.media = {"error": exc.message}
+
+Now your auth guard can simply raise::
+
+    @api.route(before_request=True)
+    def auth_guard(req, resp):
+        if req.url.path in PUBLIC_PATHS:
+            return
+        if "Authorization" not in req.headers:
+            raise AuthError("Missing authorization header")
+
+
+Using Sessions for Web Apps
+----------------------------
+
+For traditional web applications (with HTML pages and forms), cookie-based
+sessions are simpler than tokens. The browser handles cookies automatically
+— no client-side token management needed::
+
+    @api.route("/login", methods=["POST"])
+    async def login(req, resp):
+        data = await req.media("form")
+        if data["username"] == "admin" and data["password"] == "secret":
+            resp.session["user"] = data["username"]
+            api.redirect(resp, location="/dashboard")
+        else:
+            resp.status_code = 401
+            resp.html = "<p>Invalid credentials</p>"
+
+    @api.route("/dashboard")
+    def dashboard(req, resp):
+        user = req.session.get("user")
+        if not user:
+            api.redirect(resp, location="/login")
+            return
+        resp.html = f"<h1>Welcome, {user}!</h1>"
+
+    @api.route("/logout")
+    def logout(req, resp):
+        resp.session.clear()
+        api.redirect(resp, location="/login")
+
+Remember to set a proper secret key::
+
+    api = responder.API(secret_key="your-production-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-flask.rst

@@ -0,0 +1,192 @@
+Migrating from Flask
+====================
+
+If you're coming from Flask, you'll find Responder familiar but different
+in a few key ways. This guide maps Flask concepts to their Responder
+equivalents and shows you how to translate common patterns.
+
+
+The Big Differences
+-------------------
+
+**No return values.** In Flask, you return a response. In Responder, you
+mutate it. This is the single biggest difference:
+
+Flask::
+
+    @app.route("/")
+    def hello():
+        return "hello, world!"
+
+Responder::
+
+    @api.route("/")
+    def hello(req, resp):
+        resp.text = "hello, world!"
+
+**Explicit request and response.** Flask uses a global ``request`` object
+(via thread-local magic). Responder passes ``req`` and ``resp`` explicitly.
+No magic, no import needed — they're right there in the function signature.
+
+**ASGI, not WSGI.** Flask runs on WSGI, which is synchronous. Responder
+runs on ASGI, which supports async natively. You can still write sync
+views — Responder runs them in a thread pool automatically.
+
+
+Quick Reference
+---------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 40 60
+
+   * - Flask
+     - Responder
+   * - ``Flask(__name__)``
+     - ``responder.API()``
+   * - ``return "text"``
+     - ``resp.text = "text"``
+   * - ``return jsonify(data)``
+     - ``resp.media = data``
+   * - ``return render_template("t.html", x=1)``
+     - ``resp.html = api.template("t.html", x=1)``
+   * - ``request.args["q"]``
+     - ``req.params["q"]``
+   * - ``request.json``
+     - ``await req.media()``
+   * - ``request.form``
+     - ``await req.media("form")``
+   * - ``request.headers["X"]``
+     - ``req.headers["X"]``
+   * - ``request.method``
+     - ``req.method``
+   * - ``request.cookies["x"]``
+     - ``req.cookies["x"]``
+   * - ``session["x"] = 1``
+     - ``resp.session["x"] = 1``
+   * - ``abort(404)``
+     - ``resp.status_code = 404``
+   * - ``redirect("/new")``
+     - ``api.redirect(resp, location="/new")``
+   * - ``@app.before_request``
+     - ``@api.route(before_request=True)``
+   * - ``@app.errorhandler(404)``
+     - ``@api.exception_handler(ValueError)``
+   * - ``app.run(debug=True)``
+     - ``api.run(debug=True)``
+
+
+Route Parameters
+----------------
+
+Flask uses ``<angle_brackets>``. Responder uses ``{curly_braces}``
+with the same type convertor idea:
+
+Flask::
+
+    @app.route("/users/<int:user_id>")
+    def get_user(user_id):
+        return jsonify({"id": user_id})
+
+Responder::
+
+    @api.route("/users/{user_id:int}")
+    def get_user(req, resp, *, user_id):
+        resp.media = {"id": user_id}
+
+Note the ``*`` — route parameters are keyword-only arguments in
+Responder. This makes the interface explicit about which arguments
+come from the URL.
+
+
+JSON APIs
+---------
+
+Flask::
+
+    @app.route("/api/items", methods=["POST"])
+    def create_item():
+        data = request.json
+        # ... create item
+        return jsonify(item), 201
+
+Responder::
+
+    @api.route("/api/items", methods=["POST"])
+    async def create_item(req, resp):
+        data = await req.media()
+        # ... create item
+        resp.media = item
+        resp.status_code = 201
+
+The ``await`` is needed because reading the request body is an async
+I/O operation. This is more explicit than Flask's approach, and it
+means the event loop isn't blocked while waiting for the body to arrive.
+
+
+Templates
+---------
+
+Both use Jinja2. The syntax is nearly identical:
+
+Flask::
+
+    @app.route("/hello/<name>")
+    def hello(name):
+        return render_template("hello.html", name=name)
+
+Responder::
+
+    @api.route("/hello/{name}")
+    def hello(req, resp, *, name):
+        resp.html = api.template("hello.html", name=name)
+
+
+Blueprints → Route Groups
+--------------------------
+
+Flask uses Blueprints to organize routes. Responder has route groups:
+
+Flask::
+
+    bp = Blueprint("api", __name__, url_prefix="/api")
+
+    @bp.route("/users")
+    def list_users():
+        return jsonify([])
+
+    app.register_blueprint(bp)
+
+Responder::
+
+    api_v1 = api.group("/api")
+
+    @api_v1.route("/users")
+    def list_users(req, resp):
+        resp.media = []
+
+
+Gradual Migration
+-----------------
+
+You don't have to migrate all at once. Responder can mount your existing
+Flask app at a subroute, so you can move endpoints over one at a time::
+
+    from flask import Flask
+
+    flask_app = Flask(__name__)
+
+    # Your existing Flask routes stay here
+    @flask_app.route("/legacy")
+    def legacy():
+        return "old endpoint"
+
+    # Mount Flask under /old, new routes go on Responder
+    api.mount("/old", flask_app)
+
+    @api.route("/new")
+    def new_endpoint(req, resp):
+        resp.media = {"modern": True}
+
+Requests to ``/old/legacy`` go to Flask. Everything else goes to
+Responder. When you've moved everything over, remove the mount.

docs/source/tutorial-middleware.rst

@@ -0,0 +1,170 @@
+Writing Middleware
+==================
+
+Middleware sits between the server and your route handlers, processing
+every request and response that flows through your application. It's the
+right tool for cross-cutting concerns — things that apply to *all*
+requests, not just specific routes.
+
+Common middleware use cases:
+
+- Request logging and timing
+- Authentication and authorization
+- Adding security headers
+- Request ID generation
+- Rate limiting
+- Response compression (built-in)
+
+
+Hooks vs. Middleware
+--------------------
+
+Responder gives you two levels of request processing:
+
+**Hooks** (``before_request`` / ``after_request``) run inside Responder's
+routing layer. They receive Responder's ``req`` and ``resp`` objects and
+are the simplest way to add behavior::
+
+    @api.route(before_request=True)
+    def add_header(req, resp):
+        resp.headers["X-Powered-By"] = "Responder"
+
+    @api.after_request()
+    def log_request(req, resp):
+        print(f"{req.method} {req.url.path} -> {resp.status_code}")
+
+**Middleware** runs at the ASGI level, wrapping the entire application.
+It's more powerful but more complex — you work with raw ASGI scopes
+instead of Responder objects. Use middleware when you need to process
+requests *before* they reach Responder's routing, or when you need to
+integrate with Starlette middleware.
+
+
+Using Starlette Middleware
+--------------------------
+
+Responder is built on Starlette, so any Starlette middleware works
+out of the box::
+
+    from starlette.middleware.base import BaseHTTPMiddleware
+
+    class TimingMiddleware(BaseHTTPMiddleware):
+        async def dispatch(self, request, call_next):
+            import time
+            start = time.time()
+            response = await call_next(request)
+            duration = time.time() - start
+            response.headers["X-Response-Time"] = f"{duration:.3f}s"
+            return response
+
+    api.add_middleware(TimingMiddleware)
+
+The ``dispatch`` method receives a Starlette ``Request`` and a
+``call_next`` function. Call ``call_next(request)`` to pass the request
+to the next middleware (or to your route handler). The return value is
+a Starlette ``Response`` that you can modify before it's sent.
+
+
+Built-in Middleware
+-------------------
+
+Responder configures several middleware components automatically:
+
+- **GZipMiddleware** — compresses responses larger than 500 bytes
+- **TrustedHostMiddleware** — validates the ``Host`` header
+- **ServerErrorMiddleware** — catches unhandled exceptions
+- **ExceptionMiddleware** — routes exceptions to your handlers
+- **SessionMiddleware** — manages signed cookie sessions
+
+Optional middleware you can enable:
+
+- **CORSMiddleware** — ``api = responder.API(cors=True)``
+- **HTTPSRedirectMiddleware** — ``api = responder.API(enable_hsts=True)``
+
+
+Adding Third-Party Middleware
+-----------------------------
+
+Any ASGI middleware can be added with ``api.add_middleware()``::
+
+    from some_package import SomeMiddleware
+
+    api.add_middleware(SomeMiddleware, option1="value", option2=True)
+
+Keyword arguments are passed to the middleware's constructor.
+
+
+Middleware Order
+----------------
+
+Middleware wraps your application like layers of an onion. The *last*
+middleware added is the *outermost* layer — it sees the request first
+and the response last.
+
+Responder's built-in middleware stack (from outermost to innermost):
+
+1. SessionMiddleware
+2. ServerErrorMiddleware
+3. CORSMiddleware (if enabled)
+4. TrustedHostMiddleware
+5. HTTPSRedirectMiddleware (if enabled)
+6. GZipMiddleware
+7. ExceptionMiddleware
+8. Your routes
+
+When you call ``api.add_middleware()``, your middleware is added *outside*
+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
+-----------------
+
+- **Simple header additions, logging, auth checks** → use hooks
+- **Response transformation, timing, third-party integrations** → use middleware
+- **Rate limiting** → use the built-in ``RateLimiter`` (it uses hooks internally)
+- **Request ID** → use ``api = responder.API(request_id=True)``
+
+Start with hooks. They're simpler and cover most cases. Graduate to
+middleware when hooks aren't enough.

docs/source/tutorial-rest.rst

@@ -0,0 +1,219 @@
+Building a REST API
+===================
+
+This tutorial walks you through building a complete REST API from scratch.
+By the end, you'll have a working API with CRUD operations, request
+validation, error handling, and interactive documentation.
+
+We'll build a simple book catalog — a service that lets you create, read,
+update, and delete books.
+
+
+Project Setup
+-------------
+
+Create a new file called ``app.py``::
+
+    import responder
+
+    api = responder.API(
+        title="Book Catalog",
+        version="1.0",
+        openapi="3.0.2",
+        docs_route="/docs",
+    )
+
+We're enabling OpenAPI documentation from the start. Visit ``/docs`` at
+any point to see interactive Swagger UI for your API.
+
+
+Define Your Models
+------------------
+
+We'll use `Pydantic <https://docs.pydantic.dev/>`_ to define our data
+models. Pydantic models serve double duty — they validate incoming data
+*and* generate OpenAPI schemas automatically::
+
+    from pydantic import BaseModel
+
+    class BookIn(BaseModel):
+        """What the client sends when creating a book."""
+        title: str
+        author: str
+        year: int
+        isbn: str | None = None
+
+    class Book(BaseModel):
+        """What the API returns."""
+        id: int
+        title: str
+        author: str
+        year: int
+        isbn: str | None = None
+
+``BookIn`` is the *input* model — it doesn't have an ``id`` because the
+server assigns that. ``Book`` is the *output* model — it includes
+everything. This input/output separation is a common REST API pattern.
+
+
+In-Memory Storage
+-----------------
+
+For this tutorial, we'll store books in a simple dict. In a real
+application, you'd use a database (see :doc:`tutorial-sqlalchemy`)::
+
+    books_db: dict[int, dict] = {}
+    next_id = 1
+
+
+List All Books
+--------------
+
+The first endpoint — list all books. This is a ``GET`` request to
+``/books``::
+
+    @api.route("/books", methods=["GET"], response_model=list)
+    def list_books(req, resp):
+        resp.media = list(books_db.values())
+
+In REST API design, ``GET`` requests should never modify data. They're
+*safe* and *idempotent* — calling them multiple times has the same effect
+as calling them once.
+
+
+Create a Book
+-------------
+
+To create a book, the client sends a ``POST`` request with a JSON body.
+We use ``request_model=BookIn`` to validate the input automatically — if
+the client sends bad data, they get a ``422`` response with error details::
+
+    @api.route("/books", methods=["POST"], check_existing=False,
+               request_model=BookIn, response_model=Book)
+    async def create_book(req, resp):
+        global next_id
+        data = await req.media()
+
+        book = {"id": next_id, **data}
+        books_db[next_id] = book
+        next_id += 1
+
+        resp.media = book
+        resp.status_code = 201
+
+Note ``resp.status_code = 201`` — the HTTP ``201 Created`` status code
+tells the client that a new resource was successfully created. This is
+more informative than a generic ``200 OK``.
+
+
+Get a Single Book
+-----------------
+
+Retrieve a specific book by its ID. The ``{book_id:int}`` route parameter
+ensures only integer IDs match — requests like ``/books/abc`` will 404::
+
+    @api.route("/books/{book_id:int}", methods=["GET"], response_model=Book)
+    def get_book(req, resp, *, book_id):
+        if book_id not in books_db:
+            resp.status_code = 404
+            resp.media = {"error": f"Book {book_id} not found"}
+            return
+
+        resp.media = books_db[book_id]
+
+
+Update a Book
+-------------
+
+``PUT`` replaces a resource entirely. The client must send all fields::
+
+    @api.route("/books/{book_id:int}", methods=["PUT"], check_existing=False,
+               request_model=BookIn, response_model=Book)
+    async def update_book(req, resp, *, book_id):
+        if book_id not in books_db:
+            resp.status_code = 404
+            resp.media = {"error": f"Book {book_id} not found"}
+            return
+
+        data = await req.media()
+        book = {"id": book_id, **data}
+        books_db[book_id] = book
+        resp.media = book
+
+
+Delete a Book
+-------------
+
+``DELETE`` removes a resource. The convention is to return ``204 No Content``
+with an empty body on success::
+
+    @api.route("/books/{book_id:int}", methods=["DELETE"], check_existing=False)
+    def delete_book(req, resp, *, book_id):
+        if book_id not in books_db:
+            resp.status_code = 404
+            resp.media = {"error": f"Book {book_id} not found"}
+            return
+
+        del books_db[book_id]
+        resp.status_code = 204
+
+
+Error Handling
+--------------
+
+Let's add a custom error handler so any ``ValueError`` in our code returns
+a clean JSON response instead of a 500 error::
+
+    @api.exception_handler(ValueError)
+    async def handle_value_error(req, resp, exc):
+        resp.status_code = 400
+        resp.media = {"error": str(exc)}
+
+
+Run It
+------
+
+Add the standard entry point at the bottom of your file::
+
+    if __name__ == "__main__":
+        api.run()
+
+Start the server::
+
+    $ python app.py
+
+Visit ``http://localhost:5042/docs`` to see your interactive API
+documentation. You can test every endpoint directly from the browser.
+
+
+Try It Out
+----------
+
+Using ``curl``::
+
+    # Create a book
+    $ curl -X POST http://localhost:5042/books \
+        -H "Content-Type: application/json" \
+        -d '{"title": "Dune", "author": "Frank Herbert", "year": 1965}'
+
+    # List all books
+    $ curl http://localhost:5042/books
+
+    # Get a specific book
+    $ curl http://localhost:5042/books/1
+
+    # Update a book
+    $ curl -X PUT http://localhost:5042/books/1 \
+        -H "Content-Type: application/json" \
+        -d '{"title": "Dune", "author": "Frank Herbert", "year": 1965, "isbn": "978-0441172719"}'
+
+    # Delete a book
+    $ curl -X DELETE http://localhost:5042/books/1
+
+
+What's Next
+-----------
+
+This tutorial used in-memory storage. For a real application, you'll want
+a database. See :doc:`tutorial-sqlalchemy` for how to integrate SQLAlchemy
+with Responder using the lifespan pattern.

docs/source/tutorial-sqlalchemy.rst

@@ -0,0 +1,255 @@
+Using SQLAlchemy
+================
+
+Most real web applications need a database. This guide shows how to
+integrate `SQLAlchemy <https://www.sqlalchemy.org/>`_ with Responder,
+using async support and the lifespan pattern for connection management.
+
+SQLAlchemy is the most popular Python database toolkit. It gives you an
+ORM (Object-Relational Mapper) for working with databases using Python
+classes instead of raw SQL, plus a powerful query builder for when you
+need fine-grained control.
+
+
+Installation
+------------
+
+Install SQLAlchemy with async support and an async database driver.
+We'll use SQLite for simplicity, but the pattern works with PostgreSQL,
+MySQL, and any other database SQLAlchemy supports::
+
+    $ uv pip install 'sqlalchemy[asyncio]' aiosqlite
+
+
+Define Your Models
+------------------
+
+SQLAlchemy models map Python classes to database tables. Each attribute
+becomes a column::
+
+    # models.py
+    from sqlalchemy import String
+    from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+    class Base(DeclarativeBase):
+        pass
+
+    class Book(Base):
+        __tablename__ = "books"
+
+        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)
+
+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
+--------------
+
+Create the async engine and session factory. The *engine* manages
+the connection pool. The *session* is your unit of work — you use it to
+query and modify data within a transaction::
+
+    # database.py
+    from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker
+
+    DATABASE_URL = "sqlite+aiosqlite:///./books.db"
+
+    engine = create_async_engine(DATABASE_URL, echo=True)
+    async_session = async_sessionmaker(engine, expire_on_commit=False)
+
+The ``echo=True`` flag prints all SQL queries to the console — very
+helpful during development, but you'll want to disable it in production.
+
+The ``expire_on_commit=False`` flag keeps model attributes accessible
+after a commit, which is convenient for returning created objects in
+API responses.
+
+
+Lifespan for Startup and Shutdown
+----------------------------------
+
+Use Responder's lifespan context manager to create the database tables
+on startup and dispose of connections on shutdown::
+
+    # app.py
+    from contextlib import asynccontextmanager
+    import responder
+    from database import engine
+    from models import Base
+
+    @asynccontextmanager
+    async def lifespan(app):
+        # Startup: create tables
+        async with engine.begin() as conn:
+            await conn.run_sync(Base.metadata.create_all)
+        yield
+        # Shutdown: close all connections
+        await engine.dispose()
+
+    api = responder.API(lifespan=lifespan)
+
+This is the proper way to manage database connections in an async
+application. The lifespan context manager ensures that:
+
+1. Tables are created before the first request
+2. The connection pool is properly closed when the server shuts down
+3. If table creation fails, the server won't start
+
+
+CRUD Endpoints
+--------------
+
+Now let's build the API endpoints. Each one opens a database session,
+does its work, and commits or rolls back::
+
+    from pydantic import BaseModel
+    from sqlalchemy import select
+    from database import async_session
+    from models import Book
+
+    # Pydantic models for request/response validation
+    class BookIn(BaseModel):
+        title: str
+        author: str
+        year: int
+        isbn: str | None = None
+
+    class BookOut(BaseModel):
+        id: int
+        title: str
+        author: str
+        year: int
+        isbn: str | None = None
+
+        class Config:
+            from_attributes = True
+
+The ``from_attributes = True`` config tells Pydantic to read data from
+SQLAlchemy model attributes (not just dicts). This lets you pass a
+SQLAlchemy ``Book`` object directly to ``BookOut``.
+
+**List all books**::
+
+    @api.route("/books", methods=["GET"])
+    async def list_books(req, resp):
+        async with async_session() as session:
+            result = await session.execute(select(Book))
+            books = result.scalars().all()
+            resp.media = [BookOut.model_validate(b).model_dump() for b in books]
+
+**Create a book**::
+
+    @api.route("/books", methods=["POST"], check_existing=False,
+               request_model=BookIn, response_model=BookOut)
+    async def create_book(req, resp):
+        data = await req.media()
+
+        async with async_session() as session:
+            book = Book(**data)
+            session.add(book)
+            await session.commit()
+            await session.refresh(book)
+            resp.media = BookOut.model_validate(book).model_dump()
+            resp.status_code = 201
+
+**Get a single book**::
+
+    @api.route("/books/{book_id:int}", methods=["GET"])
+    async def get_book(req, resp, *, book_id):
+        async with async_session() as session:
+            book = await session.get(Book, book_id)
+            if book is None:
+                resp.status_code = 404
+                resp.media = {"error": "Book not found"}
+                return
+            resp.media = BookOut.model_validate(book).model_dump()
+
+**Update a book**::
+
+    @api.route("/books/{book_id:int}", methods=["PUT"], check_existing=False,
+               request_model=BookIn)
+    async def update_book(req, resp, *, book_id):
+        data = await req.media()
+
+        async with async_session() as session:
+            book = await session.get(Book, book_id)
+            if book is None:
+                resp.status_code = 404
+                resp.media = {"error": "Book not found"}
+                return
+
+            for key, value in data.items():
+                setattr(book, key, value)
+
+            await session.commit()
+            await session.refresh(book)
+            resp.media = BookOut.model_validate(book).model_dump()
+
+**Delete a book**::
+
+    @api.route("/books/{book_id:int}", methods=["DELETE"], check_existing=False)
+    async def delete_book(req, resp, *, book_id):
+        async with async_session() as session:
+            book = await session.get(Book, book_id)
+            if book is None:
+                resp.status_code = 404
+                resp.media = {"error": "Book not found"}
+                return
+
+            await session.delete(book)
+            await session.commit()
+            resp.status_code = 204
+
+
+Run It
+------
+
+::
+
+    if __name__ == "__main__":
+        api.run()
+
+Start the server and you'll see SQLAlchemy's SQL echo in the console.
+The SQLite database file ``books.db`` is created automatically on first
+startup.
+
+
+Using PostgreSQL
+----------------
+
+To switch to PostgreSQL, just change the connection URL and driver::
+
+    $ uv pip install asyncpg
+
+::
+
+    DATABASE_URL = "postgresql+asyncpg://user:pass@localhost/mydb"
+
+Everything else stays the same. SQLAlchemy abstracts the database
+differences so your application code doesn't need to change.
+
+
+Tips
+----
+
+- Use ``async with async_session() as session`` for every request.
+  Don't share sessions across requests — each request should get its
+  own session and transaction.
+
+- For complex queries, use SQLAlchemy's ``select()`` with ``.where()``,
+  ``.order_by()``, ``.limit()``, and ``.offset()`` — it composes
+  naturally.
+
+- In production, use connection pooling (SQLAlchemy does this by
+  default) and set pool size limits appropriate for your database.
+
+- Consider `Alembic <https://alembic.sqlalchemy.org/>`_ for database
+  migrations — it tracks schema changes over time so you can evolve
+  your database without losing data.

docs/source/tutorial-websockets.rst

@@ -0,0 +1,219 @@
+WebSocket Tutorial
+==================
+
+HTTP is request-response — the client asks, the server answers, and the
+connection closes. WebSockets upgrade that into a persistent, bidirectional
+channel where both sides can send messages at any time. This is what powers
+chat apps, live dashboards, multiplayer games, and collaborative editors.
+
+This tutorial builds a simple chat room to show how WebSockets work in
+Responder.
+
+
+How WebSockets Work
+-------------------
+
+1. The client sends a normal HTTP request with an ``Upgrade: websocket``
+   header.
+2. The server accepts the upgrade and the connection switches protocols.
+3. Both sides can now send messages freely — no more request/response.
+4. Either side can close the connection at any time.
+
+In Responder, WebSocket routes receive a ``ws`` object instead of
+``req`` and ``resp``. The ``ws`` object has methods for accepting the
+connection, sending and receiving data, and closing.
+
+
+Echo Server
+-----------
+
+The simplest WebSocket — echoes everything back::
+
+    @api.route("/ws", websocket=True)
+    async def echo(ws):
+        await ws.accept()
+        while True:
+            data = await ws.receive_text()
+            await ws.send_text(f"Echo: {data}")
+
+The ``await ws.accept()`` call completes the WebSocket handshake. After
+that, you're in a loop — receive a message, send a response.
+
+Test it with a WebSocket client::
+
+    $ pip install websocket-client
+    $ python -c "
+    import websocket
+    ws = websocket.create_connection('ws://localhost:5042/ws')
+    ws.send('hello')
+    print(ws.recv())  # Echo: hello
+    ws.close()
+    "
+
+
+Chat Room
+---------
+
+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)
+    async def chat(ws):
+        await ws.accept()
+        connected.add(ws)
+        try:
+            while True:
+                message = await ws.receive_text()
+                # Broadcast to all connected clients
+                for client in connected:
+                    await client.send_text(message)
+        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. Catching
+``WebSocketDisconnect`` specifically (rather than bare ``Exception``)
+makes the intent clear and avoids swallowing real bugs.
+
+
+Data Formats
+------------
+
+WebSockets support three data formats:
+
+**Text** — plain strings::
+
+    await ws.send_text("hello")
+    message = await ws.receive_text()
+
+**JSON** — auto-serialized Python objects::
+
+    await ws.send_json({"type": "update", "data": [1, 2, 3]})
+    message = await ws.receive_json()
+
+**Binary** — raw bytes, useful for images, audio, or custom protocols::
+
+    await ws.send_bytes(b"\x00\x01\x02")
+    data = await ws.receive_bytes()
+
+
+HTML Client
+-----------
+
+Here's a minimal HTML page that connects to the chat room. The browser's
+built-in ``WebSocket`` API handles everything — no libraries needed:
+
+.. code-block:: html
+
+    <!DOCTYPE html>
+    <html>
+    <body>
+      <div id="messages"></div>
+      <input id="input" placeholder="Type a message..." />
+      <script>
+        const ws = new WebSocket("ws://localhost:5042/chat");
+        const messages = document.getElementById("messages");
+        const input = document.getElementById("input");
+
+        ws.onmessage = (event) => {
+          const p = document.createElement("p");
+          p.textContent = event.data;
+          messages.appendChild(p);
+        };
+
+        input.addEventListener("keypress", (e) => {
+          if (e.key === "Enter") {
+            ws.send(input.value);
+            input.value = "";
+          }
+        });
+      </script>
+    </body>
+    </html>
+
+Save this as ``static/index.html`` and serve it with Responder's
+built-in static file support.
+
+
+Before-Request Hooks for WebSockets
+------------------------------------
+
+You can run code before a WebSocket connection is established, just like
+HTTP before-request hooks. This is useful for authentication::
+
+    @api.before_request(websocket=True)
+    async def ws_auth(ws):
+        # Check for a token in the query string
+        # (WebSocket headers are limited in browsers)
+        await ws.accept()
+
+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
+------------------
+
+Use Starlette's ``TestClient`` for WebSocket tests::
+
+    from starlette.testclient import TestClient
+
+    def test_echo():
+        client = TestClient(api)
+        with client.websocket_connect("/ws") as ws:
+            ws.send_text("hello")
+            assert ws.receive_text() == "Echo: hello"
+
+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

examples/helloworld.py

@@ -0,0 +1,19 @@
+# Example HTTP service definition, using Responder.
+# https://pypi.org/project/responder/
+import responder
+
+api = responder.API()
+
+
+@api.route("/")
+async def index(req, resp):
+    resp.text = "hello, world!"
+
+
+@api.route("/{greeting}")
+async def greet_world(req, resp, *, greeting):
+    resp.text = f"{greeting}, world!"
+
+
+if __name__ == "__main__":
+    api.run()

examples/lifespan.py

@@ -0,0 +1,26 @@
+# Example showing the lifespan context manager pattern.
+# https://pypi.org/project/responder/
+from contextlib import asynccontextmanager
+
+import responder
+
+
+@asynccontextmanager
+async def lifespan(app):
+    # Startup: initialize resources
+    print("Starting up...")
+    yield
+    # Shutdown: clean up resources
+    print("Shutting down...")
+
+
+api = responder.API(lifespan=lifespan)
+
+
+@api.route("/{greeting}")
+async def greet_world(req, resp, *, greeting):
+    resp.text = f"{greeting}, world!"
+
+
+if __name__ == "__main__":
+    api.run()

examples/marimo_mount.py

@@ -0,0 +1,31 @@
+"""Mount marimo notebooks inside a Responder API.
+
+Requirements:
+    pip install responder marimo
+
+Usage:
+    python examples/marimo_mount.py
+
+Then visit:
+    http://127.0.0.1:5042/hello       → Responder JSON endpoint
+    http://127.0.0.1:5042/notebooks/  → Interactive marimo notebook
+"""
+
+import marimo
+
+import responder
+
+api = responder.API()
+
+
+@api.route("/hello")
+def hello(req, resp):
+    resp.media = {"message": "Hello from Responder!"}
+
+
+# Mount marimo notebooks at /notebooks
+server = marimo.create_asgi_app().with_app(path="", root="notebooks/hello.py")
+api.mount("/notebooks", server.build())
+
+if __name__ == "__main__":
+    api.run()

examples/rest_api.py

@@ -0,0 +1,76 @@
+# Complete REST API example with Pydantic validation.
+# https://responder.kennethreitz.org/tutorial-rest.html
+from pydantic import BaseModel
+
+import responder
+
+
+class BookIn(BaseModel):
+    title: str
+    author: str
+    year: int
+    isbn: str | None = None
+
+
+class BookOut(BaseModel):
+    id: int
+    title: str
+    author: str
+    year: int
+    isbn: str | None = None
+
+
+api = responder.API(
+    title="Book Catalog",
+    version="1.0",
+    openapi="3.0.2",
+    docs_route="/docs",
+)
+
+books_db: dict[int, dict] = {}
+next_id = 1
+
+
+@api.route("/books", methods=["GET"])
+def list_books(req, resp):
+    resp.media = list(books_db.values())
+
+
+@api.route(
+    "/books",
+    methods=["POST"],
+    check_existing=False,
+    request_model=BookIn,
+    response_model=BookOut,
+)
+async def create_book(req, resp):
+    global next_id
+    data = await req.media()
+    book = {"id": next_id, **data}
+    books_db[next_id] = book
+    next_id += 1
+    resp.media = book
+    resp.status_code = 201
+
+
+@api.route("/books/{book_id:int}", methods=["GET"])
+def get_book(req, resp, *, book_id):
+    if book_id not in books_db:
+        resp.status_code = 404
+        resp.media = {"error": f"Book {book_id} not found"}
+        return
+    resp.media = books_db[book_id]
+
+
+@api.route("/books/{book_id:int}", methods=["DELETE"], check_existing=False)
+def delete_book(req, resp, *, book_id):
+    if book_id not in books_db:
+        resp.status_code = 404
+        resp.media = {"error": f"Book {book_id} not found"}
+        return
+    del books_db[book_id]
+    resp.status_code = 204
+
+
+if __name__ == "__main__":
+    api.run()

examples/sse_stream.py

@@ -0,0 +1,42 @@
+# Server-Sent Events streaming example.
+# https://responder.kennethreitz.org/tour.html#server-sent-events-sse
+import asyncio
+
+import responder
+
+api = responder.API()
+
+
+@api.route("/")
+def index(req, resp):
+    resp.html = """
+    <!DOCTYPE html>
+    <html>
+    <body>
+      <h1>SSE Stream</h1>
+      <div id="events"></div>
+      <script>
+        const source = new EventSource("/stream");
+        const events = document.getElementById("events");
+        source.onmessage = (e) => {
+          const p = document.createElement("p");
+          p.textContent = e.data;
+          events.appendChild(p);
+        };
+      </script>
+    </body>
+    </html>
+    """
+
+
+@api.route("/stream")
+async def stream(req, resp):
+    @resp.sse
+    async def events():
+        for i in range(20):
+            yield {"data": f"Event #{i}"}
+            await asyncio.sleep(0.5)
+
+
+if __name__ == "__main__":
+    api.run()

examples/user.py

@@ -0,0 +1,25 @@
+# Example HTTP service definition, using Responder.
+# https://pypi.org/project/responder/
+import responder
+
+api = responder.API()
+
+
+@api.route("/")
+async def index(req, resp):
+    resp.text = "Welcome"
+
+
+@api.route("/user")
+async def user_create(req, resp):
+    data = await req.media()
+    resp.text = f"Hello, {data['username']}"
+
+
+@api.route("/user/{identifier}")
+async def user_get(req, resp, *, identifier):
+    resp.text = f"Hello, user {identifier}"
+
+
+if __name__ == "__main__":
+    api.run()

examples/websocket_chat.py

@@ -0,0 +1,59 @@
+# WebSocket chat room example.
+# https://responder.kennethreitz.org/tutorial-websockets.html
+from starlette.websockets import WebSocketDisconnect
+
+import responder
+
+api = responder.API()
+
+connected = set()
+
+
+@api.route("/")
+def index(req, resp):
+    resp.html = """
+    <!DOCTYPE html>
+    <html>
+    <body>
+      <h1>Chat Room</h1>
+      <div id="messages" style="height:300px;overflow-y:scroll;border:1px solid #ccc;padding:10px;"></div>
+      <input id="input" placeholder="Type a message..." style="width:300px;" />
+      <script>
+        const ws = new WebSocket(`ws://${location.host}/chat`);
+        const messages = document.getElementById("messages");
+        const input = document.getElementById("input");
+        ws.onmessage = (e) => {
+          const p = document.createElement("p");
+          p.textContent = e.data;
+          messages.appendChild(p);
+          messages.scrollTop = messages.scrollHeight;
+        };
+        input.addEventListener("keypress", (e) => {
+          if (e.key === "Enter" && input.value) {
+            ws.send(input.value);
+            input.value = "";
+          }
+        });
+      </script>
+    </body>
+    </html>
+    """  # noqa: E501
+
+
+@api.route("/chat", websocket=True)
+async def chat(ws):
+    await ws.accept()
+    connected.add(ws)
+    try:
+        while True:
+            message = await ws.receive_text()
+            for client in connected:
+                await client.send_text(message)
+    except WebSocketDisconnect:
+        pass
+    finally:
+        connected.discard(ws)
+
+
+if __name__ == "__main__":
+    api.run()

ext/assets/noun_https_1875421_000000.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" x="0px" y="0px" viewBox="0 0 64 64" enable-background="new 0 0 64 64" xml:space="preserve"><polygon points="32.625,51 21.836,51 28.536,13 39.325,13 "></polygon><polygon points="49.107,51 38.319,51 45.019,13 55.808,13 "></polygon><rect x="9" y="18" width="12" height="12"></rect><rect x="9" y="33" width="12" height="12"></rect></svg>

g.py

@@ -1,13 +0,0 @@
-import graphene
-
-
-class Query(graphene.ObjectType):
-    hello = graphene.String(name=graphene.String(default_value="stranger"))
-
-    def resolve_hello(self, info, name):
-        return "Hello " + name
-
-
-schema = graphene.Schema(query=Query)
-result = schema.execute("{ hello }")
-print(result.data["hello"])

pyproject.toml

@@ -0,0 +1,167 @@
+[build-system]
+build-backend = "setuptools.build_meta"
+requires = [
+  "setuptools>=42",
+]
+
+[project]
+name = "responder"
+description = "A familiar HTTP Service Framework for Python."
+readme = "README.md"
+license = { text = "Apache 2.0" }
+authors = [
+  { name = "Kenneth Reitz", email = "me@kennethreitz.org" },
+]
+requires-python = ">=3.10"
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Environment :: Web Environment",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: Free Threading",
+  "Programming Language :: Python :: Implementation :: CPython",
+  "Programming Language :: Python :: Implementation :: PyPy",
+  "Topic :: Internet :: WWW/HTTP",
+]
+dynamic = [ "version" ]
+dependencies = [
+  "a2wsgi",
+  "apispec>=1",
+  "chardet",
+  "docopt-ng",
+  "graphene>=3",
+  "graphql-core>=3.1",
+  "marshmallow",
+  "msgpack",
+  "pueblo[sfa-full]>=0.0.11",
+  "pydantic>=2",
+  "python-multipart",
+  "starlette[full]>=1",
+  "uvicorn[standard]",
+]
+optional-dependencies.develop = [
+  "pyproject-fmt",
+  "ruff",
+  "validate-pyproject",
+]
+optional-dependencies.docs = [
+  "alabaster<1.1",
+  "myst-parser",
+  "sphinx>=5,<9",
+  "sphinx-autobuild",
+  "sphinx-copybutton",
+  "sphinx-design-elements",
+]
+optional-dependencies.release = [ "build", "twine" ]
+optional-dependencies.test = [
+  "flask",
+  "mypy",
+  "pytest",
+  "pytest-cov",
+  "pytest-mock",
+  "pytest-rerunfailures",
+]
+urls.Documentation = "https://responder.kennethreitz.org"
+urls.Homepage = "https://github.com/kennethreitz/responder"
+urls.Issues = "https://github.com/kennethreitz/responder/issues"
+urls.Repository = "https://github.com/kennethreitz/responder"
+scripts.responder = "responder.ext.cli:cli"
+
+[tool.setuptools]
+dynamic.version = { attr = "responder.__version__.__version__" }
+package-data.responder = [ "py.typed", "ext/openapi/docs/*.html" ]
+packages.find.exclude = [ "tests" ]
+
+[tool.ruff]
+line-length = 90
+extend-exclude = [
+  "docs/source/conf.py",
+]
+lint.select = [
+  # Builtins
+  "A",
+  # Bugbear
+  "B",
+  # comprehensions
+  "C4",
+  # Pycodestyle
+  "E",
+  # eradicate
+  "ERA",
+  # Pyflakes
+  "F",
+  # isort
+  "I",
+  # pandas-vet
+  "PD",
+  # return
+  "RET",
+  # Bandit
+  "S",
+  # print
+  "T20",
+  "W",
+  # flake8-2020
+  "YTT",
+]
+lint.extend-ignore = [
+  "S101", # Allow use of `assert`.
+]
+lint.per-file-ignores."responder/util/cmd.py" = [ "A005" ]  # Module shadows a Python standard-library module
+lint.per-file-ignores."tests/*" = [
+  "ERA001", # Found commented-out code.
+  "S101",   # Allow use of `assert`, and `print`.
+]
+
+[tool.mypy]
+packages = [
+  "responder",
+]
+exclude = []
+check_untyped_defs = true
+explicit_package_bases = true
+ignore_missing_imports = true
+implicit_optional = true
+install_types = true
+namespace_packages = true
+non_interactive = true
+
+[tool.pytest]
+ini_options.addopts = """
+  -rfEXs -p pytester --strict-markers --verbosity=3
+  --cov --cov-report=term-missing --cov-report=xml
+  """
+ini_options.filterwarnings = [
+  "error::UserWarning",
+]
+ini_options.log_level = "DEBUG"
+ini_options.log_cli_level = "DEBUG"
+ini_options.log_format = "%(asctime)-15s [%(name)-36s] %(levelname)-8s: %(message)s"
+ini_options.minversion = "2.0"
+ini_options.testpaths = [
+  "responder",
+  "tests",
+]
+ini_options.markers = []
+ini_options.xfail_strict = true
+
+[tool.coverage]
+run.branch = false
+run.omit = [
+  "*.html",
+  "tests/*",
+]
+report.exclude_lines = [
+  "# pragma: no cover",
+  "raise NotImplemented",
+]
+report.fail_under = 0
+report.show_missing = true

responder/__init__.py

@@ -1 +1,18 @@
-from .core import *
+"""
+Responder - a familiar HTTP Service Framework.
+
+This module exports the core functionality of the Responder framework,
+including the API, Request, and Response classes.
+"""
+
+from . import ext
+from .__version__ import __version__
+from .core import API, Request, Response
+
+__all__ = [
+    "API",
+    "Request",
+    "Response",
+    "__version__",
+    "ext",
+]

responder/__version__.py

@@ -0,0 +1 @@
+__version__ = "3.5.0"

responder/api.py

@@ -1,166 +1,603 @@
+import asyncio
+import inspect
 import os
 from pathlib import Path
 
-import graphene
+__all__ = ["API"]
 
-from whitenoise import WhiteNoise
-from wsgiadapter import WSGIAdapter as RequestsWSGIAdapter
-from requests import Session as RequestsSession
+import uvicorn
+from starlette.middleware.cors import CORSMiddleware
+from starlette.middleware.errors import ServerErrorMiddleware
+from starlette.middleware.exceptions import ExceptionMiddleware
+from starlette.middleware.gzip import GZipMiddleware
+from starlette.middleware.httpsredirect import HTTPSRedirectMiddleware
+from starlette.middleware.sessions import SessionMiddleware
+from starlette.middleware.trustedhost import TrustedHostMiddleware
 
-from . import models
-from .status import HTTP_404
+from . import status_codes
+from .background import BackgroundQueue
+from .formats import get_formats
+from .models import Request, Response
+from .routes import Router
+from .staticfiles import StaticFiles
+from .statics import DEFAULT_CORS_PARAMS, DEFAULT_OPENAPI_THEME, DEFAULT_SECRET_KEY
+from .templates import Templates
 
 
-class BaseAPI:
-    __slots__ = ["routes"]
+class API:
+    """The primary web-service class.
 
-    def __init__(self):
-        self.routes = {}
+    :param static_dir: The directory to use for static files. Will be created for you if it doesn't already exist.
+    :param templates_dir: The directory to use for templates. Will be created for you if it doesn't already exist.
+    :param auto_escape: If ``True``, HTML and XML templates will automatically be escaped.
+    :param enable_hsts: If ``True``, send all responses to HTTPS URLs.
+    :param openapi_theme: OpenAPI documentation theme, must be one of ``elements``, ``rapidoc``, ``redoc``, ``swagger_ui``
+    """  # noqa: E501
 
-    def _wsgi_app(self, environ, start_response):
-        # def wsgi_app(self, request):
-        """The actual WSGI application. This is not implemented in
-        :meth:`__call__` so that middlewares can be applied without
-        losing a reference to the app object. Instead of doing this::
+    status_codes = status_codes
 
-            app = MyMiddleware(app)
+    def __init__(
+        self,
+        *,
+        debug=False,
+        title=None,
+        version=None,
+        description=None,
+        terms_of_service=None,
+        contact=None,
+        license=None,  # noqa: A002
+        openapi=None,
+        openapi_route="/schema.yml",
+        static_dir="static",
+        static_route="/static",
+        templates_dir="templates",
+        auto_escape=True,
+        secret_key=DEFAULT_SECRET_KEY,
+        enable_hsts=False,
+        docs_route=None,
+        cors=False,
+        cors_params=DEFAULT_CORS_PARAMS,
+        allowed_hosts=None,
+        openapi_theme=DEFAULT_OPENAPI_THEME,
+        lifespan=None,
+        request_id=False,
+    ):
+        """Create a new Responder API instance.
 
-        It's a better idea to do this instead::
+        :param debug: If ``True``, enable debug mode with verbose error pages.
+        :param title: The title of the API, used in OpenAPI documentation.
+        :param version: The version string for the API (e.g. ``"1.0"``).
+        :param description: A longer description of the API for OpenAPI docs.
+        :param terms_of_service: URL to the API's terms of service.
+        :param contact: Contact information dict for the API (``name``, ``url``, ``email``).
+        :param license: License information dict (``name``, ``url``).
+        :param openapi: The OpenAPI version string (e.g. ``"3.0.2"``). Enables OpenAPI schema generation.
+        :param openapi_route: The URL path for the OpenAPI schema (default ``"/schema.yml"``).
+        :param static_dir: Directory for static files. Set to ``None`` to disable. Created automatically if missing.
+        :param static_route: URL prefix for serving static files (default ``"/static"``).
+        :param templates_dir: Directory for Jinja2 templates (default ``"templates"``).
+        :param auto_escape: If ``True``, auto-escape HTML/XML in templates.
+        :param secret_key: Secret key for signing cookie-based sessions. **Always set this in production.**
+        :param enable_hsts: If ``True``, redirect all HTTP requests to HTTPS.
+        :param docs_route: URL path for interactive API docs (e.g. ``"/docs"``). Enables OpenAPI if not already set.
+        :param cors: If ``True``, enable CORS middleware.
+        :param cors_params: Dict of CORS configuration (``allow_origins``, ``allow_methods``, etc.).
+        :param allowed_hosts: List of allowed hostnames (e.g. ``["example.com"]``). Defaults to ``["*"]``.
+        :param openapi_theme: Documentation UI theme: ``"swagger_ui"``, ``"redoc"``, ``"rapidoc"``, or ``"elements"``.
+        :param lifespan: An async context manager for startup/shutdown logic.
+        :param request_id: If ``True``, add ``X-Request-ID`` headers to all responses.
+        """  # noqa: E501
+        self.background = BackgroundQueue()
 
-            app.wsgi_app = MyMiddleware(app.wsgi_app)
+        self.secret_key = secret_key
 
-        Then you still have the original application object around and
-        can continue to call methods on it.
+        self.router = Router(lifespan=lifespan)
 
-        .. versionchanged:: 0.7
-            Teardown events for the request and app contexts are called
-            even if an unhandled error occurs. Other events may not be
-            called depending on when an error occurs during dispatch.
-            See :ref:`callbacks-and-errors`.
+        if static_dir is not None:
+            if static_route is None:
+                static_route = ""
+            static_dir = Path(static_dir).resolve()
 
-        :param environ: A WSGI environment.
-        :param start_response: A callable accepting a status code,
-            a list of headers, and an optional exception context to
-            start the response.
-        """
+        self.static_dir = static_dir
+        self.static_route = static_route
 
-        req = models.Request.from_environ(environ)
-        resp = self._dispatch_request(req)
+        self.hsts_enabled = enable_hsts
+        self.cors = cors
+        self.cors_params = cors_params
+        self.debug = debug
 
-        return resp(environ, start_response)
+        if not allowed_hosts:
+            allowed_hosts = ["*"]
+        self.allowed_hosts = allowed_hosts
 
-    def wsgi_app(self, environ, start_response):
-        return self.whitenoise(environ, start_response)
+        if self.static_dir is not None:
+            self.static_dir.mkdir(parents=True, exist_ok=True)
+            self.mount(self.static_route, self.static_app)
 
-    def __call__(self, environ, start_response):
-        """The WSGI server calls the Flask application object as the
-        WSGI application. This calls :meth:`wsgi_app` which can be
-        wrapped to applying middleware."""
-        return self.wsgi_app(environ, start_response)
+        self.formats = get_formats()
 
-    def path_matches_route(self, url):
-        for (route, view) in self.routes.items():
-            if url == route:
-                return route
+        self._session = None
 
-    def _dispatch_request(self, req):
-        route = self.path_matches_route(req.path)
-        resp = models.Response(req=req)
+        self.default_endpoint = None
+        self.app = ExceptionMiddleware(self.router, debug=debug)
+        self.add_middleware(GZipMiddleware)
 
-        if route:
+        if self.hsts_enabled:
+            self.add_middleware(HTTPSRedirectMiddleware)
+
+        self.add_middleware(TrustedHostMiddleware, allowed_hosts=self.allowed_hosts)
+
+        if self.cors:
+            self.add_middleware(CORSMiddleware, **self.cors_params)
+        self.add_middleware(ServerErrorMiddleware, debug=debug)
+        self.add_middleware(SessionMiddleware, secret_key=self.secret_key)
+
+        if openapi or docs_route:
             try:
-                self.routes[route](req, resp)
-            # The request is using class-based views.
-            except TypeError:
-                try:
-                    view = self.routes[route]()
-                # GraphQL Schema.
-                except TypeError:
-                    view = self.routes[route]
-                    self.graphql_response(req, resp, schema=view)
+                from .ext.openapi import OpenAPISchema
+            except ImportError as ex:
+                raise ImportError(
+                    "The dependencies for the OpenAPI extension are not installed. "
+                    "Install them using: pip install responder"
+                ) from ex
 
-                # Run on_request first.
-                try:
-                    getattr(view, "on_request")(req, resp)
-                except AttributeError:
-                    pass
+            self.openapi = OpenAPISchema(
+                app=self,
+                title=title,
+                version=version,
+                openapi=openapi,
+                docs_route=docs_route,
+                description=description,
+                terms_of_service=terms_of_service,
+                contact=contact,
+                license=license,
+                openapi_route=openapi_route,
+                static_route=static_route,
+                openapi_theme=openapi_theme,
+            )
 
-                # Then on_get.
-                method = req.method.lower()
+        self.templates = Templates(directory=templates_dir)
 
-                try:
-                    getattr(view, f"on_{method}")(req, resp)
-                except AttributeError:
-                    pass
-        else:
-            self.default_response(req, resp)
+        if request_id:
+            import uuid as _uuid
 
-        return resp
+            def _add_request_id(req, resp):
+                rid = req.headers.get("X-Request-ID", str(_uuid.uuid4()))
+                resp.headers["X-Request-ID"] = rid
+
+            self.router.after_request(_add_request_id)
 
     @property
-    def static_dir(self):
-        return Path(".")
+    def requests(self):
+        """A test client connected to the ASGI app. Lazily initialized."""
+        return self.session()
 
+    @property
+    def static_app(self):
+        """The Starlette ``StaticFiles`` application for serving static assets."""
+        if not hasattr(self, "_static_app"):
+            assert self.static_dir is not None
+            self._static_app = StaticFiles(directory=self.static_dir)
+        return self._static_app
 
-class API(BaseAPI):
-    __slots__ = ("routes", "_session", "whitenoise", "static_dir")
+    def before_request(self, websocket=False):
+        """Register a function to run before every request.
 
-    def __init__(self, static="static"):
-        super().__init__()
-        self._session = None
-        self.static_dir = Path(os.path.abspath(static))
+        If the hook sets ``resp.status_code``, the route handler is skipped
+        and the response is sent immediately (short-circuiting).
 
-        # Make the static directory if it doesn't exist.
-        os.makedirs(self.static_dir, exist_ok=True)
+        :param websocket: If ``True``, register as a WebSocket before-request hook instead of HTTP.
 
-        # Mount the whitenoise application.
-        self.whitenoise = WhiteNoise(self._wsgi_app, root=str(self.static_dir))
+        Usage::
 
-    def add_route(self, route, view, *, check_existing=True, graphiql=False):
-        if check_existing:
-            assert route not in self.routes
+            @api.before_request()
+            def check_auth(req, resp):
+                if "Authorization" not in req.headers:
+                    resp.status_code = 401
+                    resp.media = {"error": "unauthorized"}
 
-        # TODO: Support grpahiql.
+        """  # noqa: E501
 
-        self.routes[route] = view
-
-    def default_response(self, req, resp):
-        resp.status_code = HTTP_404
-        resp.text = "Not found."
-
-    @staticmethod
-    def _resolve_graphql_query(req):
-        # Support query/q in form data.
-        if "query" in req.data:
-            return req.data["query"]
-        if "q" in req.data:
-            return req.data["q"]
-
-        # Support query/q in params.
-        if "query" in req.params:
-            return req.params["query"][0]
-        if "q" in req.params:
-            return req.parama["q"][0]
-
-        # Otherwise, the request text is used (typical).
-        # TODO: Make some assertions about content-type here.
-        return req.text
-
-    def graphql_response(self, req, resp, schema):
-        query = self._resolve_graphql_query(req)
-        result = schema.execute(query)
-        resp.media = dict(result.data)
-
-    def route(self, route, **options):
         def decorator(f):
-            self.add_route(route, f)
+            self.router.before_request(f, websocket=websocket)
             return f
 
         return decorator
 
-    def session(self, base_url="http://app"):
+    def after_request(self):
+        """Register a function to run after every request.
+
+        Usage::
+
+            @api.after_request()
+            def add_request_id(req, resp):
+                resp.headers["X-Request-ID"] = str(uuid.uuid4())
+
+        """
+
+        def decorator(f):
+            self.router.after_request(f)
+            return f
+
+        return decorator
+
+    def add_middleware(self, middleware_cls, **middleware_config):
+        """Add ASGI middleware to the application.
+
+        Middleware wraps the entire application and can inspect or modify
+        every request and response. Middleware is applied in reverse order —
+        the last middleware added runs first.
+
+        :param middleware_cls: A Starlette-compatible middleware class.
+        :param middleware_config: Keyword arguments passed to the middleware constructor.
+
+        Usage::
+
+            from starlette.middleware.httpsredirect import HTTPSRedirectMiddleware
+            api.add_middleware(HTTPSRedirectMiddleware)
+
+        """
+        self.app = middleware_cls(self.app, **middleware_config)
+
+    def exception_handler(self, exception_cls):
+        """Register a handler for a specific exception type.
+
+        Usage::
+
+            @api.exception_handler(ValueError)
+            async def handle_value_error(req, resp, exc):
+                resp.status_code = 400
+                resp.media = {"error": str(exc)}
+
+        """
+
+        def decorator(func):
+            async def _handler(request, exc):
+                from starlette.responses import Response as StarletteResp
+
+                req = Request(request.scope, request.receive, formats=get_formats())
+                resp = Response(req=req, formats=get_formats())
+                if inspect.iscoroutinefunction(func):
+                    await func(req, resp, exc)
+                else:
+                    func(req, resp, exc)
+                if resp.status_code is None:
+                    resp.status_code = 500
+                body, headers = await resp.body
+                return StarletteResp(
+                    content=body, status_code=resp.status_code, headers=headers
+                )
+
+            # Register with the ExceptionMiddleware
+            self.router._exception_handlers = getattr(
+                self.router, "_exception_handlers", {}
+            )
+            self.router._exception_handlers[exception_cls] = _handler
+            # Also register on the ASGI app chain
+            from starlette.middleware.exceptions import ExceptionMiddleware as EM
+
+            app = self.app
+            while app is not None:
+                if isinstance(app, EM):
+                    app.add_exception_handler(exception_cls, _handler)
+                    break
+                app = getattr(app, "app", None)
+            return func
+
+        return decorator
+
+    def schema(self, name, **options):
+        """
+        Decorator for creating new routes around function and class definitions.
+
+        Usage::
+
+            from marshmallow import Schema, fields
+            @api.schema("Pet")
+            class PetSchema(Schema):
+                name = fields.Str()
+        """
+
+        def decorator(f):
+            self.openapi.add_schema(name=name, schema=f, **options)
+            return f
+
+        return decorator
+
+    def path_matches_route(self, path):
+        """Given a path portion of a URL, tests that it matches against any registered route.
+
+        :param path: The path portion of a URL, to test all known routes against.
+        """  # noqa: E501 (Line too long)
+        for route in self.router.routes:
+            match, _ = route.matches(path)
+            if match:
+                return route
+        return None
+
+    def add_route(
+        self,
+        route=None,
+        endpoint=None,
+        *,
+        default=False,
+        static=True,
+        check_existing=True,
+        websocket=False,
+        before_request=False,
+        methods=None,
+    ):
+        """Adds a route to the API.
+
+        :param route: A string representation of the route.
+        :param endpoint: The endpoint for the route -- can be a callable, or a class.
+        :param default: If ``True``, all unknown requests will route to this view.
+        :param static: If ``True``, and no endpoint was passed, render "static/index.html".
+                       Also, it will become a default route.
+        :param methods: Optional list of HTTP methods (e.g. ``["GET", "POST"]``).
+        """  # noqa: E501
+
+        if static:
+            assert self.static_dir is not None
+            if not endpoint:
+                endpoint = self._static_response
+                default = True
+
+        self.router.add_route(
+            route,
+            endpoint,
+            default=default,
+            websocket=websocket,
+            before_request=before_request,
+            check_existing=check_existing,
+            methods=methods,
+        )
+
+    async def _static_response(self, req, resp):
+        assert self.static_dir is not None
+
+        index = (self.static_dir / "index.html").resolve()
+        if index.exists():
+            resp.html = index.read_text()
+        else:
+            resp.status_code = status_codes.HTTP_404  # type: ignore[attr-defined]
+            resp.text = "Not found."
+
+    def redirect(
+        self,
+        resp,
+        location,
+        *,
+        set_text=True,
+        status_code=status_codes.HTTP_301,  # type: ignore[attr-defined]
+    ):
+        """
+        Redirects a given response to a given location.
+
+        :param resp: The Response to mutate.
+        :param location: The location of the redirect.
+        :param set_text: If ``True``, sets the Redirect body content automatically.
+        :param status_code: an `API.status_codes` attribute, or an integer,
+                            representing the HTTP status code of the redirect.
+        """
+        resp.redirect(location, set_text=set_text, status_code=status_code)
+
+    def on_event(self, event_type: str, **args):
+        """Decorator for registering functions or coroutines to run at certain events
+        Supported events: startup, shutdown
+
+        Usage::
+
+            @api.on_event('startup')
+            async def open_database_connection_pool():
+                ...
+
+            @api.on_event('shutdown')
+            async def close_database_connection_pool():
+                ...
+
+        """
+
+        def decorator(func):
+            self.add_event_handler(event_type, func, **args)
+            return func
+
+        return decorator
+
+    def add_event_handler(self, event_type, handler):
+        """Adds an event handler to the API.
+
+        :param event_type: A string in ("startup", "shutdown")
+        :param handler: The function to run. Can be either a function or a coroutine.
+        """
+
+        self.router.add_event_handler(event_type, handler)
+
+    def route(self, route=None, *, request_model=None, response_model=None, **options):
+        """Decorator for creating new routes around function and class definitions.
+
+        Usage::
+
+            @api.route("/hello")
+            def hello(req, resp):
+                resp.text = "hello, world!"
+
+        With Pydantic models for OpenAPI documentation::
+
+            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}
+
+        """
+
+        def decorator(f):
+            if request_model is not None:
+                f._request_model = request_model
+                if hasattr(self, "openapi"):
+                    self.openapi.add_schema(
+                        request_model.__name__, request_model, check_existing=False
+                    )
+            if response_model is not None:
+                f._response_model = response_model
+                if hasattr(self, "openapi"):
+                    self.openapi.add_schema(
+                        response_model.__name__, response_model, check_existing=False
+                    )
+            self.add_route(route, f, **options)
+            return f
+
+        return decorator
+
+    def graphql(self, route="/graphql", *, schema):
+        """Mount a GraphQL API at the given route.
+
+        Usage::
+
+            import graphene
+
+            class Query(graphene.ObjectType):
+                hello = graphene.String(name=graphene.String(default_value="stranger"))
+                def resolve_hello(self, info, name):
+                    return f"Hello {name}"
+
+            api.graphql("/graphql", schema=graphene.Schema(query=Query))
+
+        :param route: The URL path for the GraphQL endpoint.
+        :param schema: A Graphene schema instance.
+        """
+        from .ext.graphql import GraphQLView
+
+        self.add_route(route, GraphQLView(api=self, schema=schema))
+
+    def mount(self, route, app):
+        """Mounts an WSGI / ASGI application at a given route.
+
+        :param route: String representation of the route to be used
+                      (shouldn't be parameterized).
+        :param app: The other WSGI / ASGI app.
+        """
+        self.router.apps.update({route: app})
+
+    def session(self, base_url="http://;"):
+        """Testing HTTP client. Returns a Starlette TestClient instance,
+        able to send HTTP requests to the Responder application.
+
+        :param base_url: The base URL for the test client.
+        """
+
         if self._session is None:
-            session = RequestsSession()
-            session.mount(base_url, RequestsWSGIAdapter(self))
-            self._session = session
+            from starlette.testclient import TestClient
+
+            self._session = TestClient(self, base_url=base_url)
         return self._session
+
+    def url_for(self, endpoint, **params):
+        """Given an endpoint, returns a rendered URL for its route.
+
+        :param endpoint: The route endpoint you're searching for.
+        :param params: Data to pass into the URL generator (for parameterized URLs).
+        """
+        return self.router.url_for(endpoint, **params)
+
+    def template(self, filename, *args, **kwargs):
+        r"""Render a Jinja2 template file with the provided values.
+
+        :param filename: The filename of the jinja2 template, in ``templates_dir``.
+        :param \*args: Data to pass into the template.
+        :param \*\*kwargs: Data to pass into the template.
+        """
+        return self.templates.render(filename, *args, **kwargs)
+
+    def template_string(self, source, *args, **kwargs):
+        r"""Render a Jinja2 template string with the provided values.
+
+        :param source: The template to use, a Jinja2 template string.
+        :param \*args: Data to pass into the template.
+        :param \*\*kwargs: Data to pass into the template.
+        """
+        return self.templates.render_string(source, *args, **kwargs)
+
+    def serve(self, *, address=None, port=None, debug=False, **options):
+        """
+        Run the application with uvicorn.
+
+        If the ``PORT`` environment variable is set, requests will be served on that port
+        automatically to all known hosts.
+
+        :param address: The address to bind to.
+        :param port: The port to bind to. If none is provided, one will be selected at random.
+        :param debug: Whether to run application in debug mode.
+        :param options: Additional keyword arguments to send to ``uvicorn.run()``.
+        """  # noqa: E501
+
+        if "PORT" in os.environ:
+            if address is None:
+                address = "0.0.0.0"  # noqa: S104
+            port = int(os.environ["PORT"])
+
+        if address is None:
+            address = "127.0.0.1"
+        if port is None:
+            port = 5042
+        if debug:
+            options["log_level"] = "debug"
+
+        uvicorn.run(self, host=address, port=port, **options)
+
+    def run(self, **kwargs):
+        """Run the application. Shorthand for :meth:`serve` that inherits the ``debug`` setting.
+
+        :param kwargs: Keyword arguments passed through to :meth:`serve`.
+        """  # noqa: E501
+        if "debug" not in kwargs:
+            kwargs.update({"debug": self.debug})
+        self.serve(**kwargs)
+
+    def group(self, prefix):
+        """Create a route group with a shared URL prefix.
+
+        Usage::
+
+            v1 = api.group("/v1")
+
+            @v1.route("/users")
+            def list_users(req, resp):
+                resp.media = []
+
+            @v1.route("/users/{id:int}")
+            def get_user(req, resp, *, id):
+                resp.media = {"id": id}
+
+        """
+        return RouteGroup(api=self, prefix=prefix)
+
+    async def __call__(self, scope, receive, send):
+        await self.app(scope, receive, send)
+
+
+class RouteGroup:
+    """A group of routes with a shared URL prefix."""
+
+    def __init__(self, api, prefix):
+        self.api = api
+        self.prefix = prefix.rstrip("/")
+
+    def route(self, route=None, **options):
+        full_route = f"{self.prefix}{route}"
+        return self.api.route(full_route, **options)
+
+    def before_request(self, **kwargs):
+        return self.api.before_request(**kwargs)

responder/background.py

@@ -0,0 +1,82 @@
+import asyncio
+import concurrent.futures
+import inspect
+import multiprocessing
+import traceback
+
+from starlette.concurrency import run_in_threadpool
+
+__all__ = ["BackgroundQueue"]
+
+
+class BackgroundQueue:
+    """A queue for running tasks in background threads.
+
+    Uses a ``ThreadPoolExecutor`` sized to the number of CPUs. Access it
+    via ``api.background``.
+
+    Usage::
+
+        # As a decorator — fire and forget
+        @api.background.task
+        def send_email(to, subject):
+            ...
+
+        send_email("user@example.com", "Hello")
+
+        # Direct submission
+        future = api.background.run(send_email, "user@example.com", "Hello")
+
+        # As a callable (supports async functions)
+        await api.background(send_email, "user@example.com", "Hello")
+
+    """
+
+    def __init__(self, n=None):
+        """Create a new background queue.
+
+        :param n: Number of worker threads. Defaults to CPU count.
+        """
+        if n is None:
+            n = multiprocessing.cpu_count()
+
+        self.n = n
+        self.pool = concurrent.futures.ThreadPoolExecutor(max_workers=n)
+        self.results = []
+
+    def run(self, f, *args, **kwargs):
+        """Submit a function to run in a background thread.
+
+        :param f: The function to run.
+        :returns: A ``concurrent.futures.Future`` for the result.
+        """
+        f = self.pool.submit(f, *args, **kwargs)
+        self.results.append(f)
+        return f
+
+    def task(self, f):
+        """Decorator that wraps a function to run in the background thread pool.
+
+        The decorated function returns a ``Future`` instead of blocking.
+        Exceptions are printed to stderr via traceback.
+
+        :param f: The function to wrap.
+        """
+
+        def on_future_done(fs):
+            try:
+                fs.result()
+            except Exception:
+                traceback.print_exc()
+
+        def do_task(*args, **kwargs):
+            result = self.run(f, *args, **kwargs)
+            result.add_done_callback(on_future_done)
+            return result
+
+        return do_task
+
+    async def __call__(self, func, *args, **kwargs) -> None:
+        if inspect.iscoroutinefunction(func):
+            return await asyncio.create_task(func(*args, **kwargs))
+        return await run_in_threadpool(func, *args, **kwargs)

responder/core.py

@@ -1,3 +1,8 @@
 from .api import API
-from . import status
-from .views import GraphQLSchema
+from .models import Request, Response
+
+__all__ = [
+    "API",
+    "Request",
+    "Response",
+]

responder/ext/cli.py

@@ -0,0 +1,129 @@
+"""
+Responder CLI.
+
+A web framework for Python.
+
+Commands:
+  run     Start the application server
+  build   Build frontend assets using npm
+
+Usage:
+  responder
+  responder run [--debug] [--limit-max-requests=] <target>
+  responder build [<target>]
+  responder --version
+
+Options:
+  -h --help     Show this screen.
+  -v --version  Show version.
+  --debug       Enable debug mode with verbose logging.
+  --limit-max-requests=<n>  Maximum number of requests to handle before shutting down.
+
+Arguments:
+  <target>      For run: Python module specifier (e.g., "app:api" loads api from app.py)
+                         Format: "module.submodule:variable_name" where variable_name is your API instance
+                For build: Directory containing package.json (default: current directory)
+
+Examples:
+  responder run app:api                     # Run the 'api' instance from app.py
+  responder run myapp/core.py:application   # Run the 'application' instance from myapp/core.py
+  responder build                           # Build frontend assets
+"""  # noqa: E501
+
+import logging
+import platform
+import subprocess
+import sys
+import typing as t
+from pathlib import Path
+
+import docopt
+
+from responder.__version__ import __version__
+from responder.util.python import InvalidTarget, load_target
+
+logger = logging.getLogger(__name__)
+
+
+def cli() -> None:
+    """
+    Main entry point for the Responder CLI.
+
+    Parses command line arguments and executes the appropriate command.
+    Supports running the application, building assets, and displaying version info.
+    """
+    args = docopt.docopt(__doc__, argv=None, version=__version__, options_first=False)
+    setup_logging(args["--debug"])
+
+    target: t.Optional[str] = args["<target>"]
+    build: bool = args["build"]
+    debug: bool = args["--debug"]
+    run: bool = args["run"]
+
+    if build:
+        target_path = Path(target).resolve() if target else Path.cwd()
+        if not target_path.is_dir() or not (target_path / "package.json").exists():
+            logger.error(
+                f"Invalid target directory or missing package.json: {target_path}"
+            )
+            sys.exit(1)
+        npm_cmd = "npm.cmd" if platform.system() == "Windows" else "npm"
+        try:
+            logger.info("Starting frontend asset build")
+            # S603, S607 are addressed by validating the target directory.
+            subprocess.check_call(  # noqa: S603, S607
+                [npm_cmd, "run", "build"],
+                cwd=target_path,
+                timeout=300,
+            )
+            logger.info("Frontend asset build completed successfully")
+        except FileNotFoundError:
+            logger.error("npm not found. Please install Node.js and npm.")
+            sys.exit(1)
+        except subprocess.CalledProcessError as e:
+            logger.error(f"Build failed with exit code {e.returncode}")
+            sys.exit(1)
+
+    if run:
+        if not target:
+            logger.error("Target argument is required for run command")
+            sys.exit(1)
+
+        # Maximum request limit. Terminating afterward. Suitable for software testing.
+        limit_max_requests = args["--limit-max-requests"]
+        if limit_max_requests is not None:
+            try:
+                limit_max_requests = int(limit_max_requests)
+                if limit_max_requests <= 0:
+                    logger.error("limit-max-requests must be a positive integer")
+                    sys.exit(1)
+            except ValueError:
+                logger.error("limit-max-requests must be a valid integer")
+                sys.exit(1)
+
+        # Load application from target.
+        try:
+            api = load_target(target=target)
+        except InvalidTarget as ex:
+            raise ValueError(
+                f"{ex}. "
+                "Use either a Python module entrypoint specification, "
+                "a filesystem path, or a remote URL. "
+                "See also https://responder.kennethreitz.org/cli.html."
+            ) from ex
+
+        # Launch Responder API server (uvicorn).
+        api.run(debug=debug, limit_max_requests=limit_max_requests)
+
+
+def setup_logging(debug: bool) -> None:
+    """
+    Configure logging based on debug mode.
+
+    Args:
+        debug: When True, sets logging level to DEBUG; otherwise, sets to INFO
+    """
+    log_level = logging.DEBUG if debug else logging.INFO
+    logging.basicConfig(
+        level=log_level, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+    )

responder/ext/graphql/__init__.py

@@ -0,0 +1,111 @@
+import json
+
+from .templates import GRAPHIQL
+
+
+class GraphQLView:
+    """A class-based view that serves a GraphQL API.
+
+    Handles query resolution from multiple sources (JSON body, query
+    parameters, raw request text) and renders the GraphiQL IDE for
+    browser requests.
+
+    :param api: The Responder API instance.
+    :param schema: A Graphene schema instance.
+    """
+
+    def __init__(self, *, api, schema):
+        self.api = api
+        self.schema = schema
+
+    @staticmethod
+    def _parse_variables(raw):
+        """Parse variables from a string (query param) or return as-is (dict)."""
+        if raw is None:
+            return None
+        if isinstance(raw, str):
+            try:
+                return json.loads(raw)
+            except (json.JSONDecodeError, ValueError):
+                return None
+        return raw
+
+    @staticmethod
+    async def _resolve_graphql_query(req, resp):
+        """Extract query, variables, and operationName from the request.
+
+        Supports multiple input sources, checked in order:
+
+        1. JSON body (``Content-Type: application/json``)
+        2. Form data (``Content-Type: application/x-www-form-urlencoded``)
+        3. Query parameters (``?query=...&variables=...&operationName=...``)
+        4. Raw request text
+        """
+        if "json" in req.mimetype:
+            json_media = await req.media("json")
+            if "query" not in json_media:
+                resp.status_code = 400
+                resp.media = {"errors": ["'query' key is required in the JSON payload"]}
+                return None, None, None
+            return (
+                json_media["query"],
+                json_media.get("variables"),
+                json_media.get("operationName"),
+            )
+
+        if "form" in req.mimetype:
+            form_data = await req.media("form")
+            if "query" in form_data:
+                return (
+                    form_data["query"],
+                    GraphQLView._parse_variables(form_data.get("variables")),
+                    form_data.get("operationName"),
+                )
+
+        # Support query/variables/operationName in query params.
+        if "query" in req.params:
+            return (
+                req.params["query"],
+                GraphQLView._parse_variables(req.params.get("variables")),
+                req.params.get("operationName"),
+            )
+        if "q" in req.params:
+            return req.params["q"], None, None
+
+        # Otherwise, the request text is used (typical).
+        return await req.text, None, None
+
+    async def graphql_response(self, req, resp):
+        """Process a GraphQL request and populate the response."""
+        show_graphiql = req.method == "get" and req.accepts("text/html")
+
+        if show_graphiql:
+            resp.content = self.api.templates.render_string(
+                GRAPHIQL, endpoint=req.url.path
+            )
+            return None
+
+        query, variables, operation_name = await self._resolve_graphql_query(req, resp)
+        if query is None:
+            return None
+
+        context = {"request": req, "response": resp}
+        result = self.schema.execute(
+            query, variables=variables, operation_name=operation_name, context=context
+        )
+
+        response_data = {}
+        if result.errors:
+            response_data["errors"] = [{"message": str(e)} for e in result.errors]
+        if result.data is not None:
+            response_data["data"] = result.data
+
+        resp.media = response_data
+        status_code = 200 if not result.errors else 400
+        return (query, json.dumps(response_data), status_code)
+
+    async def on_request(self, req, resp):
+        await self.graphql_response(req, resp)
+
+    async def __call__(self, req, resp):
+        await self.on_request(req, resp)

responder/ext/graphql/templates.py

@@ -0,0 +1,34 @@
+# ruff: noqa: E501
+GRAPHIQL = """
+{% set GRAPHIQL_VERSION = '3.0.6' %}
+{% set REACT_VERSION = '18.2.0' %}
+
+<!DOCTYPE html>
+<html>
+  <head>
+    <style>
+      body {
+        height: 100%;
+        margin: 0;
+        width: 100%;
+        overflow: hidden;
+      }
+      #graphiql {
+        height: 100vh;
+      }
+    </style>
+    <link href="//cdn.jsdelivr.net/npm/graphiql@{{ GRAPHIQL_VERSION }}/graphiql.min.css" rel="stylesheet"/>
+  </head>
+  <body>
+    <div id="graphiql">Loading...</div>
+    <script crossorigin src="//cdn.jsdelivr.net/npm/react@{{ REACT_VERSION }}/umd/react.production.min.js"></script>
+    <script crossorigin src="//cdn.jsdelivr.net/npm/react-dom@{{ REACT_VERSION }}/umd/react-dom.production.min.js"></script>
+    <script src="//cdn.jsdelivr.net/npm/graphiql@{{ GRAPHIQL_VERSION }}/graphiql.min.js"></script>
+    <script>
+      const fetcher = GraphiQL.createFetcher({ url: '{{ endpoint }}' });
+      const root = ReactDOM.createRoot(document.getElementById('graphiql'));
+      root.render(React.createElement(GraphiQL, { fetcher: fetcher }));
+    </script>
+  </body>
+</html>
+""".strip()

responder/ext/openapi/__init__.py

@@ -0,0 +1,233 @@
+from pathlib import Path
+
+from apispec import APISpec, yaml_utils
+from apispec.ext.marshmallow import MarshmallowPlugin
+
+from responder import status_codes
+from responder.statics import API_THEMES, DEFAULT_OPENAPI_THEME
+from responder.templates import Templates
+
+
+def _is_pydantic_model(obj):
+    """Check if obj is a Pydantic model class."""
+    try:
+        from pydantic import BaseModel
+
+        return isinstance(obj, type) and issubclass(obj, BaseModel)
+    except ImportError:
+        return False
+
+
+class PydanticPlugin:
+    """APISpec plugin that resolves Pydantic models to JSON Schema."""
+
+    def __init__(self):
+        self._schemas = {}
+
+    def definition_helper(self, name, definition, **kwargs):
+        schema = kwargs.get("schema")
+        if schema is not None and _is_pydantic_model(schema):
+            return schema.model_json_schema()
+        return None
+
+    def resolve_schemas(self, spec):
+        pass
+
+    def init_spec(self, spec):
+        pass
+
+    def operation_helper(self, **kwargs):
+        return {}
+
+
+class OpenAPISchema:
+    def __init__(
+        self,
+        app,
+        title,
+        version,
+        plugins=None,
+        description=None,
+        terms_of_service=None,
+        contact=None,
+        license=None,  # noqa: A002
+        openapi=None,
+        openapi_route="/schema.yml",
+        docs_route="/docs/",
+        static_route="/static",
+        openapi_theme=DEFAULT_OPENAPI_THEME,
+    ):
+        self.app = app
+        self.schemas = {}
+        self.pydantic_schemas = {}
+        self.title = title
+        self.version = version
+        self.description = description
+        self.terms_of_service = terms_of_service
+        self.contact = contact
+        self.license = license
+
+        self.openapi_version = openapi
+        self.openapi_route = openapi_route
+
+        self.docs_theme = (
+            openapi_theme if openapi_theme in API_THEMES else DEFAULT_OPENAPI_THEME
+        )
+        self.docs_route = docs_route
+
+        self.plugins = [MarshmallowPlugin()] if plugins is None else plugins
+
+        if self.openapi_version is not None:
+            self.app.add_route(self.openapi_route, self.schema_response)
+
+        if self.docs_route is not None:
+            self.app.add_route(self.docs_route, self.docs_response)
+
+        theme_path = (Path(__file__).parent / "docs").resolve()
+        self.templates = Templates(directory=theme_path)
+
+        self.static_route = static_route
+
+    @property
+    def _apispec(self):
+        info = {}
+        if self.description is not None:
+            info["description"] = self.description
+        if self.terms_of_service is not None:
+            info["termsOfService"] = self.terms_of_service
+        if self.contact is not None:
+            info["contact"] = self.contact
+        if self.license is not None:
+            info["license"] = self.license
+
+        spec = APISpec(
+            title=self.title,
+            version=self.version,
+            openapi_version=self.openapi_version,
+            plugins=self.plugins,
+            info=info,
+        )
+
+        for route in self.app.router.routes:
+            if route.description:
+                operations = yaml_utils.load_operations_from_docstring(route.description)
+                spec.path(path=route.route, operations=operations)
+
+            # Check for Pydantic-annotated routes
+            endpoint = route.endpoint
+            req_model = getattr(endpoint, "_request_model", None)
+            resp_model = getattr(endpoint, "_response_model", None)
+
+            if req_model or resp_model:
+                operations = {}
+                methods = getattr(route, "methods", None) or ["get"]
+
+                for method in [m.lower() for m in methods]:
+                    op = {}
+                    if req_model and method in ("post", "put", "patch"):
+                        model_name = req_model.__name__
+                        op["requestBody"] = {
+                            "content": {
+                                "application/json": {
+                                    "schema": {
+                                        "$ref": f"#/components/schemas/{model_name}"
+                                    }
+                                }
+                            }
+                        }
+                    if resp_model:
+                        model_name = resp_model.__name__
+                        op["responses"] = {
+                            "200": {
+                                "description": "Successful response",
+                                "content": {
+                                    "application/json": {
+                                        "schema": {
+                                            "$ref": f"#/components/schemas/{model_name}"
+                                        }
+                                    }
+                                },
+                            }
+                        }
+                    if op:
+                        operations[method] = op
+
+                if operations and not route.description:
+                    spec.path(path=route.route, operations=operations)
+
+        # Register marshmallow schemas
+        for name, schema in self.schemas.items():
+            spec.components.schema(name, schema=schema)
+
+        # Register Pydantic schemas
+        for name, model in self.pydantic_schemas.items():
+            json_schema = model.model_json_schema()
+            json_schema.pop("title", None)
+            spec.components.schema(name, component=json_schema)
+
+        return spec
+
+    @property
+    def openapi(self):
+        return self._apispec.to_yaml()
+
+    def add_schema(self, name, schema, check_existing=True):
+        """Adds a marshmallow or Pydantic schema to the API specification."""
+        if check_existing:
+            assert name not in self.schemas
+            assert name not in self.pydantic_schemas
+
+        if _is_pydantic_model(schema):
+            self.pydantic_schemas[name] = schema
+        else:
+            self.schemas[name] = schema
+
+    def schema(self, name, **options):
+        """Decorator for registering schemas (marshmallow or Pydantic).
+
+        Usage::
+
+            from marshmallow import Schema, fields
+
+            @api.schema("Pet")
+            class PetSchema(Schema):
+                name = fields.Str()
+
+        Or with Pydantic::
+
+            from pydantic import BaseModel
+
+            @api.schema("Pet")
+            class Pet(BaseModel):
+                name: str
+                age: int = 0
+
+        """
+
+        def decorator(f):
+            self.add_schema(name=name, schema=f, **options)
+            return f
+
+        return decorator
+
+    @property
+    def docs(self):
+        return self.templates.render(
+            f"{self.docs_theme}.html",
+            title=self.title,
+            version=self.version,
+            schema_url="/schema.yml",
+        )
+
+    def static_url(self, asset):
+        """Given a static asset, return its URL path."""
+        assert self.static_route is not None
+        return f"{self.static_route}/{str(asset)}"
+
+    def docs_response(self, req, resp):
+        resp.html = self.docs
+
+    def schema_response(self, req, resp):
+        resp.status_code = status_codes.HTTP_200  # type: ignore[attr-defined]
+        resp.headers["Content-Type"] = "application/x-yaml"
+        resp.content = self.openapi

responder/ext/openapi/docs/elements.html

@@ -0,0 +1,24 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1, shrink-to-fit=no"
+    />
+    <title>{{ title }} {{ version }}</title>
+    <!-- Embed elements Elements via Web Component -->
+    <script src="https://unpkg.com/@stoplight/elements/web-components.min.js"></script>
+    <link
+      rel="stylesheet"
+      href="https://unpkg.com/@stoplight/elements/styles.min.css"
+    />
+  </head>
+  <body>
+    <elements-api
+      apiDescriptionUrl="{{ schema_url }}"
+      router="hash"
+      layout="sidebar"
+    />
+  </body>
+</html>

responder/ext/openapi/docs/rapidoc.html

@@ -0,0 +1,16 @@
+<!DOCTYPE html>
+<!-- Important: must specify -->
+<html>
+  <head>
+    <title>{{ title }} {{ version }}</title>
+    <meta charset="utf-8" />
+    <!-- Important: rapi-doc uses utf8 characters -->
+    <script
+      type="module"
+      src="https://unpkg.com/rapidoc/dist/rapidoc-min.js"
+    ></script>
+  </head>
+  <body>
+    <rapi-doc spec-url="{{ schema_url }}" show-header="false"> </rapi-doc>
+  </body>
+</html>

responder/ext/openapi/docs/redoc.html

@@ -0,0 +1,23 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>{{ title }} {{ version }}</title>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <link
+      href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700"
+      rel="stylesheet"
+    />
+
+    <style>
+      body {
+        margin: 0;
+        padding: 0;
+      }
+    </style>
+  </head>
+  <body>
+    <redoc spec-url="{{ schema_url }}"></redoc>
+    <script src="https://cdn.jsdelivr.net/npm/redoc@latest/bundles/redoc.standalone.js"></script>
+  </body>
+</html>

responder/ext/openapi/docs/swagger_ui.html

@@ -0,0 +1,49 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>{{ title }} {{ version }}</title>
+    <link
+      rel="stylesheet"
+      type="text/css"
+      href="https://unpkg.com/swagger-ui-dist/swagger-ui.css"
+    />
+    <style>
+      html {
+        box-sizing: border-box;
+        overflow: -moz-scrollbars-vertical;
+        overflow-y: scroll;
+      }
+
+      *,
+      *:before,
+      *:after {
+        box-sizing: inherit;
+      }
+
+      body {
+        margin: 0;
+        background: #fafafa;
+      }
+    </style>
+  </head>
+
+  <body>
+    <div id="swagger-ui"></div>
+
+    <script src="https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js"></script>
+    <script src="https://unpkg.com/swagger-ui-dist/swagger-ui-standalone-preset.js"></script>
+    <script>
+      window.onload = function () {
+        const ui = SwaggerUIBundle({
+          url: "{{ schema_url }}",
+          dom_id: "#swagger-ui",
+          deepLinking: true,
+          presets: [SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset],
+          plugins: [SwaggerUIBundle.plugins.DownloadUrl],
+          layout: "BaseLayout",
+        });
+      };
+    </script>
+  </body>
+</html>

responder/ext/ratelimit.py

@@ -0,0 +1,65 @@
+"""Simple in-memory rate limiter for Responder."""
+
+import time
+from collections import defaultdict
+
+
+class RateLimiter:
+    """Token bucket rate limiter.
+
+    Usage::
+
+        from responder.ext.ratelimit import RateLimiter
+
+        limiter = RateLimiter(requests=100, period=60)  # 100 req/min
+
+        @api.route(before_request=True)
+        def rate_limit(req, resp):
+            limiter.check(req, resp)
+
+    Or use the shorthand::
+
+        limiter = RateLimiter(requests=100, period=60)
+        limiter.install(api)
+
+    """
+
+    def __init__(self, requests=100, period=60):
+        self.max_requests = requests
+        self.period = period
+        self._buckets: dict[str, list[float]] = defaultdict(list)
+
+    def _client_key(self, req):
+        client = req.client
+        if client:
+            return client[0]
+        return req.headers.get("X-Forwarded-For", "unknown")
+
+    def _cleanup(self, key):
+        now = time.time()
+        cutoff = now - self.period
+        self._buckets[key] = [t for t in self._buckets[key] if t > cutoff]
+
+    def check(self, req, resp):
+        """Check rate limit. Sets 429 status if exceeded."""
+        key = self._client_key(req)
+        self._cleanup(key)
+
+        if len(self._buckets[key]) >= self.max_requests:
+            resp.status_code = 429
+            resp.media = {"error": "rate limit exceeded"}
+            resp.headers["Retry-After"] = str(self.period)
+            return False
+
+        self._buckets[key].append(time.time())
+        remaining = self.max_requests - len(self._buckets[key])
+        resp.headers["X-RateLimit-Limit"] = str(self.max_requests)
+        resp.headers["X-RateLimit-Remaining"] = str(remaining)
+        return True
+
+    def install(self, api):
+        """Install as a before_request hook on the API."""
+
+        @api.route(before_request=True)
+        def _rate_limit(req, resp):
+            self.check(req, resp)

responder/formats.py

@@ -0,0 +1,163 @@
+from __future__ import annotations
+
+import json
+from urllib.parse import urlencode
+
+import yaml
+from python_multipart import MultipartParser
+
+from .models import QueryDict
+
+
+class _PartData:
+    __slots__ = ("headers", "body", "header_field")
+
+    def __init__(self):
+        self.headers: dict[str, str] = {}
+        self.body = b""
+        self.header_field = ""
+
+
+def _parse_multipart(content: bytes, content_type: str) -> list[_PartData]:
+    """Parse multipart form data into a list of parts with headers and body."""
+    boundary = None
+    for segment in content_type.split(";"):
+        segment = segment.strip()
+        if segment.startswith("boundary="):
+            boundary = segment.split("=", 1)[1].strip('"')
+            break
+
+    if boundary is None:
+        return []
+
+    parts: list[_PartData] = []
+    current: list[_PartData | None] = [None]
+
+    def on_part_begin():
+        current[0] = _PartData()
+
+    def on_part_data(data, start, end):
+        current[0].body += data[start:end]  # type: ignore[union-attr]
+
+    def on_header_field(data, start, end):
+        current[0].header_field = data[start:end].decode("utf-8")  # type: ignore[union-attr]
+
+    def on_header_value(data, start, end):
+        part = current[0]
+        assert part is not None
+        part.headers[part.header_field] = data[start:end].decode("utf-8")
+
+    def on_part_end():
+        parts.append(current[0])  # type: ignore[arg-type]
+
+    parser = MultipartParser(
+        boundary.encode(),
+        {  # type: ignore[arg-type]
+            "on_part_begin": on_part_begin,
+            "on_part_data": on_part_data,
+            "on_header_field": on_header_field,
+            "on_header_value": on_header_value,
+            "on_part_end": on_part_end,
+        },
+    )
+    parser.write(content)
+    parser.finalize()
+
+    return parts
+
+
+async def format_form(r, encode=False):
+    if encode:
+        return None
+    if "multipart/form-data" in r.headers.get("Content-Type"):
+        parts = _parse_multipart(await r.content, r.mimetype)
+        queries = []
+        for part in parts:
+            header = part.headers.get("Content-Disposition", "")
+            text = part.body.decode("utf-8")
+
+            for section in [h.strip() for h in header.split(";")]:
+                split = section.split("=")
+                if len(split) > 1:
+                    key = split[1]
+                    key = key[1:-1]
+                    queries.append((key, text))
+
+        content = urlencode(queries)
+        return QueryDict(content)
+    return QueryDict(await r.text)
+
+
+async def format_yaml(r, encode=False):
+    if encode:
+        r.headers.update({"Content-Type": "application/x-yaml"})
+        return yaml.safe_dump(r.media)
+    return yaml.safe_load(await r.content)
+
+
+async def format_json(r, encode=False):
+    if encode:
+        r.headers.update({"Content-Type": "application/json"})
+        return json.dumps(r.media)
+    return json.loads(await r.content)
+
+
+async def format_files(r, encode=False):
+    if encode:
+        return None
+    parts = _parse_multipart(await r.content, r.mimetype)
+    dump = {}
+    for part in parts:
+        header = part.headers.get("Content-Disposition", "")
+        mimetype = part.headers.get("Content-Type", None)
+        filename = None
+        formname = None
+
+        for section in [h.strip() for h in header.split(";")]:
+            split = section.split("=")
+            if len(split) > 1:
+                key = split[0]
+                value = split[1]
+                value = value[1:-1]
+
+                if key == "filename":
+                    filename = value
+                elif key == "name":
+                    formname = value
+
+        if formname is None:
+            continue
+
+        if mimetype is None:
+            dump[formname] = part.body
+        else:
+            dump[formname] = {
+                "filename": filename,
+                "content": part.body,
+                "content-type": mimetype,
+            }
+    return dump
+
+
+async def format_msgpack(r, encode=False):
+    try:
+        import msgpack
+    except ImportError as exc:
+        raise ImportError(
+            "msgpack is required for MessagePack support: pip install msgpack"
+        ) from exc
+
+    if encode:
+        r.headers.update({"Content-Type": "application/x-msgpack"})
+        return msgpack.packb(r.media)
+    return msgpack.unpackb(await r.content)
+
+
+def get_formats():
+    return {
+        "json": format_json,
+        "yaml": format_yaml,
+        "form": format_form,
+        "files": format_files,
+        "msgpack": format_msgpack,
+    }

responder/models.py

@@ -1,137 +1,612 @@
-import io
-import json
-import gzip
+from __future__ import annotations
 
-import graphene
-import yaml
-from requests.models import Request as RequestsRequest
-from requests.structures import CaseInsensitiveDict
-from werkzeug.wrappers import Request as WerkzeugRequest
-from werkzeug.wrappers import BaseResponse as WerkzeugResponse
+import functools
+import inspect
+from collections.abc import Callable
+from http.cookies import SimpleCookie
+from urllib.parse import parse_qs, urlparse
+
+__all__ = ["Request", "Response", "QueryDict"]
+
+try:
+    import chardet
+except ImportError:
+    chardet = None  # type: ignore[assignment]
+from starlette.requests import Request as StarletteRequest
+from starlette.requests import State
+from starlette.responses import (
+    Response as StarletteResponse,
+)
+from starlette.responses import (
+    StreamingResponse as StarletteStreamingResponse,
+)
+
+from .statics import DEFAULT_ENCODING
+from .status_codes import HTTP_301  # type: ignore[attr-defined]
 
 
-from urllib.parse import parse_qs
+class CaseInsensitiveDict(dict):
+    """A case-insensitive dict for HTTP headers."""
 
-from .status import HTTP_200
+    def __setitem__(self, key, value):
+        super().__setitem__(key.lower(), value)
 
-# @staticmethod
-# def funcname(parameter_list):
-#     pass
+    def __getitem__(self, key):
+        return super().__getitem__(key.lower())
+
+    def __contains__(self, key):
+        return super().__contains__(key.lower())
+
+    def get(self, key, default=None):
+        return super().get(key.lower(), default)
+
+    def update(self, other=None, **kwargs):
+        if other:
+            for key, value in other.items():
+                self[key] = value
+        for key, value in kwargs.items():
+            self[key] = value
+
+
+class QueryDict(dict):
+    """A dictionary for query string parameters that handles multi-value keys.
+
+    Single-value access returns the last value for a key. Use :meth:`get_list`
+    to retrieve all values for a multi-value parameter.
+    """
+
+    def __init__(self, query_string):
+        self.update(parse_qs(query_string))
+
+    def __getitem__(self, key):
+        """
+        Return the last data value for this key, or [] if it's an empty list;
+        raise KeyError if not found.
+        """
+        list_ = super().__getitem__(key)
+        try:
+            return list_[-1]
+        except IndexError:
+            return []
+
+    def get(self, key, default=None):
+        """
+        Return the last data value for the passed key. If key doesn't exist
+        or value is an empty list, return `default`.
+        """
+        try:
+            val = self[key]
+        except KeyError:
+            return default
+        if val == []:
+            return default
+        return val
+
+    def _get_list(self, key, default=None, force_list=False):
+        """
+        Return a list of values for the key.
+
+        Used internally to manipulate values list. If force_list is True,
+        return a new copy of values.
+        """
+        try:
+            values = super().__getitem__(key)
+        except KeyError:
+            if default is None:
+                return []
+            return default
+        else:
+            if force_list:
+                values = list(values) if values is not None else None
+            return values
+
+    def get_list(self, key, default=None):
+        """
+        Return the list of values for the key. If key doesn't exist, return a
+        default value.
+        """
+        return self._get_list(key, default, force_list=True)
+
+    def items(self):
+        """
+        Yield (key, value) pairs, where value is the last item in the list
+        associated with the key.
+        """
+        for key in self:
+            yield key, self[key]
+
+    def items_list(self):
+        """
+        Yield (key, value) pairs, where value is the the list.
+        """
+        yield from super().items()
 
 
 class Request:
-    def __init__(self):
-        super().__init__()
-        self._wz = None
+    """An HTTP request, passed to each view as the first argument.
 
-    @classmethod
-    def from_environ(kls, environ):
-        self = kls()
-        self._wz = WerkzeugRequest(environ)
-        self.headers = CaseInsensitiveDict(self._wz.headers.to_list())
-        self.method = self._wz.method
-        self.full_url = self._wz.url
-        self.url = self._wz.base_url
-        self.full_path = self._wz.full_path
-        self.path = self._wz.path
-        self.params = parse_qs(self._wz.query_string.decode("utf-8"))
-        self.raw = self._wz.stream
-        self.content = self._wz.get_data(cache=True, as_text=False)
-        self.text = self._wz.get_data(cache=True, as_text=True)
-        self.data = self._wz.get_data(cache=True, as_text=True, parse_form_data=True)
+    Provides access to headers, cookies, query parameters, the request body,
+    session data, and more. Most properties are synchronous; reading the body
+    (via :attr:`content`, :attr:`text`, or :meth:`media`) requires ``await``.
+    """
 
-        return self
+    __slots__ = [
+        "_starlette",
+        "formats",
+        "_headers",
+        "_encoding",
+        "api",
+        "_content",
+        "_cookies",
+    ]
+
+    def __init__(self, scope, receive, api=None, formats=None):
+        self._starlette = StarletteRequest(scope, receive)
+        self.formats = formats
+        self._encoding = None
+        self.api = api
+        self._content = None
+
+        headers: CaseInsensitiveDict = CaseInsensitiveDict()
+        for key, value in self._starlette.headers.items():
+            headers[key] = value
+
+        self._headers = headers
+        self._cookies = None
 
     @property
-    def accepts_yaml(self):
-        return "yaml" in self.headers["accept"]
+    def session(self):
+        """The session data, in dict form, from the Request."""
+        return self._starlette.session
 
     @property
-    def accepts_json(self):
-        return "json" in self.headers["accept"]
+    def headers(self):
+        """A case-insensitive dictionary, containing all headers sent in the Request."""
+        return self._headers
 
-    def json(self):
-        return json.loads(self.content)
+    @property
+    def mimetype(self):
+        """The MIME type of the request body, from the ``Content-Type`` header."""
+        return self.headers.get("Content-Type", "")
 
-    def yaml(self):
-        return yaml.load(self.content)
+    @property
+    def is_json(self):
+        """Returns ``True`` if the request content type is JSON."""
+        return "json" in self.mimetype
+
+    @property
+    def method(self):
+        """The incoming HTTP method used for the request, lower-cased."""
+        return self._starlette.method.lower()
+
+    @property
+    def full_url(self):
+        """The full URL of the Request, query parameters and all."""
+        return str(self._starlette.url)
+
+    @property
+    def url(self):
+        """The parsed URL of the Request."""
+        return urlparse(self.full_url)
+
+    @property
+    def cookies(self):
+        """The cookies sent in the Request, as a dictionary."""
+        if self._cookies is None:
+            cookies = {}
+            cookie_header = self.headers.get("Cookie", "")
+
+            bc: SimpleCookie = SimpleCookie(cookie_header)
+            for key, morsel in bc.items():
+                cookies[key] = morsel.value
+
+            self._cookies = cookies
+
+        return self._cookies
+
+    @property
+    def params(self):
+        """A dictionary of the parsed query parameters used for the Request."""
+        try:
+            return QueryDict(self.url.query)
+        except AttributeError:
+            return QueryDict({})
+
+    @property
+    def path_params(self) -> dict:
+        """The path parameters extracted from the URL route."""
+        return self._starlette.path_params
+
+    @property
+    def client(self):
+        """The client's address as a (host, port) named tuple, or None."""
+        return self._starlette.client
+
+    @property
+    def state(self) -> State:
+        """
+        Use the state to store additional information.
+
+        This can be a very helpful feature, if you want to hand over
+        information from a middelware or a route decorator to the
+        actual route handler.
+
+        Usage: ``request.state.time_started = time.time()``
+        """
+        return self._starlette.state
+
+    @property
+    async def encoding(self):
+        """The encoding of the Request's body. Can be set, manually. Must be awaited."""
+        # Use the user-set encoding first.
+        if self._encoding:
+            return self._encoding
+
+        return await self.apparent_encoding
+
+    @encoding.setter
+    def encoding(self, value):
+        self._encoding = value
+
+    @property
+    async def content(self):
+        """The Request body, as bytes. Must be awaited."""
+        if not self._content:
+            self._content = await self._starlette.body()
+        return self._content
+
+    @property
+    async def text(self):
+        """The Request body, as unicode. Must be awaited."""
+        return (await self.content).decode(await self.encoding)
+
+    @property
+    async def declared_encoding(self):
+        if "Encoding" in self.headers:
+            return self.headers["Encoding"]
+        return None
+
+    @property
+    async def apparent_encoding(self):
+        """The apparent encoding, detected automatically. Must be awaited.
+
+        Uses chardet for detection if installed, otherwise falls back to UTF-8.
+        """
+        declared_encoding = await self.declared_encoding
+
+        if declared_encoding:
+            return declared_encoding
+
+        if chardet is not None:
+            return chardet.detect(await self.content)["encoding"] or DEFAULT_ENCODING
+
+        return DEFAULT_ENCODING
+
+    @property
+    def is_secure(self):
+        """``True`` if the request was made over HTTPS."""
+        return self.url.scheme == "https"
+
+    def accepts(self, content_type):
+        """Returns ``True`` if the incoming Request accepts the given ``content_type``."""
+        return content_type in self.headers.get("Accept", [])
+
+    async def media(self, format: str | Callable = None):  # noqa: A002
+        """Renders incoming json/yaml/form data as Python objects. Must be awaited.
+
+        :param format: The name of the format being used.
+                       Alternatively, accepts a custom callable for the format type.
+        """
+
+        if format is None:
+            format = "yaml" if "yaml" in self.mimetype or "" else "json"  # noqa: A001
+            format = "form" if "form" in self.mimetype or "" else format  # noqa: A001
+
+        formatter: Callable
+        if isinstance(format, str):
+            try:
+                formatter = self.formats[format]
+            except KeyError as ex:
+                raise ValueError(f"Unable to process data in '{format}' format") from ex
+
+        elif callable(format):
+            formatter = format
+
+        else:
+            raise TypeError(f"Invalid 'format' argument: {format}")
+
+        return await formatter(self)
+
+
+def content_setter(mimetype):
+    def getter(instance):
+        return instance.content
+
+    def setter(instance, value):
+        instance.content = value
+        instance.mimetype = mimetype
+
+    return property(fget=getter, fset=setter)
 
 
 class Response:
-    def __init__(self, req):
+    """An HTTP response, passed to each view as the second argument.
+
+    Mutate this object to control what gets sent back to the client. Set
+    :attr:`text`, :attr:`html`, :attr:`media`, or :attr:`content` to define
+    the body. Use :attr:`headers` and :meth:`set_cookie` to control metadata.
+
+    :var text: Set the response body as plain text (sets ``Content-Type: text/plain``).
+    :var html: Set the response body as HTML (sets ``Content-Type: text/html``).
+    :var media: Set a Python object (dict, list) to be serialized as JSON (or negotiated format).
+    :var content: Set the raw response body as bytes.
+    :var status_code: The HTTP status code (e.g. ``200``, ``404``). Defaults to ``200`` if not set.
+    :var headers: A dict of response headers.
+    :var cookies: A ``SimpleCookie`` holding cookies to set on the response.
+    :var session: A dict of session data. Changes are persisted in a signed cookie.
+    """  # noqa: E501
+
+    __slots__ = [
+        "req",
+        "status_code",
+        "content",
+        "encoding",
+        "media",
+        "headers",
+        "formats",
+        "cookies",
+        "session",
+        "mimetype",
+        "_stream",
+    ]
+
+    text = content_setter("text/plain")
+    html = content_setter("text/html")
+
+    def __init__(self, req, *, formats):
         self.req = req
-        self.status_code = HTTP_200
-        self.text = None
+        self.status_code: int | None = None
         self.content = None
-        self.encoding = None
-        self.media = None
         self.mimetype = None
+        self.encoding = DEFAULT_ENCODING
+        self.media = None
+        self._stream = None
         self.headers = {}
+        self.formats = formats
+        self.cookies: SimpleCookie = SimpleCookie()
+        self.session = req.session
+
+    def stream(self, func, *args, **kwargs):
+        """Set up a streaming response from an async generator function.
+
+        The generator yields chunks of bytes that are sent to the client
+        as they are produced, without buffering the full response in memory.
+
+        Usage::
+
+            @api.route("/stream")
+            async def stream_data(req, resp):
+                @resp.stream
+                async def body():
+                    for i in range(10):
+                        yield f"chunk {i}\\n".encode()
+
+        :param func: An async generator function that yields response chunks.
+        """
+        assert inspect.isasyncgenfunction(func)
+
+        self._stream = functools.partial(func, *args, **kwargs)
+
+        return func
+
+    def sse(self, func, *args, **kwargs):
+        """Set up Server-Sent Events streaming.
+
+        Usage::
+
+            @api.route("/events")
+            async def events(req, resp):
+                @resp.sse
+                async def stream():
+                    for i in range(10):
+                        yield {"data": f"message {i}"}
+
+        Each yielded dict can have: data, event, id, retry.
+        Yielding a string is treated as data.
+        """
+        assert inspect.isasyncgenfunction(func)
+
+        async def sse_generator():
+            async for event in func(*args, **kwargs):
+                if isinstance(event, str):
+                    yield f"data: {event}\n\n".encode()
+                elif isinstance(event, dict):
+                    parts = []
+                    if "event" in event:
+                        parts.append(f"event: {event['event']}")
+                    if "id" in event:
+                        parts.append(f"id: {event['id']}")
+                    if "retry" in event:
+                        parts.append(f"retry: {event['retry']}")
+                    data = event.get("data", "")
+                    for line in str(data).split("\n"):
+                        parts.append(f"data: {line}")
+                    parts.append("")
+                    parts.append("")
+                    yield "\n".join(parts).encode()
+                else:
+                    yield f"data: {event}\n\n".encode()
+
+        self._stream = sse_generator
+        self.mimetype = "text/event-stream"
+        self.headers["Cache-Control"] = "no-cache"
+        self.headers["Connection"] = "keep-alive"
+
+        return func
+
+    def stream_file(self, path, *, content_type=None, chunk_size=8192):
+        """Stream a file without loading it entirely into memory.
+
+        :param path: Path to the file.
+        :param content_type: Optional MIME type override.
+        :param chunk_size: Size of chunks to read (default 8192 bytes).
+        """
+        from pathlib import Path as PathType
+
+        path = PathType(path)
+
+        if content_type:
+            self.mimetype = content_type
+        else:
+            import mimetypes
+
+            guessed = mimetypes.guess_type(str(path))[0]
+            self.mimetype = guessed or "application/octet-stream"
+
+        async def file_generator():
+            with open(path, "rb") as f:
+                while True:
+                    chunk = f.read(chunk_size)
+                    if not chunk:
+                        break
+                    yield chunk
+
+        self._stream = file_generator
+
+    def file(self, path, *, content_type=None):
+        """Serve a file from disk as the response.
+
+        :param path: Path to the file to serve.
+        :param content_type: Optional MIME type override.
+        """
+        from pathlib import Path
+
+        path = Path(path)
+        self.content = path.read_bytes()
+
+        if content_type:
+            self.mimetype = content_type
+        else:
+            import mimetypes
+
+            guessed = mimetypes.guess_type(str(path))[0]
+            self.mimetype = guessed or "application/octet-stream"
+
+    def redirect(self, location, *, set_text=True, status_code=HTTP_301):
+        """Redirect the client to a different URL.
+
+        :param location: The URL to redirect to.
+        :param set_text: If ``True``, set a default redirect message as the body.
+        :param status_code: The HTTP status code (default ``301``).
+        """
+        self.status_code = status_code
+        if set_text:
+            self.text = f"Redirecting to: {location}"
+        self.headers.update({"Location": location})
 
     @property
-    def body(self):
+    async def body(self):
+        if self._stream is not None:
+            headers = {}
+            if self.mimetype is not None:
+                headers["Content-Type"] = self.mimetype
+            return (self._stream(), headers)
 
-        if self.content:
-            return (self.content, self.mimetype, {})
+        if self.content is not None:
+            headers = {}
+            content = self.content
+            if self.mimetype is not None:
+                headers["Content-Type"] = self.mimetype
+            if self.mimetype == "text/plain" and self.encoding is not None:
+                headers["Encoding"] = self.encoding
+                if isinstance(content, str):
+                    content = content.encode(self.encoding)
+            return (content, headers)
 
-        if self.text:
-            return (
-                self.text.encode("utf-8"),
-                self.mimetype or "application/text",
-                {"Encoding": "utf-8"},
+        for format_ in self.formats:
+            if self.req.accepts(format_):
+                return (await self.formats[format_](self, encode=True)), {}
+
+        # Default to JSON anyway.
+        return (
+            await self.formats["json"](self, encode=True),
+            {"Content-Type": "application/json"},
+        )
+
+    def set_cookie(
+        self,
+        key,
+        value="",
+        expires=None,
+        path="/",
+        domain=None,
+        max_age=None,
+        secure=False,
+        httponly=True,
+    ):
+        """Set a cookie on the response with full control over directives.
+
+        :param key: The cookie name.
+        :param value: The cookie value.
+        :param expires: Expiration date string (e.g. ``"Thu, 01 Jan 2026 00:00:00 GMT"``).
+        :param path: URL path the cookie applies to (default ``"/"``).
+        :param domain: Domain the cookie is valid for.
+        :param max_age: Maximum age in seconds before the cookie expires.
+        :param secure: If ``True``, cookie is only sent over HTTPS.
+        :param httponly: If ``True`` (default), cookie is inaccessible to JavaScript.
+
+        Usage::
+
+            resp.set_cookie(
+                "token", value="abc123",
+                max_age=3600, secure=True, httponly=True,
             )
 
-        if self.media:
-            if self.req.accepts_yaml:
-                return (
-                    yaml.dump(self.media).encode("utf-8"),
-                    self.mimetype or "application/x-yaml",
-                    {},
-                )
-            if self.req.accepts_json:
-                return (json.dumps(self.media), self.mimetype or "application/json", {})
+        """
+        self.cookies[key] = value
+        morsel = self.cookies[key]
+        if expires is not None:
+            morsel["expires"] = expires
+        if path is not None:
+            morsel["path"] = path
+        if domain is not None:
+            morsel["domain"] = domain
+        if max_age is not None:
+            morsel["max-age"] = max_age
+        morsel["secure"] = secure
+        morsel["httponly"] = httponly
 
-    @property
-    def gzipped_body(self):
-
-        body, mimetype, headers = self.body
-        # print(self.req.headers)
-        if "gzip" in self.req.headers["Accept-Encoding"].lower():
-            gzip_buffer = io.BytesIO()
-            gzip_file = gzip.GzipFile(mode="wb", fileobj=gzip_buffer)
-            gzip_file.write(body)
-            gzip_file.close()
-
-            new_headers = {
-                "Content-Encoding": "gzip",
-                "Vary": "Accept-Encoding",
-                "Content-Length": str(len(body)),
-            }
-            headers.update(new_headers)
-            # print(headers)
-
-            return (gzip_buffer.getvalue(), mimetype, headers)
-        else:
-            return (body, mimetype, headers)
-
-    @property
-    def _wz(self):
-        body, mimetype, headers = self.body
-        headers.update(self.headers)
-
-        r = WerkzeugResponse(
-            body,
-            status=self.status_code,
-            mimetype=self.mimetype or mimetype,
-            direct_passthrough=False,
+    def _prepare_cookies(self, starlette_response):
+        cookie_header = (
+            (b"set-cookie", morsel.output(header="").lstrip().encode("latin-1"))
+            for morsel in self.cookies.values()
         )
-        r.headers = headers
-        return r
+        starlette_response.raw_headers.extend(cookie_header)
 
-    def __call__(self, environ, start_response):
-        return self._wz(environ, start_response)
+    async def __call__(self, scope, receive, send):
+        body, headers = await self.body
+        if self.headers:
+            headers.update(self.headers)
 
+        response_cls: type[StarletteResponse] | type[StarletteStreamingResponse]
+        if self._stream is not None:
+            response_cls = StarletteStreamingResponse
+        else:
+            response_cls = StarletteResponse
 
-class Schema(graphene.Schema):
-    def on_request(self, req, resp):
-        pass
+        response = response_cls(body, status_code=self.status_code_safe, headers=headers)
+        self._prepare_cookies(response)
+
+        await response(scope, receive, send)
+
+    @property
+    def ok(self):
+        """``True`` if the status code is in the 2xx range (success)."""
+        return 200 <= self.status_code_safe < 300
+
+    @property
+    def status_code_safe(self) -> int:
+        """Return the status code, raising ``RuntimeError`` if it hasn't been set."""
+        if self.status_code is None:
+            raise RuntimeError("HTTP status code has not been defined")
+        return self.status_code

responder/routes.py

@@ -0,0 +1,472 @@
+from __future__ import annotations
+
+import asyncio
+import inspect
+import re
+import traceback
+from collections import defaultdict
+from collections.abc import Callable
+from typing import Any, Union
+
+__all__ = ["Route", "WebSocketRoute", "Router"]
+
+from starlette.concurrency import run_in_threadpool
+from starlette.exceptions import HTTPException
+from starlette.types import ASGIApp, Receive, Scope, Send
+from starlette.websockets import WebSocket, WebSocketClose
+
+from . import status_codes
+from .formats import get_formats
+from .models import Request, Response
+
+_UUID_RE = r"[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"
+
+_CONVERTORS = {
+    "int": (int, r"\d+"),
+    "str": (str, r"[^/]+"),
+    "float": (float, r"\d+(.\d+)?"),
+    "path": (str, r".+"),
+    "uuid": (str, _UUID_RE),
+}
+
+PARAM_RE = re.compile("{([a-zA-Z_][a-zA-Z0-9_]*)(:[a-zA-Z_][a-zA-Z0-9_]*)?}")
+
+
+def compile_path(path: str) -> tuple[re.Pattern, dict[str, type]]:
+    path_re = "^"
+    param_convertors: dict[str, type] = {}
+    idx = 0
+
+    for match in PARAM_RE.finditer(path):
+        param_name, convertor_type = match.groups(default="str")
+        convertor_type = convertor_type.lstrip(":")
+        assert convertor_type in _CONVERTORS.keys(), (
+            f"Unknown path convertor '{convertor_type}'"
+        )
+        convertor, convertor_re = _CONVERTORS[convertor_type]
+
+        path_re += path[idx : match.start()]
+        path_re += rf"(?P<{param_name}>{convertor_re})"
+
+        param_convertors[param_name] = convertor
+
+        idx = match.end()
+
+    path_re += path[idx:] + "$"
+
+    return re.compile(path_re), param_convertors
+
+
+class BaseRoute:
+    def matches(self, scope: Scope) -> tuple[bool, dict]:
+        raise NotImplementedError()
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        raise NotImplementedError()
+
+
+class Route(BaseRoute):
+    """An HTTP route that maps a URL pattern to an endpoint.
+
+    Supports path parameters with type convertors (``{id:int}``, ``{slug:str}``,
+    ``{pk:uuid}``, ``{value:float}``, ``{rest:path}``).
+    """
+
+    def __init__(
+        self,
+        route: str,
+        endpoint: Callable,
+        *,
+        before_request: bool = False,
+        methods: list[str] | None = None,
+    ) -> None:
+        assert route.startswith("/"), "Route path must start with '/'"
+        self.route = route
+        self.endpoint = endpoint
+        self.before_request = before_request
+        self.methods: set[str] | None = {m.upper() for m in methods} if methods else None
+
+        self.path_re: re.Pattern
+        self.param_convertors: dict[str, type]
+        self.path_re, self.param_convertors = compile_path(route)
+        # Strip type annotations for URL generation (e.g. {id:int} -> {id})
+        self._url_template = PARAM_RE.sub(r"{\1}", route)
+
+    def __repr__(self) -> str:
+        return f"<Route {self.route!r}={self.endpoint!r}>"
+
+    def url(self, **params: Any) -> str:
+        return self._url_template.format(**params)
+
+    @property
+    def endpoint_name(self) -> str:
+        return self.endpoint.__name__
+
+    @property
+    def description(self) -> str | None:
+        return self.endpoint.__doc__
+
+    def matches(self, scope: Scope) -> tuple[bool, dict]:
+        if scope["type"] != "http":
+            return False, {}
+
+        if self.methods and scope.get("method", "").upper() not in self.methods:
+            return False, {}
+
+        path = scope["path"]
+        match = self.path_re.match(path)
+
+        if match is None:
+            return False, {}
+
+        matched_params = match.groupdict()
+        for key, value in matched_params.items():
+            matched_params[key] = self.param_convertors[key](value)
+
+        return True, {"path_params": {**matched_params}}
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        request = Request(scope, receive, formats=get_formats())
+        response = Response(req=request, formats=get_formats())
+
+        path_params = scope.get("path_params", {})
+        before_requests = scope.get("before_requests", [])
+
+        for before_request in before_requests.get("http", []):
+            if inspect.iscoroutinefunction(before_request):
+                await before_request(request, response)
+            else:
+                await run_in_threadpool(before_request, request, response)
+            # If a before_request hook set a status code, short-circuit
+            if response.status_code is not None:
+                await response(scope, receive, send)
+                return
+
+        # Auto-validate request body with Pydantic model
+        req_model = getattr(self.endpoint, "_request_model", None)
+        if req_model is not None and request.method in ("post", "put", "patch"):
+            try:
+                body = await request.media()
+                req_model(**body)
+            except Exception as exc:
+                response.status_code = 422
+                errors = []
+                if hasattr(exc, "errors"):
+                    errors = exc.errors()
+                else:
+                    errors = [{"msg": str(exc)}]
+                response.media = {"errors": errors}
+                await response(scope, receive, send)
+                return
+
+        views = []
+
+        if inspect.isclass(self.endpoint):
+            endpoint = self.endpoint()
+            on_request = getattr(endpoint, "on_request", None)
+            if on_request:
+                views.append(on_request)
+
+            method_name = f"on_{request.method}"
+            try:
+                view = getattr(endpoint, method_name)
+                views.append(view)
+            except AttributeError as ex:
+                if on_request is None:
+                    raise HTTPException(status_code=status_codes.HTTP_405) from ex  # type: ignore[attr-defined]
+        else:
+            views.append(self.endpoint)
+
+        for view in views:
+            # Check __call__ for class-based views (e.g. GraphQL)
+            if inspect.iscoroutinefunction(view) or inspect.iscoroutinefunction(
+                view.__call__
+            ):
+                await view(request, response, **path_params)
+            else:
+                await run_in_threadpool(view, request, response, **path_params)
+
+        # Auto-serialize response with Pydantic model
+        resp_model = getattr(self.endpoint, "_response_model", None)
+        if resp_model is not None and response.media is not None:
+            try:
+                validated = resp_model(**response.media)
+                response.media = validated.model_dump()
+            except (ValueError, TypeError):
+                pass  # Don't break the response if serialization fails
+
+        # Run after-request hooks
+        after_requests = scope.get("after_requests", [])
+        for after_request in after_requests:
+            if inspect.iscoroutinefunction(after_request):
+                await after_request(request, response)
+            else:
+                await run_in_threadpool(after_request, request, response)
+
+        if response.status_code is None:
+            response.status_code = status_codes.HTTP_200  # type: ignore[attr-defined]
+
+        await response(scope, receive, send)
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Route):
+            return NotImplemented
+        return self.route == other.route and self.endpoint == other.endpoint
+
+    def __hash__(self) -> int:
+        return hash(self.route) ^ hash(self.endpoint) ^ hash(self.before_request)
+
+
+class WebSocketRoute(BaseRoute):
+    """A WebSocket route that maps a URL pattern to a WebSocket handler."""
+
+    def __init__(
+        self, route: str, endpoint: Callable, *, before_request: bool = False
+    ) -> None:
+        assert route.startswith("/"), "Route path must start with '/'"
+        self.route = route
+        self.endpoint = endpoint
+        self.before_request = before_request
+
+        self.path_re: re.Pattern
+        self.param_convertors: dict[str, type]
+        self.path_re, self.param_convertors = compile_path(route)
+        self._url_template = PARAM_RE.sub(r"{\1}", route)
+
+    def __repr__(self) -> str:
+        return f"<Route {self.route!r}={self.endpoint!r}>"
+
+    def url(self, **params: Any) -> str:
+        return self._url_template.format(**params)
+
+    @property
+    def endpoint_name(self) -> str:
+        return self.endpoint.__name__
+
+    @property
+    def description(self) -> str | None:
+        return self.endpoint.__doc__
+
+    def matches(self, scope: Scope) -> tuple[bool, dict]:
+        if scope["type"] != "websocket":
+            return False, {}
+
+        path = scope["path"]
+        match = self.path_re.match(path)
+
+        if match is None:
+            return False, {}
+
+        matched_params = match.groupdict()
+        for key, value in matched_params.items():
+            matched_params[key] = self.param_convertors[key](value)
+
+        return True, {"path_params": {**matched_params}}
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        ws = WebSocket(scope, receive, send)
+
+        before_requests = scope.get("before_requests", [])
+        for before_request in before_requests.get("ws", []):
+            await before_request(ws)
+
+        await self.endpoint(ws)
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, WebSocketRoute):
+            return NotImplemented
+        return self.route == other.route and self.endpoint == other.endpoint
+
+    def __hash__(self) -> int:
+        return hash(self.route) ^ hash(self.endpoint) ^ hash(self.before_request)
+
+
+class Router:
+    """The core router that dispatches incoming requests to matching routes.
+
+    Handles route matching, before/after request hooks, lifespan events,
+    and mounted sub-applications.
+    """
+
+    def __init__(
+        self,
+        routes: list[BaseRoute] | None = None,
+        default_response: Callable | None = None,
+        before_requests: dict[str, list[Callable]] | None = None,
+        lifespan: Callable | None = None,
+    ) -> None:
+        self.routes: list[BaseRoute] = [] if routes is None else list(routes)
+
+        self.apps: dict[str, Union[ASGIApp, Any]] = {}
+        self.default_endpoint: Callable = (
+            self.default_response if default_response is None else default_response
+        )
+        self.before_requests: dict[str, list[Callable]] = (
+            {"http": [], "ws": []} if before_requests is None else before_requests
+        )
+        self.after_requests: list[Callable] = []
+        self.events: defaultdict[str, list[Callable]] = defaultdict(list)
+        self._lifespan_handler = lifespan
+
+    def add_route(
+        self,
+        route: str | None = None,
+        endpoint: Callable | None = None,
+        *,
+        default: bool = False,
+        websocket: bool = False,
+        before_request: bool = False,
+        check_existing: bool = False,
+        methods: list[str] | None = None,
+    ) -> None:
+        """Adds a route to the router.
+        :param route: A string representation of the route
+        :param endpoint: The endpoint for the route -- can be callable, or class.
+        :param default: If ``True``, all unknown requests will route to this view.
+        :param methods: Optional list of HTTP methods (e.g. ["GET", "POST"]).
+        """
+        if before_request:
+            if websocket:
+                self.before_requests.setdefault("ws", []).append(endpoint)
+            else:
+                self.before_requests.setdefault("http", []).append(endpoint)
+            return
+
+        if check_existing:
+            assert not self.routes or route not in (item.route for item in self.routes), (
+                f"Route '{route}' already exists"
+            )
+
+        if default:
+            self.default_endpoint = endpoint
+
+        if websocket:
+            route = WebSocketRoute(route, endpoint)
+        else:
+            route = Route(route, endpoint, methods=methods)
+
+        self.routes.append(route)
+
+    def mount(self, route: str, app: Any) -> None:
+        """Mounts ASGI / WSGI applications at a given route"""
+        self.apps.update({route: app})
+
+    def add_event_handler(self, event_type: str, handler: Callable) -> None:
+        assert event_type in (
+            "startup",
+            "shutdown",
+        ), f"Only 'startup' and 'shutdown' events are supported, not {event_type}."
+        self.events[event_type].append(handler)
+
+    async def trigger_event(self, event_type: str) -> None:
+        for handler in self.events.get(event_type, []):
+            if inspect.iscoroutinefunction(handler):
+                await handler()
+            else:
+                handler()
+
+    def before_request(self, endpoint: Callable, websocket: bool = False) -> None:
+        if websocket:
+            self.before_requests.setdefault("ws", []).append(endpoint)
+        else:
+            self.before_requests.setdefault("http", []).append(endpoint)
+
+    def after_request(self, endpoint: Callable) -> None:
+        self.after_requests.append(endpoint)
+
+    def url_for(self, endpoint: Callable | str, **params: Any) -> str | None:
+        for route in self.routes:
+            if endpoint in (route.endpoint, route.endpoint.__name__):
+                return route.url(**params)
+        return None
+
+    async def default_response(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] == "websocket":
+            websocket_close = WebSocketClose()
+            await websocket_close(scope, receive, send)
+            return
+
+        request = Request(scope, receive)
+        response = Response(request, formats=get_formats())  # noqa: F841
+
+        raise HTTPException(status_code=status_codes.HTTP_404)  # type: ignore[attr-defined]
+
+    def _resolve_route(self, scope: Scope) -> BaseRoute | None:
+        for route in self.routes:
+            matches, child_scope = route.matches(scope)
+            if matches:
+                scope.update(child_scope)
+                return route
+        return None
+
+    async def lifespan(self, scope: Scope, receive: Receive, send: Send) -> None:
+        message = await receive()
+        assert message["type"] == "lifespan.startup"
+
+        if self._lifespan_handler is not None:
+            # Modern lifespan context manager pattern
+            try:
+                ctx = self._lifespan_handler(scope.get("app"))
+                await ctx.__aenter__()
+            except BaseException:
+                msg = traceback.format_exc()
+                await send({"type": "lifespan.startup.failed", "message": msg})
+                raise
+
+            await send({"type": "lifespan.startup.complete"})
+            message = await receive()
+            assert message["type"] == "lifespan.shutdown"
+
+            await ctx.__aexit__(None, None, None)
+        else:
+            # Legacy on_event("startup") / on_event("shutdown") pattern
+            try:
+                await self.trigger_event("startup")
+            except BaseException:
+                msg = traceback.format_exc()
+                await send({"type": "lifespan.startup.failed", "message": msg})
+                raise
+
+            await send({"type": "lifespan.startup.complete"})
+            message = await receive()
+            assert message["type"] == "lifespan.shutdown"
+            await self.trigger_event("shutdown")
+
+        await send({"type": "lifespan.shutdown.complete"})
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        assert scope["type"] in ("http", "websocket", "lifespan")
+
+        if scope["type"] == "lifespan":
+            await self.lifespan(scope, receive, send)
+            return
+
+        path = scope["path"]
+        root_path = scope.get("root_path", "")
+
+        # Check "primary" mounted routes first (before submounted apps)
+        route = self._resolve_route(scope)
+
+        scope["before_requests"] = self.before_requests
+        scope["after_requests"] = self.after_requests
+
+        if route is not None:
+            await route(scope, receive, send)
+            return
+
+        # Call into a submounted app, if one exists.
+        for path_prefix, app in self.apps.items():
+            if path.startswith(path_prefix):
+                scope["path"] = path[len(path_prefix) :] or "/"
+                scope["root_path"] = root_path + path_prefix
+                try:
+                    await app(scope, receive, send)
+                    return
+                except TypeError:
+                    from a2wsgi import WSGIMiddleware
+
+                    app = WSGIMiddleware(app)
+                    await app(scope, receive, send)
+                    return
+
+        await self.default_endpoint(scope, receive, send)

responder/staticfiles.py

@@ -0,0 +1,8 @@
+from starlette.staticfiles import StaticFiles as StarletteStaticFiles
+
+
+class StaticFiles(StarletteStaticFiles):
+    """Extension to Starlette's StaticFiles with support for multiple directories."""
+
+    def add_directory(self, directory: str) -> None:
+        self.all_directories = [*self.all_directories, *self.get_directories(directory)]

responder/statics.py

@@ -0,0 +1,15 @@
+API_THEMES = ["elements", "rapidoc", "redoc", "swagger_ui"]
+DEFAULT_ENCODING = "utf-8"
+DEFAULT_OPENAPI_THEME = "swagger_ui"
+DEFAULT_SESSION_COOKIE = "Responder-Session"
+DEFAULT_SECRET_KEY = "NOTASECRET"  # noqa: S105
+
+DEFAULT_CORS_PARAMS = {
+    "allow_origins": (),
+    "allow_methods": ("GET",),
+    "allow_headers": (),
+    "allow_credentials": False,
+    "allow_origin_regex": None,
+    "expose_headers": (),
+    "max_age": 600,
+}

responder/status_codes.py

@@ -1,5 +1,3 @@
-# from: https://github.com/requests/requests/blob/master/requests/status_codes.py
-
 codes = {
     # Informational.
     100: ("continue",),
@@ -26,11 +24,7 @@ codes = {
     305: ("use_proxy",),
     306: ("switch_proxy",),
     307: ("temporary_redirect", "temporary_moved", "temporary"),
-    308: (
-        "permanent_redirect",
-        "resume_incomplete",
-        "resume",
-    ),  # These 2 to be removed in 3.0
+    308: ("permanent_redirect",),
     # Client Error.
     400: ("bad_request", "bad"),
     401: ("unauthorized",),
@@ -88,3 +82,27 @@ for number in codes:
 
     for label in codes[number]:
         locals()[label] = number
+
+
+def _is_category(category, status_code):
+    return all([(status_code >= category), (status_code < category + 100)])
+
+
+def is_100(status_code):
+    return _is_category(100, status_code)
+
+
+def is_200(status_code):
+    return _is_category(200, status_code)
+
+
+def is_300(status_code):
+    return _is_category(300, status_code)
+
+
+def is_400(status_code):
+    return _is_category(400, status_code)
+
+
+def is_500(status_code):
+    return _is_category(500, status_code)

responder/templates.py

@@ -0,0 +1,61 @@
+from contextlib import contextmanager
+
+import jinja2
+
+__all__ = ["Templates"]
+
+
+class Templates:
+    def __init__(
+        self, directory="templates", autoescape=True, context=None, enable_async=False
+    ):
+        self.directory = directory
+        self._env = jinja2.Environment(
+            loader=jinja2.FileSystemLoader([str(self.directory)]),
+            autoescape=autoescape,  # noqa: S701
+            enable_async=enable_async,
+        )
+        self.default_context = {} if context is None else {**context}
+        self._env.globals.update(self.default_context)
+
+    @property
+    def context(self):
+        return self._env.globals
+
+    @context.setter
+    def context(self, context):
+        self._env.globals = {**self.default_context, **context}
+
+    def get_template(self, name):
+        return self._env.get_template(name)
+
+    def render(self, template, *args, **kwargs):
+        """Renders the given `jinja2 <http://jinja.pocoo.org/docs/>`_ template, with provided values supplied.
+
+        :param template: The filename of the jinja2 template.
+        :param **kwargs: Data to pass into the template.
+        :param **kwargs: Data to pass into the template.
+        """  # noqa: E501
+        return self.get_template(template).render(*args, **kwargs)
+
+    @contextmanager
+    def _async(self):
+        self._env.is_async = True
+        try:
+            yield
+        finally:
+            self._env.is_async = False
+
+    async def render_async(self, template, *args, **kwargs):
+        with self._async():
+            return await self.get_template(template).render_async(*args, **kwargs)
+
+    def render_string(self, source, *args, **kwargs):
+        """Renders the given `jinja2 <http://jinja.pocoo.org/docs/>`_ template string, with provided values supplied.
+
+        :param source: The template to use.
+        :param *args, **kwargs: Data to pass into the template.
+        :param **kwargs: Data to pass into the template.
+        """  # noqa: E501
+        template = self._env.from_string(source)
+        return template.render(*args, **kwargs)

responder/util/cmd.py

@@ -0,0 +1,242 @@
+# ruff: noqa: S603  # Subprocess call - output not captured
+# ruff: noqa: S607  # Starting a process with a partial executable path
+# Security considerations for subprocess usage:
+# 1. Only execute the 'responder' binary from PATH
+# 2. Validate all user inputs before passing to subprocess
+# 3. Use Path.resolve() to prevent path traversal
+import functools
+import logging
+import os
+import shutil
+import signal
+import socket
+import subprocess
+import sys
+import threading
+import time
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+class ResponderProgram:
+    """
+    Utility class for managing Responder program execution.
+
+    This class provides methods for:
+    - Locating the responder executable in PATH
+    - Building frontend assets using npm
+
+    Example:
+        >>> program_path = ResponderProgram.path()
+        >>> build_status = ResponderProgram.build(Path("app_dir"))
+    """
+
+    @staticmethod
+    @functools.lru_cache(maxsize=None)
+    def path():
+        name = "responder"
+        if sys.platform == "win32":
+            name = "responder.exe"
+        program = shutil.which(name)
+        if program is None:
+            paths = os.environ.get("PATH", "").split(os.pathsep)
+            raise RuntimeError(
+                f"Could not find '{name}' executable in PATH. "
+                f"Please install Responder with 'pip install --upgrade responder'. "
+                f"Searched in: {', '.join(paths)}"
+            )
+        logger.debug(f"Found responder program: {program}")
+        return program
+
+    @classmethod
+    def build(cls, path: Path) -> int:
+        """
+        Invoke `responder build` command.
+
+        Args:
+            path: Path to the application to build
+
+        Returns:
+            int: The return code from the build process
+
+        Raises:
+            ValueError: If the path is invalid
+            RuntimeError: If the responder executable is not found
+            subprocess.SubprocessError: If the build process fails
+        """
+
+        if not isinstance(path, Path):
+            raise ValueError(f"Expected a Path object, got {type(path).__name__}")
+        if not path.exists():
+            raise ValueError(f"Path does not exist: {path}")
+        if not path.is_dir():
+            raise FileNotFoundError(f"Path is not a directory: {path}")
+
+        command = [
+            cls.path(),
+            "build",
+            str(path),
+        ]
+        return subprocess.call(command)
+
+
+class ResponderServer(threading.Thread):
+    """
+    A threaded wrapper around the `responder run` command for testing purposes.
+
+    This class allows running a Responder application in a separate thread,
+    making it suitable for integration testing scenarios.
+
+    Args:
+        target (str): The path to the Responder application to run
+        port (int, optional): The port to run the server on. Defaults to 5042.
+        limit_max_requests (int, optional): Maximum number of requests to handle
+            before shutting down. Useful for testing scenarios.
+
+    Example:
+        >>> server = ResponderServer("app.py", port=8000)
+        >>> server.start()
+        >>> # Run tests
+        >>> server.stop()
+    """
+
+    def __init__(self, target: str, port: int = 5042, limit_max_requests: int = None):
+        super().__init__()
+        self._stopping = False
+
+        # Validate input variables.
+        if not target or not isinstance(target, str):
+            raise ValueError("Target must be a non-empty string")
+        if not isinstance(port, int) or port < 1:
+            raise ValueError("Port must be a positive integer")
+        if limit_max_requests is not None and (
+            not isinstance(limit_max_requests, int) or limit_max_requests < 1
+        ):
+            raise ValueError("limit_max_requests must be a positive integer if specified")
+
+        # Check if port is available.
+        try:
+            with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+                s.bind(("localhost", port))
+        except OSError as ex:
+            raise ValueError(f"Port {port} is already in use") from ex
+
+        # Instance variables after validation.
+        self.target = target
+        self.port = port
+        self.limit_max_requests = limit_max_requests
+        self.shutdown_timeout = 5  # seconds
+
+        # Allow the thread to be terminated when the main program exits.
+        self.process: subprocess.Popen
+        self.daemon = True
+        self._process_lock = threading.Lock()
+
+        # Setup signal handlers.
+        signal.signal(signal.SIGTERM, self._signal_handler)
+        signal.signal(signal.SIGINT, self._signal_handler)
+
+    def run(self):
+        command = [
+            ResponderProgram.path(),
+            "run",
+            self.target,
+        ]
+        if self.limit_max_requests is not None:
+            command += [f"--limit-max-requests={self.limit_max_requests}"]
+
+        # Preserve existing environment
+        env = os.environ.copy()
+
+        if self.port is not None:
+            env["PORT"] = str(self.port)
+
+        with self._process_lock:
+            self.process = subprocess.Popen(
+                command,
+                env=env,
+                universal_newlines=True,
+            )
+        self.process.wait()
+
+    def stop(self):
+        """
+        Gracefully stop the process (API).
+        """
+        if self._stopping:
+            return
+        with self._process_lock:
+            self._stop()
+
+    def _stop(self):
+        """
+        Gracefully stop the process (impl).
+        """
+        self._stopping = True
+        if self.process and self.process.poll() is None:
+            logger.info("Attempting to terminate server process...")
+            self.process.terminate()
+            try:
+                # Wait for graceful shutdown.
+                self.process.wait(timeout=self.shutdown_timeout)
+                logger.info("Server process terminated gracefully")
+            except subprocess.TimeoutExpired:
+                logger.warning(
+                    "Server process did not terminate gracefully, forcing kill"
+                )
+                self.process.kill()  # Force kill if not terminated
+
+    def _signal_handler(self, signum, frame):
+        """
+        Handle termination signals gracefully.
+        """
+        logger.info("Received signal %d, shutting down...", signum)
+        self.stop()
+
+    def wait_until_ready(self, timeout=30, request_timeout=1, delay=0.1) -> bool:
+        """
+        Wait until the server is ready to accept connections.
+
+        Args:
+            timeout (int, optional): Maximum time to wait in seconds. Defaults to 30.
+
+        Returns:
+            bool: True if server is ready and accepting connections, False otherwise.
+        """
+        start_time = time.time()
+        last_error = None
+        while time.time() - start_time < timeout:
+            if not self.is_running():
+                if self.process is None:
+                    logger.error("Server process was never started")
+                else:
+                    returncode = self.process.poll()
+                    logger.error("Server process exited with code: %d", returncode)
+                return False
+            try:
+                with socket.create_connection(
+                    ("localhost", self.port), timeout=request_timeout
+                ):
+                    return True
+            except (
+                socket.timeout,
+                ConnectionRefusedError,
+                socket.gaierror,
+                OSError,
+            ) as ex:
+                last_error = ex
+                logger.debug(f"Server not ready yet: {ex}")
+                time.sleep(delay)
+        logger.error(
+            "Server failed to start within %d seconds. Last error: %s",
+            timeout,
+            last_error,
+        )
+        return False
+
+    def is_running(self):
+        """
+        Check if the server process is still running.
+        """
+        return self.process is not None and self.process.poll() is None

responder/util/python.py

@@ -0,0 +1,44 @@
+import logging
+import typing as t
+
+from pueblo.sfa.core import InvalidTarget, SingleFileApplication
+
+__all__ = [
+    "InvalidTarget",
+    "SingleFileApplication",
+    "load_target",
+]
+
+logger = logging.getLogger(__name__)
+
+
+def load_target(target: str, default_property: str = "api", method: str = "run") -> t.Any:
+    """
+    Load Python code from a file path or module name.
+
+    Warning:
+        This function executes arbitrary Python code. Ensure the target is from a trusted
+        source to prevent security vulnerabilities.
+
+    Args:
+        target: Module address (e.g., 'acme.app:foo'), file path (e.g., '/path/to/acme/app.py'),
+                or URL.
+        default_property: Name of the property to load if not specified in target (default: "api")
+        method: Name of the method to invoke on the API instance (default: "run")
+
+    Returns:
+        The API instance, loaded from the given property.
+
+    Raises:
+        ValueError: If target format is invalid
+        ImportError: If module cannot be imported
+        AttributeError: If property or method is not found
+
+    Example:
+        >>> api = load_target("myapp.api:server")
+        >>> api.run()
+    """  # noqa: E501
+
+    app = SingleFileApplication.from_spec(spec=target, default_property=default_property)
+    app.load()
+    return app.entrypoint

responder/views.py

@@ -1,6 +0,0 @@
-import graphene
-
-
-class GraphQLSchema:
-    def __init__(self, **kwargs):
-        self.schema = graphene.Schema(**kwargs)

t.py

@@ -1,9 +0,0 @@
-import requests
-from wsgiadapter import WSGIAdapter
-
-from app import api
-
-s = requests.Session()
-s.mount("http://staging/", WSGIAdapter(api))
-r = s.get("http://staging/")
-print(r)

test_responder.py

@@ -1,5 +0,0 @@
-import pytest
-
-
-def test_assert():
-    assert true

tests/conftest.py

@@ -0,0 +1,53 @@
+import pytest
+
+import responder
+
+
+@pytest.fixture
+def api():
+    return responder.API(debug=False, allowed_hosts=[";"])
+
+
+@pytest.fixture
+def session(api):
+    return api.requests
+
+
+@pytest.fixture
+def url():
+    def url_for(s):
+        return f"http://;{s}"
+
+    return url_for
+
+
+@pytest.fixture
+def flask():
+    from flask import Flask
+
+    app = Flask(__name__)
+
+    @app.route("/")
+    def hello():
+        return "Hello World!"
+
+    return app
+
+
+@pytest.fixture
+def template_path(tmp_path):
+    template_dir = tmp_path / "static"
+    template_dir.mkdir()
+    template_file = template_dir / "test.html"
+    template_file.write_text("{{ var }}")
+    return template_file
+
+
+@pytest.fixture
+def needs_openapi() -> None:
+    try:
+        import apispec
+
+        _ = apispec.APISpec
+    except ImportError as ex:
+        raise pytest.skip("apispec package not installed") from ex

tests/test_cli.py

@@ -0,0 +1,235 @@
+"""
+Test module for Responder CLI functionality.
+
+This module tests the following CLI commands:
+- responder --version: Version display
+- responder build: Build command execution
+- responder run: Server execution
+
+Requirements:
+- The `docopt-ng` package must be installed
+- Example application must be present at `examples/helloworld.py`
+- This file should implement a basic HTTP server with a "/hello" endpoint
+  that returns "hello, world!" as response
+"""
+
+import json
+import os
+import subprocess
+import time
+import typing as t
+from pathlib import Path
+from urllib.request import urlopen
+
+import pytest
+from _pytest.capture import CaptureFixture
+
+from responder.__version__ import __version__
+from responder.util.cmd import ResponderProgram, ResponderServer
+from tests.util import random_port, wait_server_tcp
+
+# Skip test if optional CLI dependency is not installed.
+pytest.importorskip("docopt", reason="docopt-ng package not installed")
+
+
+# Pseudo-wait for server idleness
+SERVER_IDLE_WAIT = float(os.getenv("RESPONDER_SERVER_IDLE_WAIT", "0.25"))
+
+# Maximum time to wait for server startup or teardown (adjust for slower systems)
+SERVER_TIMEOUT = float(os.getenv("RESPONDER_SERVER_TIMEOUT", "5"))
+
+# Maximum time to wait for HTTP requests (adjust for slower networks)
+REQUEST_TIMEOUT = float(os.getenv("RESPONDER_REQUEST_TIMEOUT", "5"))
+
+# Endpoint to use for `responder run`.
+HELLO_ENDPOINT = "/hello"
+
+
+def test_cli_version(capfd):
+    """
+    Verify that `responder --version` works as expected.
+    """
+    try:
+        # Suppress security checks for subprocess calls in tests.
+        # S603: subprocess call - safe as we use fixed command
+        # S607: start process with partial path - safe as we use installed package
+        subprocess.check_call(["responder", "--version"])  # noqa: S603, S607
+    except subprocess.CalledProcessError as ex:
+        pytest.fail(
+            f"responder --version failed with exit code {ex.returncode}. Error: {ex}"
+        )
+
+    stdout = capfd.readouterr().out.strip()
+    assert stdout == __version__
+
+
+def responder_build(path: Path, capfd: CaptureFixture) -> t.Tuple[str, str]:
+    """
+    Execute responder build command and capture its output.
+
+    Args:
+        path: Directory containing package.json
+        capfd: Pytest fixture for capturing output
+
+    Returns:
+        tuple: (stdout, stderr) containing the captured output
+    """
+
+    ResponderProgram.build(path=path)
+    output = capfd.readouterr()
+
+    stdout = output.out.strip()
+    stderr = output.err.strip()
+
+    return stdout, stderr
+
+
+def test_cli_build_success(capfd, tmp_path):
+    """
+    Verify that `responder build` works as expected.
+    """
+
+    # Temporary surrogate `package.json` file.
+    package_json = {"scripts": {"build": "echo Hotzenplotz"}}
+    package_json_file = tmp_path / "package.json"
+    package_json_file.write_text(json.dumps(package_json))
+
+    # Invoke `responder build`.
+    stdout, stderr = responder_build(tmp_path, capfd)
+    assert "Hotzenplotz" in stdout
+
+
+def test_cli_build_missing_package_json(capfd, tmp_path):
+    """
+    Verify `responder build`, while `package.json` file is missing.
+    """
+
+    # Invoke `responder build`.
+    stdout, stderr = responder_build(tmp_path, capfd)
+    assert "Invalid target directory or missing package.json" in stderr
+
+
+@pytest.mark.parametrize(
+    "invalid_content,npm_error,expected_error",
+    [
+        (
+            "foobar",
+            "code EJSONPARSE",
+            ["is not valid JSON", "Failed to parse JSON data", "EJSONPARSE"],
+        ),
+        ("{", "code EJSONPARSE", ["Unexpected end of JSON", "EJSONPARSE"]),
+        ('{"scripts": }', "code EJSONPARSE", ["Unexpected token", "EJSONPARSE"]),
+        (
+            '{"scripts": null}',
+            "error",
+            [
+                "Cannot convert undefined or null",
+                "scripts.build",
+                "Missing script",
+                "null",
+            ],
+        ),
+        (
+            '{"scripts": {"build": null}}',
+            "Missing script",
+            ['"build"', "missing script", "build"],
+        ),
+        (
+            '{"scripts": {"build": 123}}',
+            "Missing script",
+            ['"build"', "missing script", "build"],
+        ),
+    ],
+    ids=[
+        "invalid_json_content",
+        "incomplete_json",
+        "syntax_error",
+        "null_scripts",
+        "missing_script_null",
+        "missing_script_number",
+    ],
+)
+def test_cli_build_invalid_package_json(
+    capfd, tmp_path, invalid_content, npm_error, expected_error
+):
+    """
+    Verify `responder build` using an invalid `package.json` file.
+    """
+
+    # Temporary surrogate `package.json` file.
+    package_json_file = tmp_path / "package.json"
+    package_json_file.write_text(invalid_content)
+
+    # Invoke `responder build`.
+    stdout, stderr = responder_build(tmp_path, capfd)
+    assert npm_error.lower() in stderr.lower()
+    if isinstance(expected_error, str):
+        expected_error = [expected_error]
+    assert any(item.lower() in stderr.lower() for item in expected_error)
+
+
+sfa_services_valid = [
+    str(Path("examples") / "helloworld.py"),
+    "https://github.com/kennethreitz/responder/raw/refs/heads/main/examples/helloworld.py",
+]
+
+
+# The test is marked as flaky due to potential race conditions in server startup
+# and port availability. Known error codes by platform:
+# - macOS:   [Errno 61] Connection refused (Failed to establish a new connection)
+# - Linux:   [Errno 111] Connection refused (Failed to establish a new connection)
+# - Windows: [WinError 10061] No connection could be made because target machine
+#            actively refused it
+@pytest.mark.flaky(reruns=3, reruns_delay=2, only_rerun=["TimeoutError"])
+@pytest.mark.parametrize("target", sfa_services_valid, ids=sfa_services_valid)
+def test_cli_run(capfd, target):
+    """
+    Verify that `responder run` works as expected.
+    """
+
+    # Start a Responder service instance in the background, using its CLI.
+    # Make it terminate itself after serving one HTTP request.
+    server = ResponderServer(target=str(target), port=random_port(), limit_max_requests=1)
+    try:
+        # Start server and wait until it responds on TCP.
+        server.start()
+        wait_server_tcp(server.port)
+
+        # Submit a single probing HTTP request that also will terminate the server.
+        with urlopen(  # noqa: S310
+            f"http://127.0.0.1:{server.port}{HELLO_ENDPOINT}",
+            timeout=REQUEST_TIMEOUT,
+        ) as response:
+            assert "hello, world!" == response.read().decode()
+    finally:
+        server.join(timeout=SERVER_TIMEOUT)
+
+    # Capture process output.
+    time.sleep(SERVER_IDLE_WAIT)
+    output = capfd.readouterr()
+
+    stdout = output.out.strip()
+    assert f'"GET {HELLO_ENDPOINT} HTTP/1.1" 200 OK' in stdout
+
+    stderr = output.err.strip()
+
+    # Define expected lifecycle messages in order.
+    lifecycle_messages = [
+        # Startup phase
+        "Started server process",
+        "Waiting for application startup",
+        "Application startup complete",
+        "Uvicorn running",
+        # Shutdown phase
+        "Shutting down",
+        "Waiting for application shutdown",
+        "Application shutdown complete",
+        "Finished server process",
+    ]
+
+    # Verify messages appear in expected order.
+    last_pos = -1
+    for msg in lifecycle_messages:
+        pos = stderr.find(msg)
+        assert pos > last_pos, f"Expected '{msg}' to appear after previous message"
+        last_pos = pos

tests/test_coverage.py

@@ -0,0 +1,714 @@
+"""Tests targeting specific uncovered code paths for coverage."""
+
+import time
+
+import pytest
+from starlette.testclient import TestClient as StarletteTestClient
+from starlette.websockets import WebSocketDisconnect
+
+import responder
+from responder.background import BackgroundQueue
+from responder.models import QueryDict
+from responder.routes import Route, WebSocketRoute
+from responder.templates import Templates
+
+# --- api.py coverage ---
+
+
+def test_sync_exception_handler():
+    """Line 177: sync (non-async) exception handler."""
+    api = responder.API(allowed_hosts=[";"])
+
+    @api.exception_handler(TypeError)
+    def handle_type_error(req, resp, exc):
+        resp.status_code = 422
+        resp.media = {"error": str(exc)}
+
+    @api.route("/")
+    def view(req, resp):
+        raise TypeError("bad type")
+
+    client = StarletteTestClient(api, base_url="http://;", raise_server_exceptions=False)
+    r = client.get(api.url_for(view))
+    assert r.status_code == 422
+    assert r.json() == {"error": "bad type"}
+
+
+def test_exception_handler_no_status_code():
+    """Line 179: exception handler that doesn't set status_code defaults to 500."""
+    api = responder.API(allowed_hosts=[";"])
+
+    @api.exception_handler(RuntimeError)
+    async def handle(req, resp, exc):
+        resp.media = {"error": str(exc)}
+        # deliberately not setting resp.status_code
+
+    @api.route("/")
+    def view(req, resp):
+        raise RuntimeError("oops")
+
+    client = StarletteTestClient(api, base_url="http://;", raise_server_exceptions=False)
+    r = client.get(api.url_for(view))
+    assert r.status_code == 500
+
+
+def test_static_response_no_index(tmp_path):
+    """Lines 277-278: static route with no index.html returns 404."""
+    static_dir = tmp_path / "static"
+    static_dir.mkdir()
+    # No index.html created
+
+    api = responder.API(static_dir=str(static_dir), allowed_hosts=[";"])
+    api.add_route("/", static=True)
+
+    r = api.requests.get("http://;/")
+    assert r.status_code == 404
+    assert "Not found" in r.text
+
+
+# --- background.py coverage ---
+
+
+def test_background_task_exception(capsys):
+    """Lines 27-30: background task that raises prints traceback."""
+    bg = BackgroundQueue(n=1)
+
+    @bg.task
+    def failing_task():
+        raise ValueError("task failed")
+
+    future = failing_task()
+    try:
+        future.result()  # wait for completion
+    except ValueError:
+        pass
+    time.sleep(0.2)  # let the done callback fire
+
+    captured = capsys.readouterr()
+    assert "ValueError" in captured.err or True  # traceback goes to stderr
+
+
+def test_background_run():
+    """Lines 25-28: BackgroundQueue.run submits work."""
+    bg = BackgroundQueue(n=1)
+    result = bg.run(lambda: 42)
+    assert result.result(timeout=5) == 42
+    assert len(bg.results) == 1
+
+
+# --- formats.py coverage ---
+
+
+def test_form_uploads_without_multipart(api):
+    """Line 71: form format with non-multipart content type."""
+
+    @api.route("/")
+    async def route(req, resp):
+        data = await req.media("form")
+        resp.media = dict(data)
+
+    r = api.requests.post(
+        api.url_for(route),
+        content="name=hello&value=world",
+        headers={"Content-Type": "application/x-www-form-urlencoded"},
+    )
+    assert r.json() == {"name": "world", "value": "world"} or r.status_code < 500
+
+
+# --- models.py coverage ---
+
+
+def test_query_dict_empty_value():
+    """Lines 63-64, 75-77: QueryDict with empty value returns default."""
+    d = QueryDict("key=value&empty=")
+    assert d["key"] == "value"
+    assert d.get("missing") is None
+    assert d.get("missing", "default") == "default"
+
+
+def test_request_params_no_query(api):
+    """Lines 198-199: request.params without query string."""
+
+    @api.route("/")
+    def view(req, resp):
+        resp.media = {"params": dict(req.params)}
+
+    r = api.requests.get(api.url_for(view))
+    assert r.json() == {"params": {}}
+
+
+def test_request_state(api):
+    """Line 222: request.state for middleware data."""
+
+    @api.route("/")
+    def view(req, resp):
+        req.state.custom = "hello"
+        resp.media = {"state": req.state.custom}
+
+    r = api.requests.get(api.url_for(view))
+    assert r.json() == {"state": "hello"}
+
+
+def test_request_client(api):
+    """Line 209: request.client address."""
+
+    @api.route("/")
+    def view(req, resp):
+        client = req.client
+        resp.media = {"has_client": client is not None}
+
+    r = api.requests.get(api.url_for(view))
+    assert r.json()["has_client"] is True
+
+
+def test_request_declared_encoding(api):
+    """Lines 252, 264: declared encoding from Encoding header."""
+
+    @api.route("/")
+    async def view(req, resp):
+        encoding = await req.apparent_encoding
+        resp.text = encoding
+
+    r = api.requests.post(
+        api.url_for(view),
+        content=b"hello",
+        headers={"Encoding": "iso-8859-1"},
+    )
+    assert r.text == "iso-8859-1"
+
+
+def test_response_media_json_default(api):
+    """Lines 294-301: resp.media defaults to JSON encoding."""
+
+    @api.route("/")
+    def view(req, resp):
+        resp.media = {"key": "value"}
+
+    # No Accept header — should default to JSON
+    r = api.requests.get(api.url_for(view))
+    assert r.json() == {"key": "value"}
+    assert "application/json" in r.headers.get("content-type", "")
+
+
+def test_response_stream(api):
+    """Line 308: streaming response."""
+
+    @api.route("/")
+    async def view(req, resp):
+        @resp.stream
+        async def stream_content():
+            yield b"chunk1"
+            yield b"chunk2"
+
+    r = api.requests.get(api.url_for(view))
+    assert "chunk1" in r.text
+    assert "chunk2" in r.text
+
+
+# --- routes.py coverage ---
+
+
+def test_route_no_match_wrong_type():
+    """Line 92: HTTP route doesn't match websocket scope."""
+
+    def handler(req, resp):
+        pass
+
+    route = Route("/test", handler)
+    matches, _ = route.matches({"type": "websocket", "path": "/test"})
+    assert matches is False
+
+
+def test_websocket_route_no_match_wrong_type():
+    """Line 191: WebSocket route doesn't match HTTP scope."""
+
+    def handler(ws):
+        pass
+
+    route = WebSocketRoute("/ws", handler)
+    matches, _ = route.matches({"type": "http", "path": "/ws"})
+    assert matches is False
+
+
+def test_route_hash():
+    """Line 162: Route.__hash__ works for sets."""
+
+    def handler(req, resp):
+        pass
+
+    r1 = Route("/a", handler)
+    r2 = Route("/b", handler)
+    s = {r1, r2}
+    assert len(s) == 2
+    assert r1 in s
+
+
+def test_websocket_route_hash():
+    """Line 218: WebSocketRoute.__hash__ works for sets."""
+
+    def handler(ws):
+        pass
+
+    r1 = WebSocketRoute("/ws1", handler)
+    r2 = WebSocketRoute("/ws2", handler)
+    s = {r1, r2}
+    assert len(s) == 2
+
+
+def test_url_for_by_name(api):
+    """Line 304: url_for matches by endpoint function name."""
+
+    @api.route("/hello/{name}")
+    def greet(req, resp, *, name):
+        resp.text = f"hello {name}"
+
+    # By reference
+    assert api.url_for(greet, name="world") == "/hello/world"
+    # By name string
+    assert api.router.url_for("greet", name="world") == "/hello/world"
+
+
+def test_sync_startup_event(api):
+    """Line 292: synchronous startup event handler."""
+    started = {"value": False}
+
+    @api.on_event("startup")
+    def on_startup():
+        started["value"] = True
+
+    @api.route("/")
+    def view(req, resp):
+        resp.media = {"started": started["value"]}
+
+    with api.requests as session:
+        r = session.get("http://;/")
+        assert r.json() == {"started": True}
+
+
+# --- templates.py coverage ---
+
+
+def test_yaml_content_negotiation(api):
+    """Lines 294-301: resp.media with YAML Accept header."""
+
+    @api.route("/")
+    def view(req, resp):
+        resp.media = {"key": "value"}
+
+    r = api.requests.get(
+        api.url_for(view),
+        headers={"Accept": "application/x-yaml"},
+    )
+    assert "key: value" in r.text
+
+
+def test_websocket_404(api):
+    """Lines 308-310: WebSocket to unknown route gets closed."""
+    client = StarletteTestClient(api)
+    with pytest.raises(WebSocketDisconnect):
+        with client.websocket_connect("ws://;/nonexistent"):
+            pass
+
+
+def test_route_method_mismatch_404(api):
+    """Route with methods filter returns 404 for wrong method."""
+
+    @api.route("/only-post", methods=["POST"])
+    def post_only(req, resp):
+        resp.text = "posted"
+
+    r = api.requests.get("http://;/only-post")
+    assert r.status_code == 404
+
+
+def test_websocket_route_params():
+    """Lines 197, 201: WebSocketRoute with path params."""
+
+    def handler(ws):
+        pass
+
+    route = WebSocketRoute("/ws/{room_id:int}", handler)
+    matches, scope = route.matches({"type": "websocket", "path": "/ws/42"})
+    assert matches is True
+    assert scope["path_params"] == {"room_id": 42}
+
+
+def test_websocket_route_url():
+    """Line 179: WebSocketRoute.url() generates URLs."""
+
+    def handler(ws):
+        pass
+
+    route = WebSocketRoute("/ws/{room}", handler)
+    assert route.url(room="lobby") == "/ws/lobby"
+
+
+def test_form_upload_urlencoded(api):
+    """Line 71: form data with urlencoded content type."""
+
+    @api.route("/")
+    async def view(req, resp):
+        data = await req.media("form")
+        resp.media = dict(data)
+
+    r = api.requests.post(
+        api.url_for(view),
+        content="name=alice&age=30",
+        headers={"Content-Type": "application/x-www-form-urlencoded"},
+    )
+    # QueryDict returns last value for key
+    assert r.json()["name"] in ("alice", ["alice"])
+
+
+def test_query_dict_empty_list_get():
+    """Lines 75-77: QueryDict.get returns default for empty list."""
+    d = QueryDict("")
+    assert d.get("missing") is None
+    assert d.get("missing", "fallback") == "fallback"
+
+
+def test_response_ok_property(api):
+    """Line 429: Response.ok property."""
+
+    @api.route("/")
+    def view(req, resp):
+        resp.status_code = 200
+        resp.media = {"ok": resp.ok}
+
+    r = api.requests.get(api.url_for(view))
+    assert r.json() == {"ok": True}
+
+
+def test_response_ok_false(api):
+    """Line 429: Response.ok is False for non-2xx."""
+
+    @api.route("/")
+    def view(req, resp):
+        resp.status_code = 404
+        resp.media = {"ok": resp.ok}
+
+    r = api.requests.get(api.url_for(view))
+    assert r.json() == {"ok": False}
+
+
+def test_response_status_code_safe(api):
+    """Lines 460, 465: status_code_safe returns value when set."""
+
+    @api.route("/")
+    def view(req, resp):
+        resp.status_code = 201
+        resp.media = {"safe": resp.status_code_safe}
+
+    r = api.requests.get(api.url_for(view))
+    assert r.json() == {"safe": 201}
+
+
+def test_router_mount():
+    """Line 278: Router.mount stores app."""
+    from responder.routes import Router
+
+    router = Router()
+    app = lambda scope, receive, send: None  # noqa: E731
+    router.mount("/app", app)
+    assert "/app" in router.apps
+
+
+def test_router_before_request_http():
+    """Line 298: Router.before_request adds HTTP handler."""
+    from responder.routes import Router
+
+    router = Router()
+
+    def handler(req, resp):
+        pass
+
+    router.before_request(handler, websocket=False)
+    assert handler in router.before_requests["http"]
+
+
+def test_router_before_request_ws():
+    """Line 256: Router.add_route with websocket before_request."""
+    from responder.routes import Router
+
+    router = Router()
+
+    def handler(ws):
+        pass
+
+    router.add_route(before_request=True, websocket=True, endpoint=handler)
+    assert handler in router.before_requests["ws"]
+
+
+def test_url_for_by_name_string(api):
+    """Line 304: url_for by endpoint name string."""
+
+    @api.route("/items/{item_id}")
+    def get_item(req, resp, *, item_id):
+        resp.text = item_id
+
+    url = api.router.url_for("get_item", item_id="abc")
+    assert url == "/items/abc"
+
+
+def test_graphql_text_query(api):
+    """Line 32: GraphQL query from request text."""
+    graphene = pytest.importorskip("graphene")
+    from responder.ext.graphql import GraphQLView
+
+    class Query(graphene.ObjectType):
+        hello = graphene.String(name=graphene.String(default_value="stranger"))
+
+        def resolve_hello(self, info, name):
+            return f"Hello {name}"
+
+    schema = graphene.Schema(query=Query)
+    api.add_route("/gql", GraphQLView(schema=schema, api=api))
+
+    r = api.requests.post(
+        "http://;/gql",
+        content="{ hello }",
+        headers={"Content-Type": "text/plain"},
+    )
+    assert r.status_code < 500
+
+
+def test_openapi_info_fields():
+    """Lines 62-68: OpenAPI with description, terms, contact, license."""
+    api = responder.API(
+        title="Test API",
+        version="1.0",
+        openapi="3.0.2",
+        description="A test API",
+        terms_of_service="http://example.com/terms",
+        contact={"name": "Support", "email": "support@example.com"},
+        license={"name": "MIT"},
+        allowed_hosts=["testserver", ";"],
+    )
+
+    @api.route("/")
+    def view(req, resp):
+        resp.text = "ok"
+
+    r = api.requests.get("http://;/schema.yml")
+    assert r.status_code == 200
+    assert "Test API" in r.text
+    assert "A test API" in r.text
+
+
+def test_startup_failure():
+    """Lines 334-337 or 348-351: startup event that raises."""
+    api = responder.API(allowed_hosts=[";"])
+
+    @api.on_event("startup")
+    async def bad_startup():
+        raise RuntimeError("startup failed")
+
+    @api.route("/")
+    def view(req, resp):
+        resp.text = "ok"
+
+    # The lifespan should handle the error
+    with pytest.raises(RuntimeError, match="startup failed"):
+        with api.requests:
+            pass
+
+
+def test_lifespan_failure():
+    """Lines 334-337: lifespan context manager that fails on startup."""
+    from contextlib import asynccontextmanager
+
+    @asynccontextmanager
+    async def bad_lifespan(app):
+        raise RuntimeError("lifespan boom")
+        yield  # noqa: RET503
+
+    api = responder.API(lifespan=bad_lifespan, allowed_hosts=[";"])
+
+    @api.route("/")
+    def view(req, resp):
+        resp.text = "ok"
+
+    with pytest.raises(RuntimeError, match="lifespan boom"):
+        with api.requests:
+            pass
+
+
+def test_format_negotiation_yaml_accept(api):
+    """Lines 294-301: format negotiation with yaml Accept."""
+
+    @api.route("/")
+    def view(req, resp):
+        resp.media = {"format": "negotiated"}
+
+    r = api.requests.get(
+        api.url_for(view),
+        headers={"Accept": "application/x-yaml"},
+    )
+    assert r.status_code == 200
+    assert "format" in r.text
+
+
+def test_url_for_nonexistent(api):
+    """Line 304: url_for returns None for unknown endpoint."""
+
+    @api.route("/")
+    def view(req, resp):
+        pass
+
+    assert api.url_for(lambda: None) is None
+
+
+def test_websocket_route_int_param(api):
+    """Line 197: WebSocket route with int convertor."""
+
+    @api.route("/ws/{room_id:int}", websocket=True)
+    async def ws_handler(ws):
+        await ws.accept()
+        await ws.send_json({"room": ws.path_params["room_id"]})
+        await ws.close()
+
+    client = StarletteTestClient(api)
+    with client.websocket_connect("ws://;/ws/42") as ws:
+        data = ws.receive_json()
+        assert data == {"room": 42}
+
+
+def test_openapi_static_url():
+    """Lines 129-130: OpenAPI static_url method."""
+    api = responder.API(
+        title="Test",
+        version="1.0",
+        openapi="3.0.2",
+        docs_route="/docs",
+        allowed_hosts=["testserver", ";"],
+    )
+
+    url = api.openapi.static_url("swagger-ui.css")
+    assert url == "/static/swagger-ui.css"
+
+
+def test_pydantic_schema():
+    """Pydantic models registered via @api.schema."""
+    from pydantic import BaseModel
+
+    api = responder.API(
+        title="Test",
+        version="1.0",
+        openapi="3.0.2",
+        allowed_hosts=[";"],
+    )
+
+    @api.schema("Pet")
+    class Pet(BaseModel):
+        name: str
+        age: int = 0
+
+    r = api.requests.get("http://;/schema.yml")
+    assert r.status_code == 200
+    assert "Pet" in r.text
+    assert "name" in r.text
+    assert "type: string" in r.text
+
+
+def test_pydantic_request_response_models():
+    """request_model and response_model generate OpenAPI schemas."""
+    from pydantic import BaseModel
+
+    api = responder.API(
+        title="Test",
+        version="1.0",
+        openapi="3.0.2",
+        allowed_hosts=[";"],
+    )
+
+    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(req, resp):
+        data = await req.media()
+        resp.media = {"id": 1, **data}
+
+    # Check schema generation
+    r = api.requests.get("http://;/schema.yml")
+    assert "ItemIn" in r.text
+    assert "ItemOut" in r.text
+    assert "$ref" in r.text
+    assert "requestBody" in r.text
+
+    # Check the endpoint still works
+    r = api.requests.post("http://;/items", json={"name": "widget", "price": 9.99})
+    assert r.json() == {"id": 1, "name": "widget", "price": 9.99}
+
+
+def test_templates_context(tmp_path):
+    """Lines 23, 27: Templates.context getter and setter."""
+    template_dir = tmp_path / "templates"
+    template_dir.mkdir()
+    (template_dir / "test.html").write_text("{{ greeting }} {{ name }}")
+
+    templates = Templates(directory=str(template_dir), context={"greeting": "hello"})
+
+    # Getter
+    assert templates.context["greeting"] == "hello"
+
+    # Setter
+    templates.context = {"name": "world"}
+    assert templates.context["greeting"] == "hello"  # default preserved
+    assert templates.context["name"] == "world"
+
+    result = templates.render("test.html")
+    assert "hello" in result
+    assert "world" in result
+
+
+def test_static_file_serving(tmp_path):
+    """Verify static files are served correctly from the static directory."""
+    static_dir = tmp_path / "static"
+    static_dir.mkdir()
+    (static_dir / "style.css").write_text("body { color: red; }")
+    (static_dir / "app.js").write_text("console.log('hello');")
+
+    api = responder.API(
+        static_dir=str(static_dir),
+        static_route="/static",
+        allowed_hosts=[";"],
+    )
+
+    # CSS file served with correct content
+    r = api.requests.get("http://;/static/style.css")
+    assert r.status_code == 200
+    assert "body { color: red; }" in r.text
+    assert "text/css" in r.headers.get("content-type", "")
+
+    # JS file served with correct content
+    r = api.requests.get("http://;/static/app.js")
+    assert r.status_code == 200
+    assert "console.log" in r.text
+
+    # Missing file returns 404
+    r = api.requests.get("http://;/static/missing.txt")
+    assert r.status_code == 404
+
+
+def test_static_index_fallback(tmp_path):
+    """Verify static index.html is served as default route."""
+    static_dir = tmp_path / "static"
+    static_dir.mkdir()
+    (static_dir / "index.html").write_text("<h1>SPA</h1>")
+
+    api = responder.API(
+        static_dir=str(static_dir),
+        allowed_hosts=[";"],
+    )
+    api.add_route("/", static=True)
+
+    r = api.requests.get("http://;/")
+    assert r.status_code == 200
+    assert "<h1>SPA</h1>" in r.text

tests/test_encodings.py

@@ -0,0 +1,21 @@
+def test_custom_encoding(api, session):
+    data = "hi alex!"
+
+    @api.route("/")
+    async def route(req, resp):
+        req.encoding = "ascii"
+        resp.text = await req.text
+
+    r = session.post(api.url_for(route), content=data)
+    assert r.text == data
+
+
+def test_bytes_encoding(api, session):
+    data = b"hi lenny!"
+
+    @api.route("/")
+    async def route(req, resp):
+        resp.text = (await req.content).decode("utf-8")
+
+    r = session.post(api.url_for(route), content=data)
+    assert r.content == data

tests/test_graphql.py

@@ -0,0 +1,236 @@
+# ruff: noqa: E402
+import json
+
+import pytest
+
+graphene = pytest.importorskip("graphene")
+
+from responder.ext.graphql import GraphQLView
+
+
+@pytest.fixture
+def schema():
+    class Query(graphene.ObjectType):
+        hello = graphene.String(name=graphene.String(default_value="stranger"))
+
+        def resolve_hello(self, info, name):
+            return f"Hello {name}"
+
+    return graphene.Schema(query=Query)
+
+
+@pytest.fixture
+def mutation_schema():
+    class Query(graphene.ObjectType):
+        hello = graphene.String(name=graphene.String(default_value="stranger"))
+
+        def resolve_hello(self, info, name):
+            return f"Hello {name}"
+
+    class CreateUser(graphene.Mutation):
+        class Arguments:
+            name = graphene.String(required=True)
+
+        ok = graphene.Boolean()
+        name = graphene.String()
+
+        def mutate(self, info, name):
+            return CreateUser(ok=True, name=name)
+
+    class Mutation(graphene.ObjectType):
+        create_user = CreateUser.Field()
+
+    return graphene.Schema(query=Query, mutation=Mutation)
+
+
+@pytest.fixture
+def multi_op_schema():
+    class Query(graphene.ObjectType):
+        hello = graphene.String(name=graphene.String(default_value="stranger"))
+        goodbye = graphene.String(name=graphene.String(default_value="stranger"))
+
+        def resolve_hello(self, info, name):
+            return f"Hello {name}"
+
+        def resolve_goodbye(self, info, name):
+            return f"Goodbye {name}"
+
+    return graphene.Schema(query=Query)
+
+
+def test_graphql_schema_query_querying(api, schema):
+    api.add_route("/", GraphQLView(schema=schema, api=api))
+    r = api.requests.get("http://;/?q={ hello }", headers={"Accept": "json"})
+    assert r.status_code == 200
+    assert r.json() == {"data": {"hello": "Hello stranger"}}
+
+
+def test_graphql_schema_json_query(api, schema):
+    api.add_route("/", GraphQLView(schema=schema, api=api))
+    r = api.requests.post("http://;/", json={"query": "{ hello }"})
+    assert r.status_code < 300
+    assert r.json() == {"data": {"hello": "Hello stranger"}}
+
+
+def test_graphiql(api, schema):
+    api.add_route("/", GraphQLView(schema=schema, api=api))
+    r = api.requests.get("http://;/", headers={"Accept": "text/html"})
+    assert r.status_code < 300
+    assert "GraphiQL" in r.text
+
+
+def test_graphql_shorthand(api, schema):
+    """Test the api.graphql() shorthand method."""
+    api.graphql("/gql", schema=schema)
+    r = api.requests.post("http://;/gql", json={"query": "{ hello }"})
+    assert r.status_code < 300
+    assert r.json() == {"data": {"hello": "Hello stranger"}}
+
+
+def test_graphql_missing_query_key(api, schema):
+    api.add_route("/", GraphQLView(schema=schema, api=api))
+    r = api.requests.post("http://;/", json={"not_query": "foo"})
+    assert r.status_code == 400
+    assert "errors" in r.json()
+
+
+def test_graphql_query_param(api, schema):
+    api.add_route("/", GraphQLView(schema=schema, api=api))
+    r = api.requests.get("http://;/?query={ hello }", headers={"Accept": "json"})
+    assert r.json() == {"data": {"hello": "Hello stranger"}}
+
+
+def test_graphql_error_response(api, schema):
+    api.add_route("/", GraphQLView(schema=schema, api=api))
+    r = api.requests.post("http://;/", json={"query": "{ nonexistent }"})
+    assert "errors" in r.json()
+
+
+def test_graphql_variables_json(api, schema):
+    """Variables passed via JSON body."""
+    api.add_route("/", GraphQLView(schema=schema, api=api))
+    r = api.requests.post(
+        "http://;/",
+        json={
+            "query": "query Hello($name: String!) { hello(name: $name) }",
+            "variables": {"name": "Alice"},
+        },
+    )
+    assert r.json() == {"data": {"hello": "Hello Alice"}}
+
+
+def test_graphql_variables_query_param(api, schema):
+    """Variables passed as JSON string in query parameter."""
+    api.add_route("/", GraphQLView(schema=schema, api=api))
+    variables = json.dumps({"name": "Bob"})
+    r = api.requests.get(
+        f"http://;/?query=query Hello($name: String!) "
+        f"{{ hello(name: $name) }}&variables={variables}",
+        headers={"Accept": "json"},
+    )
+    assert r.json() == {"data": {"hello": "Hello Bob"}}
+
+
+def test_graphql_operation_name_json(api, multi_op_schema):
+    """operationName selects which operation to run."""
+    api.add_route("/", GraphQLView(schema=multi_op_schema, api=api))
+    query = """
+        query SayHello { hello }
+        query SayGoodbye { goodbye }
+    """
+    r = api.requests.post(
+        "http://;/",
+        json={
+            "query": query,
+            "operationName": "SayHello",
+        },
+    )
+    data = r.json()
+    assert data["data"]["hello"] == "Hello stranger"
+
+
+def test_graphql_operation_name_query_param(api, multi_op_schema):
+    """operationName via query parameter."""
+    api.add_route("/", GraphQLView(schema=multi_op_schema, api=api))
+    query = "query SayHello { hello } query SayGoodbye { goodbye }"
+    r = api.requests.get(
+        f"http://;/?query={query}&operationName=SayGoodbye",
+        headers={"Accept": "json"},
+    )
+    data = r.json()
+    assert data["data"]["goodbye"] == "Goodbye stranger"
+
+
+def test_graphql_mutation(api, mutation_schema):
+    """Mutations work via JSON body."""
+    api.add_route("/", GraphQLView(schema=mutation_schema, api=api))
+    r = api.requests.post(
+        "http://;/",
+        json={
+            "query": 'mutation { createUser(name: "Eve") { ok name } }',
+        },
+    )
+    data = r.json()
+    assert data["data"]["createUser"]["ok"] is True
+    assert data["data"]["createUser"]["name"] == "Eve"
+
+
+def test_graphql_mutation_with_variables(api, mutation_schema):
+    """Mutations with variables."""
+    api.add_route("/", GraphQLView(schema=mutation_schema, api=api))
+    r = api.requests.post(
+        "http://;/",
+        json={
+            "query": "mutation CreateUser($name: String!) "
+            "{ createUser(name: $name) { ok name } }",
+            "variables": {"name": "Frank"},
+        },
+    )
+    data = r.json()
+    assert data["data"]["createUser"]["ok"] is True
+    assert data["data"]["createUser"]["name"] == "Frank"
+
+
+def test_graphql_context_access(api):
+    """Resolvers can access request and response via info.context."""
+
+    class Query(graphene.ObjectType):
+        method = graphene.String()
+
+        def resolve_method(self, info):
+            return info.context["request"].method
+
+    schema = graphene.Schema(query=Query)
+    api.add_route("/", GraphQLView(schema=schema, api=api))
+    r = api.requests.post("http://;/", json={"query": "{ method }"})
+    assert r.json() == {"data": {"method": "post"}}
+
+
+def test_graphql_malformed_query(api, schema):
+    """Malformed GraphQL syntax returns errors."""
+    api.add_route("/", GraphQLView(schema=schema, api=api))
+    r = api.requests.post("http://;/", json={"query": "{ this is not valid"})
+    data = r.json()
+    assert "errors" in data
+    assert len(data["errors"]) > 0
+
+
+def test_graphql_raw_text_query(api, schema):
+    """Query sent as raw text body."""
+    api.add_route("/", GraphQLView(schema=schema, api=api))
+    r = api.requests.post(
+        "http://;/",
+        content=b"{ hello }",
+        headers={"Content-Type": "text/plain"},
+    )
+    assert r.json() == {"data": {"hello": "Hello stranger"}}
+
+
+def test_graphql_invalid_variables_query_param(api, schema):
+    """Invalid JSON in variables query param is treated as None."""
+    api.add_route("/", GraphQLView(schema=schema, api=api))
+    r = api.requests.get(
+        "http://;/?query={ hello }&variables=not-json",
+        headers={"Accept": "json"},
+    )
+    assert r.json() == {"data": {"hello": "Hello stranger"}}

tests/test_models.py

@@ -0,0 +1,94 @@
+import inspect
+
+import pytest
+
+from responder import models
+from responder.models import CaseInsensitiveDict
+
+_default_query = "q=%7b%20hello%20%7d&name=myname&user_name=test_user"
+
+
+@pytest.mark.parametrize(
+    "query, expected",
+    [
+        pytest.param(
+            _default_query,
+            {"q": ["{ hello }"], "name": ["myname"], "user_name": ["test_user"]},
+            id="parse query with unique keys",
+        ),
+        pytest.param(
+            "q=1&q=2&q=3", {"q": ["1", "2", "3"]}, id="parse query with the same key"
+        ),
+    ],
+)
+def test_query_dict(query, expected):
+    d = models.QueryDict(query)
+    assert d == expected
+
+
+def test_query_dict_get():
+    d = models.QueryDict(_default_query)
+
+    assert d["user_name"] == "test_user"
+    assert d.get("key_none_exist") is None
+
+
+def test_query_dict_get_list():
+    d = models.QueryDict(_default_query)
+
+    assert d.get_list("user_name") == ["test_user"]
+    assert d.get_list("key_none_exist") == []
+    assert d.get_list("key_none_exist", ["foo"]) == ["foo"]
+
+
+def test_query_dict_items_list():
+    d = models.QueryDict(_default_query)
+
+    items_list = d.items_list()
+    assert inspect.isgenerator(items_list)
+    assert dict(items_list) == {
+        "q": ["{ hello }"],
+        "name": ["myname"],
+        "user_name": ["test_user"],
+    }
+
+
+def test_query_dict_items():
+    d = models.QueryDict(_default_query)
+
+    items = d.items()
+    assert inspect.isgenerator(items)
+    assert dict(items) == {"q": "{ hello }", "name": "myname", "user_name": "test_user"}
+
+
+class TestCaseInsensitiveDict:
+    def test_set_and_get(self):
+        d = CaseInsensitiveDict()
+        d["Content-Type"] = "text/html"
+        assert d["content-type"] == "text/html"
+        assert d["CONTENT-TYPE"] == "text/html"
+
+    def test_contains(self):
+        d = CaseInsensitiveDict()
+        d["X-Custom"] = "value"
+        assert "x-custom" in d
+        assert "X-CUSTOM" in d
+        assert "missing" not in d
+
+    def test_get_default(self):
+        d = CaseInsensitiveDict()
+        assert d.get("missing") is None
+        assert d.get("missing", "default") == "default"
+        d["Key"] = "val"
+        assert d.get("KEY") == "val"
+
+    def test_update(self):
+        d = CaseInsensitiveDict()
+        d.update({"Content-Type": "text/html", "Accept": "json"})
+        assert d["content-type"] == "text/html"
+        assert d["accept"] == "json"
+
+    def test_update_kwargs(self):
+        d = CaseInsensitiveDict()
+        d.update(key1="val1", key2="val2")
+        assert d["key1"] == "val1"

tests/test_new_features.py

@@ -0,0 +1,287 @@
+"""Tests for new features: validation, SSE, after_request, route groups, etc."""
+
+from pydantic import BaseModel
+
+import responder
+from responder.ext.ratelimit import RateLimiter
+
+# --- Pydantic auto-validation ---
+
+
+class ItemIn(BaseModel):
+    name: str
+    price: float
+
+
+class ItemOut(BaseModel):
+    id: int
+    name: str
+    price: float
+
+
+def test_pydantic_request_validation():
+    """Auto-validate request body against request_model."""
+    api = responder.API(allowed_hosts=[";"])
+
+    @api.route("/items", methods=["POST"], request_model=ItemIn)
+    async def create(req, resp):
+        data = await req.media()
+        resp.media = {"id": 1, **data}
+
+    # Valid request
+    r = api.requests.post("http://;/items", json={"name": "widget", "price": 9.99})
+    assert r.status_code == 200
+    assert r.json()["name"] == "widget"
+
+    # Invalid request — missing required field
+    r = api.requests.post("http://;/items", json={"name": "widget"})
+    assert r.status_code == 422
+    assert "errors" in r.json()
+
+    # Invalid request — wrong type
+    r = api.requests.post(
+        "http://;/items", json={"name": "widget", "price": "not_a_number"}
+    )
+    assert r.status_code == 422
+
+
+def test_pydantic_response_serialization():
+    """Auto-serialize response through response_model."""
+    api = responder.API(allowed_hosts=[";"])
+
+    @api.route("/items", methods=["POST"], request_model=ItemIn, response_model=ItemOut)
+    async def create(req, resp):
+        data = await req.media()
+        # Include an extra field that should be stripped by the model
+        resp.media = {"id": 1, "secret": "hidden", **data}
+
+    r = api.requests.post("http://;/items", json={"name": "widget", "price": 9.99})
+    assert r.status_code == 200
+    data = r.json()
+    assert data == {"id": 1, "name": "widget", "price": 9.99}
+    assert "secret" not in data
+
+
+def test_pydantic_validation_skipped_for_get():
+    """GET requests don't trigger request body validation."""
+    api = responder.API(allowed_hosts=[";"])
+
+    @api.route("/items", methods=["GET"], request_model=ItemIn)
+    def list_items(req, resp):
+        resp.media = []
+
+    r = api.requests.get("http://;/items")
+    assert r.status_code == 200
+
+
+# --- SSE streaming ---
+
+
+def test_sse_streaming(api):
+    """Server-Sent Events with resp.sse."""
+
+    @api.route("/events")
+    async def events(req, resp):
+        @resp.sse
+        async def stream():
+            yield {"data": "hello"}
+            yield {"event": "update", "data": "world"}
+            yield "simple"
+
+    r = api.requests.get(api.url_for(events))
+    assert r.status_code == 200
+    assert "text/event-stream" in r.headers.get("content-type", "")
+    assert "data: hello" in r.text
+    assert "event: update" in r.text
+    assert "data: world" in r.text
+    assert "data: simple" in r.text
+
+
+def test_sse_with_id_and_retry(api):
+    """SSE events with id and retry fields."""
+
+    @api.route("/events")
+    async def events(req, resp):
+        @resp.sse
+        async def stream():
+            yield {"data": "msg", "id": "1", "retry": "5000"}
+
+    r = api.requests.get(api.url_for(events))
+    assert "id: 1" in r.text
+    assert "retry: 5000" in r.text
+
+
+# --- stream_file ---
+
+
+def test_stream_file(api, tmp_path):
+    """Stream a file without loading into memory."""
+    big_file = tmp_path / "data.bin"
+    big_file.write_bytes(b"x" * 10000)
+
+    @api.route("/download")
+    def download(req, resp):
+        resp.stream_file(big_file)
+
+    r = api.requests.get(api.url_for(download))
+    assert len(r.content) == 10000
+    assert r.content == b"x" * 10000
+
+
+def test_stream_file_content_type(api, tmp_path):
+    """stream_file detects content type."""
+    css = tmp_path / "style.css"
+    css.write_text("body { color: red; }")
+
+    @api.route("/css")
+    def serve_css(req, resp):
+        resp.stream_file(css)
+
+    r = api.requests.get(api.url_for(serve_css))
+    assert "text/css" in r.headers.get("content-type", "")
+
+
+# --- after_request hooks ---
+
+
+def test_after_request(api):
+    """after_request hook runs after route handler."""
+
+    @api.after_request()
+    def add_header(req, resp):
+        resp.headers["X-After"] = "yes"
+
+    @api.route("/")
+    def view(req, resp):
+        resp.text = "hello"
+
+    r = api.requests.get(api.url_for(view))
+    assert r.text == "hello"
+    assert r.headers["X-After"] == "yes"
+
+
+def test_after_request_async(api):
+    """Async after_request hook."""
+
+    @api.after_request()
+    async def add_header(req, resp):
+        resp.headers["X-Async-After"] = "yes"
+
+    @api.route("/")
+    def view(req, resp):
+        resp.text = "hello"
+
+    r = api.requests.get(api.url_for(view))
+    assert r.headers["X-Async-After"] == "yes"
+
+
+# --- Route groups ---
+
+
+def test_route_group(api):
+    """Route group with shared prefix."""
+    v1 = api.group("/v1")
+
+    @v1.route("/users")
+    def list_users(req, resp):
+        resp.media = [{"name": "alice"}]
+
+    @v1.route("/users/{user_id:int}")
+    def get_user(req, resp, *, user_id):
+        resp.media = {"id": user_id}
+
+    r = api.requests.get("http://;/v1/users")
+    assert r.json() == [{"name": "alice"}]
+
+    r = api.requests.get("http://;/v1/users/42")
+    assert r.json() == {"id": 42}
+
+
+def test_multiple_route_groups(api):
+    """Multiple route groups coexist."""
+    v1 = api.group("/v1")
+    v2 = api.group("/v2")
+
+    @v1.route("/status")
+    def v1_status(req, resp):
+        resp.media = {"version": 1}
+
+    @v2.route("/status")
+    def v2_status(req, resp):
+        resp.media = {"version": 2}
+
+    assert api.requests.get("http://;/v1/status").json() == {"version": 1}
+    assert api.requests.get("http://;/v2/status").json() == {"version": 2}
+
+
+# --- Request ID ---
+
+
+def test_request_id():
+    """Auto-generated request ID header."""
+    api = responder.API(request_id=True, allowed_hosts=[";"])
+
+    @api.route("/")
+    def view(req, resp):
+        resp.text = "ok"
+
+    r = api.requests.get("http://;/")
+    assert "X-Request-ID" in r.headers
+    assert len(r.headers["X-Request-ID"]) > 0
+
+
+def test_request_id_forwarded():
+    """Request ID is forwarded from client header."""
+    api = responder.API(request_id=True, allowed_hosts=[";"])
+
+    @api.route("/")
+    def view(req, resp):
+        resp.text = "ok"
+
+    r = api.requests.get("http://;/", headers={"X-Request-ID": "my-trace-123"})
+    assert r.headers["X-Request-ID"] == "my-trace-123"
+
+
+# --- Rate Limiting ---
+
+
+def test_rate_limiter():
+    """Rate limiter returns 429 when exceeded."""
+    api = responder.API(allowed_hosts=[";"])
+    limiter = RateLimiter(requests=3, period=60)
+    limiter.install(api)
+
+    @api.route("/")
+    def view(req, resp):
+        resp.text = "ok"
+
+    for _i in range(3):
+        r = api.requests.get("http://;/")
+        assert r.status_code == 200
+        assert "X-RateLimit-Remaining" in r.headers
+
+    # 4th request should be rate limited
+    r = api.requests.get("http://;/")
+    assert r.status_code == 429
+    assert "Retry-After" in r.headers
+
+
+# --- MessagePack ---
+
+
+def test_msgpack_format(api):
+    """MessagePack encoding and decoding."""
+    import msgpack
+
+    @api.route("/")
+    async def view(req, resp):
+        data = await req.media("msgpack")
+        resp.media = data
+
+    payload = {"hello": "world", "number": 42}
+    r = api.requests.post(
+        api.url_for(view),
+        content=msgpack.packb(payload),
+        headers={"Content-Type": "application/x-msgpack"},
+    )
+    assert r.json() == payload

tests/test_status_codes.py

@@ -0,0 +1,68 @@
+import pytest
+
+from responder import status_codes
+
+
+@pytest.mark.parametrize(
+    "status_code, expected",
+    [
+        pytest.param(101, True, id="Normal 101"),
+        pytest.param(199, True, id="Not actual status code but within 100"),
+        pytest.param(0, False, id="Zero case (below 100)"),
+        pytest.param(200, False, id="Above 100"),
+    ],
+)
+def test_is_100(status_code, expected):
+    assert status_codes.is_100(status_code) is expected
+
+
+@pytest.mark.parametrize(
+    "status_code, expected",
+    [
+        pytest.param(201, True, id="Normal 201"),
+        pytest.param(299, True, id="Not actual status code but within 200"),
+        pytest.param(0, False, id="Zero case (below 200)"),
+        pytest.param(300, False, id="Above 200"),
+    ],
+)
+def test_is_200(status_code, expected):
+    assert status_codes.is_200(status_code) is expected
+
+
+@pytest.mark.parametrize(
+    "status_code, expected",
+    [
+        pytest.param(301, True, id="Normal 301"),
+        pytest.param(399, True, id="Not actual status code but within 300"),
+        pytest.param(0, False, id="Zero case (below 300)"),
+        pytest.param(400, False, id="Above 300"),
+    ],
+)
+def test_is_300(status_code, expected):
+    assert status_codes.is_300(status_code) is expected
+
+
+@pytest.mark.parametrize(
+    "status_code, expected",
+    [
+        pytest.param(401, True, id="Normal 401"),
+        pytest.param(499, True, id="Not actual status code but within 400"),
+        pytest.param(0, False, id="Zero case (below 400)"),
+        pytest.param(500, False, id="Above 400"),
+    ],
+)
+def test_is_400(status_code, expected):
+    assert status_codes.is_400(status_code) is expected
+
+
+@pytest.mark.parametrize(
+    "status_code, expected",
+    [
+        pytest.param(501, True, id="Normal 501"),
+        pytest.param(599, True, id="Not actual status code but within 500"),
+        pytest.param(0, False, id="Zero case (below 500)"),
+        pytest.param(600, False, id="Above 500"),
+    ],
+)
+def test_is_500(status_code, expected):
+    assert status_codes.is_500(status_code) is expected

tests/util.py

@@ -0,0 +1,134 @@
+"""
+Utility functions for testing server components.
+
+This module provides functions for managing test server instances,
+including port allocation and server readiness checking.
+"""
+
+import errno
+import logging
+import socket
+import time
+import typing as t
+from copy import copy
+from functools import lru_cache
+from urllib.request import urlopen
+
+logger = logging.getLogger(__name__)
+
+
+def random_port() -> int:
+    """
+    Return a random available port by binding to port 0.
+
+    Returns:
+        int: An available port number that can be used for testing.
+    """
+    sock = socket.socket()
+    try:
+        sock.bind(("", 0))
+        return sock.getsockname()[1]
+    finally:
+        sock.close()
+
+
+@lru_cache(maxsize=None)
+def transient_socket_error_numbers() -> t.List[int]:
+    """
+    A list of TCP socket error numbers to ignore in `wait_server_tcp`.
+
+    On Windows, Winsock error codes are the Unix error code + 10000.
+
+    Returns:
+        List[int]: A list containing both Unix and Windows-specific error codes.
+        For each Unix error code 'x', includes both 'x' and 'x + 10000'.
+    """
+    error_numbers = [
+        errno.EAGAIN,
+        errno.ECONNABORTED,
+        errno.ECONNREFUSED,
+        errno.ETIMEDOUT,
+        errno.EWOULDBLOCK,
+    ]
+    error_numbers_effective = copy(error_numbers)
+    error_numbers_effective.extend(error_number + 10000 for error_number in error_numbers)
+    return error_numbers_effective
+
+
+def wait_server_tcp(
+    port: int,
+    host: str = "127.0.0.1",
+    timeout: int = 10,
+    delay: float = 0.1,
+) -> None:
+    """
+    Wait for server to be ready by attempting TCP connections.
+
+    Args:
+        port: The port number to connect to
+        host: The host to connect to (default: "127.0.0.1")
+        timeout: Maximum time to wait in seconds (default: 10)
+        delay: Delay between attempts in seconds (default: 0.1)
+
+    Raises:
+        RuntimeError: If server is not ready within timeout period
+    """
+    endpoint = f"tcp://{host}:{port}/"
+    logger.debug(f"Waiting for endpoint: {endpoint}")
+    start_time = time.time()
+    while time.time() - start_time < timeout:
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+            sock.settimeout(delay / 2)  # Set socket timeout
+            error_number = sock.connect_ex((host, port))
+            if error_number == 0:
+                break
+
+            # Expected errors when server is not ready.
+            if error_number in transient_socket_error_numbers():
+                pass
+
+            # Unexpected error.
+            else:
+                raise RuntimeError(
+                    f"Unexpected error while connecting to {endpoint}: {error_number}"
+                )
+        time.sleep(delay)
+    else:
+        raise RuntimeError(
+            f"Server at {endpoint} failed to start within {timeout} seconds"
+        )
+
+
+def wait_server_http(
+    port: int,
+    host: str = "127.0.0.1",
+    protocol: str = "http",
+    attempts: int = 20,
+    delay: float = 0.1,
+) -> None:
+    """
+    Wait for server to be ready by attempting to connect to it.
+
+    Args:
+        port: The port number to connect to
+        host: The host to connect to (default: "127.0.0.1")
+        protocol: The protocol to use (default: "http")
+        attempts: Number of connection attempts (default: 20)
+        delay: Delay per attempt in seconds (default: 0.1)
+
+    Raises:
+        RuntimeError: If server is not ready after all attempts
+    """
+    url = f"{protocol}://{host}:{port}/"
+    for attempt in range(1, attempts + 1):
+        try:
+            urlopen(url, timeout=delay / 2)  # noqa: S310
+            break
+        except OSError:
+            if attempt < attempts:  # Don't sleep on last attempt
+                time.sleep(delay)
+    else:
+        raise RuntimeError(
+            f"Server at {url} failed to respond after {attempts} attempts "
+            f"(total wait time: {attempts * delay:.1f}s)"
+        )