Quick Start
1
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.2
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.3
Tune via Python
Pass the values directly to
GatewayConfig:How It Works
Loopback is always exempt. Connections from any semantic loopback address (
127.0.0.0/8, ::1, localhost), or a gateway bound to loopback, bypass the pre-auth budget entirely. Your local dev workflow is never affected.Configuration Options
Validation: Both values must be
>= 0. Negative values raise ValueError at startup.
Close Codes Reference
Minimal correct reconnect handler:
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

