clientip

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 2, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Overview

Package clientip resolves the real client address behind reverse proxies — the stdlib replacement for gin's ClientIP/SetTrustedProxies pair (security-sensitive: this value keys the identity login rate limiter).

Fail-closed by construction: with no trusted proxies configured the resolver always returns the direct socket peer, so a client cannot spoof X-Forwarded-For to escape IP-keyed rate limiting.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Resolver

type Resolver struct {
	// contains filtered or unexported fields
}

Resolver derives the client IP from RemoteAddr plus forwarding headers, honouring headers only when the direct peer is a trusted proxy. Immutable after construction; safe for concurrent use.

func NewResolver

func NewResolver(trustedProxies []string) (*Resolver, error)

NewResolver parses the trusted proxy list (single IPs or CIDR blocks). An empty list is valid and means "trust nobody" — the fail-closed default. Malformed entries error out so a typo can't silently widen or narrow the trust boundary.

func (*Resolver) ClientIP

func (r *Resolver) ClientIP(req *http.Request) string

ClientIP resolves the client address for req.

Algorithm (gin-compatible):

  1. The direct peer comes from RemoteAddr. When it is not a trusted proxy, forwarding headers are ignored entirely and the peer IP is returned — a client-sent X-Forwarded-For never wins.
  2. When the peer is trusted, X-Forwarded-For is walked right to left, skipping trusted proxies; the first untrusted hop is the client. An all-trusted chain yields the leftmost entry. A malformed entry invalidates the whole header (next header, then the peer, is used instead).
  3. X-Real-IP is consulted the same way when X-Forwarded-For yields nothing.

Returns "" only when RemoteAddr itself is unparseable and no header applies. Callers should skip IP-keyed decisions on "" rather than treating it as one shared bucket.

func (*Resolver) Ignored

func (r *Resolver) Ignored(req *http.Request) (header, peer string)

Ignored reports the forwarding header ClientIP disregards on req because the direct peer is not a trusted proxy: the first of the headers req carries, and the peer's address without its port. Both are empty when req carries none, when the peer is trusted, and when RemoteAddr holds no IP address, which no trusted_proxies entry could match.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL