Add rate limit response headers to all rate-limited endpoints

Responses from rate-limited endpoints now include:
- X-RateLimit-Limit: max requests per window
- X-RateLimit-Remaining: requests left in current window
- X-RateLimit-Reset: seconds until window resets

Implemented via HTTP middleware that reads rate limit state.
429 responses also include headers. 4 new tests.
428 tests passing.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: kenneives

src/api/rate_limit.py

@@ -34,6 +34,19 @@ def check(self, key: str, limit: int, window_seconds: int = 60) -> bool:
         self._windows[key].append(time.time())
         return True
 
+    def get_remaining(self, key: str, limit: int, window_seconds: int = 60) -> int:
+        """Return how many requests remain in the current window."""
+        self._clean_window(key, window_seconds)
+        used = len(self._windows.get(key, []))
+        return max(0, limit - used)
+
+    def get_reset_time(self, key: str, window_seconds: int = 60) -> int:
+        """Return seconds until the oldest request in the window expires."""
+        if key not in self._windows or not self._windows[key]:
+            return 0
+        oldest = min(self._windows[key])
+        return max(0, int(window_seconds - (time.time() - oldest)))
+
 
 # Global instance
 _limiter = InMemoryRateLimiter()
@@ -62,14 +75,28 @@ def _rate_limit_response(
     }
 
 
+def _set_rate_limit_headers(
+    request: Request, key: str, limit: int, window: int = 60,
+) -> None:
+    """Store rate limit info on request state for middleware to add to response."""
+    remaining = _limiter.get_remaining(key, limit, window)
+    reset = _limiter.get_reset_time(key, window)
+    request.state.rate_limit_limit = limit
+    request.state.rate_limit_remaining = remaining
+    request.state.rate_limit_reset = reset
+
+
 async def rate_limit_reads(request: Request) -> None:
     ip = _get_client_ip(request)
     limit = settings.rate_limit_reads_per_minute
-    if not _limiter.check(f"read:{ip}", limit):
+    key = f"read:{ip}"
+    if not _limiter.check(key, limit):
         raise HTTPException(
             status_code=status.HTTP_429_TOO_MANY_REQUESTS,
             detail="Rate limit exceeded",
+            headers=_rate_limit_response(0, limit),
         )
+    _set_rate_limit_headers(request, key, limit)
     # Per-entity limit (2x IP limit to be generous)
     entity_id = _get_entity_id(request)
     if entity_id:
@@ -78,32 +105,41 @@ async def rate_limit_reads(request: Request) -> None:
             raise HTTPException(
                 status_code=status.HTTP_429_TOO_MANY_REQUESTS,
                 detail="Rate limit exceeded",
+                headers=_rate_limit_response(0, entity_limit),
             )
 
 
 async def rate_limit_writes(request: Request) -> None:
     ip = _get_client_ip(request)
     limit = settings.rate_limit_writes_per_minute
-    if not _limiter.check(f"write:{ip}", limit):
+    key = f"write:{ip}"
+    if not _limiter.check(key, limit):
         raise HTTPException(
             status_code=status.HTTP_429_TOO_MANY_REQUESTS,
             detail="Rate limit exceeded",
+            headers=_rate_limit_response(0, limit),
         )
+    _set_rate_limit_headers(request, key, limit)
     entity_id = _get_entity_id(request)
     if entity_id:
         entity_limit = limit * 2
         if not _limiter.check(f"write:entity:{entity_id}", entity_limit):
             raise HTTPException(
                 status_code=status.HTTP_429_TOO_MANY_REQUESTS,
                 detail="Rate limit exceeded",
+                headers=_rate_limit_response(0, entity_limit),
             )
 
 
 async def rate_limit_auth(request: Request) -> None:
     """Stricter limit for auth endpoints."""
     ip = _get_client_ip(request)
-    if not _limiter.check(f"auth:{ip}", settings.rate_limit_auth_per_minute):
+    limit = settings.rate_limit_auth_per_minute
+    key = f"auth:{ip}"
+    if not _limiter.check(key, limit):
         raise HTTPException(
             status_code=status.HTTP_429_TOO_MANY_REQUESTS,
             detail="Too many attempts. Try again later.",
+            headers=_rate_limit_response(0, limit),
         )
+    _set_rate_limit_headers(request, key, limit)

src/main.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from fastapi import FastAPI
+from fastapi import FastAPI, Request, Response
 from fastapi.middleware.cors import CORSMiddleware
 
 from src.api.account_router import router as account_router
@@ -77,6 +77,19 @@
     allow_headers=["*"],
 )
 
+@app.middleware("http")
+async def rate_limit_headers_middleware(request: Request, call_next) -> Response:
+    """Add rate limit headers to responses when available."""
+    response: Response = await call_next(request)
+    if hasattr(request.state, "rate_limit_limit"):
+        response.headers["X-RateLimit-Limit"] = str(request.state.rate_limit_limit)
+        response.headers["X-RateLimit-Remaining"] = str(
+            request.state.rate_limit_remaining
+        )
+        response.headers["X-RateLimit-Reset"] = str(request.state.rate_limit_reset)
+    return response
+
+
 app.include_router(account_router, prefix=settings.api_v1_prefix)
 app.include_router(activity_router, prefix=settings.api_v1_prefix)
 app.include_router(admin_router, prefix=settings.api_v1_prefix)

tests/test_rate_limit_headers.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+import pytest
+import pytest_asyncio
+from httpx import ASGITransport, AsyncClient
+
+from src.database import get_db
+from src.main import app
+
+
+@pytest_asyncio.fixture
+async def client(db):
+    async def override_get_db():
+        yield db
+
+    app.dependency_overrides[get_db] = override_get_db
+    transport = ASGITransport(app=app)
+    async with AsyncClient(transport=transport, base_url="http://test") as ac:
+        yield ac
+    app.dependency_overrides.clear()
+
+
+REGISTER_URL = "/api/v1/auth/register"
+LOGIN_URL = "/api/v1/auth/login"
+
+USER = {
+    "email": "ratelimit@example.com",
+    "password": "Str0ngP@ss",
+    "display_name": "RateLimitUser",
+}
+
+
+def _auth(token: str) -> dict:
+    return {"Authorization": f"Bearer {token}"}
+
+
+async def _setup_user(client: AsyncClient) -> str:
+    await client.post(REGISTER_URL, json=USER)
+    resp = await client.post(
+        LOGIN_URL, json={"email": USER["email"], "password": USER["password"]}
+    )
+    return resp.json()["access_token"]
+
+
+@pytest.mark.asyncio
+async def test_rate_limit_headers_on_read(client: AsyncClient, db):
+    """Rate-limited read endpoints include rate limit headers."""
+    token = await _setup_user(client)
+
+    resp = await client.get(
+        "/api/v1/feed/posts",
+        headers=_auth(token),
+    )
+    assert resp.status_code == 200
+    assert "x-ratelimit-limit" in resp.headers
+    assert "x-ratelimit-remaining" in resp.headers
+    assert "x-ratelimit-reset" in resp.headers
+    assert int(resp.headers["x-ratelimit-limit"]) > 0
+    assert int(resp.headers["x-ratelimit-remaining"]) >= 0
+
+
+@pytest.mark.asyncio
+async def test_rate_limit_headers_on_write(client: AsyncClient, db):
+    """Rate-limited write endpoints include rate limit headers."""
+    token = await _setup_user(client)
+
+    resp = await client.post(
+        "/api/v1/feed/posts",
+        json={"content": "Testing rate limit headers"},
+        headers=_auth(token),
+    )
+    assert resp.status_code == 201
+    assert "x-ratelimit-limit" in resp.headers
+    assert int(resp.headers["x-ratelimit-remaining"]) >= 0
+
+
+@pytest.mark.asyncio
+async def test_rate_limit_remaining_decreases(client: AsyncClient, db):
+    """Remaining count decreases with each request."""
+    token = await _setup_user(client)
+
+    resp1 = await client.get(
+        "/api/v1/feed/posts",
+        headers=_auth(token),
+    )
+    remaining1 = int(resp1.headers["x-ratelimit-remaining"])
+
+    resp2 = await client.get(
+        "/api/v1/feed/posts",
+        headers=_auth(token),
+    )
+    remaining2 = int(resp2.headers["x-ratelimit-remaining"])
+
+    assert remaining2 < remaining1
+
+
+@pytest.mark.asyncio
+async def test_no_rate_limit_headers_on_unrated(client: AsyncClient, db):
+    """Endpoints without rate limiting don't have rate limit headers."""
+    resp = await client.get("/health")
+    assert resp.status_code == 200
+    assert "x-ratelimit-limit" not in resp.headers