Fix rate limiting: key off X-Forwarded-For, not the proxy peer address

Live-tested against the deployed HF Space right after the previous
merge: fired 25 rapid requests against a 20/60s limit and every single
one returned 200. Root cause: the Space is only reachable through
Hugging Face's own reverse proxy, so request.client.host (what the
rate limiter was keying on) is the proxy's own connecting address, not
the real caller - so requests either share one wrong bucket or never
accumulate against a consistent key at all.

This is also why the mocked integration tests never caught it:
Starlette's TestClient always presents a fixed synthetic peer address,
so it could validate the RateLimiter's own logic (already covered)
but not this deployment-specific IP-detection gap.

Fix: app/main.py now derives the client key via a new get_client_ip()
helper that prefers X-Forwarded-For's left-most entry - trustworthy
here since the container has no other ingress path. Added a
TDD-first regression test (test_rate_limit_keys_on_x_forwarded_for_not_the_proxy_peer)
that reproduces the bug against a fixed TestClient peer and proves
distinct forwarded clients are tracked independently.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0184VjamhUurkWmPhkhEC7iC

app/main.py

@@ -22,6 +22,23 @@ class ScrapeRequest(BaseModel):
     url: HttpUrl
 
 
+def get_client_ip(request: Request) -> str:
+    """Identify the caller for rate limiting.
+
+    Prefers X-Forwarded-For's left-most (original client) entry over
+    request.client.host. The app is only reachable through a platform
+    reverse proxy (e.g. Hugging Face Spaces' gateway) which sets this
+    header on every request and is the only path to the container - so it
+    can be trusted here. request.client.host would instead reflect that
+    proxy's own connecting address, not the real caller, which silently
+    breaks per-client rate limiting.
+    """
+    forwarded_for = request.headers.get("x-forwarded-for")
+    if forwarded_for:
+        return forwarded_for.split(",")[0].strip()
+    return request.client.host if request.client else "unknown"
+
+
 def create_app(
     settings: Optional[Settings] = None,
     browser_manager: Optional[BrowserManager] = None,
@@ -75,7 +92,7 @@ def create_app(
         return {"status": "ok", "browser_ready": browser_manager.get_browser() is not None}
 
     async def process_scrape(url: str, request: Request) -> dict:
-        client_ip = request.client.host if request.client else "unknown"
+        client_ip = get_client_ip(request)
 
         try:
             if not rate_limiter.allow(client_ip):

tests/test_api.py

@@ -158,6 +158,36 @@ def test_rate_limit_blocks_after_the_configured_number_of_requests():
     assert r3.status_code == 429
 
 
+def test_rate_limit_keys_on_x_forwarded_for_not_the_proxy_peer():
+    # The app is only reachable through Hugging Face's reverse proxy, so
+    # request.client.host is always the proxy's own connecting address, not
+    # the real caller. Without honoring X-Forwarded-For, every caller would
+    # share (or fragment across) the wrong bucket and the limit would never
+    # engage correctly - this reproduces that against a fixed TestClient
+    # peer address, where two distinct forwarded IPs must be tracked
+    # independently and a repeated one must accumulate hits.
+    settings = base_settings(rate_limit_requests=2, rate_limit_window_seconds=60, cache_ttl_seconds=0)
+    with make_client(settings=settings) as client:
+        a1 = client.get(
+            "/scrape", params={"url": "https://example.com/a1"}, headers={"X-Forwarded-For": "1.2.3.4"}
+        )
+        a2 = client.get(
+            "/scrape", params={"url": "https://example.com/a2"}, headers={"X-Forwarded-For": "1.2.3.4"}
+        )
+        a3 = client.get(
+            "/scrape", params={"url": "https://example.com/a3"}, headers={"X-Forwarded-For": "1.2.3.4"}
+        )
+        # A different forwarded client is not affected by 1.2.3.4's limit.
+        b1 = client.get(
+            "/scrape", params={"url": "https://example.com/b1"}, headers={"X-Forwarded-For": "5.6.7.8"}
+        )
+
+    assert a1.status_code == 200
+    assert a2.status_code == 200
+    assert a3.status_code == 429
+    assert b1.status_code == 200
+
+
 def test_api_key_required_when_configured():
     settings = base_settings(api_key="secret123")
     with make_client(settings=settings) as client: