Crate axum_client_ip

axum-client-ip

Client IP address extractors for Axum

V1 breaking changes

• Removed InsecureClientIp and related “leftmost” IP logic. The library now focuses solely on secure extraction based on trusted headers.
• Renamed SecureClientIp to ClientIp.
• Renamed SecureClientIpSource to ClientIpSource.

The changes are triggered by “rightmost” IP extraction bug.

Configurable vs specific extractors

There’s a configurable ClientIp extractor you can use to make your application independent from a proxy it can run behind (if any) and also separate extractors for each proxy / source header.

Extractor / ClientIpSource Variant	Header Used	Typical Proxy / Service
CfConnectingIp	CF-Connecting-IP	Cloudflare
CloudFrontViewerAddress	CloudFront-Viewer-Address	AWS CloudFront
FlyClientIp	Fly-Client-IP	Fly.io
RightmostForwarded	Forwarded	Proxies supporting RFC 7239 (extracts rightmost for=)
RightmostXForwardedFor	X-Forwarded-For	Nginx, Apache, HAProxy, CDNs, LBs
TrueClientIp	True-Client-IP	Cloudflare, Akamai
XRealIp	X-Real-Ip	Nginx
ConnectInfo	N/A (uses socket address)	No proxy, e.g. listening directly to 80 port

Configurable extractor

The configurable extractor assumes initializing ClientIpSource at runtime (e.g. with an environment variable). This makes sense when you ship a pre-compiled binary, people meant to use in different environments. Here’s an initialization example.

Specific extractors

Specific extractors don’t require runtime initialization, but you’d have to recompile your binary when you change proxy server.

// With the renaming, you have to change only one line when you change proxy
use axum_client_ip::XRealIp as ClientIp;

async fn handler(ClientIp(ip): ClientIp) {
    todo!()
}

Contributing

• please run .pre-commit.sh before sending a PR, it will check everything

License

This project is licensed under the MIT license.

Structs

CfConnectingIp

Extracts an IP from CF-Connecting-IP (Cloudflare) header

ClientIp

Client IP extractor with configurable source

CloudFrontViewerAddress

Extracts an IP from CloudFront-Viewer-Address (AWS CloudFront) header

FlyClientIp

Extracts an IP from Fly-Client-IP (Fly.io) header

ParseClientIpSourceError

Invalid ClientIpSource

RightmostForwarded

Extracts the rightmost IP from Forwarded header

RightmostXForwardedFor

Extracts the rightmost IP from X-Forwarded-For header

TrueClientIp

Extracts an IP from True-Client-IP (Akamai, Cloudflare) header

XRealIp

Extracts an IP from X-Real-Ip (Nginx) header

Enums

ClientIpSource

ClientIp source configuration

Rejection

Rejection type for IP extractors