Client IP
ClientIp: the transport peer, or the client a trusted proxy names — rightmost hop, read whole or not at all, observation-grade.
ClientIp answers which address a request came from: the transport peer, or,
behind a proxy you listed, the client that proxy names. It is a best guess for
geolocation hints and sampling keys, never an authentication input.
use nest_rs::http::ClientIp;
#[get("/whoami")]async fn whoami(&self, ip: ClientIp) -> String { format!("you look like {} (forwarded={})", ip.ip, ip.forwarded)}Which address answers
Section titled “Which address answers”ClientIp resolves against the transport peer, and only believes a
forwarding header when that peer is a proxy you listed:
- No peer address at all (a unix socket, or a proxy that hides it) ⇒
0.0.0.0,forwarded = false. The extractor never fails. - The peer is not in
<PREFIX>_HTTP__TRUSTED_PROXIES⇒ that peer is the client,forwarded = false, and the headers are not read. - The peer is a trusted proxy ⇒ the client is the rightmost hop that
is not itself a trusted proxy, read from
Forwarded(RFC 7239) andX-Forwarded-For, thenX-Real-IP;forwarded = true. If every hop is a trusted proxy, the outermost answers. If two headers name different clients none is believed, and if no header names a usable hop the proxy’s own address answers, both withforwarded = false. Hops parse as a bare IP,IP:port, or a bracketed IPv6 ([ip],[ip]:port);unknownor an obfuscated_idnames no address, so where it stands for the client, the proxy withheld it and no client is named.
A header is read whole or not at all. One the parser cannot read — a quote no
quote closes, a pair with no =, a hop that is no address — names no client,
whatever the other headers say: the proxy’s own address answers, and one warn
on nest_rs::http, filed inside the request, names the header, never what it
held. A quote left open is the reason: a proxy appending a quoted value to a
caller’s line would close the caller’s quote, and the caller’s own hop would
read as the rightmost. X-Real-IP, one hop in no order, answers alone only
where neither chain names a client; beside a chain, it names that chain’s client
or neither is believed. A proxy writing X-Real-IP and passing the caller’s own
X-Forwarded-For through would otherwise let the caller choose.
Trusted proxies
Section titled “Trusted proxies”With no trusted proxy configured — the default — step 2 always wins, so
forwarded stays false and a header a caller sets changes nothing.
# The deployment's ingress, named once. Read by ClientIp *and* the throttler.NESTRS_HTTP__TRUSTED_PROXIES=10.0.0.1,10.42.0.0/16An entry is an address or a CIDR range, and in code a TrustedProxy:
trusted_proxy!("10.42.0.0/16") for a literal, checked as the program compiles,
so a typo in a #[module]’s imports fails the build rather than the boot;
ip.into() for an address a value holds, and "10.42.0.0/16".parse()? for text
read at run time. An ingress whose pods move is named by their range. Everything
inside one is believed, so it names your proxies and nothing a caller connects
from. A /0 fails the boot, since it would believe every caller, and so do ranges
holding between them every address of a family a caller connects from
(0.0.0.0/1,128.0.0.0/1, or 0.0.0.0/1,128.0.0.0/2,192.0.0.0/3, short only of
multicast and reserved space), from the environment and from code alike; so does a range with address bits set past
its prefix (10.0.0.1/8), which could mean the one proxy or the whole range. A listener on [::] reports an IPv4 peer as ::ffff:10.0.0.1: that is
10.0.0.1, to this list and in the address ClientIp answers.
What to list behind each proxy
Section titled “What to list behind each proxy”Each proxy writes its hop as its documentation says, and each shape below is pinned by the HTTP suite:
| In front of the app | What it writes | What to list |
|---|---|---|
nginx, proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for | the caller’s X-Forwarded-For with its peer appended; X-Real-IP $remote_addr beside it agrees | nginx’s address |
Envoy, use_remote_address: true | its downstream appended to x-forwarded-for | every Envoy hop, the mesh’s range |
HAProxy, option forwardfor or option forwarded | an X-Forwarded-For line of its own after the caller’s, or forwarded: proto=http;for=… | HAProxy’s address |
AWS Application Load Balancer, append mode | the client appended, ip:port ([ip]:port for IPv6) with client port preservation | the subnets its nodes take |
| Google Cloud external Application Load Balancer | the client appended, then the forwarding rule’s own address | its front ends (35.191.0.0/16, 130.211.0.0/22) and the forwarding rule’s address |
Behind Google Cloud’s balancer, leaving the forwarding rule’s address off the
list answers that address for every caller: it stands right of the client, and
anything not listed is the client. A proxy writing one header passes the others
through as the caller sent them, and two headers naming different clients are
both refused; behind HAProxy’s option forwarded alone, a caller’s own
X-Forwarded-For leaves its request with the proxy’s address, so have the proxy
delete what it does not write (http-request del-header X-Forwarded-For).
Rightmost, not leftmost. A proxy appends the address it received the request
from to the right of the chain, so the genuine client is the last hop your
infrastructure wrote; a caller can only prepend, and a prepended entry lands to
the left of it. Keying on the leftmost hop is the spoofable rule. A chain over
several field lines is one list, in order, since a proxy may add its own line
after the caller’s; X-Real-IP, one hop, is read from its last line.
Going further
Section titled “Going further”- Extractors — the other values a handler takes from the request.
- HTTP configuration —
<PREFIX>_HTTP__TRUSTED_PROXIESbeside the server’s other settings. - Rate limiting — the throttler keying on the same client.