Documentation
¶
Overview ¶
Package middleware provides HTTP middleware for Adele applications, including real-IP resolution, request IDs, panic recovery, rate limiting, session loading, maintenance mode, and trusted-proxy header handling.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func RealIP ¶
RealIP is a middleware that sets a http.Request's RemoteAddr to the results of parsing either the True-Client-IP,
X-Real-IP or the X-Forwarded-For headers (in that order).
This middleware should be inserted fairly early in the middleware stack to ensure that subsequent layers (e.g., request loggers) which examine the RemoteAddr will see the intended value. You should only use this middleware if you can trust the headers passed to you (in particular, the three headers this middleware uses), for example because you have placed a reverse proxy like HAProxy or nginx in front of chi. If your reverse proxies are configured to pass along arbitrary header values from the client, or if you use this middleware without a reverse proxy, malicious clients will be able to make you very sad (or, depending on how you're using RemoteAddr, vulnerable to an attack of some sort).
func Recoverer ¶
Recoverer is a middleware that recovers from panics, logs the panic (and a backtrace), and returns a HTTP 500 (Internal Server Error) status if possible. Recoverer prints a request ID if one is provided.
func RequestID ¶
RequestID is a middleware that injects a request ID into the context of each request. A request ID is a string of the form "host.example.com/random-0001", where "random" is a base62 random string that uniquely identifies this go process, and where the last number is an atomically incremented request counter.
func TrustedProxy ¶ added in v1.0.10
TrustedProxy is a middleware that securely establishes the runtime trust model for requests arriving behind a reverse proxy. It is a single, self-contained middleware that performs BOTH security layers, because the framework has no outer server-level wrapper:
The spoofing gate. TrustedProxy is mounted in BootstrapMux BEFORE RealIP (adele.go:379, ahead of RequestID:380 and RealIP:381), so the request's r.RemoteAddr at this point is still the actual kernel-supplied TCP peer. If that peer is NOT in TRUSTED_PROXIES, every header in trustedProxyHeaderNames is deleted so that the framework's RealIP (which rewrites r.RemoteAddr from True-Client-IP / X-Real-IP / X-Forwarded-For with no trust validation) becomes a no-op and r.RemoteAddr stays the true peer. This prevents a malicious client from spoofing its source IP and defeating any per-IP authorization or throttling downstream.
The proto/host rewrite. When the peer IS trusted, the forwarded headers survive, and if the derived client IP is also trusted, X-Forwarded-Proto and X-Forwarded-Host are honored to rewrite r.URL.Scheme / r.TLS and r.Host / r.URL.Host respectively.
Configuration via environment variables (read at construction with os.Getenv — this is a package-level middleware with no a.Helpers access):
TRUSTED_PROXIES: Comma-separated list of trusted proxy IPs/CIDRs.
Examples: "127.0.0.1,192.168.1.0/24" or "10.0.0.0/8"
TRUST_PROXY_HEADERS: Comma-separated list of headers to trust.
Examples: "proto,host" or "proto,host,port,for"
Secure by default: with TRUSTED_PROXIES unset, no peer is trusted, so the forwarded headers are always stripped, RealIP becomes a no-op, and r.RemoteAddr remains the true TCP peer. A misconfigured deployment behind a real load balancer will attribute all activity to the LB IP (visible in logs/metrics) but no spoofing is possible.
Security considerations:
- Never set TRUSTED_PROXIES to "*" or "0.0.0.0/0" in production.
- Only include your actual reverse-proxy IPs (LB subnets, ingress CIDRs).
- Headers from untrusted peers are completely ignored.
Types ¶
type FrameworkTrace ¶
type FrameworkTrace struct {
AdeleVersion string
AppName string
RootPath string
FrameCount int
GoVersion string
FileName string
FilePath string
PackagePath string
MainPath string
PanicMessage string
PanicType string
PanicLine string
Stack []FrameworkTraceEntry
StackFormatted []string
StackRaw []byte
SourceRaw string
SourceFormatted []string
SourceHighlight string
}
type FrameworkTraceEntry ¶
type Middleware ¶
type Middleware struct {
Cookie Cookie
FrameworkVersion string
AppName string
RootPath string
Log *logrus.Logger
MaintenanceMode bool
Session *scs.SessionManager
Rate int
Duration time.Duration
Limit func(requestLimit int, windowLength time.Duration, options ...httprate.Option) func(next http.Handler) http.Handler
}
func (*Middleware) CheckForMaintenanceMode ¶
func (a *Middleware) CheckForMaintenanceMode(next http.Handler) http.Handler
func (*Middleware) RateLimiter ¶
func (a *Middleware) RateLimiter() func(next http.Handler) http.Handler
func (*Middleware) RecovererWithDebug ¶
func (m *Middleware) RecovererWithDebug(next http.Handler) http.Handler
The recover with debug middleware is designed to manage the panic behavior of the framework by catching the panic sequence and restoring normal execution. When this takes place, the middleware will render a built-in go template that displays the panic message and related information. Please see the FrameworkTrace struct for details about what information is displayed in the user interface.
func (*Middleware) SessionLoad ¶
func (a *Middleware) SessionLoad(next http.Handler) http.Handler
Load and save session on each request
Source Files