Module

_proxy

Proxy header validation — extract real client info from trusted reverse proxies.

Whentrusted_hostsis configured, X-Forwarded-For/Proto/Host headers are honoured only if the direct peer IP is in the trusted set. When no trusted hosts are configured, forwarded headers are stripped to prevent spoofing.

RFC 7239 defines a formalForwarded header, but the X-Forwarded-* family remains the de-facto standard used by nginx, Caddy, AWS ALB, Cloudflare, and virtually every reverse proxy in production.

4Functions

Functions

apply_proxy_headers 2 dict[str, Any] ▼
Rewrite ASGI scope fields using proxy headers from a trusted peer. **When the …
def apply_proxy_headers(scope: dict[str, Any], *, trusted_hosts: frozenset[str]) -> dict[str, Any]

Rewrite ASGI scope fields using proxy headers from a trusted peer.

When the direct peer is trusted:

  • client is overwritten with the leftmost IP from X-Forwarded-For
  • scheme is overwritten from X-Forwarded-Proto
  • server host is overwritten from X-Forwarded-Host
  • Host is rewritten from X-Forwarded-Hostfor downstream routing

When the direct peer is not trusted (ortrusted_hostsis empty), allX-Forwarded-*headers are stripped from the scope to prevent downstream apps from trusting spoofed values.

Parameters
Name Type Description
scope dict[str, Any]

Mutable ASGI scope dict (modified in place and returned).
trusted_hosts frozenset[str]

Tuple of trusted peer IPs/hostnames. The wildcard"*"trusts all peers (use only behind a known proxy layer).
Returns
dict[str, Any]
_split_host_port 2 tuple[str, int] ▼
Split a Host-style value into an ASGI server tuple.
def _split_host_port(host: str, default_port: int) -> tuple[str, int]
Parameters
Name Type Description
host str
default_port int
Returns
tuple[str, int]
_replace_header 3 list[tuple[bytes, bytes]… ▼
Replace the first header named *name*, or append it if missing.
def _replace_header(headers: list[list[bytes]], name: bytes, value: bytes) -> list[tuple[bytes, bytes] | list[bytes]]
Parameters
Name Type Description
headers list[list[bytes]]
name bytes
value bytes
Returns
list[tuple[bytes, bytes] | list[bytes]]
_strip_forwarded_headers 1 None ▼
Remove all X-Forwarded-* headers from an ASGI scope. Prevents untrusted client…
def _strip_forwarded_headers(scope: dict[str, Any]) -> None

Remove all X-Forwarded-* headers from an ASGI scope.

Prevents untrusted clients from injecting proxy headers that downstream ASGI apps might naively trust.

Parameters
Name Type Description
scope dict[str, Any]