Middleware

A3S Gateway provides 15 built-in middlewares that can be composed into ordered pipelines. Returning a response from handle_request short-circuits the pipeline.

Built-in Middlewares

JWT Authentication

Validates Authorization: Bearer tokens using HS256. Returns 401 on failure.

middlewares "auth-jwt" {
  type  = "jwt"
  value = "${JWT_SECRET}"
}

API Key Authentication

Validates a header value against an allowlist. Returns 401 on failure.

middlewares "auth-apikey" {
  type   = "api-key"
  header = "X-API-Key"
  keys   = ["key-1", "key-2", "key-3"]
}

Basic Authentication

HTTP Basic Auth. Returns 401 with WWW-Authenticate header on failure.

middlewares "auth-basic" {
  type     = "basic-auth"
  username = "admin"
  password = "secret"
}

Forward Authentication

Delegates auth to an external service. Copies specified headers from the auth response to the upstream request. Returns 401 if the auth service rejects.

middlewares "ext-auth" {
  type                          = "forward-auth"
  forward_auth_url              = "http://auth.internal:9090/verify"
  forward_auth_response_headers = ["X-User-Id", "X-User-Role"]
}

Rate Limiting (In-Memory)

Token bucket rate limiter. Returns 429 Too Many Requests when exhausted.

middlewares "rate-limit" {
  type  = "rate-limit"
  rate  = 100
  burst = 50
}

Rate Limiting (Redis)

Distributed rate limiting via Redis. Requires --features redis.

middlewares "rate-limit-distributed" {
  type      = "rate-limit-redis"
  rate      = 200
  burst     = 100
  redis_url = "redis://127.0.0.1:6379"
}

CORS

Sets CORS response headers. Handles preflight OPTIONS requests automatically.

middlewares "cors" {
  type            = "cors"
  allowed_origins = ["https://example.com", "https://app.example.com"]
  allowed_methods = ["GET", "POST", "PUT", "DELETE"]
  allowed_headers = ["Content-Type", "Authorization"]
  max_age         = 3600
}

Headers

Add or override request/response headers.

middlewares "custom-headers" {
  type = "headers"
  request_headers = {
    "X-Forwarded-Proto" = "https"
  }
  response_headers = {
    "X-Frame-Options" = "DENY"
    "Strict-Transport-Security" = "max-age=31536000"
  }
}

Strip Prefix

Removes path prefixes before forwarding to the backend.

middlewares "strip-api" {
  type     = "strip-prefix"
  prefixes = ["/api/v1", "/api/v2"]
}

Body Limit

Rejects requests exceeding the body size limit. Returns 413 Payload Too Large.

middlewares "body-limit" {
  type           = "body-limit"
  max_body_bytes = 1048576
}

Retry

Retries failed requests with a configurable interval.

middlewares "retry" {
  type              = "retry"
  max_retries       = 3
  retry_interval_ms = 500
}

Circuit Breaker

Closed → Open → HalfOpen state machine. Opens after consecutive failures, tries half-open after cooldown.

middlewares "circuit-breaker" {
  type              = "circuit-breaker"
  failure_threshold = 5
  cooldown_secs     = 30
  success_threshold = 2
}

IP Allowlist

Rejects requests from IPs not in the allowlist. Supports CIDR notation. Returns 403.

middlewares "ip-allow" {
  type        = "ip-allow"
  allowed_ips = ["192.168.1.0/24", "10.0.0.0/8"]
}

Compress

Compresses responses using brotli (preferred), gzip, or deflate based on Accept-Encoding.

middlewares "compress" {
  type = "compress"
}

TCP Filter

Connection-level filtering for TCP entrypoints: in-flight connection limit and IP allowlist. Configured via entrypoint fields:

entrypoints "tcp-db" {
  address         = "0.0.0.0:5432"
  protocol        = "tcp"
  max_connections  = 1000
  tcp_allowed_ips  = ["10.0.0.0/8", "192.168.1.0/24"]
}

Summary

Prop

Type

Middleware

On this page