Metadata-Version: 2.5
Name: async-proxy-headers
Version: 0.1.0
Summary: Standalone ASGI middleware for trusted proxy headers, extracted from Uvicorn
Project-URL: Homepage, https://github.com/kosovojs/async-proxy-headers
Project-URL: Repository, https://github.com/kosovojs/async-proxy-headers
Project-URL: Issues, https://github.com/kosovojs/async-proxy-headers/issues
Project-URL: Changelog, https://github.com/kosovojs/async-proxy-headers/releases
Project-URL: Upstream project, https://github.com/encode/uvicorn
License-Expression: BSD-3-Clause
License-File: LICENSE.md
Keywords: asgi,forwarded,middleware,proxy,uvicorn
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# 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](https://github.com/encode/uvicorn), maintained
by Encode OSS Ltd and contributors. See
[UPSTREAM.md](https://github.com/kosovojs/async-proxy-headers/blob/main/UPSTREAM.md)
for exact provenance and changes.

## Install

```console
uv add async-proxy-headers
```

## Use

```python
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.

> [!WARNING]
> Only trust proxies you control. Never use `trusted_hosts="*"` when clients can
> reach the ASGI application directly: they could spoof their address or scheme.

## Development

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

```console
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](LICENSE.md). This project is not
endorsed by or affiliated with Encode OSS Ltd or the Uvicorn maintainers.
