Middleware Overview

A3S Gateway middleware puts authentication, rate limiting, circuit breaking, retries, request rewriting, response rewriting, and network access control into a declarative request path.

A3S Gateway ships 15 built-in middleware capabilities:

• 14 HTTP pipeline middlewares, defined as middlewares "<name>" { type = "..." } and referenced from a router's middlewares = [...] list.
• 1 TCP connection filter, tcp-filter, configured directly on TCP entrypoints. It is not a valid HTTP middleware type.

Execution Model

HTTP middlewares run in router-list order before the backend request and in reverse order before the response returns to the client. Any middleware can short-circuit the chain, for example with 401, 429, or 503.

routers "api" {
  rule        = "Host(`api.example.com`) && PathPrefix(`/v1`)"
  service     = "api-backend"
  middlewares = ["ip-allow", "auth-jwt", "rate-limit", "strip-api"]
}

That request runs as ip-allow -> auth-jwt -> rate-limit -> strip-api; response hooks run in the opposite order.

Configuration Blocks

Each HTTP pipeline middleware is a named block. The name is referenced by routers; type selects the implementation.

middlewares "<name>" {
  type = "<middleware-type>"
  # ...type-specific keys...
}

Configuration files must use the .acl extension. Every block requires type; unknown types fail loading with Unknown middleware type. Required-key validation is strict: missing or invalid values abort loading rather than being silently skipped.

Chapter Map

Authentication

• API Key: header-based API key allowlist.
• Basic Auth: HTTP Basic username/password.
• JWT: HS256 HMAC JWT validation and x-jwt-subject injection.
• Forward Auth: delegate auth to an external service.

Traffic Control

• Rate Limit: in-process token bucket.
• Redis Rate Limit: distributed token bucket across gateway replicas.
• Circuit Breaker: Closed / Open / HalfOpen state machine.
• Retry: inject retry policy headers for the proxy layer.
• Body Limit: cap request body size.

Transform

• CORS: preflight handling and CORS response headers.
• Headers: request/response header insertion and overwrite.
• Strip Prefix: path prefix stripping with a single-segment wildcard.
• Compress: mark responses eligible for proxy-layer compression.

Network

• IP Allow: client IP / CIDR allowlist.
• TCP Filter: TCP entrypoint connection limit and IP filtering.

Supported type Values

type can be api-key, basic-auth, jwt, forward-auth, rate-limit, rate-limit-redis, circuit-breaker, retry, body-limit, cors, headers, strip-prefix, compress, or ip-allow.

tcp-filter is not a valid HTTP type; configure it on TCP entrypoints with max_connections and tcp_allowed_ips.

Quick Reference