Support X-Forwarded-Host in ProxyHeadersMiddleware

[Kludex]

Closes #965

Summary

Adds X-Forwarded-Host support to ProxyHeadersMiddleware. When the connecting peer is in forwarded_allow_ips and the header is present, the middleware:

• Replaces the host request header in scope["headers"] with the forwarded value
• Sets scope["server"] to (host, port), parsing IPv4/IPv6/host:port via the existing _parse_host_port helper used for X-Forwarded-For
• Defaults the port to 443 when the (possibly already-rewritten) scope["scheme"] is https or wss, and 80 otherwise

This matches the behavior of Werkzeug's ProxyFix (linked by @Kludex in the issue as the reference) and addresses the redirect_slashes and StaticFiles redirect breakage that surfaces when a reverse proxy rewrites Host to its internal hostname (e.g., Caddy 2.11+, Heroku, many CDNs).

Behaviour

• Trust gating reuses the existing forwarded_allow_ips check; no new CLI flag.
• Empty / whitespace-only X-Forwarded-Host is a no-op.
• The order in the middleware is proto -> for -> host, so the host block can use the forwarded scheme to pick the default port.
• The original Host header is replaced (not appended) - matches Werkzeug and Hypercorn.

Tests

New cases cover untrusted-peer ignore, hostname / host:port / IPv4 / IPv4+port / bracketed IPv6 / IPv6+port shapes, scheme-driven default ports for http/https/ws/wss, host-header replacement (no duplicates), and the combined for+proto+host case.

Checklist

• I understand that this PR may be closed in case there was no previous discussion. (This doesn't apply to typos!)
• I've added a test for each change that was introduced, and I tried as much as possible to make a single atomic change.
• I've updated the documentation accordingly.

AI Disclaimer

This PR was developed with the assistance of either Claude or Codex. I've reviewed and verified the changes.

[github-actions]

📖 Docs preview: https://1adee858.uvicorn.pages.dev

[codspeed-hq]

Merging this PR will not alter performance

✅ 24 untouched benchmarks

---

_{Comparing x-forwarded-host (a162bc9) with main (10ddc6d)}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f68cc4f524

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Parse only one X-Forwarded-Host hop before rewriting host

When a trusted proxy sends a multi-hop X-Forwarded-Host value (comma-separated, which is common with chained proxies), this code parses the entire header as one host instead of selecting a single hop first. That means scope["server"] can be set to an invalid hostname like "example.com,proxy.local" (or lose a valid port in IPv6+port chains), and the rewritten Host header will also contain the full list, which can break URL generation/redirect behavior in proxied production setups. Split the header into hops (and choose the intended trusted hop) before calling _parse_host_port.

Useful? React with 👍 / 👎.