Documentation
¶
Overview ¶
Package identity resolves canonical request identity values.
Resolver extracts client IP, scheme, host, and request ID from an HTTP request. Forwarded headers are honored only when the direct peer matches configured trusted proxies, which keeps proxy-derived identity explicit and safe by default.
Purpose: See the package summary above. Import: `github.com/aatuh/api-toolkit/v4/httpx/identity`. Example: See docs/api-reference.md for package example links and docs/cookbook.md for task recipes. Errors: Constructors, parsers, and handlers return or write documented errors according to their signatures; packages with plain data types do not add hidden error channels. Concurrency: Treat configured middleware and helpers as immutable after construction; request and response values remain request-scoped unless a type documents stronger guarantees. Stability: Stable core API under VERSIONING.md and scripts/apicheck.sh. When not to use: Prefer net/http, application-owned types, or narrower helpers when this package contract is not needed.
Index ¶
- func ParseTrustedProxies(values []string) ([]netip.Prefix, error)
- func RequestID(req *http.Request) string
- type ClientInfo
- type HeaderPolicy
- type Resolver
- func (r Resolver) ClientIP(req *http.Request) (netip.Addr, bool)
- func (r Resolver) ClientIPString(req *http.Request) string
- func (r Resolver) Host(req *http.Request) string
- func (r Resolver) Resolve(req *http.Request) ClientInfo
- func (r Resolver) Scheme(req *http.Request) string
- func (r Resolver) TrustsRemoteAddr(remote string) bool
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ParseTrustedProxies ¶
ParseTrustedProxies parses CIDR strings into prefixes.
Types ¶
type ClientInfo ¶
ClientInfo captures canonical client identity attributes.
type HeaderPolicy ¶
type HeaderPolicy uint8
HeaderPolicy controls which forwarded headers may be honored.
const ( // HeaderPolicyNone ignores forwarded headers. HeaderPolicyNone HeaderPolicy = 0 // HeaderPolicyXForwarded trusts X-Forwarded-* headers from trusted proxies. HeaderPolicyXForwarded HeaderPolicy = 1 << iota // HeaderPolicyForwarded trusts RFC 7239 Forwarded headers from trusted proxies. HeaderPolicyForwarded // HeaderPolicyBoth trusts both Forwarded and X-Forwarded-* headers. HeaderPolicyBoth = HeaderPolicyXForwarded | HeaderPolicyForwarded )
type Resolver ¶
type Resolver struct {
TrustedProxies []netip.Prefix
HeaderPolicy HeaderPolicy
}
Resolver derives canonical client identity values from an http.Request. Forwarded headers are honored only when the direct peer is trusted.
func (Resolver) ClientIPString ¶
ClientIPString returns the best-effort client IP string.
Example ¶
package main
import (
"context"
"fmt"
"net/http"
"net/http/httptest"
"github.com/aatuh/api-toolkit/v4/httpx/identity"
)
func main() {
proxies, err := identity.ParseTrustedProxies([]string{"10.0.0.1"})
if err != nil {
panic(err)
}
resolver := identity.Resolver{
TrustedProxies: proxies,
HeaderPolicy: identity.HeaderPolicyXForwarded,
}
req := httptest.NewRequestWithContext(context.Background(), http.MethodGet, "/", nil)
req.RemoteAddr = "10.0.0.1:1234"
req.Header.Set("X-Forwarded-For", "203.0.113.7")
fmt.Println(resolver.ClientIPString(req))
}
Output: 203.0.113.7
func (Resolver) Host ¶
Host returns the request host, honoring forwarded headers only for trusted proxies.
func (Resolver) Resolve ¶
func (r Resolver) Resolve(req *http.Request) ClientInfo
Resolve extracts the canonical client identity from the request.
func (Resolver) Scheme ¶
Scheme returns the request scheme, honoring forwarded headers only for trusted proxies.
func (Resolver) TrustsRemoteAddr ¶
TrustsRemoteAddr reports whether the remote address is within trusted proxies.
Source Files