fix(http): say when proxy headers go unread, and trust X-Real-IP only at one hop

With TRUST_PROXY_HOPS=0 behind a proxy that sends only X-Real-IP, every
client address resolves to nothing and all anonymous sign-ins share one
rate-limit bucket, with nothing in the log to say why. The first request
that carries a forwarding header the setting does not let HealthLog read
now logs one warning naming the header and the setting to change.

X-Real-IP stood in for a missing X-Forwarded-For at any hop count. It is a
single address, so it is now read only with TRUST_PROXY_HOPS=1; with two
or more hops the chain the count describes is X-Forwarded-For.

The upload, import and native batch routes that bypass the proxy now carry
Cross-Origin-Resource-Policy and Cross-Origin-Embedder-Policy like every
other response, and so do the proxy's early exits.

The env examples described an unset TRUST_PROXY_HOPS as right for a
directly exposed host; unset means one hop, and that host wants 0.
This commit is contained in:
Marc-André Bombeck committed 2026-09-26 22:45:51 +02:00
1 parent 995bd2385a
commit 7d05f68f23
7 files changed
+142 -17

No files matched your search

+11 -5
View File
@@ -52,11 +52,17 @@ every anonymous caller into one shared rate-limit bucket. Match the
value to the actual hop count.
`X-Real-IP` gets the same trust as `X-Forwarded-For`. It is read only
when `TRUST_PROXY_HOPS` is `1` or more and the request carries no
`X-Forwarded-For`, which covers a proxy that sets only `X-Real-IP`. With
`0` neither header is believed, because without a proxy in front both
come from the caller. If your proxy sets only `X-Real-IP` and you had
set `0` for it, set `1` instead.
when `TRUST_PROXY_HOPS` is exactly `1` and the request carries no
`X-Forwarded-For`, which covers a single proxy that sets only
`X-Real-IP`. With `0` neither header is believed, because without a proxy
in front both come from the caller. With `2` or more, the hop count
describes an `X-Forwarded-For` chain, so have your proxies send one.
If requests arrive with a forwarding header the setting does not let
HealthLog read, the log shows one warning naming the header and the
setting. Every anonymous caller then shares one rate-limit bucket, so one
person mistyping a password can hold sign-in back for everyone. The usual
cause is `0` behind a proxy that sends only `X-Real-IP`: set `1`.
## Caddy