Implement room membership DoS protection with per-client room limits, per-room capacity caps, total room count ceiling, and resource-pressure circuit breaker

[levoski1]

Title

Implement room membership DoS protection with per-client room limits, per-room capacity caps, total room count ceiling, and resource-pressure circuit breaker

Difficulty

10/10 — Expert. Estimated effort: 3–4 days for a senior engineer.

Context

RoomManager.join() in src/room-manager.js (lines 51–58) accepts any clientId into any roomId with no limits whatsoever. A single misbehaving client can call join_room for 100,000 different room IDs, creating 100,000 entries in _rooms and 100,000 entries in _clientRooms. Each room entry is a Map<string, WebSocket> (minimum ~100 bytes overhead per Map), and each client-room entry is a Set<string> that grows by one per join. At 100K rooms, this is ~10MB of pure overhead — and that's from a single client.

Conversely, a single room can accumulate unlimited members. A public "region-global" room could attract 50,000 clients, making every broadcast() call iterate 50,000 WebSocket objects — an O(N) event-loop-blocking operation that takes ~50ms per broadcast at 50K members (issue 4 addresses broadcast backpressure, but the root cause is the lack of room capacity limits).

The project.md describes the system as supporting "fleet tracking, asset monitoring, geofencing enforcement, and live mapping." In a real deployment, rooms correspond to fleet IDs, regions, or user groups — all of which have natural cardinality and membership bounds. The absence of these bounds makes the system trivially vulnerable to resource exhaustion.

Problem statement

Implement a multi-layered resource accounting and DoS protection system for RoomManager:

1. Per-client room limit: A single client cannot join more than maxRoomsPerClient rooms (configurable, default 50). Excess join_room attempts return { type: "error", payload: { code: "ROOM_LIMIT_EXCEEDED", message: "..." } }.
2. Per-room member limit: A single room cannot have more than maxMembersPerRoom clients (configurable, default 10,000). Excess joins return { type: "error", payload: { code: "ROOM_FULL", message: "..." } }.
3. Total room count ceiling: The RoomManager cannot hold more than maxRooms rooms (configurable, default 10,000). When the ceiling is hit, new room creation (first join to a non-existent room) is rejected with { type: "error", payload: { code: "MAX_ROOMS_REACHED", message: "..." } }.
4. Resource-pressure circuit breaker: When total memory usage of the RoomManager (estimated via roomCount × avgRoomSize + clientCount × avgClientRoomCount) exceeds a configurable threshold, the circuit breaker opens. While open, all join_room operations are rejected with { type: "error", payload: { code: "CIRCUIT_BREAKER_OPEN", message: "..." } }. The breaker closes automatically when memory pressure subsides (configurable recovery threshold).
5. Metrics exposure: RoomManager exposes stats getter returning { roomCount, clientCount, totalMembers, circuitBreakerState }.

Current behavior

src/room-manager.js join() (lines 51–58):

join(clientId, roomId, ws) {
  if (clientId == null) throw new TypeError("clientId is required");
  if (roomId == null) throw new TypeError("roomId is required");
  if (ws == null) throw new TypeError("ws is required");
  this._ensureRoom(roomId).set(clientId, ws);
  this._ensureClientRooms(clientId).add(roomId);
}

No limits. No resource accounting. No circuit breaker. A single client can join unlimited rooms, and a single room can hold unlimited members.

Required behavior

• RoomManager constructor accepts { maxRoomsPerClient, maxMembersPerRoom, maxRooms, circuitBreaker: { enabled, memoryThresholdBytes, recoveryThresholdBytes } } with sane defaults.
• join() checks all limits before adding membership and returns/throws structured error objects (not just TypeError).
• The circuit breaker uses process.memoryUsage().heapUsed to estimate memory pressure.
• All existing room-manager.test.js, room-manager-extended.test.js, room-manager-additional.test.js tests pass (they don't hit any limits with default settings).
• New tests for: limit enforcement, circuit breaker open/close transitions, metrics exposure.

Constraints

• Do not change the join(clientId, roomId, ws) method signature — callers pass the same arguments.
• join() must throw TypeError for null/undefined required args (existing behavior) AND return/throw structured errors for limit violations.
• Circuit breaker must not add per-request overhead beyond a single process.memoryUsage() call (which is ~1μs in Node.js).
• Do not add new npm dependencies.
• Do not modify server.js or any test file (except adding new test files).
• The maxMembersPerRoom limit must be enforced atomically — no TOCTOU race between checking the count and adding the member (Node.js single-threaded, so this is naturally satisfied, but the code must not yield between check and insert).

Acceptance criteria

• join("c1", "r1", ws) succeeds when client has < maxRoomsPerClient rooms
• join("c1", "r2", ws) throws/returns error when client already has maxRoomsPerClient rooms
• join("c1", "r1", ws) succeeds when room has < maxMembersPerRoom members
• join("c2", "r1", ws) throws/returns error when room already has maxMembersPerRoom members
• First join to a new room succeeds when roomCount < maxRooms
• First join to a new room fails when roomCount === maxRooms (existing room joins still work)
• Circuit breaker opens when heapUsed > memoryThresholdBytes
• Circuit breaker closes when heapUsed < recoveryThresholdBytes
• When circuit breaker is open, all join() calls are rejected
• stats getter returns { roomCount, clientCount, totalMembers, circuitBreakerState }
• All 30 existing RoomManager tests pass unchanged
• npm run lint passes

Out of scope

• Changes to server.js, auth.js, validator.js, rate-limiter.js, index.js, logger.js.
• Implementing per-room message rate limiting (that is a broadcast concern).
• Dynamic limit adjustment based on system load (static limits are sufficient for this issue).

Hints and references

• process.memoryUsage().heapUsed returns the V8 heap usage in bytes. It's fast (~1μs) but not free — call it only on join(), not on every broadcast().
• The circuit breaker pattern has three states: CLOSED (normal), OPEN (rejecting), HALF_OPEN (testing recovery). For this implementation, CLOSED and OPEN are sufficient — the breaker transitions directly from OPEN to CLOSED when memory drops below the recovery threshold.
• For maxMembersPerRoom, the check is simply room.size >= maxMembersPerRoom after _ensureRoom(roomId) — the room is guaranteed to exist at that point.
• For maxRoomsPerClient, check _clientRooms.get(clientId)?.size ?? 0 before _ensureClientRooms(clientId).add(roomId).
• For maxRooms, check _rooms.size before _ensureRoom(roomId) — but only when the room doesn't already exist: !this._rooms.has(roomId) && this._rooms.size >= maxRooms.

[comzzy-comzzy]

This aligns well with my experience building backend systems where reliability and resource management are important. My approach is to implement the safeguards in layers so each limit is enforced consistently without changing the existing API.
I'll focus on keeping the membership checks efficient, making the circuit breaker predictable under memory pressure, and exposing clear metrics that make the system easier to monitor. I'll also add comprehensive test coverage for the limit enforcement, circuit breaker transitions, and edge cases while ensuring the existing test suite continues to pass unchanged.

[salienne]

Hello there, after reviewing the issue and related code paths, I believe I can implement this feature effectively while adhering to the project's standards and conventions. Kindly assign it to me.

[mayborn005]

Hello @maintainer, I’ve gone through the requirements and I’m confident I can implement a proper solution that matches the acceptance criteria. Kindly assign this issue to me. And I will deliver at the shortest possible time.

[Chigybillionz]

Hello,

You can check out some of my previous work here:

GitHub: https://github.com/chigybillionz

I'd like to work on this issue. 💻

I noticed this is a comprehensive resilience improvement centered on preventing resource exhaustion while preserving the existing RoomManager API. I'll implement configurable limits for per-client room memberships, per-room capacity, and total room creation, along with a lightweight circuit breaker driven by process.memoryUsage().heapUsed. I'll expose the requested runtime metrics, ensure limit checks remain atomic within the existing flow, return clear structured errors for resource-limit violations while preserving the current TypeError behavior for invalid arguments, and add thorough test coverage for all new scenarios without breaking the existing RoomManager test suite. ✅

Feel free to review my GitHub profile to see the projects and contributions I've worked on. Looking forward to shipping this improvement. 🚀

[kimanicode]

Hi, I'd like to take this issue. I'll add per-client and per-room limits, a total room ceiling, and a two-state (CLOSED/OPEN) circuit breaker based on process.memoryUsage().heapUsed to RoomManager.join(), keeping the existing signature and TypeError behavior while returning structured errors for limit violations, plus a stats getter. I'll add tests for limit enforcement, breaker transitions, and metrics, making sure all 30 existing tests and lint still pass. Please assign it to me, thanks.

[queentiffany1111-cloud]

Application for Issue #198: Implement room membership DoS protection with per-client room limits, per-room capacity caps, total room count ceiling, and resource-pressure circuit breaker

---

Motivation & Cultural Fit

Unbounded in-memory collections are one of the fastest paths to heap exhaustion and severe event-loop lag in high-concurrency Node.js real-time services. In a spatial tracking gateway handling active fleets and geofences, a single unconstrained client joining 100K rooms or a massive room iteration during broadcast creates catastrophic DoS vectors.

With 2 years of systems-level experience in Rust and low-latency systems programming, I approach memory allocation, collection bounds, and resource lifecycle management with extreme rigor. I want to implement a zero-dependency, atomic, and mathematically predictable DoS protection layer in RoomManager that protects the heap and keeps event-loop microtask queues running fast under extreme pressure.

Technical Competence & Relevant Experience

• Systems Memory & Resource Accounting: My background in systems engineering (Rust) gives me an instinct for static memory bounding, object overhead tracking, and state-machine design. I treat JS Map and Set operations not just as high-level data structures, but as real V8 heap allocations that need explicit ceiling guards and $O(1)$ limit validation.
• Deterministic Circuit Breakers: I have designed reactive circuit breaker patterns that sample process telemetry (process.memoryUsage().heapUsed) with zero-copy overhead. I understand how to handle hysteresis (differencing memoryThresholdBytes and recoveryThresholdBytes) to prevent rapid state flickering at edge thresholds.
• Zero-Overhead & Strict Spec Adherence: I write ultra-clean JS/TS that introduces zero new npm dependencies, maintains 100% backwards compatibility with existing method signatures, and guarantees $O(1)$ atomic check-and-set semantics without yielding the V8 event loop.

---

My Proposed Execution Plan

I will implement the complete multi-layered DoS protection system inside src/room-manager.js and deliver a dedicated, comprehensive test suite that satisfies all acceptance criteria:

1. Configurable Multi-Layered Boundary Engine

• Constructor Configuration: Expand RoomManager constructor to take optional bounds overrides with production-sane defaults (maxRoomsPerClient: 50, maxMembersPerRoom: 10000, maxRooms: 10000, and circuit breaker parameters).
• Atomic Order of Checks: In join(clientId, roomId, ws), preserve the initial TypeError assertions, followed immediately by atomic, non-yielding validation steps:

1. Circuit Breaker Check: Sample process.memoryUsage().heapUsed. Transition state to OPEN if threshold exceeded, or back to CLOSED if below recovery threshold. Reject immediately if OPEN (CIRCUIT_BREAKER_OPEN).
2. Room Count Ceiling: Check !this._rooms.has(roomId) && this._rooms.size >= maxRooms (MAX_ROOMS_REACHED).
3. Client Limits: Check _clientRooms.get(clientId)?.size >= maxRoomsPerClient (ROOM_LIMIT_EXCEEDED).
4. Room Capacity: Check _rooms.get(roomId)?.size >= maxMembersPerRoom (ROOM_FULL).

• Structured Error Model: Ensure all limit rejections throw/return structured error payloads carrying exact error codes without changing the join() signature.

2. Memory Telemetry & Metrics Exposure

• Hysteresis Circuit Breaker: Implement smooth state transitions between CLOSED and OPEN based on memoryThresholdBytes and recoveryThresholdBytes, ensuring the V8 heap check stays within the ~1µs budget per join() call.
• Telemetry Getter: Add an efficient stats getter returning real-time aggregates: { roomCount, clientCount, totalMembers, circuitBreakerState }.

3. Comprehensive Unit Testing & Regression Protection

• Existing Suite Validation: Verify all 30 existing tests in room-manager.test.js, room-manager-extended.test.js, and room-manager-additional.test.js pass cleanly without modifications.
• New Suite (test/room-manager-dos.test.js): Add focused tests for:
• Client room capacity overflow & structured error verification.
• Room member ceiling enforcement.
• Total room count ceiling on new room creation (while allowing existing rooms to accept members).
• Mocked memory pressure triggering circuit breaker OPEN/CLOSED state transitions.
• Accuracy of stats metrics under continuous join/leave activity.

I am ready to jump in immediately, deliver clean and fully tested code, and make RoomManager completely immune to memory exhaustion!

[grantfox-oss]

🦊 GrantFox — @queentiffany1111-cloud has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #198)
2. Your PR will be reviewed by the RiftCore00 maintainers

Good luck! Track your progress on GrantFox.