Skip to content

fix(ratelimit): limit pad messages per connection with a burst allowance - #8498

Merged
JohnMcLear merged 3 commits into
developfrom
fix/commit-rate-limit-per-connection
Nov 17, 2026
Merged

JohnMcLear merged 3 commits into
developfrom
fix/commit-rate-limit-per-connection

Conversation

@JohnMcLear

@JohnMcLear JohnMcLear commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

commitRateLimiting gave each IP 10 messages per second. On instances behind a TCP proxy or NAT, every browser has the same IP. The Home Assistant add-on is one example: it uses a socat front-man, so X-Forwarded-For doesn't help. A few tabs on one pad used up the shared budget and got {disconnect: 'rateLimited'}. They rejoined, and each rejoin burst kicked the other tabs, in a loop. The over-limit messages were dropped, chat included.

A single client can also trip the limit alone. I measured a 3-tab pad with ep_webrtc in production mode. Core sends only CLIENT_READY on join. For each peer pair, ep_webrtc sends a hangup, an invite, a description and one message per ICE candidate. When the second tab joined, 14 messages arrived within 150 ms, and the limiter fired.

Change

  • The limiter is now keyed on the socket.io connection instead of the IP. Tabs, NAT users and proxied clients no longer share a budget.
  • A burst budget sits on top of the steady rate: burstPoints/burstDuration, default 50 extra messages per 10 s. It uses rate-limiter-flexible's BurstyRateLimiter. The steady rate stays at points/duration (10/s).
  • A connection that floods still drains both budgets and is disconnected, as before.
  • The burst budget refills, so the highest rate a connection can sustain is now about 15/s (10 + 50/10) instead of 10/s. src/tests/ratelimit/testlimits.sh now floods at 20/s (50 ms) rather than 99 ms.
  • Any other options in commitRateLimiting, such as blockDuration, still apply to the steady limiter.

Trade-off

There is no longer a per-IP cap. One IP can open several connections and get several budgets. Opening a connection was never limited, though, and per-IP limiting was already weak against IPv6 or multiple IPs. A per-IP cap also cannot tell users behind a shared IP apart, which is the bug being fixed. If you need per-IP connection caps, set them at the reverse proxy. This keeps the original anti-abuse goal: one connection can't flood the pad.

Plugin-side fix for the WebRTC burst: ether/ep_webrtc#316 (batches ICE candidates).

Tests

src/tests/backend/specs/commitRateLimiting.ts turns the limiter on with the shipped defaults. Three of its cases fail on develop:

  • 4 sockets from one IP join and chat;
  • a single-client 20-message join burst;
  • a flooder must not limit a neighbour on the same IP.

A fourth case checks that a flood is still disconnected.

I also checked by hand with 4 headless Chromium tabs running ep_webrtc against a production-mode server: zero rate-limit events. The settings template and the docs (doc/configuration.md, doc/privacy.md) are updated. settings.json.docker is left as is, and the new keys fall back to the defaults.

🤖 Generated with Claude Code

https://claude.ai/code/session_01TcYAoDMav4BPPE9JrMtSvw

commitRateLimiting was keyed on the client IP at 10 messages/second. Behind
a TCP proxy or NAT every client shares that budget, and a single WebRTC
join (one message per ICE candidate per peer) can exceed it alone. The
over-limit client is disconnected, rejoins, and the rejoin burst kicks the
other tabs in a loop.

Key the limiter on the socket.io connection and add a burst budget
(burstPoints/burstDuration, default 50 per 10s) on top of the steady
points/duration rate. Sustained flooding still disconnects.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TcYAoDMav4BPPE9JrMtSvw
@qodo-code-review

Copy link
Copy Markdown

ⓘ Qodo reviews are paused because the subscription is no longer active. Ask your workspace admin to reactivate the subscription to resume reviews. Manage billing

@qodo-free-for-open-source-projects

Copy link
Copy Markdown

PR Summary by Qodo

Limit pad messages per connection with burst allowance

🐞 Bug fix ✨ Enhancement 🧪 Tests 📝 Documentation ⚙️ Configuration changes 🕐 20-40 Minutes

Grey Divider

AI Description

• Give each socket connection its own message budget so clients behind shared IPs cannot limit each
 other.
• Allow short message bursts while retaining disconnection for sustained flooding.
• Document the new defaults and test shared-IP joins, bursts, and flooding.
Diagram

graph TD
  C["Socket messages"] --> H["Pad handler"] --> L["Bursty limiter"] --> S{"Steady available?"}
  S -->|no| B{"Burst available?"} -->|no| D["Rate-limit disconnect"]
  S -->|yes| P["Process message"]
  B -->|yes| P
Loading
High-Level Assessment

The following are alternative approaches to this PR:

1. Retain a layered per-IP cap
  • ➕ Preserves an aggregate limit on connections from one IP.
  • ➖ Can still penalize unrelated users behind NAT or a TCP proxy, the failure this PR addresses.
2. Raise the per-connection steady limit
  • ➕ Uses a single budget and simpler configuration.
  • ➖ Permits a higher sustained message rate to accommodate brief join spikes.

Recommendation: Use the PR's per-connection steady and burst budgets: they isolate shared-IP users without making short joins consume a sustained-flood allowance. If an aggregate IP connection cap is required, enforce it separately at the reverse proxy.

Files changed (6) +191 / -19

Bug fix (1) +21 / -8
PadMessageHandler.tsApply steady and burst limits per socket connection +21/-8

Apply steady and burst limits per socket connection

• Replaces the IP-keyed memory limiter with a BurstyRateLimiter keyed by socket ID. Retains the rate-limit response and adds connection context to warnings; omitted burst settings fall back to defaults.

src/node/handler/PadMessageHandler.ts

Tests (1) +116 / -0
commitRateLimiting.tsCover shared-IP isolation and burst behavior +116/-0

Cover shared-IP isolation and burst behavior

• Adds production-mode socket tests for multiple tabs sharing an IP, a single-client burst, flood rejection, and isolation of a neighboring client. Tests also check that permitted chat messages are stored.

src/tests/backend/specs/commitRateLimiting.ts

Documentation (2) +28 / -4
configuration.mdDocument per-connection pad message budgets +24/-0

Document per-connection pad message budgets

• Adds the steady and burst settings, their defaults, and the rate-limited disconnect behavior. Clarifies that tabs behind one IP have separate budgets.

doc/configuration.md

privacy.mdCorrect the rate-limiter state description +4/-4

Correct the rate-limiter state description

• States that in-memory limiter state is keyed by socket.io connection ID rather than client IP.

doc/privacy.md

Other (2) +26 / -7
settings.json.templateExpose burst settings in the configuration template +14/-4

Expose burst settings in the configuration template

• Adds burstDuration and burstPoints with 10-second and 50-message defaults. Revises comments to describe per-connection message limits and disconnection.

settings.json.template

Settings.tsDefine burst defaults and settings types +12/-3

Define burst defaults and settings types

• Adds optional burst setting fields to the type and supplies 50 messages per 10 seconds as runtime defaults. Updates comments to reflect per-connection behavior.

src/node/utils/Settings.ts

@qodo-free-for-open-source-projects

qodo-free-for-open-source-projects Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

Grey Divider


Remediation recommended

1. Custom rate limits silently stop applying ✓ Resolved
Description
socketio() now forwards only duration and points to the steady limiter, discarding other
configured rate-limiter options such as blockDuration. Deployments that use those options retain
them in settings.commitRateLimiting, but the new limiter construction no longer applies them.

Grey Divider

Tip of the day
💡 Did you know, you can enable the Remediation agent and Qodo fixes findings in a dedicated fix PR

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

Grey Divider

Qodo Logo

@JohnMcLear

JohnMcLear commented Nov 17, 2026 •

Copy link
Copy Markdown
Member Author

Addressed the Qodo finding in b81a8c5: the burst keys are destructured out and the rest of commitRateLimiting (e.g. blockDuration) goes to the steady limiter unchanged.

With the burst allowance a connection can sustain up to ~15/s, so 99 ms
spacing no longer trips the limiter. Document the effective ceiling.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TcYAoDMav4BPPE9JrMtSvw
@JohnMcLear
JohnMcLear merged commit 3d757ac into develop Nov 17, 2026
42 checks passed
@JohnMcLear
JohnMcLear deleted the fix/commit-rate-limit-per-connection branch November 17, 2026 15:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant