Crate axum_client_ip

Crate axum_client_ip 

Source
Expand description

§axum-client-ip

License Crates.io Docs.rs

Client IP address extractors for the Axum web framework. The crate is just a thin wrapper around a framework-independent client-ip crate.

§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 VariantHeader UsedTypical Proxy / Service
CfConnectingIpCF-Connecting-IPCloudflare
CloudFrontViewerAddressCloudFront-Viewer-AddressAWS CloudFront
FlyClientIpFly-Client-IPFly.io
RightmostForwardedForwardedProxies supporting RFC 7239 (extracts rightmost for=)
RightmostXForwardedForX-Forwarded-ForNginx, Apache, HAProxy, CDNs, LBs
TrueClientIpTrue-Client-IPCloudflare, Akamai
XRealIpX-Real-IpNginx
ConnectInfoN/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