fix: WebSocket connection-manager concurrency + proxy-aware rate limiting

[williaby]

Summary

Tier 2 of the architecture review. Stacked on #61 — base is the PR #61 branch, so this diff shows only the tier-2 changes. Rebase/retarget to main once #61 merges.

C3 — WebSocket ConnectionManager concurrency safety

The previous manager had two real races when a broadcast overlapped a connect/disconnect on the same batch:

• "Set changed size during iteration" — broadcast() iterated the live connection set while await-ing each send_json; a concurrent disconnect mutating that set raised mid-iteration. Now it iterates a snapshot (list(...)).
• Key resurrection — cleanup used defaultdict access (self._connections[key].discard(...)), which recreated a batch key that a concurrent disconnect had just emptied and removed, leaking entries. Switched to a plain dict with non-resurrecting cleanup (.get/.pop) in both broadcast and disconnect.

Rationale for not adding an asyncio.Lock: under CPython's single-threaded event loop, connect/disconnect mutations are synchronous (atomic w.r.t. other coroutines); the only interleaving point is the awaited sends in broadcast, which the snapshot + non-resurrecting cleanup fully cover. A lock would force disconnect to become async (rippling into the router and tests) for no additional correctness here.

H6 — proxy-aware rate limiting

Behind Cloudflare, request.client.host is the proxy IP, so per-IP rate limiting effectively keyed every request on one IP. RateLimitMiddleware can now resolve the client IP from a configured header:

• New settings rate_limit_trust_proxy (default off) and rate_limit_client_ip_header (default CF-Connecting-IP).
• Default off is deliberate: the header is only trusted when behind a proxy that overwrites it; otherwise a client could spoof it to evade limits. When off, behavior is unchanged (request.client.host).
• Comma-separated forwarding headers (e.g. X-Forwarded-For) use the first (originating) entry.

Verification

Gate	Result
Tests	456 passed, 1 skipped (+8 new)
Coverage	92.16% (gate: 80%)
ruff check + format	clean
basedpyright	0 errors

New tests: broadcast tolerates concurrent disconnect; broadcast doesn't resurrect a removed batch; proxy IP resolution (trusted/untrusted/missing-header/forwarded-list/no-client) + an integration test proving distinct CF-Connecting-IP values are limited independently.

Test plan

• uv run pytest — 456 passed, 1 skipped
• uv run ruff check . / ruff format --check
• uv run basedpyright src/ — 0 errors
• Coverage ≥ 80% (actual 92.16%)

https://claude.ai/code/session_01PA6dtgMhfzSe22VVtqBfxE

---

Generated by Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

🗂️ Base branches to auto review (3)

• main
• master
• develop

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 1c50f07b-915d-4e91-b3d1-8b73f2a0fe72

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/tier-2-concurrency

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

This PR targets tier-2 reliability/security improvements: safer WebSocket batch connection bookkeeping during concurrent disconnects, and configurable proxy-aware IP selection for rate limiting.

Changes:

• Replaces ConnectionManager’s defaultdict with a plain dict and snapshot-based broadcast iteration.
• Adds proxy header configuration for rate-limit client IP resolution.
• Adds regression/unit tests for WebSocket races and proxy-aware rate limiting.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/rag_processor/websocket/connection_manager.py	Makes connection cleanup non-resurrecting and broadcast iteration mutation-safe.
src/rag_processor/middleware/security.py	Adds trusted proxy header support to rate-limit key selection and wires it through security config.
src/rag_processor/core/config.py	Adds settings for proxy-aware rate limiting.
src/rag_processor/main.py	Passes new rate-limit proxy settings into middleware configuration.
tests/unit/test_websocket.py	Adds regression coverage for broadcast/disconnect races and updates direct connection setup.
tests/unit/test_middleware_security.py	Adds tests for proxy header IP resolution and independent forwarded-IP rate limiting.