ClientIP middleware proposal, intended to replace RealIP

[VojtechVitek]

A proposed solution for the RealIP middleware issues outlined at:
#708
https://adam-p.ca/blog/2022/03/x-forwarded-for/
#711
#453
#908

Summary of differences:

• Unlike RealIP, ClientIP middleware doesn't change the value of req.RemoteAddr
• Instead, it parses and saves the client IP to a context and provides .GetClientIP() getter
• Makes users choose what to trust explicitly, e.g. a custom header / XFF header / req.RemoteAddr
• XFF algorithm now selects the rightmost trusted IP address from all X-Forwarded-For headers
• Additionally, XFF accepts a list of trusted IP prefixes, so users can opt-in to trust IP range
  belonging to their infrastructure, such as proxies or Load Balances, depending on their setup
• Should prevent client IP spoofing, which could affect rate-limiting in https://github.com/go-chi/httprate

Kudos to Adam Pritchard, Jonathan Yu, Yuya Okumura, Liam Stanley, and everyone else involved in the detailed reports and discussion.

I'm seeking early feedback and reviews on the proposed API.

CC @jawnsy @adam-p @convto @Dirbaio @pkieltyka @mfridman @lrstanley @n33pm

P.S.: This PR uses the "net/netip" package and assumes that we'll accept proposal to drop support for Go 1.17 and older. Please have a look!

---

Example usage:

// Trust Cloudflare header:
r.Use(middleware.ClientIPFromHeader("CF-Connecting-IP"))
r.Use(middleware.ClientIPFromHeader("True-Client-IP")) // alternative in Cloudflare Enterprise

// Trust Azure header:
r.Use(middleware.ClientIPFromHeader("X-Azure-ClientIP"))

// Trust header from Nginx with ngx_http_realip_module:
r.Use(middleware.ClientIPFromHeader("X-Real-IP"))

// Trust header from Apache with mod_remoteip:
r.Use(middleware.ClientIPFromHeader("X-Client-IP"))

// Trust X-Forwarded-For header set by reverse-proxy in a private network:
r.Use(middleware.ClientIPFromXFFHeader("203.0.113.0/24"))

// Trust X-Forwarded-For header set by AWS CloudFront:
r.Use(middleware.ClientIPFromXFFHeader(
    "13.32.0.0/15",   // CloudFront IPv4
    "52.46.0.0/18",   // CloudFront IPv4
    "2600:9000::/28", // CloudFront IPv6
))

// Go server serving the Internet traffic directly:
r.Use(middleware.ClientIPFromRemoteAddr)

Get the client IP address value in HTTP handler:

clientIP := middleware.GetClientIP(r.Context())
// log the clientIP .. or use it for rate-limiting

[convto]

I’ve checked the implementation, and I completely agree with the approach.
It addresses the concerns beautifully, and I’m very grateful for the effort put into this!

[VojtechVitek]

P.S.: This PR uses the "net/netip" package and assumes that we'll accept #963.

Rebased against master. The CI tests are now passing since we dropped support for Go 1.19 and older and thus can we use "net/netip" pkg.

@jawnsy @adam-p @convto @Dirbaio @pkieltyka @mfridman @lrstanley @n33pm @c2h5oh

I'd appreciate any more reviews 👀 🙏 .

[c2h5oh]

If trusted prefixes are set then we only care and/or can trust the first value past those trusted prefixes. No loopback, private or unspecified addresses should exist past/in between trusted prefixes unless headers have been tampered with.

1. Move trusted prefixes check block before this
2. Loopback/private/unspecified check should exit without setting client IP if any trusted prefixes are set

[c2h5oh]

Having numTrustedProxies as an alternative to trusted prefixes would be a useful option too. If you control exactly n proxies, but not necessarily all possible proxies on a network (e.g. corporate intranet situation).

When set we should look only at nth rightmost value and only check if it's unspecified or loopback to reject - private is fine.