Struct under::RemoteAddress

pub struct RemoteAddress<'r> { /* private fields */ }

A type that helps retrieve the remote address of a request.

Because the process is incredibly complex, we can’t just have a single function that returns a single IP address - the source of that IP address is incredibly important, and we need to know what sources the application in question trusts.

The basic idea is this: there are multiple potential sources to load an IP address from. All of these potential sources must be derivable from the request itself. The application must then specify which sources it trusts to be able to load an IP address from. Those sources themselves can have their own configurations that allow them to be more fine-grained. We do not suggest a default - or, rather, disencourage it. Instead, we make it easier to specify.

For more information, see https://adam-p.ca/blog/2022/03/x-forwarded-for/.

Examples

request.set_header("X-Forwarded-For", "1.1.1.1, 2.2.2.2, 3.3.3.3");
let ip = request.remote_address()
    .trust_cloudflare_header()
    .trust_forwarded_for(-1)
    .trust_peer_address()
    .apply();
assert_eq!(ip, Some(IpAddr::from([3, 3, 3, 3])));

Implementations

impl RemoteAddress<'_>

pub fn trust_forwarded_for(&mut self, index: isize) -> &mut Self

Adds a source that loads from the X-Forwarded-For header. The index here specifies which entry in the X-Forwarded-For header to use. This is useful for load balancing applications that use multiple load balancers, or have multiple proxies between the application or the user. Ideally, the application would specify the right-most specific source, not including the load balancers.

This source correctly parses multiple X-Forwarded-For headers, implicitly concatenating them.

Examples

request.set_header("X-Forwarded-For", "1.1.1.1, 2.2.2.2, 3.3.3.3");
let ip = request.remote_address()
    .trust_forwarded_for(0)
    .apply();
assert_eq!(ip, Some(IpAddr::from([1, 1, 1, 1])));
let ip = request.remote_address()
    .trust_forwarded_for(-1)
    .apply();
assert_eq!(ip, Some(IpAddr::from([3, 3, 3, 3])));

pub fn trust_forwarded(&mut self, index: isize) -> &mut Self

Adds a source that loads from the Forwarded header. The index here specifies which entry in the Forwarded header to use. This is useful for load balancing applications that use multiple load balancers, or have multiple proxies between the application or the user. Ideally, the application would specify the right-most specific source, not including the load balancers.

This source correctly parses multiple Forwarded headers, implicitly concatenating them.

Examples

request.set_header("Forwarded", "for=1.1.1.1, for=2.2.2.2, for=3.3.3.3");
let ip = request.remote_address()
   .trust_forwarded(0)
   .apply();
assert_eq!(ip, Some(IpAddr::from([1, 1, 1, 1])));
let ip = request.remote_address()
  .trust_forwarded(-1)
  .apply();
assert_eq!(ip, Some(IpAddr::from([3, 3, 3, 3])));

pub fn trust_header(&mut self, header: impl Into<Cow<'static, str>>) -> &mut Self

Adds a source that loads from a specific header. This is useful for load balancing applications where the load balancer adds a header to the request that contains the IP address of the client. Note that, however, if the load balancer is not trusted, or that the application can ever be accessed without the load balancer, this will not work. This source iterates over all possible header values, from top to bottom, and returns the first one that parses as an IP address.

Examples

request.set_header("X-Real-IP", "1.1.1.1");
request.add_header("X-Real-IP", "2.2.2.2");
let ip = request.remote_address().trust_header("X-Real-IP").apply();
assert_eq!(ip, Some(IpAddr::from([1, 1, 1, 1])));

pub fn trust_cloudflare_header(&mut self) -> &mut Self

Adds a source that loads from the header "CF-Connecting-IP". This uses the same logic as Self::trust_header to parse the header.

pub fn trust_real_ip_header(&mut self) -> &mut Self

Adds a source that loads from the header "X-Real-IP". This uses the same logic as Self::trust_header to parse the header.

pub fn trust_client_ip_header(&mut self) -> &mut Self

Adds a source that loads from the header "True-Client-IP". This uses the same logic as Self::trust_header to parse the header.

pub fn trust_peer_address(&mut self) -> &mut Self

Adds a source that loads from the peer address of the TCP connection. There generally will always be a peer address, but if the application is behind a reverse proxy, this peer address will be the address of the reverse proxy, instead of the user’s machine. As such, this is most likely not what you want.

Examples

let ip = request.remote_address()
    .trust_peer_address()
    .apply();
assert_eq!(ip, Some(IpAddr::from([127, 0, 0, 1])));

pub fn apply(&self) -> Option<IpAddr>

Applies the sources to the request, extracting the IP address. Since all sources are fallible, this will return None if all of the sources fail. All sources are evaluated from the first source added to the last.

Examples

request.set_header("X-Forwarded-For", "1.1.1.1, 2.2.2.2, 3.3.3.3");
let ip = request.remote_address()
    .trust_cloudflare_header()
    .trust_forwarded_for(-1)
    .trust_peer_address()
    .apply();
assert_eq!(ip, Some(IpAddr::from([3, 3, 3, 3])));

Trait Implementations

impl<'r> Clone for RemoteAddress<'r>

fn clone(&self) -> RemoteAddress<'r>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'r> Debug for RemoteAddress<'r>

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

Formats the value using the given formatter.