README
¶
realip
Validate proxy forwarding headers (X-Forwarded-For, X-Real-IP, True-Client-IP) to determine the client IP address or forward trusted header values.
How it works
Usage
By default, FromRequest() returns the remote address without checking headers.
var rip = realip.New()
func handler(w http.ResponseWriter, r *http.Request) {
clientIP := rip.FromRequest(r)
}
You can configure which headers to check and which peers to trust.
privateLAN, _ := netip.ParsePrefix("10.0.0.0/8")
var rip = realip.New(
realip.WithHeaders([]string{realip.XForwardedFor, realip.XRealIP}),
realip.WithTrustedPeers([]netip.Prefix{privateLAN}),
)
Getting header values
If you need to pass the validated header value downstream instead of extracting the IP, use HeaderFromRequest():
var rip = realip.New(
realip.WithHeaders([]string{realip.XForwardedFor, realip.XRealIP}),
realip.WithTrustedPeers([]netip.Prefix{privateLAN}),
)
func handler(w http.ResponseWriter, r *http.Request) {
// Returns the raw header value if all security checks pass
headerValue := rip.HeaderFromRequest(r)
if headerValue != "" {
clientReq.Header.Set("X-Forwarded-For", headerValue)
}
}
Options
WithHeaders
Specifies which HTTP headers to check for client IP addresses, in order of preference.
realip.WithHeaders([]string{realip.XForwardedFor, realip.XRealIP})
Common headers: X-Forwarded-For, X-Real-IP, True-Client-IP
WithTrustedPeers
Defines which IP ranges are allowed to set forwarding headers.
When TrustedPeers is set, headers are only checked if the request comes from a trusted peer. Otherwise, the remote address is returned.
realip.WithTrustedPeers([]netip.Prefix{proxyNetwork})
Required for security: Only requests from these IPs will have their headers trusted.
WithTrustedProxies
Specifies IP ranges of internal proxies that should be skipped when parsing the forwarding chain.
Used when you have multiple internal proxies and need to find the first external IP.
realip.WithTrustedProxies([]netip.Prefix{privateLAN})
For example, with X-Forwarded-For: 203.0.113.195, 10.0.0.3, 10.0.0.4, this skips 10.0.0.3 and 10.0.0.4 to return 203.0.113.195.
WithProxyCnt
Sets the exact number of proxy hops to skip from the end of the forwarding chain.
If you know there are exactly N proxies in your chain, use ProxyCnt to skip them.
var rip = realip.New(
realip.WithHeaders([]string{realip.XForwardedFor}),
realip.WithProxyCnt(1),
realip.WithTrustedPeers([]netip.Prefix{proxyNetwork}),
)
With X-Forwarded-For: 203.0.113.195, 70.41.3.18, 150.172.238.178, this skips the last IP and returns 70.41.3.18.
Documentation
¶
Overview ¶
Package realip provides functions to validate proxy forwarding headers to determine the client IP address or forward trusted header values.
Index ¶
- Constants
- type Option
- type RealIP
- func (r *RealIP) FromRequest(req *http.Request) string
- func (r *RealIP) HeaderFromRequest(req *http.Request) string
- func (r *RealIP) SetHeaders(headers []string)
- func (r *RealIP) SetProxyCnt(cnt int)
- func (r *RealIP) SetTrustedPeers(peers []netip.Prefix)
- func (r *RealIP) SetTrustedProxies(proxies []netip.Prefix)
Constants ¶
const ( XRealIP = "X-Real-IP" XForwardedFor = "X-Forwarded-For" TrueClientIP = "True-Client-IP" )
Common HTTP request headers.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Option ¶
type Option func(r *RealIP)
Option is a function that configures RealIP settings.
func WithHeaders ¶
WithHeaders sets which HTTP headers to check for the real client IP. Common headers include X-Forwarded-For, X-Real-IP, and True-Client-IP. The headers are checked in order; the first matching header is used.
func WithProxyCnt ¶
WithProxyCnt sets the exact number of proxies in the chain. If you know there are exactly N proxies between the client and your server, use this to skip those N IPs from the X-Forwarded-For header and get the real client IP.
func WithTrustedPeers ¶
WithTrustedPeers sets the IP ranges that are allowed to set client IP headers. This is a security-critical setting. Only requests from trusted peers (proxies) will have their headers checked. Other requests will use the remote address.
func WithTrustedProxies ¶
WithTrustedProxies sets the IP ranges of internal proxies in a chain. When you have multiple proxies, this helps identify which IPs in the X-Forwarded-For header are proxies so they can be skipped to find the real client IP.
type RealIP ¶
type RealIP struct {
// contains filtered or unexported fields
}
RealIP holds settings for extracting the client IP from an HTTP request.
func (*RealIP) FromRequest ¶
FromRequest gets the client IP from the request.
func (*RealIP) HeaderFromRequest ¶ added in v0.0.2
HeaderFromRequest validates the request's proxy chain and returns the header value if all security checks pass. Unlike FromRequest, this returns the raw header value rather than extracting an IP address, making it suitable for passing the header downstream to other services.
Returns an empty string if: - No trusted peers are configured (secure default) - The immediate peer is not trusted - The configured headers are not present in the request
func (*RealIP) SetHeaders ¶
SetHeaders updates the headers to check for the real client IP. This allows changing configuration after RealIP has been created.
func (*RealIP) SetProxyCnt ¶
SetProxyCnt updates the exact number of proxies in the chain. This allows changing configuration after RealIP has been created.
func (*RealIP) SetTrustedPeers ¶
SetTrustedPeers updates the IP ranges that are allowed to set client IP headers. This allows changing configuration after RealIP has been created.
func (*RealIP) SetTrustedProxies ¶
SetTrustedProxies updates the IP ranges of internal proxies. This allows changing configuration after RealIP has been created.
Source Files