74 lines
3.5 KiB
Markdown
74 lines
3.5 KiB
Markdown
# `axum-client-ip`
|
|
|
|
[](https://choosealicense.com/licenses/mit/)
|
|
[](https://crates.io/crates/axum-client-ip)
|
|
[](https://docs.rs/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` to `ClientIp`.
|
|
- Renamed `SecureClientIpSource` to `ClientIpSource`.
|
|
|
|
The changes are triggered by
|
|
["rightmost" IP extraction bug](https://github.com/imbolc/axum-client-ip/issues/32).
|
|
|
|
## 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 |
|
|
| [`XEnvoyExternalAddress`] | `X-Envoy-External-Address` | Envoy, Istio |
|
|
| [`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.
|
|
|
|
```rust,no_run
|
|
// 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][license].
|
|
|
|
[.pre-commit.sh]:
|
|
https://github.com/imbolc/axum-client-ip/blob/main/.pre-commit.sh
|
|
[Axum]: https://github.com/tokio-rs/axum
|
|
[client-ip]: https://github.com/imbolc/client-ip
|
|
[example]:
|
|
https://github.com/imbolc/axum-client-ip/blob/main/examples/configurable.rs
|
|
[license]: https://github.com/imbolc/axum-client-ip/blob/main/LICENSE
|