Middleware
There is no top-level middleware: array in Octopus. The root configuration object has no
such field, so a middleware: list at the top level is silently ignored. Middleware behavior is
configured through typed fields and the plugin system, described below. (Some older
example files show a middleware: array — disregard it.)
How the request pipeline is built01
When the gateway starts it assembles a global middleware chain. Only two middleware are added to that global chain, and only when enabled:
Compression — added when
gateway.compression.enabledis true (the default).Auth gateway — added when any
auth_providersare defined orauth.global_enforceis true. This single middleware performs authentication and authorization for every request, honoring the per-route auth fields.
Everything else is configured declaratively on the objects it applies to (the gateway, a route, or an upstream) or supplied through plugins.
Where each behavior lives02
| Behavior | Where it is configured |
| Compression | gateway.compression — see Gateway. |
| Authentication | auth_providers + auth (global), plus per-route auth_provider / skip_auth — see Auth. |
| Authorization | auth.authz (global), plus per-route require_roles / require_scopes / authz_rule — see Auth. |
| CORS | Global cors, plus per-route routes[].cors — see Auth and Routes. |
| Rate limiting | Per-route routes[].rate_limit — see Routes. |
| Request timeout | gateway.request_timeout, overridable per route via routes[].timeout — see Gateway and Routes. |
| Body size limit | gateway.max_body_size — see Gateway. |
| TLS / mTLS termination | gateway.tls — see TLS. |
| Health checks / circuit breaking | Per-upstream health_check / circuit_breaker — see Upstreams. |
| Everything else | The plugins array — see below. |
Available middleware implementations03
The octopus-middleware crate ships many more middleware than the two wired into the global chain.
These are exposed through the typed fields above and through the plugin system — not through a
free-form list. They include: compression, an auth gateway, forward auth, JWT, CORS, rate limiting,
circuit breaker, retry, timeout, request/connection limits, IP filtering, a WAF, bot detection,
security headers, header and body transforms, request ID injection, request deduplication, response
caching, redirects, canary routing, and audit logging.
See the Middleware section for conceptual coverage of each.
Plugins04
The plugins array attaches plugin instances to the gateway. Plugins are the extension point for
middleware not covered by the typed fields.
plugins:
- name: request-id
plugin_type: static
enabled: true
priority: 100
config:
header: X-Request-Id| Key | Type | Default | Description |
name | string | — | Plugin name. Required. |
plugin_type | string | static | Plugin type: static or dynamic. |
enabled | boolean | true | Whether the plugin is active. |
priority | integer | 0 | Execution priority — higher runs first. |
config | map of string→value | {} | Plugin-specific configuration (arbitrary JSON values). |
See Plugins for authoring and loading plugins.