Headers, paths, and content

Middlewares that rewrite, redirect, or transform the request and response.

Headers

pkg/middlewares/headers/. The all-purpose header manipulator. Adds, removes, or overrides request and response headers; manages CORS; manages security headers (HSTS, CSP, X-Frame-Options, etc.).

http:
  middlewares:
    sec-headers:
      headers:
        customRequestHeaders:
          X-Forwarded-Proto: https
        customResponseHeaders:
          X-Custom: hello
        accessControlAllowOriginList:
          - https://example.com
        accessControlAllowMethods: [GET, POST]
        accessControlAllowCredentials: true
        accessControlMaxAge: 600
        addVaryHeader: true
        forceSTSHeader: true
        stsSeconds: 31536000
        stsIncludeSubdomains: true
        contentSecurityPolicy: "default-src 'self'"
        contentTypeNosniff: true
        frameDeny: true
        browserXssFilter: true
        referrerPolicy: no-referrer

The middleware is implemented as several composable handlers stacked together: a CORS handler, a security-headers handler, a custom-headers handler. They all share pkg/middlewares/headers/ for state.

Forwarded headers

pkg/middlewares/forwardedheaders/. Strips or forwards X-Forwarded-* headers based on whether the source is a trusted network. The trust list is configured per entry point in static config (forwardedHeaders.trustedIPs); the middleware applies the same logic to dynamic configurations.

This is the security control that prevents arbitrary clients from impersonating proxies.

Path rewriting

The five path middlewares are short and self-explanatory:

Middleware	Source	Effect
Add prefix	pkg/middlewares/addprefix	Prepend prefix to the request path.
Strip prefix	pkg/middlewares/stripprefix	Drop one or more prefixes from the path.
Strip prefix (regex)	pkg/middlewares/stripprefixregex	Same with regex patterns.
Replace path	pkg/middlewares/replacepath	Replace the path with a literal string.
Replace path (regex)	pkg/middlewares/replacepathregex	Replace the path using a regex + replacement.

All five preserve the original path under the X-Replaced-Path request header so upstream apps can recover it if needed.

Redirect

pkg/middlewares/redirect/. Two flavors:

• redirectScheme — change the URL scheme (http → https) or the port. The "force HTTPS" idiom.
• redirectRegex — match the URL with a regex and substitute.

http:
  middlewares:
    https-redirect:
      redirectScheme:
        scheme: https
        permanent: true

    legacy:
      redirectRegex:
        regex: "^https://www\\.old\\.com/(.*)"
        replacement: 'https://new.com/${1}'
        permanent: true

permanent: true returns 308; false returns 307.

Compression

pkg/middlewares/compress/. Encodes responses with one of gzip, deflate, brotli (zstd too in recent builds), based on the client's Accept-Encoding header.

http:
  middlewares:
    compress:
      compress:
        excludedContentTypes:
          - image/png
          - image/jpeg
        minResponseBodyBytes: 1024

The middleware short-circuits when the response is already compressed or below minResponseBodyBytes.

Buffering

Buffering — covered in Resilience — also serves a content-shaping role by enforcing maximum body sizes.

Custom errors

pkg/middlewares/customerrors/. Renders a custom upstream-fetched error page for selected response codes:

http:
  middlewares:
    error-pages:
      errors:
        status: ['404', '500-599']
        service: error-pages
        query: /{status}.html

When an upstream returns a matching status, the middleware fetches /{status}.html from the configured service and serves that body to the client. Useful for branded error pages.

Content type detection

pkg/middlewares/contenttype/. Determines or overrides the response Content-Type header. Some upstreams return generic application/octet-stream; the middleware can sniff the body and set a more specific type.

gRPC-Web bridge

pkg/middlewares/grpcweb/. Wraps a gRPC-over-HTTP/2 upstream so that gRPC-Web (HTTP/1.1) clients can talk to it. Translates grpc-web-text and grpc-web framings to and from gRPC trailers.

Chain

pkg/middlewares/chain/. Bundles multiple middlewares behind one configuration name. Useful when a router needs the same several middlewares applied repeatedly:

http:
  middlewares:
    secure:
      chain:
        middlewares:
          - basic-auth
          - https-redirect
          - sec-headers

The chain middleware does no transformation itself — it's a configuration convenience.

Encoded characters

pkg/middlewares/encodedcharacters/. Controls how percent-encoded characters in the request path are handled (covered in Resilience since the security implications often dominate).

Pass TLS client cert

Covered in Authentication and access control. The middleware encodes the negotiated client certificate (subject, issuer, SANs, full PEM) into request headers for the upstream to consume.

Request decorator

pkg/middlewares/requestdecorator/. Internal-use middleware that some providers attach to all router chains. Mostly invisible to operators but worth knowing about when reading the middleware factory.

For the always-on observability middlewares, see Observability.