Struct IpExtractor 

pub struct IpExtractor { /* private fields */ }

Extracts the real client IP from proxy headers.

When deployed behind a reverse proxy (Cloudflare, nginx, Caddy), the direct peer IP is the proxy, not the actual client. This extractor checks proxy headers in priority order (CF-Connecting-IP, X-Real-IP, X-Forwarded-For) but only when the peer IP is in the configured trusted proxy list.

Trusted proxies can be specified as individual IPs (auto-promoted to /32 or /128) or CIDR ranges (e.g. 10.0.0.0/8, fd00::/8).

Safe default: When trusted_proxies is empty, all proxy headers are ignored and the peer address is returned directly. This prevents IP spoofing when no proxy is configured.

Implementations

impl IpExtractor

pub fn new(trusted_proxy_strs: &[String]) -> Result<Self, String>

Create a new extractor from a list of trusted proxy strings.

Accepts individual IPs (10.0.0.1) and CIDR ranges (10.0.0.0/8). Bare IPs are auto-promoted to /32 (IPv4) or /128 (IPv6). Invalid entries are skipped with a warning.

pub fn is_empty(&self) -> bool

Returns true if no trusted proxies are configured.

pub fn extract(&self, headers: &HeaderMap, peer_addr: SocketAddr) -> IpAddr

Extract the real client IP from headers and peer address.

Priority:

1. If no trusted proxies configured, return peer IP (safe default).
2. If peer IP is not trusted, return peer IP (untrusted source).
3. Try CF-Connecting-IP header (Cloudflare).
4. Try X-Real-IP header (nginx).
5. Try rightmost non-trusted IP in X-Forwarded-For.
6. Fall back to peer IP.

Trait Implementations

impl Debug for IpExtractor

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.