Middlewares

A middleware is a request transformer attached to a router. Each middleware lives in its own subpackage of pkg/middlewares/ and is registered in pkg/server/middleware/middlewares.go. Configuration types are declared in pkg/config/dynamic/middlewares.go (a 65k-byte file — every middleware has a struct there).

How middlewares attach to a request

graph LR
    Router[matched router] --> Chain
    subgraph Chain
        ObsIn[Capture<br/>pkg/middlewares/capture] --> Tracing[Tracing wrapper<br/>pkg/middlewares/observability]
        Tracing --> User1[user middleware 1]
        User1 --> User2[user middleware 2]
        User2 --> Metrics[Metrics<br/>pkg/middlewares/metrics]
        Metrics --> AccessLog[AccessLog<br/>pkg/middlewares/accesslog]
    end
    AccessLog --> Service[service handler]

The chain is built by pkg/server/middleware/middlewares.go plus pkg/server/middleware/observability.go. User-defined middlewares are sandwiched between the always-on observability middlewares.

Catalog

The catalog below groups the 30+ middlewares in pkg/middlewares/ by purpose. Each row points to the implementation; the configuration shape is in pkg/config/dynamic/middlewares.go.

Authentication

Middleware	Package	Notes
Basic auth	pkg/middlewares/auth/basic_auth.go	htpasswd-style credentials.
Digest auth	pkg/middlewares/auth/digest_auth.go	Less common.
Forward auth	pkg/middlewares/auth/forward.go	Delegates to an upstream /auth endpoint.

Rate limiting and concurrency

Middleware	Package	Notes
Rate limiter	pkg/middlewares/ratelimiter	Token-bucket per source.
In-flight req	pkg/middlewares/inflightreq	Caps simultaneous requests per source.
Circuit breaker	pkg/middlewares/circuitbreaker	Opens on configurable expressions (e.g. NetworkErrorRatio() > 0.5).
Retry	pkg/middlewares/retry	Replays the request on transient failures.

IP allow / deny

Middleware	Package	Notes
IP allow list	pkg/middlewares/ipallowlist	Source-IP-based allow list.
IP white list	pkg/middlewares/ipwhitelist	Legacy alias retained for backwards compatibility.
pkg/middlewares/extractor.go	shared	Common source-IP extraction (PROXY, X-Forwarded-For).

Path / URL rewriting

Middleware	Package	Notes
Add prefix	pkg/middlewares/addprefix	Prepends a path segment.
Strip prefix	pkg/middlewares/stripprefix	Removes a path segment.
Strip prefix (regex)	pkg/middlewares/stripprefixregex	Same with a pattern.
Replace path	pkg/middlewares/replacepath	Replaces the path entirely.
Replace path (regex)	pkg/middlewares/replacepathregex	Same with a pattern.
Encoded characters	pkg/middlewares/encodedcharacters	Reject or normalize percent-encoded path segments.

Headers and cookies

Middleware	Package	Notes
Headers	pkg/middlewares/headers	Add / remove / overwrite request and response headers; CORS; HSTS.
Forwarded headers	pkg/middlewares/forwardedheaders	Trust-network gating for X-Forwarded-*.
Pass TLS client cert	pkg/middlewares/passtlsclientcert	Encodes the client cert into headers for upstream consumption.
Request decorator	pkg/middlewares/requestdecorator	Per-request mutations used by some providers internally.

Compression and content

Middleware	Package	Notes
Compress	pkg/middlewares/compress	gzip/deflate/brotli/zstd; per-content-type configuration.
Buffering	pkg/middlewares/buffering	Buffers request/response when total size exceeds limit.
Content type	pkg/middlewares/contenttype	Auto-detects or overrides response content type.
Custom errors	pkg/middlewares/customerrors	Renders friendly error pages for selected statuses.
gRPC-Web	pkg/middlewares/grpcweb	Bridges HTTP/1.1 gRPC-Web clients to gRPC over HTTP/2.

TLS, redirect, and chain

Middleware	Package	Notes
Redirect	pkg/middlewares/redirect	HTTP→HTTPS, regex-based redirects.
Chain	pkg/middlewares/chain	Bundle multiple middlewares behind one name.
SNI check	pkg/middlewares/snicheck	Matches HTTP host against TLS SNI.
Capture	pkg/middlewares/capture	Records latency/bytes for downstream observability use.
Recovery	pkg/middlewares/recovery	Recovers from panics. Always-on.

Observability (always-on)

Middleware	Package	Notes
Access log	pkg/middlewares/accesslog	CLF / JSON access log.
Metrics	pkg/middlewares/metrics	Per-router/per-service counters.
Observability	pkg/middlewares/observability	Tracing wrapper.
Handler switcher	pkg/middlewares/handler_switcher.go	Atomic swap of the active handler chain.
Response modifier	pkg/middlewares/response_modifier.go	Helper for middlewares that need to alter the response body or headers post-write.

Routing-control / internal

Middleware	Package	Notes
Deny router recursion	pkg/middlewares/denyrouterrecursion	Refuses chains that would loop.
Router → router	pkg/middlewares/gatewayapi	Adapters used by the Gateway API provider.
Ingress-NGINX shim	pkg/middlewares/ingressnginx	NGINX-annotation translations.

TCP middlewares

pkg/middlewares/tcp/ is the TCP-specific tree. TCP middlewares are simpler — they operate on net.Conn rather than HTTP requests and only support a subset of behaviors (IP allow lists, in-flight connection limits, etc.).

Pages in this section

• Authentication and access control
• Rate limiting and resilience
• Headers, paths, and content
• Observability middlewares

These are summary pages — the deep details are in pkg/middlewares/<name>/<name>.go itself, which is short and idiomatic in almost every case.