Skip to content

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.

crates/features/src/users/http/controller.rs
use nest_rs::http::ClientIp;
#[get("/whoami")]
async fn whoami(&self, ip: ClientIp) -> String {
format!("you look like {} (forwarded={})", ip.ip, ip.forwarded)
}

ClientIp resolves against the transport peer, and only believes a forwarding header when that peer is a proxy you listed:

  1. No peer address at all (a unix socket, or a proxy that hides it) ⇒ 0.0.0.0, forwarded = false. The extractor never fails.
  2. The peer is not in <PREFIX>_HTTP__TRUSTED_PROXIES ⇒ that peer is the client, forwarded = false, and the headers are not read.
  3. The peer is a trusted proxy ⇒ the client is the rightmost hop that is not itself a trusted proxy, read from Forwarded (RFC 7239) and X-Forwarded-For, then X-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 with forwarded = false. Hops parse as a bare IP, IP:port, or a bracketed IPv6 ([ip], [ip]:port); unknown or an obfuscated _id names 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.

With no trusted proxy configured — the default — step 2 always wins, so forwarded stays false and a header a caller sets changes nothing.

Terminal window
# The deployment's ingress, named once. Read by ClientIp *and* the throttler.
NESTRS_HTTP__TRUSTED_PROXIES=10.0.0.1,10.42.0.0/16

An 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.

Each proxy writes its hop as its documentation says, and each shape below is pinned by the HTTP suite:

In front of the appWhat it writesWhat to list
nginx, proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_forthe caller’s X-Forwarded-For with its peer appended; X-Real-IP $remote_addr beside it agreesnginx’s address
Envoy, use_remote_address: trueits downstream appended to x-forwarded-forevery Envoy hop, the mesh’s range
HAProxy, option forwardfor or option forwardedan X-Forwarded-For line of its own after the caller’s, or forwarded: proto=http;for=…HAProxy’s address
AWS Application Load Balancer, append modethe client appended, ip:port ([ip]:port for IPv6) with client port preservationthe subnets its nodes take
Google Cloud external Application Load Balancerthe client appended, then the forwarding rule’s own addressits 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.

  • Extractors — the other values a handler takes from the request.
  • HTTP configuration — <PREFIX>_HTTP__TRUSTED_PROXIES beside the server’s other settings.
  • Rate limiting — the throttler keying on the same client.