Rate limiting and resilience

Middlewares that protect upstreams from overload, retry transient failures, and shape traffic.

Rate limiter

pkg/middlewares/ratelimiter/. A token-bucket limiter keyed by the source IP (or any client identifier the IP-strategy resolves):

http:
  middlewares:
    public-api:
      rateLimit:
        average: 100
        period: 1s
        burst: 200
        sourceCriterion:
          ipStrategy:
            depth: 2

Behavior:

• average and period define the steady-state rate; burst allows a temporary spike.
• sourceCriterion chooses the limiter key — IP (with PROXY/forwarded resolution) or a request header.
• The limiter is in-memory and per-process. For multi-instance Traefik deployments, the rate limit is per-instance — not coordinated.

In-flight requests

pkg/middlewares/inflightreq/. Limits the number of simultaneous requests per client:

http:
  middlewares:
    inflight-cap:
      inFlightReq:
        amount: 50
        sourceCriterion:
          requestHeaderName: X-Client-ID

When the limit is hit, the middleware returns 429 Too Many Requests. The shared extractor.go resolves the source — the same logic the rate limiter uses.

In-flight connections (TCP)

pkg/middlewares/tcp/inflightconn/. The TCP-level analogue. Counts TCP connections per source. Useful for capacity-protecting raw TCP services.

A recent commit added a "limit-connections" feature in the TCP load-balancer space; the middleware-side counterpart lives here.

Circuit breaker

pkg/middlewares/circuitbreaker/. Trips when an expression evaluates true and short-circuits with a fallback response:

http:
  middlewares:
    breaker:
      circuitBreaker:
        expression: 'NetworkErrorRatio() > 0.5'
        checkPeriod: 100ms
        fallbackDuration: 10s
        recoveryDuration: 10s
        responseCode: 502

Available metrics in expressions:

• NetworkErrorRatio()
• LatencyAtQuantileMS(quantile)
• ResponseCodeRatio(from, to, dividedFrom, dividedTo)

Implementation uses github.com/vulcand/oxy's breaker library.

Retry

pkg/middlewares/retry/. Replays the request on transient failures:

http:
  middlewares:
    api-retry:
      retry:
        attempts: 3
        initialInterval: 100ms

Retries happen at the middleware level — the request is rebuffered and re-sent through the rest of the chain. Combined with the smart round-tripper's own retry logic in pkg/server/service/smart_roundtripper.go, retries can occur both at the HTTP middleware layer and the transport layer.

The middleware does not retry requests with non-idempotent bodies (POST without Idempotency-Key semantics) — applications must opt in by ensuring their handlers are safe.

Buffering

pkg/middlewares/buffering/. Sets max request/response body sizes and behavior when limits are crossed:

http:
  middlewares:
    buffering:
      buffering:
        maxRequestBodyBytes: 10485760
        memRequestBodyBytes: 1048576
        maxResponseBodyBytes: 10485760
        memResponseBodyBytes: 1048576
        retryExpression: 'IsNetworkError() && Attempts() < 2'

Buffering is what makes safe retries on POST possible — by buffering the request body, the middleware can replay it.

Snichek

pkg/middlewares/snicheck/. Defends against TLS↔HTTP host header mismatch attacks: returns 421 Misdirected Request if the HTTP Host header does not match the TLS SNI. Used by Gateway API routes.

Encoded characters

pkg/middlewares/encodedcharacters/. Recent addition. Controls how Traefik handles percent-encoded characters in the request path (e.g. %2F representing /). The behavior is configurable per middleware to match upstream expectations and avoid the request-smuggling class of bugs that arise when the proxy and upstream interpret encoded characters differently.

The default behavior is documented in the v3.7 migration notes — see the warning emitted by cmd/traefik/traefik.go at startup.

Capture, recovery, and observability wrappers

These are inserted by the framework, not by the user, and are covered in Observability:

• pkg/middlewares/recovery/ — panic recovery.
• pkg/middlewares/capture/ — latency/byte capture.
• pkg/middlewares/observability/ — tracing wrapper.
• pkg/middlewares/metrics/ — metrics emission.
• pkg/middlewares/accesslog/ — per-request log line.

For shaping headers, paths, and content, see Transformations.