async-proxy-headers

Small, dependency-free ASGI middleware for applying X-Forwarded-For and X-Forwarded-Proto only when the connecting proxy is trusted.

This package extracts Uvicorn's mature ProxyHeadersMiddleware so applications can use it without depending on an ASGI server implementation. The code and tests are derived from Uvicorn, maintained by Encode OSS Ltd and contributors. See UPSTREAM.md for exact provenance and changes.

Install

uv add async-proxy-headers

Use

from async_proxy_headers import ProxyHeadersMiddleware

app = ProxyHeadersMiddleware(app, trusted_hosts="127.0.0.1")

trusted_hosts accepts an IP address, IP network, literal host, comma-separated string, or list of those values. "*" trusts every connecting peer.

Development

The uvicorn/ Git submodule records the exact upstream checkout used for the extraction. It is not included in built distributions.

git submodule update --init
uv sync
uv run pytest
uv run pytest -m e2e
uv run ruff check src tests
uv run mypy
uv build
uv run twine check dist/*

The E2E suite launches Uvicorn, Gunicorn's native ASGI worker, and Granian, sends a real HTTP request through each, and verifies the middleware-adjusted client address and scheme returned by the application.

Releases publish through PyPI Trusted Publishing. Before the first release, create the async-proxy-headers PyPI project (or use PyPI's pending publisher) for GitHub owner kosovojs, repository async-proxy-headers, workflow publish.yml, environment pypi.

License and credit

BSD-3-Clause, matching Uvicorn. Uvicorn's copyright notice, license conditions, and disclaimer are retained in LICENSE.md. This project is not endorsed by or affiliated with Encode OSS Ltd or the Uvicorn maintainers.