clientip

Documentation

Overview

Package clientip provides(in a best effort manner) a client's IP address.

Index

• Constants
• func DirectAddress(remoteAddr string) string
• func Get(r *http.Request) string
• func Leftmost(headers http.Header) string
• func ProxyHeader(headers http.Header) string
• func Rightmost(headers http.Header) string
• func SingleIPHeader(headerName string, headers http.Header) string
• func With(r *http.Request, clientAddr string) *http.Request
• type ClientIPstrategy
  • func SingleIpStrategy(headerName string) ClientIPstrategy

Constants

const (
	// DirectIpStrategy derives the client IP from [http.Request.RemoteAddr].
	// It should be used if the server accepts direct connections, rather than through a proxy.
	DirectIpStrategy = ClientIPstrategy("DirectIpStrategy")

	// LeftIpStrategy derives the client IP from the leftmost valid & non-private IP address in the `X-Fowarded-For` or `Forwarded` header.
	LeftIpStrategy = ClientIPstrategy("LeftIpStrategy")

	// RightIpStrategy derives the client IP from the rightmost valid & non-private IP address in the `X-Fowarded-For` or `Forwarded` header.
	RightIpStrategy = ClientIPstrategy("RightIpStrategy")

	// ProxyStrategy derives the client IP from the [PROXY protocol v1].
	// This should be used when your application is behind a TCP proxy that uses the v1 PROXY protocol.
	//
	// [PROXY protocol v1]: https://www.haproxy.org/download/2.8/doc/proxy-protocol.txt
	ProxyStrategy = ClientIPstrategy("ProxyStrategy")
)

Functions

func DirectAddress

func DirectAddress(remoteAddr string) string

DirectAddress returns the client socket IP, stripped of port. This strategy should be used if the server accepts direct connections, rather than through a proxy.

func Get

func Get(r *http.Request) string

Get returns the "real" client IP address. See github.com/komuw/ong/middleware.ClientIP

func Leftmost

func Leftmost(headers http.Header) string

Leftmost derives the client IP from the leftmost valid and non-private IP address in the X-Fowarded-For or Forwarded header. This strategy should be used when a valid, non-private IP closest to the client is desired. Note: This MUST NOT be used for security purposes. This IP can be trivially SPOOFED.

The returned IP may contain a zone identifier. If no valid IP can be derived, empty string will be returned.

func ProxyHeader

func ProxyHeader(headers http.Header) string

ProxyHeader derives an IP address based off the PROXY protocol v1.

func Rightmost

func Rightmost(headers http.Header) string

Rightmost derives the client IP from the rightmost valid and non-private IP address in the X-Fowarded-For or Forwarded header. This strategy should be used when all reverse proxies between the internet and the server have private-space IP addresses.

The returned IP may contain a zone identifier. If no valid IP can be derived, empty string will be returned.

func SingleIPHeader

func SingleIPHeader(headerName string, headers http.Header) string

SingleIPHeader derives an IP address from a single-IP header. A non-exhaustive list of such single-IP headers is: X-Real-IP, CF-Connecting-IP, True-Client-IP, Fastly-Client-IP, X-Azure-ClientIP, X-Azure-SocketIP, Fly-Client-IP. This strategy should be used when the given header is added by a trusted reverse proxy. You MUST ensure that this header is not spoofable (as is possible with Akamai's use of True-Client-IP, Fastly's default use of Fastly-Client-IP, and Azure's X-Azure-ClientIP). See the single-IP wiki page for more info.

The returned IP may contain a zone identifier. If no valid IP can be derived, empty string will be returned.

func With

func With(r *http.Request, clientAddr string) *http.Request

With returns a *http.Request whose context contains a client IP address.

Types

type ClientIPstrategy

type ClientIPstrategy string

ClientIPstrategy is an option that describes the strategy to use when fetching the client's IP address.

Warning: This should be used with caution. Clients CAN easily spoof IP addresses. Fetching the "real" client is done in a best-effort basis and can be grossly inaccurate & precarious. You should especially heed this warning if you intend to use the IP addresses for security related activities. Proceed at your own risk.

func SingleIpStrategy

func SingleIpStrategy(headerName string) ClientIPstrategy

SingleIpStrategy derives the client IP from http header headerName.

headerName MUST NOT be either `X-Forwarded-For` or `Forwarded`. It can be something like `CF-Connecting-IP`, `Fastly-Client-IP`, `Fly-Client-IP`, etc; depending on your usecase.