`rate_limiting`¶

The rate_limiting section enables a simple in-memory token-bucket limiter for inbound requests.

Fields¶

Field	Type	Default	Notes
`enabled`	bool	`false`	master switch
`requests_per_minute`	integer	`60`	steady-state budget
`burst_size`	integer	`10`	short burst allowance

Example¶

rate_limiting:
  enabled: true
  requests_per_minute: 120
  burst_size: 20

How keys are derived¶

The limiter prefers request identity in this order:

authenticated subject from inbound auth context (when security.provider: api_key is enabled and validated)
the direct socket peer address captured before any forwarded-IP middleware runs

Raw Authorization, X-API-Key, X-Forwarded-For, and X-Real-IP values are not accepted as limiter identities. A client cannot create a fresh bucket merely by changing an unverified credential or forwarded-address header.

That keeps rate limiting useful both with and without gateway-level inbound auth. If a trusted reverse proxy fronts the gateway, unauthenticated traffic is grouped by the proxy's socket address; enable inbound authentication when you need per-client buckets through that proxy.

Response headers¶

When the limiter is enabled, LunarGate reports the configured per-minute limit and the number of complete requests currently available in X-RateLimit-Limit and X-RateLimit-Remaining. Fractional tokens are rounded down, so the remaining count never promises a request that the bucket cannot yet satisfy.

A rejected request also includes Retry-After, rounded up to the next whole second in which one token becomes available (with a minimum of one second).

Practical guidance¶

Treat this as gateway-local protection, not distributed global rate limiting.
If you run multiple gateway replicas, each instance keeps its own in-memory limiter state.
Use conservative values first, then tune from live traffic.

rate_limiting¶