httpx

func WithCheck ¶

func WithCheck(fn func(r *http.Request) bool) AccessGuardOption

WithCheck sets a fully custom single-step validator.

Strong semantics:

• If WithCheck is set, it MUST be the only validation mechanism. Combining it with token/IP options is an assembly/config error (panic).
• fn must be fast and must not block; it must not do I/O.

func WithDenyStatus ¶

func WithDenyStatus(code int) AccessGuardOption

WithDenyStatus sets the HTTP status code used for denied requests.

Default is 403 (Forbidden). If code <= 0, it leaves the default unchanged.

func WithIPAllowList ¶

func WithIPAllowList(cidrsOrIPs []string) AccessGuardOption

WithIPAllowList enables IP validation with a static allowlist.

Entries may be CIDRs (e.g. "10.0.0.0/8", "fd00::/8") or single IPs (e.g. "192.168.1.1", "2001:db8::1"), where single IPs are treated as /32 or /128.

Semantics:

• cidrsOrIPs == nil: enabled, but deny-all (fail-closed)
• len(cidrsOrIPs) == 0: enabled, but deny-all (fail-closed)
• invalid entries are ignored; if no valid entries remain, deny-all (fail-closed)

To disable IP validation, do NOT configure any IP-related option.

func WithIPAllowSet ¶

func WithIPAllowSet(set IPAllowSetLike) AccessGuardOption

WithIPAllowSet enables IP validation with a user-provided allow set.

set must be non-nil. To disable IP validation, do NOT configure any IP-related option.

func WithIPResolver ¶

func WithIPResolver(fn func(r *http.Request) (net.IP, bool)) AccessGuardOption

WithIPResolver sets a custom IP resolver.

Default is:

• RealIPFromRequest(r) when present
• otherwise parseIP(r.RemoteAddr)

If fn is nil, the option is ignored.

func WithOnDeny ¶

func WithOnDeny(fn func(r *http.Request, reason DenyReason)) AccessGuardOption

WithOnDeny sets a hook called when AccessGuard denies a request.

Observability-only: implementations must be fast and must not panic. Implementations must NOT write the response. If the hook panics, AccessGuard will swallow the panic and report it to stderr (style aligned with Timeout / BodyLimit).

func WithOr ¶

func WithOr() AccessGuardOption

WithOr switches the combination logic from the default AND to OR.

When both token and IP are enabled:

• default (AND): ok = tokenOK && ipOK
• WithOr (OR): ok = tokenOK || ipOK

func WithTokenCheck ¶

func WithTokenCheck(fn func(token string) bool) AccessGuardOption

WithTokenCheck enables token validation with a fully custom checker.

fn must be fast and must not block; it must not do I/O. If fn is nil, the option is ignored.

func WithTokenHeader ¶

func WithTokenHeader(name string) AccessGuardOption

WithTokenHeader sets the header name used for token validation.

Default is DefaultAccessGuardTokenHeader. Empty/blank names are ignored.

func WithTokenSet ¶

func WithTokenSet(set TokenSetLike) AccessGuardOption

WithTokenSet enables token validation with a user-provided token set.

set must be non-nil. To disable token validation, do NOT configure any token-related option.

func WithTokens ¶

func WithTokens(tokens []string) AccessGuardOption

WithTokens enables token validation with a static token set.

Semantics:

• tokens == nil: enabled, but deny-all (fail-closed)
• len(tokens) == 0: enabled, but deny-all (fail-closed)
• blank/whitespace tokens are ignored; if none remain, deny-all (fail-closed)

To disable token validation, do NOT configure any token-related option.

func NewAtomicIPAllowList ¶

func NewAtomicIPAllowList() *AtomicIPAllowList

NewAtomicIPAllowList creates a new allowlist in the deny-all state.

func NewAtomicTokenSet ¶

func NewAtomicTokenSet() *AtomicTokenSet

NewAtomicTokenSet creates a new token set in the deny-all state.

func WithLimitFunc ¶

func WithLimitFunc(fn BodyLimitFunc) BodyLimitOption

WithLimitFunc sets a per-request BodyLimitFunc.

If fn is nil, it leaves the default unchanged.

func WithOnReject ¶

func WithOnReject(fn BodyLimitHandler) BodyLimitOption

WithOnReject sets a BodyLimitHandler called when a request is rejected due to Content-Length exceeding the limit, or when downstream reads exceed the limit.

If fn is nil, it leaves the default unchanged.

func WithAllowCredentials ¶

func WithAllowCredentials(v bool) CORSOption

WithAllowCredentials controls whether Access-Control-Allow-Credentials is set.

Default is true (debug-friendly).

func WithAllowNullOrigin ¶

func WithAllowNullOrigin(v bool) CORSOption

WithAllowNullOrigin controls whether Origin: "null" is allowed when an allowlist is configured via WithAllowedOrigins.

Default is false (when allowlist is configured, Origin:"null" is rejected unless enabled).

func WithAllowedHeaders ¶

func WithAllowedHeaders(headers []string) CORSOption

WithAllowedHeaders restricts allowed request headers for CORS preflight.

If headers is nil or empty, headers are not restricted (default; reflected from request). If headers is non-empty but no valid headers are parsed, it denies all headers (fail-closed).

Enforcement:

• For preflight: all headers in Access-Control-Request-Headers must be allowed, otherwise CORS is skipped.

func WithAllowedMethods ¶

func WithAllowedMethods(methods []string) CORSOption

WithAllowedMethods restricts allowed methods for CORS.

If methods is nil or empty, methods are not restricted (default). If methods is non-empty but no valid methods are parsed, it denies all methods (fail-closed).

Enforcement:

• For preflight: Access-Control-Request-Method must be allowed, otherwise CORS is skipped.
• For non-preflight: the request method must be allowed, otherwise CORS is skipped.

func WithAllowedOrigins ¶

func WithAllowedOrigins(origins []string) CORSOption

WithAllowedOrigins sets the allowlist of allowed origins/host patterns.

If origins is nil or empty, it means "allow any Origin" (default; debug-friendly). Empty/blank entries are ignored.

Safety note:

• If origins is non-empty but none of the entries are valid patterns after parsing, the middleware will deny all origins (fail-closed) to avoid accidental "allow any" due to configuration typos.

Matching is based on the request Origin's hostname only (scheme and port are ignored). Supported patterns:

• "example.com": matches "example.com" and any subdomain.
• "*.example.com": matches any subdomain under "example.com", but not "example.com" itself.
• "*.a.example.com": matches any subdomain under "a.example.com", but not "a.example.com" itself.

For convenience, entries may also be full origins like "https://example.com:8443"; only the hostname part is used.

func WithEnabledFunc ¶

func WithEnabledFunc(fn func(r *http.Request) bool) CORSOption

WithEnabledFunc sets a per-request toggle for CORS.

If fn is nil, it leaves the default unchanged.

When fn returns false, CORS is skipped entirely:

• no CORS headers are written
• preflight requests are not short-circuited

func WithExposeHeaders ¶

func WithExposeHeaders(headers []string) CORSOption

WithExposeHeaders sets Access-Control-Expose-Headers for non-preflight responses.

Default is exposing X-Request-ID (httpx DefaultRequestIDHeader), so browser clients can read it via fetch/XHR (useful for correlating logs and debugging).

If headers is nil or empty, Access-Control-Expose-Headers is not set (disabled). Empty/blank entries are ignored; duplicates are removed (case-insensitive).

func WithExposeHeadersAppend ¶

func WithExposeHeadersAppend(headers []string) CORSOption

WithExposeHeadersAppend appends headers to Access-Control-Expose-Headers.

It appends to the current expose list (default starts with X-Request-ID). If the expose header was disabled via WithExposeHeaders(nil), Append will start from empty. Empty/blank entries are ignored; duplicates are removed (case-insensitive).

func WithMatchFunc ¶

func WithMatchFunc(fn func(r *http.Request) bool) CORSOption

WithMatchFunc sets a per-request matcher for CORS.

If fn is nil, it leaves the default unchanged.

When fn returns false, CORS is skipped entirely:

• no CORS headers are written
• preflight requests are not short-circuited

func WithMaxAge ¶

func WithMaxAge(d time.Duration) CORSOption

WithMaxAge controls Access-Control-Max-Age for preflight responses.

Default is 10 minutes (debug-friendly, reduces repeated preflight requests). If d <= 0, Access-Control-Max-Age is not set.

func WithPreflightStatus ¶

func WithPreflightStatus(code int) CORSOption

WithPreflightStatus sets the status code for successful preflight responses.

Allowed values are 200 (OK) and 204 (No Content). Default is 204. Invalid values are ignored and keep the default unchanged.

func AccessGuard ¶

func AccessGuard(opts ...AccessGuardOption) Middleware

AccessGuard returns a middleware that enforces an access guard based on:

• optional token validation (token from a header + validator)
• optional client IP allowlist (real IP from RealIP middleware when present)

Rules:

• If IP allowlist is enabled, the client IP must match one of the allowlisted CIDRs/IPs. Client IP is taken from RealIP middleware when present; otherwise it falls back to RemoteAddr.
• If token validation is enabled, the request must provide exactly one non-empty token header value that matches the configured token validator.
• If both are enabled, both checks must pass (AND).
• If neither is enabled, it panics (configuration/assembly error).

Security defaults:

• When token validation is enabled but the token set is empty, it denies all (fail-closed).
• When IP validation is enabled but the allowlist is empty, it denies all (fail-closed).
• OR must be explicitly enabled via WithOr().

// Token + IP allowlist.
h := Chain(
	RealIP(WithTrustedProxies([]string{"10.0.0.0/8"})),
	AccessGuard(
		WithTokens([]string{"tokenA"}),
		WithIPAllowList([]string{"203.0.113.0/24"}),
	),
).Handler(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	w.WriteHeader(http.StatusOK)
}))

req := httptest.NewRequest(http.MethodGet, "http://example.test/", nil)
req.RemoteAddr = "10.0.0.1:12345"                 // trusted proxy
req.Header.Set("X-Forwarded-For", "203.0.113.50") // real client
req.Header.Set(DefaultAccessGuardTokenHeader, "tokenA")
rr := httptest.NewRecorder()
h.ServeHTTP(rr, req)
_ = rr.Result()

// Token-only guard: no RealIP middleware required.
set := NewAtomicTokenSet()
set.Update([]string{"tokenA"})

h := AccessGuard(
	WithTokenSet(set),
)(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	w.WriteHeader(http.StatusOK)
}))

req := httptest.NewRequest(http.MethodGet, "http://example.test/", nil)
req.Header.Set(DefaultAccessGuardTokenHeader, "tokenA")
rr := httptest.NewRecorder()
h.ServeHTTP(rr, req)
_ = rr.Result()

func BodyLimit ¶

func BodyLimit(maxBytes int64, opts ...BodyLimitOption) Middleware

BodyLimit returns a middleware that enforces a maximum request body size.

Behavior:

• It computes a per-request limit from maxBytes and WithLimitFunc.
• If maxBytes <= 0, or BodyLimitFunc returns ok=false, or ok=true with n <= 0, BodyLimit is skipped for that request.
• If Content-Length is known and exceeds the limit, it rejects early with 413 Request Entity Too Large, without calling downstream. In this case, it also hints the client/proxy to close the connection to avoid keep-alive reuse with an unread request body.
• Otherwise, it wraps r.Body with http.MaxBytesReader so downstream reads past the limit fail with *http.MaxBytesError.

OnReject trigger:

• If WithOnReject is provided, it is called for observability when:
• the request is rejected early (Source=content-length), or
• downstream reads exceed the limit (Source=read).
• For Source=read, OnReject is called after downstream returns, and only if downstream actually read past the limit (i.e., observed a *http.MaxBytesError).
• If BodyLimit is skipped for a request, OnReject will not be called.

Ordering:

• Place BodyLimit before any handler/middleware that may read or buffer the request body (e.g., decompression, request body logging, multipart parsing, JSON decoding).

Tuning/ops:

• WithLimitFunc is designed to work naturally with runtime-tunable configs. A common convention is returning n <= 0 to temporarily disable the limit for a request.

Downstream handling:

BodyLimit does NOT translate read-time errors into a response. Downstream handlers that read r.Body should treat *http.MaxBytesError as 413 Request Entity Too Large (or the equivalent in your API) and must stop processing immediately to avoid partial-body bugs.

Example:

b, err := io.ReadAll(r.Body)
if err != nil {
	var mbe *http.MaxBytesError
	if errors.As(err, &mbe) {
		http.Error(w, http.StatusText(http.StatusRequestEntityTooLarge), http.StatusRequestEntityTooLarge)
		return
	}
	http.Error(w, "bad request", http.StatusBadRequest)
	return
}

// Global default limit (e.g., for API handlers).
apiLimit := BodyLimit(1<<20 /* 1 MiB */, WithOnReject(func(r *http.Request, info BodyLimitInfo) {
	_ = r
	_ = info
	// Record metrics / logs here (do NOT write response).
}))

// Per-request override/skip (e.g., tune at runtime; skip long-lived or special endpoints).
conditional := BodyLimit(1<<20, WithLimitFunc(func(r *http.Request) (int64, bool) {
	if r.URL != nil && r.URL.Path == "/upload/large" {
		return 0, false // skip
	}
	return 1 << 20, true
}))

_ = apiLimit
_ = conditional

func CORS ¶

func CORS(opts ...CORSOption) Middleware

CORS returns a middleware that adds CORS headers for browser clients.

Defaults are intentionally "debug-friendly":

• Any Origin is allowed by default (Origin is reflected).
• Access-Control-Allow-Credentials is enabled by default.
• Preflight (OPTIONS + Access-Control-Request-Method) is short-circuited by default with 204 No Content.
• Preflight responses include Access-Control-Max-Age by default (10 minutes).
• Access-Control-Expose-Headers is set by default to expose X-Request-ID.

Safety and predictability:

• CORS is applied only when the request has exactly one non-empty Origin header value.
• If WithAllowedOrigins is set to a non-empty list, the Origin hostname must match one of the allowed patterns (scheme and port are ignored).
• When the origin is not allowed (or the Origin header is invalid), the middleware does not write any CORS headers.

Preflight behavior:

• A request is considered preflight when method is OPTIONS and the request has a non-empty Access-Control-Request-Method header.
• For allowed preflight requests, it writes CORS preflight response headers and returns 204 without calling downstream.
• For disallowed preflight requests, it does not short-circuit; downstream decides.

Ordering:

• Place CORS before authentication/authorization middleware when you want preflight requests to succeed. If a preflight request reaches an auth middleware first, it may be rejected, causing browsers to fail the actual cross-origin request.

Tuning:

• WithEnabledFunc and WithMatchFunc are designed to work naturally with runtime tuning flags: return false to temporarily disable CORS for a request.

// Default: allow any Origin (reflected), allow credentials, short-circuit preflight.
h := CORS()(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	w.WriteHeader(http.StatusOK)
}))

req := httptest.NewRequest(http.MethodGet, "http://example.test/", nil)
req.Header.Set("Origin", "https://frontend.example")
rr := httptest.NewRecorder()
h.ServeHTTP(rr, req)
_ = rr.Result()

// Runtime toggle (e.g. wired to tuning/feature flag).
var enabled int32
atomic.StoreInt32(&enabled, 1)

h := CORS(WithEnabledFunc(func(r *http.Request) bool {
	return atomic.LoadInt32(&enabled) == 1
}))(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	w.WriteHeader(http.StatusOK)
}))

req := httptest.NewRequest(http.MethodGet, "http://example.test/", nil)
req.Header.Set("Origin", "https://frontend.example")
rr := httptest.NewRecorder()
h.ServeHTTP(rr, req)
_ = rr.Result()

// Apply CORS only to a subtree (e.g. debug endpoints).
h := CORS(WithMatchFunc(func(r *http.Request) bool {
	return strings.HasPrefix(r.URL.Path, "/debug/")
}))(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	w.WriteHeader(http.StatusOK)
}))

req := httptest.NewRequest(http.MethodGet, "http://example.test/debug/ping", nil)
req.Header.Set("Origin", "https://frontend.example")
rr := httptest.NewRecorder()
h.ServeHTTP(rr, req)
_ = rr.Result()

func RealIP ¶

func RealIP(opts ...RealIPOption) Middleware

RealIP returns a middleware that extracts the real client IP from the request.

Behavior:

• By default, it does NOT trust any headers and uses RemoteAddr directly.
• If trusted proxies are configured (via WithTrustedProxies), and the direct client IP is within a trusted CIDR, it extracts the real IP from headers.
• For X-Forwarded-For, it scans right-to-left, skipping trusted proxies, and returns the first untrusted IP. If an invalid entry is encountered, behavior depends on WithXFFInvalidPolicy (default: XFFInvalidStop).
• For X-Real-IP (and other single-value headers), it uses the value only when the header has exactly one non-empty value; multiple values are treated as invalid/ambiguous.
• The extracted IP is stored in the request context for downstream handlers. If no IP can be extracted (e.g., unparseable RemoteAddr), the context is left unchanged.

Security:

• Default-safe: without trusted proxies configured, headers are ignored.
• Only configure trusted proxies for IPs you actually trust (e.g., your load balancer).

func Recover ¶

func Recover(opts ...RecoverOption) Middleware

Recover returns a middleware that recovers from panics in downstream handlers.

It re-panics http.ErrAbortHandler to preserve net/http semantics.

If the response has not been written yet, it writes a 500 Internal Server Error. If the response has already started, it does not modify the response.

Observability:

• If WithOnPanic is provided, it is called with the panic value and stack.
• Otherwise, panics are reported to stderr by default.

func RequestID ¶

func RequestID(opts ...RequestIDOption) Middleware

RequestID returns a middleware that ensures each request has a request id.

Behavior:

• Incoming: by default, it reads X-Request-ID (or the configured incoming headers), validates it, and uses the first valid value (in configured order).
• If no valid incoming id is found (or trustIncoming is false), it generates a new id.
• It stores the request id in the request context for downstream handlers.
• It sets the response header X-Request-ID (DefaultRequestIDHeader) by default.

Defaults are chosen to be explicit and safe:

• Only X-Request-ID is checked by default; users can extend via WithIncomingHeaders.
• Incoming ids are validated (length + allowed characters) to avoid log/header pollution.
• The response header is set by default for easier debugging.

func Timeout ¶

func Timeout(timeout time.Duration, opts ...TimeoutOption) Middleware

Timeout returns a middleware that derives a request context with a timeout.

Behavior:

• It derives a request context with deadline = now + timeout, unless:
• timeout <= 0, or
• TimeoutFunc returns ok=false, or d <= 0, or
• the incoming request context already has an earlier (or equal) deadline (i.e., it never extends an existing deadline).
• It calls the downstream handler with the derived context when applied.
• After downstream returns, if the derived context ended with context.DeadlineExceeded, it calls the TimeoutHandler (if provided) for observability.

OnTimeout trigger:

• OnTimeout is called only when Timeout actually derived a context for the request. If Timeout is skipped (by timeout <= 0 or TimeoutFunc), or if it keeps the parent context due to an existing earlier/equal deadline, OnTimeout will not be called.

Notes:

• Timeout does NOT write any response on timeout (standard-library flavored, low-risk).
• Timeout does NOT start a goroutine; it relies on cooperative cancellation via context.

// Global default timeout (e.g., for API handlers).
apiTimeout := Timeout(2*time.Second, WithOnTimeout(func(r *http.Request, info TimeoutInfo) {
	_ = r
	_ = info
	// Record metrics / logs here (do NOT write response).
}))

// Per-request override/skip (e.g., skip long-lived streaming endpoints).
conditional := Timeout(2*time.Second, WithTimeoutFunc(func(r *http.Request) (time.Duration, bool) {
	if r.URL != nil && r.URL.Path == "/sse" {
		return 0, false // skip
	}
	return 2 * time.Second, true
}))

_ = apiTimeout
_ = conditional

func Chain ¶

func Chain(mws ...Middleware) Middlewares

Chain creates a middleware chain from the provided middlewares.

Nil middlewares are ignored.

func WithTrustedHeaders ¶

func WithTrustedHeaders(headers []string) RealIPOption

WithTrustedHeaders sets the list of header names to check for the real IP, in order.

Default is ["X-Forwarded-For", "X-Real-IP"]. Empty/blank names are ignored. If the resulting list is empty, it falls back to the default.

func WithTrustedProxies ¶

func WithTrustedProxies(cidrs []string) RealIPOption

WithTrustedProxies sets the list of trusted proxy CIDRs.

Only when the direct client IP (from RemoteAddr) is within one of these CIDRs, the middleware will trust and extract IP from headers.

Accepts CIDR notation (e.g., "10.0.0.0/8") or single IPs (e.g., "192.168.1.1"). Single IPs are treated as /32 (IPv4) or /128 (IPv6). Invalid entries are silently ignored.

For strict validation (e.g., fail-fast at startup), use ParseTrustedProxies.

func WithXFFInvalidPolicy ¶

func WithXFFInvalidPolicy(p XFFInvalidPolicy) RealIPOption

WithXFFInvalidPolicy sets how X-Forwarded-For parsing handles invalid entries.

Default is XFFInvalidStop (most conservative).

func WithOnPanic ¶

func WithOnPanic(fn PanicHandler) RecoverOption

WithOnPanic sets a PanicHandler. If not set, Recover reports panics to stderr by default.

func WithGenerator ¶

func WithGenerator(fn RequestIDGenerator) RequestIDOption

WithGenerator sets a custom request id generator.

If fn is nil, it leaves the default generator unchanged.

func WithIncomingHeaders ¶

func WithIncomingHeaders(headers []string) RequestIDOption

WithIncomingHeaders sets the list of header names to look for an incoming request id, in order.

Empty/blank names are ignored. If the resulting list is empty, it falls back to the default (X-Request-ID).

func WithMaxLen ¶

func WithMaxLen(n int) RequestIDOption

WithMaxLen sets the maximum allowed length for an incoming request id.

If n <= 0, it leaves the default unchanged.

func WithSetResponseHeader ¶

func WithSetResponseHeader(v bool) RequestIDOption

WithSetResponseHeader controls whether RequestID sets DefaultRequestIDHeader on the response.

Default is true.

func WithTrustIncoming ¶

func WithTrustIncoming(v bool) RequestIDOption

WithTrustIncoming controls whether RequestID trusts and uses incoming request id headers.

Default is true.

func WithValidator ¶

func WithValidator(fn func(string) bool) RequestIDOption

WithValidator sets a custom validator for incoming request ids.

If fn is nil, it leaves the default validator unchanged.

func WithNow ¶

func WithNow(fn func() time.Time) TimeoutOption

WithNow sets a custom clock function used by Timeout.

This is primarily intended for tests. If fn is nil, it leaves the default unchanged.

func WithOnTimeout ¶

func WithOnTimeout(fn TimeoutHandler) TimeoutOption

WithOnTimeout sets a TimeoutHandler called when the derived context ends with context.DeadlineExceeded.

If fn is nil, it leaves the default unchanged.

func WithTimeoutFunc ¶

func WithTimeoutFunc(fn TimeoutFunc) TimeoutOption

WithTimeoutFunc sets a per-request TimeoutFunc.

If fn is nil, it leaves the default unchanged.