Add circuit breakers

app.py

@@ -6,7 +6,7 @@
 from __future__ import annotations
 
 import os
-from collections.abc import AsyncIterator
+from collections.abc import AsyncGenerator
 from contextlib import asynccontextmanager
 
 import redis.asyncio as aioredis
@@ -41,6 +41,7 @@
     StaticCacheHeadersMiddleware,
     configure_cors,
 )
+from middleware.timeout import RequestTimeoutMiddleware
 from repositories.indexes import ensure_indexes
 from routes.api_v1 import router as api_v1_router
 from routes.auth import router as auth_router
@@ -75,12 +76,15 @@ def create_app(settings: AppSettings | None = None) -> FastAPI:
         )
 
     @asynccontextmanager
-    async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+    async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
         # ── Startup ──────────────────────────────────────────────────────────
         mongo_client: AsyncMongoClient = AsyncMongoClient(
             settings.db.mongodb_uri,
             maxPoolSize=settings.db.max_pool_size,
             minPoolSize=settings.db.min_pool_size,
+            serverSelectionTimeoutMS=settings.db.server_selection_timeout_ms,
+            connectTimeoutMS=settings.db.connect_timeout_ms,
+            socketTimeoutMS=settings.db.socket_timeout_ms,
         )
         app.state.mongo_client = mongo_client
         app.state.db = mongo_client[settings.db.db_name]
@@ -235,8 +239,12 @@ async def docs(request: Request):
     app.add_middleware(
         MaxContentLengthMiddleware, max_content_length=settings.max_content_length
     )
-    # 5. Request logging — innermost, logs all requests with request_id
+    # 5. Request logging — logs all requests with request_id
     app.add_middleware(RequestLoggingMiddleware)
+    # 6. Request deadline — innermost
+    app.add_middleware(
+        RequestTimeoutMiddleware, timeout_seconds=settings.request_timeout_seconds
+    )
 
     # ── Error handlers + rate limiter ────────────────────────────────────
     app.state.limiter = limiter

config.py

@@ -23,6 +23,10 @@ class DatabaseSettings(BaseSettings):
     db_name: str = "url-shortener"
     max_pool_size: int = 200
     min_pool_size: int = 10
+    # socket_timeout sized for /metric aggregation; hot-path cap lives in RequestTimeoutMiddleware.
+    server_selection_timeout_ms: int = 3000
+    connect_timeout_ms: int = 3000
+    socket_timeout_ms: int = 120000
 
 
 class RedisSettings(BaseSettings):
@@ -148,6 +152,7 @@ class AppSettings(BaseSettings):
     max_active_api_keys: int = 20
     max_date_range_days: int = 90
     http_client_timeout: float = 5.0
+    request_timeout_seconds: float = 8.0
 
     # Validator constraints (overridable by self-hosters via env vars)
     blocked_url_regex_timeout: float = 0.2
@@ -167,7 +172,9 @@ def _must_be_positive_int(cls, v: int, info) -> int:
             raise ValueError(f"{info.field_name} must be >= 1, got {v}")
         return v
 
-    @field_validator("http_client_timeout", "blocked_url_regex_timeout")
+    @field_validator(
+        "http_client_timeout", "blocked_url_regex_timeout", "request_timeout_seconds"
+    )
     @classmethod
     def _must_be_positive_float(cls, v: float, info) -> float:
         if v <= 0:

config/apps.yaml

@@ -78,10 +78,18 @@ apps:
   spoo-raycast:
     name: Raycast Extension
     icon: raycast.svg
-    description: Shorten links from Raycast
+    description: Shorten and manage your spoo.me links from Raycast
     verified: true
-    status: coming_soon
+    status: live
     type: device_auth
+    redirect_uris:
+      - https://raycast.com/redirect?*
+    links:
+      raycast: https://www.raycast.com/spoo-me/spoo
+    permissions:
+      - Access your spoo.me account
+      - Create and manage short URLs
+      - View and export your analytics
 
   spoo-vscode:
     name: VS Code Extension

middleware/timeout.py

@@ -0,0 +1,43 @@
+"""Request deadline middleware — caps request time below the platform timeout."""
+
+from __future__ import annotations
+
+import asyncio
+
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response
+
+from infrastructure.logging import get_logger
+from shared.ip_utils import get_client_ip
+
+log = get_logger("spoo.timeout")
+
+EXEMPT_PATHS: frozenset[str] = frozenset({"/metric"})
+
+
+class RequestTimeoutMiddleware(BaseHTTPMiddleware):
+    def __init__(self, app, timeout_seconds: float = 8.0) -> None:
+        super().__init__(app)
+        self._timeout = timeout_seconds
+
+    async def dispatch(
+        self, request: Request, call_next: RequestResponseEndpoint
+    ) -> Response:
+        if request.url.path in EXEMPT_PATHS:
+            return await call_next(request)
+
+        try:
+            return await asyncio.wait_for(call_next(request), timeout=self._timeout)
+        except asyncio.TimeoutError:
+            log.error(
+                "request_deadline_exceeded",
+                method=request.method,
+                path=request.url.path,
+                timeout_seconds=self._timeout,
+                client_ip=get_client_ip(request),
+            )
+            return JSONResponse(
+                status_code=504,
+                content={"error": "Request timed out", "code": "request_timeout"},
+            )

routes/auth/device.py

@@ -67,11 +67,15 @@ def _device_error(request: Request, error: str, status_code: int = 400) -> Respo
 
 
 def _build_callback_redirect(
-    code: str, state: str, redirect_uri: str, app: AppEntry
+    code: str,
+    state: str,
+    redirect_uri: str,
+    app: AppEntry,
+    svc: DeviceAuthSvc,
 ) -> RedirectResponse:
     """Build the redirect to the callback page or a registered redirect_uri."""
     params = urlencode({"code": code, "state": state})
-    if redirect_uri and redirect_uri in app.redirect_uris:
+    if redirect_uri and svc.validate_redirect_uri(redirect_uri, app):
         separator = "&" if "?" in redirect_uri else "?"
         return RedirectResponse(f"{redirect_uri}{separator}{params}", status_code=302)
     return RedirectResponse(f"/auth/device/callback?{params}", status_code=302)
@@ -122,7 +126,9 @@ async def device_login(
         code = await device_auth_service.create_device_auth_code(
             profile.id, profile.email, app_id=app_id
         )
-        return _build_callback_redirect(code, state, redirect_uri, app)
+        return _build_callback_redirect(
+            code, state, redirect_uri, app, device_auth_service
+        )
 
     # No grant: show consent screen
     csrf_token = generate_secure_token(_CSRF_TOKEN_BYTES)
@@ -193,7 +199,9 @@ async def device_consent_approve(
     )
 
     # Clear CSRF cookie and redirect
-    response = _build_callback_redirect(code, state, redirect_uri, app)
+    response = _build_callback_redirect(
+        code, state, redirect_uri, app, device_auth_service
+    )
     response.delete_cookie(_CSRF_COOKIE_NAME)
     return response
 

routes/health_routes.py

@@ -1,15 +1,8 @@
-"""
-Health check endpoint.
-
-GET /health — checks MongoDB and Redis connectivity.
-Rules:
-- MongoDB failure → "unhealthy" (503) — the app cannot function without it.
-- Redis failure or absence → "degraded" (200) — Redis is optional.
-"""
+"""GET /health — liveness probe."""
 
 from __future__ import annotations
 
-from fastapi import APIRouter, Request
+from fastapi import APIRouter
 from fastapi.responses import JSONResponse
 
 from middleware.openapi import PUBLIC_SECURITY
@@ -23,46 +16,6 @@
     operation_id="healthCheck",
     summary="Health Check",
 )
-async def health_check(request: Request) -> JSONResponse:
-    """Check the health of the application and its dependencies.
-
-    Pings MongoDB and Redis to determine overall system status:
-
-    - **healthy** (200): Both MongoDB and Redis are reachable.
-    - **degraded** (200): MongoDB is reachable but Redis is down or not configured.
-    - **unhealthy** (503): MongoDB is unreachable -- the app cannot function.
-
-    **Authentication**: Not required (public endpoint)
-
-    **Rate Limits**: None
-    """
-    checks: dict[str, str] = {}
-    overall = "healthy"
-
-    try:
-        db = request.app.state.db
-        await db.client.admin.command("ping")
-        checks["mongodb"] = "ok"
-    except Exception:
-        checks["mongodb"] = "error"
-        overall = "unhealthy"
-
-    redis = request.app.state.redis
-    if redis is None:
-        checks["redis"] = "not_configured"
-        if overall == "healthy":
-            overall = "degraded"
-    else:
-        try:
-            await redis.ping()
-            checks["redis"] = "ok"
-        except Exception:
-            checks["redis"] = "error"
-            if overall == "healthy":
-                overall = "degraded"
-
-    status_code = 503 if overall == "unhealthy" else 200
-    return JSONResponse(
-        status_code=status_code,
-        content={"status": overall, "checks": checks},
-    )
+async def health_check() -> JSONResponse:
+    """Liveness probe. Public, unauthenticated, no dependency checks."""
+    return JSONResponse(status_code=200, content={"status": "ok"})

routes/legacy/url_shortener.py

@@ -558,7 +558,7 @@ async def metric(
     async def query() -> dict:
         start = time.time()
 
-        cursor = await db["urls"].aggregate(METRIC_PIPELINE_V1)
+        cursor = await db["urls"].aggregate(METRIC_PIPELINE_V1, maxTimeMS=90000)
         results = await cursor.to_list(length=1)
         v1_result = results[0] if results else {}
         v1_shortlinks = v1_result.get("total-shortlinks", 0)

schemas/dto/responses/common.py

@@ -22,18 +22,10 @@ class ErrorResponse(ResponseBase):
     details: Any | None = None
 
 
-class HealthChecks(ResponseBase):
-    """Individual service check statuses inside HealthResponse."""
-
-    mongodb: str
-    redis: str
-
-
 class HealthResponse(ResponseBase):
-    """Response body for GET /health."""
+    """Response body for GET /health (liveness probe)."""
 
     status: str
-    checks: dict[str, str]
 
 
 class MessageResponse(ResponseBase):

services/auth/device.py

@@ -67,8 +67,22 @@ def resolve_app(self, app_id: str) -> AppEntry | None:
         return entry if entry and entry.is_live_device_app() else None
 
     def validate_redirect_uri(self, redirect_uri: str, app: AppEntry) -> bool:
-        """Return True if redirect_uri is empty or in the app's allowlist."""
-        return not redirect_uri or redirect_uri in app.redirect_uris
+        """Return True if redirect_uri is empty, exact-matches an allowlist
+        entry, or prefix-matches an entry ending with ``*``.
+
+        The ``*`` suffix is used for OAuth clients (e.g. Raycast) that append
+        a varying query string to a fixed redirect URL. Only exact or
+        explicit-wildcard entries are accepted; implicit wildcards are not.
+        """
+        if not redirect_uri:
+            return True
+        for allowed in app.redirect_uris:
+            if allowed.endswith("*"):
+                if redirect_uri.startswith(allowed[:-1]):
+                    return True
+            elif redirect_uri == allowed:
+                return True
+        return False
 
     async def create_device_auth_code(
         self, user_id: ObjectId, email: str, app_id: str | None = None

tests/integration/test_device_auth.py

@@ -107,7 +107,13 @@ def device_auth_svc():
     # resolve_app and validate_redirect_uri are sync — must not be coroutines
     svc.resolve_app = MagicMock(side_effect=_resolve_app)
     svc.validate_redirect_uri = MagicMock(
-        side_effect=lambda uri, app: not uri or uri in app.redirect_uris
+        side_effect=lambda uri, app: (
+            not uri
+            or any(
+                uri.startswith(a[:-1]) if a.endswith("*") else uri == a
+                for a in app.redirect_uris
+            )
+        )
     )
     return svc