Gateway Edge Protections

Per-IP connection budget and unauthorized-frame flood guard for internet-exposed gateway deployments

Two built-in guards protect publicly exposed gateways: a per-IP connection budget that caps half-open sockets before authentication, and a per-connection flood guard that closes connections sending too many unauthorized frames.

Quick Start

1. Defaults are on

   Both protections are active the moment you start the gateway — no configuration required.

   praisonai serve gateway

   from praisonaiagents import GatewayConfig
   
   config = GatewayConfig(
       preauth_max_connections_per_ip=32,   # default
       max_unauthorized_frames=10,          # default
   )

   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 gateway.yaml under the top-level gateway: block:

   gateway:
     preauth_max_connections_per_ip: 64   # raise for shared-egress IPs
     max_unauthorized_frames: 20          # raise for exploratory clients

   Missing keys inherit the defaults (32 and 10). Set either key to 0 to disable that protection.

3. Tune via Python

   Pass the values directly to GatewayConfig:

   from praisonaiagents import Agent, GatewayConfig
   
   agent = Agent(
       name="PublicGatewayAgent",
       instructions="Handle public requests securely.",
       gateway=GatewayConfig(
           preauth_max_connections_per_ip=64,
           max_unauthorized_frames=20,
       )
   )

How It Works

Configuration Options

Validation: Both values must be >= 0. Negative values raise ValueError at startup.

# 0 disables the protection — use when your edge proxy already handles this
from praisonaiagents import GatewayConfig

config = GatewayConfig(
    preauth_max_connections_per_ip=0,   # disabled — trust upstream proxy
    max_unauthorized_frames=0,          # disabled — trust upstream proxy
)

Close Codes Reference

Minimal correct reconnect handler:

import asyncio
import websockets

CLOSE_CODE_UNAUTHORIZED_FLOOD = 4028
CLOSE_CODE_PREAUTH_BUDGET = 4029

async def connect_with_backoff(uri, agent_id, token):
    backoff = 1.0
    auth_uri = f"{uri}?token={token}" if token else uri
    while True:
        try:
            async with websockets.connect(auth_uri) as ws:
                backoff = 1.0
                await ws.send(f'{{"type":"hello","agent_id":"{agent_id}"}}')
                async for message in ws:
                    handle(message)
        except websockets.exceptions.ConnectionClosed as e:
            if e.code == CLOSE_CODE_UNAUTHORIZED_FLOOD:
                print("Unauthorized frame flood (4028): fix token before retrying")
                await asyncio.sleep(backoff * 10)
            elif e.code == CLOSE_CODE_PREAUTH_BUDGET:
                print(f"Pre-auth budget (4029): backing off {backoff}s")
                await asyncio.sleep(backoff)
                backoff = min(backoff * 2, 60)
            else:
                await asyncio.sleep(backoff)
                backoff = min(backoff * 2, 60)
        except (websockets.exceptions.WebSocketException, OSError) as e:
            print(f"Connection failed ({e}): backing off {backoff}s")
            await asyncio.sleep(backoff)
            backoff = min(backoff * 2, 60)

def handle(message):
    print("Received:", message)

When to Change the Defaults

gateway:
  trusted_proxies:
    - 10.0.0.0/8   # the CIDR of your reverse proxy

gateway:
  preauth_max_connections_per_ip: 0   # proxy handles this
  max_unauthorized_frames: 0          # proxy handles this

gateway:
  preauth_max_connections_per_ip: 128   # office of ~40 people, peak 3 tabs each

gateway:
  max_unauthorized_frames: 30   # generous budget for scope discovery

gateway:
  preauth_max_connections_per_ip: 8   # strict: 8 concurrent pre-auth slots
  max_unauthorized_frames: 3          # strict: close on 3rd unauthorized frame

Unresolvable IP Handling

When the client IP is literally missing (e.g., a broken reverse-proxy configuration omits the X-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.

This __unresolved__ bucket applies only when the source IP is absent — it is not how trusted-proxy resolution works. To resolve the real client behind a declared proxy (rather than bucketing on the proxy peer), set gateway.trusted_proxies. See Trusted Proxies.

AuthRateLimiter Overflow Hardening

Beyond the two user-tunable knobs, the underlying AuthRateLimiter 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.

This is not a user-tunable knob. It is active by default on all gateway deployments.

Best Practices

Related