feat: Add rate limit headers to API responses

Adds X-RateLimit-* headers to responses for authenticated requests:
- X-RateLimit-Limit: Max requests per hour (1000 default)
- X-RateLimit-Remaining: Remaining requests in current window
- X-RateLimit-Reset: Unix timestamp when window resets

This allows API clients to monitor their rate limit status and
implement backoff strategies before hitting 429 errors.

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

Author: StuMason

src/polar_flow_server/app.py

@@ -20,6 +20,7 @@
 from polar_flow_server.api import api_routers
 from polar_flow_server.core.config import settings
 from polar_flow_server.core.database import close_database, engine, init_database
+from polar_flow_server.middleware import RateLimitHeadersMiddleware
 from polar_flow_server.routes import root_redirect
 
 # Configure structured logging
@@ -120,7 +121,7 @@ def create_app() -> Litestar:
                 ),
             ),
         ],
-        middleware=[session_config.middleware],
+        middleware=[session_config.middleware, RateLimitHeadersMiddleware],
         csrf_config=csrf_config,
         stores={"session_store": session_store},
         debug=settings.log_level == "DEBUG",

src/polar_flow_server/middleware/__init__.py

@@ -0,0 +1,5 @@
+"""Middleware modules."""
+
+from polar_flow_server.middleware.rate_limit import RateLimitHeadersMiddleware
+
+__all__ = ["RateLimitHeadersMiddleware"]

src/polar_flow_server/middleware/rate_limit.py

@@ -0,0 +1,72 @@
+"""Rate limit response headers.
+
+Adds X-RateLimit-* headers to responses for authenticated requests.
+"""
+
+from litestar import Response
+from litestar.connection import ASGIConnection
+from litestar.types import Message, Receive, Scope, Send
+
+from polar_flow_server.core.auth import RATE_LIMIT_STATE_KEY
+
+
+def add_rate_limit_headers(response: Response, connection: ASGIConnection) -> Response:
+    """Add rate limit headers to the response.
+
+    This is an after_request hook that reads rate limit info from
+    connection state (set by per_user_api_key_guard) and adds
+    X-RateLimit-* headers to the response.
+
+    Headers added:
+    - X-RateLimit-Limit: Max requests per hour
+    - X-RateLimit-Remaining: Remaining requests in current window
+    - X-RateLimit-Reset: Unix timestamp when window resets
+    """
+    rate_limit_info = connection.state.get(RATE_LIMIT_STATE_KEY)
+
+    if rate_limit_info:
+        response.headers["X-RateLimit-Limit"] = str(rate_limit_info["limit"])
+        response.headers["X-RateLimit-Remaining"] = str(rate_limit_info["remaining"])
+        response.headers["X-RateLimit-Reset"] = str(rate_limit_info["reset"])
+
+    return response
+
+
+class RateLimitHeadersMiddleware:
+    """Middleware to add rate limit headers to responses.
+
+    Note: This middleware captures the state after the app processes the request,
+    allowing it to access state set by guards during request processing.
+    """
+
+    def __init__(self, app: "ASGIApp") -> None:  # noqa: F821
+        """Initialize middleware with the ASGI app."""
+        self.app = app
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        """Process the request and add rate limit headers to response."""
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        # Initialize state dict if not present
+        if "state" not in scope:
+            scope["state"] = {}
+
+        async def send_wrapper(message: Message) -> None:
+            """Wrap send to inject rate limit headers."""
+            if message["type"] == "http.response.start":
+                rate_limit_info = scope.get("state", {}).get(RATE_LIMIT_STATE_KEY)
+                if rate_limit_info:
+                    headers = list(message.get("headers", []))
+                    headers.extend(
+                        [
+                            (b"x-ratelimit-limit", str(rate_limit_info["limit"]).encode()),
+                            (b"x-ratelimit-remaining", str(rate_limit_info["remaining"]).encode()),
+                            (b"x-ratelimit-reset", str(rate_limit_info["reset"]).encode()),
+                        ]
+                    )
+                    message = {**message, "headers": headers}
+            await send(message)
+
+        await self.app(scope, receive, send_wrapper)