Use settings for FastAPI debug and RBAC

Introduce FASTAPI_DEBUG, UVICORN_WORKER_COUNT, RBAC_CACHE_BACKEND, and RBAC_PERMISSION_CACHE_TTL_SECONDS in config.settings and wire them into the app. Use FASTAPI_DEBUG for the FastAPI debug flag, and replace ad-hoc env lookups in the lifespan/startup logic with the new config constants to validate worker count, cache backend, and permission cache TTL. Improve logging to report the configured settings, and preserve exception chaining when OpenAI client initialization fails.

Author: edwinjosechittilappilly

src/app/factory.py

@@ -11,6 +11,7 @@
 from app.lifespan import run_shutdown, run_startup
 from app.middleware import RequestLoggingMiddleware
 from app.routes import register_all_routes
+from config.settings import FASTAPI_DEBUG
 from utils.logging_config import get_logger
 from utils.version_utils import OPENRAG_VERSION
 
@@ -21,7 +22,7 @@ async def create_app():
     """Create and configure the FastAPI application"""
     services = await initialize_services()
 
-    app = FastAPI(title="OpenRAG API", version=OPENRAG_VERSION, debug=True)
+    app = FastAPI(title="OpenRAG API", version=OPENRAG_VERSION, debug=FASTAPI_DEBUG)
     app.state.services = services
     app.state.background_tasks = set()
 

src/app/lifespan.py

@@ -8,11 +8,16 @@
 """
 
 import asyncio
-import os
 
 from fastapi import FastAPI
 
-from config.settings import clients, get_openrag_config
+from config.settings import (
+    RBAC_CACHE_BACKEND,
+    RBAC_PERMISSION_CACHE_TTL_SECONDS,
+    UVICORN_WORKER_COUNT,
+    clients,
+    get_openrag_config,
+)
 from services.startup_orchestrator import startup_tasks
 from utils.logging_config import get_logger
 from utils.telemetry import Category, MessageId, TelemetryClient
@@ -108,26 +113,24 @@ async def run_startup(app: FastAPI):
     # permissions for up to OPENRAG_PERM_CACHE_TTL seconds after
     # role mutations. Until the cache moves to a shared backend
     # (Redis), this constraint is real and must be enforced.
-    _workers = int(os.getenv("UVICORN_WORKERS", "1") or "1")
-    if _workers > 1:
+    if UVICORN_WORKER_COUNT > 1:
         logger.error(
             "Multi-worker deployment unsupported until cache is "
             "shared across processes. Set UVICORN_WORKERS=1.",
-            requested_workers=_workers,
+            requested_workers=UVICORN_WORKER_COUNT,
         )
         raise RuntimeError("UVICORN_WORKERS>1 is not supported")
-    cache_backend = os.getenv("CACHE_BACKEND", "memory").lower()
-    if cache_backend not in ("memory",):
+    if RBAC_CACHE_BACKEND not in ("memory",):
         logger.error(
             "Unsupported CACHE_BACKEND. Only 'memory' is wired.",
-            requested=cache_backend,
+            requested=RBAC_CACHE_BACKEND,
         )
-        raise RuntimeError(f"unsupported CACHE_BACKEND={cache_backend!r}")
+        raise RuntimeError(f"unsupported CACHE_BACKEND={RBAC_CACHE_BACKEND!r}")
     logger.info(
         "Permission cache configured",
-        backend=cache_backend,
-        workers=_workers,
-        perm_cache_ttl_s=int(os.getenv("OPENRAG_PERM_CACHE_TTL", "60") or "60"),
+        backend=RBAC_CACHE_BACKEND,
+        workers=UVICORN_WORKER_COUNT,
+        perm_cache_ttl_s=RBAC_PERMISSION_CACHE_TTL_SECONDS,
     )
 
     # RBAC kill-switch visibility. OPENRAG_RBAC_ENFORCE=false makes

src/config/settings.py

@@ -74,6 +74,25 @@
 SEGMENT_WRITE_KEY = os.getenv("SEGMENT_WRITE_KEY", "")
 ENVIRONMENT = os.getenv("ENVIRONMENT", "")
 
+# Enable FastAPI's `debug` mode (verbose error responses on the FastAPI app
+# instance). Named explicitly so it isn't confused with logging-level "debug"
+# or other unrelated debug flags. Defaults to False; flip via FASTAPI_DEBUG=true.
+FASTAPI_DEBUG = os.getenv("FASTAPI_DEBUG", "false").lower() in ("true", "1", "yes")
+
+# Number of uvicorn worker processes to allow. Multi-worker is currently
+# unsupported because the RBAC permission cache and the OAuth-subject→DB-id
+# cache are per-process; the lifespan startup hook hard-fails if this is >1
+# until the cache moves to a shared backend (Redis).
+UVICORN_WORKER_COUNT = get_env_int("UVICORN_WORKERS", 1)
+
+# Backend for the in-process RBAC permission cache. Only "memory" is wired
+# today; the lifespan hook rejects anything else.
+RBAC_CACHE_BACKEND = os.getenv("CACHE_BACKEND", "memory").lower()
+
+# TTL (seconds) for cached RBAC permission lookups. Stale permissions can
+# linger for up to this many seconds after a role mutation.
+RBAC_PERMISSION_CACHE_TTL_SECONDS = get_env_int("OPENRAG_PERM_CACHE_TTL", 60)
+
 # Docling service URL configuration
 # Priority:
 # 1. DOCLING_SERVE_URL environment variable
@@ -600,7 +619,7 @@ def run_probe_in_thread():
                 logger.info("Successfully initialized OpenAI client")
             except Exception as e:
                 logger.error(f"Failed to initialize OpenAI client: {e.__class__.__name__}: {str(e)}")
-                raise ValueError(f"Failed to initialize OpenAI client: {str(e)}. Please complete onboarding or set OPENAI_API_KEY environment variable.")
+                raise ValueError(f"Failed to initialize OpenAI client: {str(e)}. Please complete onboarding or set OPENAI_API_KEY environment variable.") from e
 
             return self._patched_async_client