Documentation
¶
Overview ¶
Package proxy extracts the real client IP, scheme, and host from trusted reverse proxy headers.
When a celeris server sits behind a load balancer or reverse proxy (e.g. Nginx, Cloudflare, AWS ALB), the TCP peer is the proxy, not the end user. New returns a middleware that inspects X-Forwarded-For, X-Real-Ip, X-Forwarded-Proto, and X-Forwarded-Host -- but only when the immediate peer is in the configured Config.TrustedProxies list. An empty TrustedProxies list is the safe default: the middleware becomes a no-op and trusts nothing, preventing IP spoofing. There is no "trust all" toggle; specify CIDRs (or "0.0.0.0/0") explicitly. Invalid entries panic at New.
Run it via celeris.Server.Pre so the overrides take effect before routing and before any middleware reads ClientIP, Scheme, or Host:
s.Pre(proxy.New(proxy.Config{
TrustedProxies: []string{"10.0.0.0/8", "172.16.0.0/12"},
}))
Config.TrustedHeaders selects which headers to inspect (default "x-forwarded-for" and "x-real-ip"); X-Forwarded-For is walked right-to-left to defeat left-side spoofing, while any other listed header is treated as a single-value IP. The Disable* fields use the zero-value-enabled convention: Config.DisableForwardedProto and Config.DisableForwardedHost both default to false, so a minimal Config processes both headers. Use Config.SkipPaths or Config.Skip to bypass the middleware. RFC 7239 (Forwarded) is not implemented.
Documentation ¶
Full guides and examples: https://goceleris.dev/docs/middleware-security
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func New ¶
func New(config ...Config) celeris.HandlerFunc
New creates a proxy middleware that extracts real client IP, scheme, and host from trusted reverse proxy headers. Pass zero or one Config; zero-value fields are filled with safe defaults.
Example ¶
package main
import (
"github.com/goceleris/celeris/middleware/proxy"
)
func main() {
// Trust Cloudflare and local reverse proxy.
_ = proxy.New(proxy.Config{
TrustedProxies: []string{"173.245.48.0/20", "10.0.0.0/8"},
})
}
Output:
Example (CustomHeader) ¶
package main
import (
"github.com/goceleris/celeris/middleware/proxy"
)
func main() {
// Trust Cloudflare's CF-Connecting-IP header.
_ = proxy.New(proxy.Config{
TrustedProxies: []string{"173.245.48.0/20"},
TrustedHeaders: []string{"cf-connecting-ip"},
})
}
Output:
Example (DisableForwardedProto) ¶
package main
import (
"github.com/goceleris/celeris/middleware/proxy"
)
func main() {
// Disable X-Forwarded-Proto processing (X-Forwarded-Host remains enabled).
_ = proxy.New(proxy.Config{
TrustedProxies: []string{"10.0.0.0/8"},
DisableForwardedProto: true,
})
}
Output:
Example (RealIPOnly) ¶
package main
import (
"github.com/goceleris/celeris/middleware/proxy"
)
func main() {
// Only use X-Real-Ip (ignore X-Forwarded-For).
_ = proxy.New(proxy.Config{
TrustedProxies: []string{"10.0.0.0/8"},
TrustedHeaders: []string{"X-Real-Ip"},
})
}
Output:
Types ¶
type Config ¶
type Config struct {
// Skip defines a function to skip this middleware for certain requests.
Skip func(c *celeris.Context) bool
// SkipPaths lists paths to skip (exact match).
SkipPaths []string
// TrustedProxies lists CIDRs or bare IPs whose forwarded headers are trusted.
// Bare IPs are expanded to /32 (IPv4) or /128 (IPv6).
// An empty list means no headers are trusted (safe default -- middleware is a no-op).
// Invalid entries cause a panic at init time.
TrustedProxies []string
// TrustedHeaders lists which forwarded headers to inspect.
// "x-forwarded-for" and "x-real-ip" have built-in chain-walk and validation
// logic. Any other header name (e.g. "cf-connecting-ip") is treated as a
// single-value IP header: the value is parsed with netip.ParseAddr and used
// only if valid.
// Values are lowercased at init time.
// Default: ["x-forwarded-for", "x-real-ip"].
TrustedHeaders []string
// DisableForwardedProto disables processing of X-Forwarded-Proto.
// When false (default), X-Forwarded-Proto is used to override Scheme.
DisableForwardedProto bool
// DisableForwardedHost disables processing of X-Forwarded-Host.
// When false (default), X-Forwarded-Host is used to override Host.
DisableForwardedHost bool
}
Config controls proxy header extraction behavior.
Source Files