Expand description
§axum-client-ip
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
toClientIp
. - Renamed
SecureClientIpSource
toClientIpSource
.
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§
- CfConnecting
Ip - Extracts an IP from
CF-Connecting-IP
(Cloudflare) header - Client
Ip - Client IP extractor with configurable source
- Cloud
Front Viewer Address - Extracts an IP from
CloudFront-Viewer-Address
(AWS CloudFront) header - FlyClient
Ip - Extracts an IP from
Fly-Client-IP
(Fly.io) header - Parse
Client IpSource Error - Invalid
ClientIpSource
- Rightmost
Forwarded - Extracts the rightmost IP from
Forwarded
header - RightmostX
Forwarded For - Extracts the rightmost IP from
X-Forwarded-For
header - True
Client Ip - Extracts an IP from
True-Client-IP
(Akamai, Cloudflare) header - XRealIp
- Extracts an IP from
X-Real-Ip
(Nginx) header
Enums§
- Client
IpSource ClientIp
source configuration- Rejection
- Rejection type for IP extractors