Rate limiting
A route's routes[].rate_limit block is enforced: when any route declares a limit, the gateway
adds a route-aware limiter (RouteRateLimiter) to the request chain. The crate also ships a
full-featured token-bucket limiter (octopus_middleware::RateLimit) and a distributed variant for
embedded/library use.
routes[].rate_limit is enforced. The route-aware limiter applies a fixed window per route
— keyed by the route's path pattern, so all requests matching a route (including wildcard paths)
share one window — and returns 429 Too Many Requests when the window is exceeded. The counter is
currently held in an in-process state store (per replica); a shared backend (e.g. Redis) for
cross-replica limits is planned.
Not yet enforced: identity-based limiting (the auth gateway sets an AuthRateLimitKey, but nothing
consumes it) and per-API-key rate_limit on auth_providers entries.
routes[].rate_limit01
| Key | Type | Default | Description |
requests_per_window | int | (required) | Requests allowed per window for the route |
window_size | duration | (required) | Window length (e.g. 1s, 1m) |
routes:
- path: /api/*
upstream: backend
methods: [GET, POST]
rate_limit:
requests_per_window: 100
window_size: 1mDurations use humantime syntax (1s, 500ms, 1m, 1h). On the 429 response the limiter sets
Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining: 0, and X-RateLimit-Reset.
The builder-only token-bucket limiter02
octopus_middleware::RateLimit (built on the governor library) is a richer limiter available for
embedded/library use via the builder — it is
not wired into the gateway binary. It supports:
Strategies
| Strategy | Behavior |
| Token bucket (default) | Allows bursts up to the quota, refilled over the window |
| Fixed window | Simple per-window counter |
Key extractors
| Extractor | Key source |
| Global (default) | A single shared limiter for all traffic |
| IP | Client IP address |
| Header | A configured header (e.g. an API-key header) |
| Path | The request path |
| Identity | The AuthRateLimitKey set by the auth gateway (user:<id>) |
It also supports a map of per-path limits with independent quotas.
Distributed variant
With the crate's distributed feature, DistributedRateLimit backs a single limit with shared
state (octopus-state) so it holds across replicas. The route-aware RouteRateLimiter that enforces
routes[].rate_limit uses the same state abstraction (with an in-process backend today).
Related03
Routes — where
routes[].rate_limitlives.State — the store behind shared rate-limit counters.
Middleware overview — the request-chain order and wiring status.