| name | websocket-rate-limit-design |
| description | Design WebSocket rate limits: connection/upgrade budgets, concurrent sockets, per-message and byte/frame caps, subscription fan-out, close/backpressure signals, and abuse-resistant keying. Use when WebSocket rate limit design, WS throttle, socket quota, message RPS, concurrent connection limit, upgrade flood, subscription cost, or realtime abuse protection for owned systems.
|
WebSocket Rate Limit Design
Design fair, abuse-resistant WebSocket throttling: upgrade rate, concurrent
sockets, inbound/outbound message and byte budgets, subscription fan-out cost,
and clear client signals. Prefer the repo’s gateway, mesh, or WS framework
limiters over a second ad-hoc counter layer. Pure HTTP REST quotas →
api-rate-limit-design. In-process queue pressure → backpressure-patterns.
Scope And Authorization
- Design/implement on systems you own or are contracted to change — not to
exhaust third-party realtime endpoints.
- Adversarial keying (header trust, multi-egress, path aliases) →
rate-limit-bypass-testing under explicit authorization only.
- Prefer staging/synthetic clients for soak tests; avoid volumes that degrade
shared production fan-out. Redact tokens and user ids in samples.
- Auth-sensitive actions over WS (login, OTP) need dual keys and progressive
delay — never pure per-IP soft limits only.
When To Use
- Limits for upgrade rate, concurrent connections, message RPS,
frame/message size, and subscribe/publish cost
- Multi-tier realtime quotas (anonymous / free / paid / partner)
- Close codes, app error frames, and client retry after throttle
- Enforcement placement (edge L7, proxy, accept loop, room fan-out)
- Mentions: WebSocket rate limit, WS throttle, socket quota, message flood,
connection storm, subscription limit, realtime abuse, concurrent WS
Do not use as primary for:
| Need | Skill instead |
|---|
HTTP REST / API 429 product design | api-rate-limit-design |
| Auth/origin/CSWSH and WS security testing | websocket-security |
| Binary codecs / schema recovery | websocket-binary-reverse-engineering |
| Bounded buffers, slow consumer, overflow | backpressure-patterns |
| Authorized bypass / key-split testing | rate-limit-bypass-testing |
| Account hard lock after auth fails | account-lockout-design |
| Implementation quality baseline | code-quality-standards |
Repo Config First
Repo gateways, proxies, and existing WS stacks outrank defaults below.
- Existing enforcers: nginx/Envoy connection limits, gateway WS policies,
framework middleware, Redis counters, max room subscribers — configure first
- Identity after upgrade: user, org, API key, device bound to the socket
- Trusted client IP: LB/edge hop only; never sole key on client
X-Forwarded-For
- Protocol surface: text vs binary, subprotocols, existing max frame size
- Auth on upgrade: cookie/JWT/query ticket ADRs — align quotas with threat model
- Observability: connect/reject, messages/s, close codes, fan-out lag metrics
- Config/flags: dynamic per-plan concurrent and message budgets
Precedence: Follow the repo. Flag IP-only limits on authenticated sockets,
unlimited inbound frames, silent drops of critical events, or duplicate limiters
without one documented budget.
Workflow
-
Inventory surfaces and abuse cases.
| Surface | Abuse if unlimited | Suggested keying (start) |
|---|
| HTTP upgrade | Connection storm / FD exhaustion | Trusted IP + user/API key |
| Concurrent sockets | Resource hog / multi-tab abuse | User or device (+ IP ceiling) |
| Inbound app messages | Parse/CPU flood, command spam | Socket + user + message type |
| Large frames / blobs | Memory DoS | Global max frame + per-user bytes/s |
| Subscribe / join room | Fan-out amplification | User + room count + members |
| Server push / broadcast | Cost / noisy neighbor | Publisher + tenant + cost units |
| Auth actions over WS | Stuffing / OTP grind | Normalized account and IP |
-
Layer limits (compose; none alone is enough).
- L1 Admit: upgrades/min per IP and identity; max handshake size
- L2 Concurrency: max sockets per user/device/org; optional process cap
- L3 Message rate: token bucket per socket and user; separate ping vs costly ops
- L4 Payload: max message bytes, frames/s, decompression bomb caps
- L5 Business cost: subscribe count, broadcast weight, stream tokens as units
-
Algorithm and store. Token bucket for message rate; lease on open / release on
close for concurrency; cost weights for variable fan-out. Atomic distributed
counters; document fail-open vs fail-closed if the store is down.
-
Signal clients (no silent blackhole for first-party APIs).
- App error frame: stable
code (e.g. rate_limit_exceeded), retry_after_seconds
- Or documented close (e.g. 1008 / custom app code); reason without secrets
- After limit: pause reads or reject messages; queue pressure →
backpressure-patterns
- Clients honor backoff (
retry-backoff-patterns); reconnect storms need L1+L2
Routing
| Situation | Primary | Helper |
|---|
| WS connect, concurrent, message, byte, fan-out budgets | This skill | — |
HTTP REST quotas, 429 headers, plan tiers | api-rate-limit-design | this for sockets |
| Origin/auth/CSWSH, ticket leakage, WS security tests | websocket-security | this for quotas |
| Bounded buffers, slow consumer, overflow | backpressure-patterns | this for admit caps |
| Authorized bypass / multi-egress / header trust | rate-limit-bypass-testing | this for policy |
| Auth hard lockout (not soft WS QPS) | account-lockout-design | this for msg caps |
| Binary schema / codec RE | websocket-binary-reverse-engineering | — |
| Implement limiters, counters, tests, logs | code-quality-standards | always |
Keep this skill primary for WS-specific budgets. Use api-rate-limit-design
for pure HTTP; backpressure-patterns for internal queue depth;
rate-limit-bypass-testing when proving keys expand — feed findings back here.
Output Checklist
