Reduce per-request DB overhead (Task 4)

- Cache setup_completed flag in app.state._setup_complete_cached after
  first successful is_setup_complete() call; all subsequent API requests
  skip the DB query entirely (one-way transition, cleared on restart).
- Add in-memory session token TTL cache (10 s) in require_auth; the second
  request with the same token within the window skips session_repo.get_session.
- Call invalidate_session_cache() on logout so revoked tokens are evicted
  immediately rather than waiting for TTL expiry.
- Add clear_session_cache() for test isolation.
- 5 new tests covering the cached fast-path for both optimisations.
- 460 tests pass, 83% coverage, zero ruff/mypy warnings.

backend/app/dependencies.py

@@ -6,6 +6,7 @@ Routers import directly from this module — never from ``app.state``
 directly — to keep coupling explicit and testable.
 """
 
+import time
 from typing import Annotated
 
 import aiosqlite
@@ -14,11 +15,44 @@ from fastapi import Depends, HTTPException, Request, status
 
 from app.config import Settings
 from app.models.auth import Session
+from app.utils.time_utils import utc_now
 
 log: structlog.stdlib.BoundLogger = structlog.get_logger()
 
 _COOKIE_NAME = "bangui_session"
 
+# ---------------------------------------------------------------------------
+# Session validation cache
+# ---------------------------------------------------------------------------
+
+#: How long (seconds) a validated session token is served from the in-memory
+#: cache without re-querying SQLite.  Eliminates repeated DB lookups for the
+#: same token arriving in near-simultaneous parallel requests.
+_SESSION_CACHE_TTL: float = 10.0
+
+#: ``token → (Session, cache_expiry_monotonic_time)``
+_session_cache: dict[str, tuple[Session, float]] = {}
+
+
+def clear_session_cache() -> None:
+    """Flush the entire in-memory session validation cache.
+
+    Useful in tests to prevent stale state from leaking between test cases.
+    """
+    _session_cache.clear()
+
+
+def invalidate_session_cache(token: str) -> None:
+    """Evict *token* from the in-memory session cache.
+
+    Must be called during logout so the revoked token is no longer served
+    from cache without a DB round-trip.
+
+    Args:
+        token: The session token to remove.
+    """
+    _session_cache.pop(token, None)
+
 
 async def get_db(request: Request) -> aiosqlite.Connection:
     """Provide the shared :class:`aiosqlite.Connection` from ``app.state``.
@@ -63,6 +97,11 @@ async def require_auth(
     The token is read from the ``bangui_session`` cookie or the
     ``Authorization: Bearer`` header.
 
+    Validated tokens are cached in memory for :data:`_SESSION_CACHE_TTL`
+    seconds so that concurrent requests sharing the same token avoid repeated
+    SQLite round-trips.  The cache is bypassed on expiry and explicitly
+    cleared by :func:`invalidate_session_cache` on logout.
+
     Args:
         request: The incoming FastAPI request.
         db: Injected aiosqlite connection.
@@ -88,8 +127,18 @@ async def require_auth(
             headers={"WWW-Authenticate": "Bearer"},
         )
 
+    # Fast path: serve from in-memory cache when the entry is still fresh and
+    # the session itself has not yet exceeded its own expiry time.
+    cached = _session_cache.get(token)
+    if cached is not None:
+        session, cache_expires_at = cached
+        if time.monotonic() < cache_expires_at and session.expires_at > utc_now().isoformat():
+            return session
+        # Stale cache entry — evict and fall through to DB.
+        _session_cache.pop(token, None)
+
     try:
-        return await auth_service.validate_session(db, token)
+        session = await auth_service.validate_session(db, token)
     except ValueError as exc:
         raise HTTPException(
             status_code=status.HTTP_401_UNAUTHORIZED,
@@ -97,6 +146,9 @@ async def require_auth(
             headers={"WWW-Authenticate": "Bearer"},
         ) from exc
 
+    _session_cache[token] = (session, time.monotonic() + _SESSION_CACHE_TTL)
+    return session
+
 
 # Convenience type aliases for route signatures.
 DbDep = Annotated[aiosqlite.Connection, Depends(get_db)]

backend/app/main.py

@@ -289,12 +289,19 @@ class SetupRedirectMiddleware(BaseHTTPMiddleware):
             return await call_next(request)
 
         # If setup is not complete, block all other API requests.
-        if path.startswith("/api"):
+        # Fast path: setup completion is a one-way transition.  Once it is
+        # True it is cached on app.state so all subsequent requests skip the
+        # DB query entirely.  The flag is reset only when the app restarts.
+        if path.startswith("/api") and not getattr(
+            request.app.state, "_setup_complete_cached", False
+        ):
             db: aiosqlite.Connection | None = getattr(request.app.state, "db", None)
             if db is not None:
                 from app.services import setup_service  # noqa: PLC0415
 
-                if not await setup_service.is_setup_complete(db):
+                if await setup_service.is_setup_complete(db):
+                    request.app.state._setup_complete_cached = True
+                else:
                     return RedirectResponse(
                         url="/api/setup",
                         status_code=status.HTTP_307_TEMPORARY_REDIRECT,

backend/app/routers/auth.py

@@ -12,7 +12,7 @@ from __future__ import annotations
 import structlog
 from fastapi import APIRouter, HTTPException, Request, Response, status
 
-from app.dependencies import DbDep, SettingsDep
+from app.dependencies import DbDep, SettingsDep, invalidate_session_cache
 from app.models.auth import LoginRequest, LoginResponse, LogoutResponse
 from app.services import auth_service
 
@@ -101,6 +101,7 @@ async def logout(
     token = _extract_token(request)
     if token:
         await auth_service.logout(db, token)
+        invalidate_session_cache(token)
     response.delete_cookie(key=_COOKIE_NAME)
     return LogoutResponse()