Skip to content

README.md

Latest commit

 

History

History
61 lines (44 loc) · 2.73 KB

README.md

File metadata and controls

61 lines (44 loc) · 2.73 KB

IP Extractor Library

Go package for extracting a client IP address from net/http requests with an explicit trust model for reverse proxies.

The exported header constants in this package use lower-case values so they can be used directly with ExtractFrom and gRPC metadata. Header matching remains case-insensitive.

Defaults

  • Proxy headers are disabled by default.
  • Only Request.RemoteAddr is used unless proxy support is explicitly enabled.
  • The default extractor is permissive: malformed proxy headers are ignored rather than turning the whole request into an error.

Proxy Modes

  • ProxiesDenied

    • Default mode.
    • Ignores forwarded, x-forwarded-for, and other proxy headers.
    • Safest choice unless the service is known to sit behind trusted reverse proxies.

  • ProxiesAllowedList

    • Trusts proxy headers only when Request.RemoteAddr belongs to a configured allow-list.
    • Supports both individual IP addresses and CIDR ranges.
    • Recommended for production behind load balancers or reverse proxies.

  • ProxiesAllowedAll

    • Trusts proxy headers from any source.
    • Unsafe unless an upstream component strips and rewrites forwarding headers.
    • Kept explicit via WithUnsafeTrustAllProxies().

Strict vs Permissive

  • Permissive mode:

    • Ignores malformed proxy headers.
    • Falls back to safer sources when possible.
    • Good default for typical production handlers.

  • Strict mode:

    • Returns typed errors for malformed forwarded, invalid IP tokens, conflicting trusted headers, untrusted proxy usage, and invalid configuration.
    • Returns ErrAmbiguousHeader when multiple physical keys normalize to the same configured logical header, such as X-Forwarded-For and x-forwarded-for.
    • Useful for diagnostics, ingress validation, and security-sensitive services.

Header Handling

  • Standardized:

    • forwarded is parsed according to RFC 7239, including quoted strings, escaping, IPv6-in-brackets, obfuscated identifiers, unknown, multiple header fields, and HTTP list semantics.

  • De-facto:

    • x-forwarded-for is parsed as a comma-separated proxy chain.
    • x-real-ip, x-client-ip, cf-connecting-ip, fastly-client-ip, true-client-ip, and x-cluster-client-ip are treated as single-IP headers.

  • Ambiguous / legacy:

    • x-forwarded and forwarded-for are treated as single-IP headers only.
    • They remain lower priority than forwarded and x-forwarded-for.

Duplicate Header Keys

  • Header matching is case-insensitive.
  • In strict mode, multiple physical keys that normalize to the same logical header are rejected with ErrAmbiguousHeader.
  • In permissive mode, ExtractFrom prefers the exact lower-case key when present. Otherwise it prefers the lexicographically smallest key spelling.