Quick Start
Defaults are on
Both protections are active the moment you start the gateway — no configuration required.Internet-facing deployments are protected immediately. Loopback clients (
127.0.0.1, localhost, ::1) are always exempt.Tune via YAML
Override the defaults in your Missing keys inherit the defaults (
gateway.yaml under the top-level gateway: block:32 and 10). Set either key to 0 to disable that protection.How It Works
| Mechanism | Scope | Trigger | Action |
|---|---|---|---|
PreauthConnectionBudget | Per source IP | Concurrent pre-auth WS slots ≥ preauth_max_connections_per_ip | Reject upgrade with close 4029 |
UnauthorizedFloodGuard | Per connection | Unauthorized frames ≥ max_unauthorized_frames | Close connection with 4028 |
AuthRateLimiter overflow | Per IP | Key map saturated, new IP arrives | Reject closed (preserves existing lockouts) |
Loopback is always exempt. Connections from
127.0.0.1, ::1, localhost, or a gateway bound to loopback bypass the pre-auth budget entirely. Your local dev workflow is never affected.Configuration Options
| Option | Type | Default | Description |
|---|---|---|---|
preauth_max_connections_per_ip | int | 32 | Max concurrent unauthenticated WebSocket connections per source IP. 0 disables. Loopback exempt. |
max_unauthorized_frames | int | 10 | Close the connection after N unauthorized frames on a single connection. 0 disables. |
>= 0. Negative values raise ValueError at startup.
Close Codes Reference
| Code | Cause | Client action |
|---|---|---|
4008 | WS upgrade rate limit (AuthRateLimiter per-IP handshake bucket) | Back off, retry after retry_after_seconds hint |
4028 | Too many unauthorized frames on this connection | Fix scope/token. Do NOT reconnect immediately |
4029 | Per-IP pre-auth connection budget exhausted | Wait, close/reuse existing connections before retrying |
When to Change the Defaults
Behind a trusted reverse proxy (nginx, Cloudflare, WAF)
Behind a trusted reverse proxy (nginx, Cloudflare, WAF)
If your proxy already caps concurrent connections per IP and applies its own rate limiting, you can disable both guards:Only disable when the proxy is on the same trusted network and you are confident it enforces comparable limits. A misconfigured proxy with
preauth_max_connections_per_ip=0 leaves the gateway fully open to half-open socket exhaustion.Chatty exploratory clients
Chatty exploratory clients
Clients probing for available scopes before obtaining a token may exhaust their unauthorized frame budget quickly. Raise The cleaner fix is client-side: fetch a token before opening the WebSocket, not after.
max_unauthorized_frames or, better, fix the client to send a valid token on the first frame:Hardening for hostile environments
Hardening for hostile environments
Lower both values to reduce the attack surface for internet-exposed deployments facing active scanning:Test with your legitimate traffic first — values that are too low will reject real users.
Unresolvable IP Handling
When the client IP cannot be resolved (e.g., a broken reverse-proxy configuration omits theX-Forwarded-For header), all unresolvable connections are grouped into a single shared bucket keyed __unresolved__. This is fail-closed — the shared bucket still counts toward the cap, so a flood of unresolvable IPs cannot exhaust the gateway by bypassing IP-level limits.
AuthRateLimiter Overflow Hardening
Beyond the two user-tunable knobs, the underlyingAuthRateLimiter includes a defensive-in-depth overflow fix:
- When the key map is saturated (max tracked IPs reached) and a new IP arrives, the request is rejected rather than admitted — preventing a fresh-IP flood from evicting existing lockouts.
- Existing lockouts are preserved even when the map is full — a flood of new IPs cannot clear the lockout of a previously blocked attacker.
- Expired-lockout recovery: IPs already in the lockout table can clear their stale entry even when the map is saturated, preventing permanent trapping.
Best Practices
Leave the defaults on for public gateways
Leave the defaults on for public gateways
Both guards — the per-IP connection budget and the unauthorized-frame flood guard — are active by default. Don’t disable them on internet-exposed deployments; they close the pre-auth window that a naive gateway leaves open to half-open socket floods.
Understand the close codes when debugging
Understand the close codes when debugging
A client closed with 4029 hit the per-IP pre-auth connection budget; 4028 means it sent too many unauthorized frames on one connection. Treat 4029 as “too many sockets from this IP” and 4028 as “this connection misbehaved after connecting” when triaging client issues.
Tune the budget to your real client fan-out
Tune the budget to your real client fan-out
If legitimate clients behind a shared NAT trip the per-IP budget, raise it deliberately rather than turning the guard off. Size it to the maximum concurrent connections you expect from a single source IP, with headroom for reconnect storms.
Don't rely on edge guards alone
Don't rely on edge guards alone
These protections stop pre-auth abuse, not authenticated misuse. Pair them with per-identity rate limiting and authentication so an attacker who gets past the handshake still faces request-level limits.
Related
Gateway
Full gateway configuration reference
Security
Security policies and deployment hardening
Gateway Handshake Protocol
Version negotiation, capabilities, and structured connection errors
Gateway Rate Limiting
Per-identity request rate limiting with sliding-window policy

