(feat) add resolver startup bootstrap

Author: stefankumarasinghe

main.py

@@ -11,14 +11,14 @@
 
 import asyncio
 import contextlib
+import os
 import logging
 import sys
 import time
 from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
 
 import httpx
-import uvicorn
 from fastapi import FastAPI
 from fastapi.responses import JSONResponse
 from fastapi.routing import APIRoute
@@ -30,6 +30,7 @@
 from database import dispose_database, init_database, init_db
 from datasources.exceptions import BackendStartupTimeout
 from middleware.openapi import install_custom_openapi
+from middleware.runtime_ssl import RuntimeSSLOptions, run_uvicorn
 from services.rca_job_service import rca_job_service
 from services.security_service import InternalAuthMiddleware
 
@@ -72,6 +73,32 @@ def _generate_operation_id(route: APIRoute) -> str:
     return route.name
 
 
+async def _bootstrap_database() -> None:
+    timeout_seconds = float(os.getenv("DATABASE_STARTUP_TIMEOUT", "180"))
+    retry_delay_seconds = float(os.getenv("DATABASE_STARTUP_RETRY_DELAY", "2"))
+    deadline = time.monotonic() + timeout_seconds
+    attempt = 0
+
+    while True:
+        attempt += 1
+        try:
+            if settings.database_url:
+                init_database(settings.database_url)
+                init_db()
+                log.info("Resolver database initialization completed")
+            return
+        except Exception as exc:  # pylint: disable=broad-exception-caught
+            if time.monotonic() >= deadline:
+                raise RuntimeError("Resolver database did not become ready before startup timeout") from exc
+            log.warning(
+                "Resolver database not ready (attempt %d, retrying in %.1fs): %s",
+                attempt,
+                retry_delay_seconds,
+                exc,
+            )
+            await asyncio.sleep(retry_delay_seconds)
+
+
 class ResolverReadyResponse(BaseModel):
     ready: bool = Field(description="Whether resolver dependencies are currently ready.")
     backends: dict[str, str] = Field(
@@ -175,8 +202,7 @@ async def _wait_for_all_bg(data_settings: Settings, tenant_id: str) -> None:
 @asynccontextmanager
 async def lifespan(_app: FastAPI) -> AsyncIterator[None]:
     if settings.database_url:
-        init_database(settings.database_url)
-        init_db()
+        await _bootstrap_database()
         await rca_job_service.startup_recovery()
 
     tenant_id = settings.default_tenant_id
@@ -245,21 +271,11 @@ async def ready() -> JSONResponse:
 
 
 if __name__ == "__main__":
-    if settings.ssl_enabled:
-        uvicorn.run(
-            "main:app",
-            host=settings.host,
-            port=settings.port,
-            log_level="info",
-            access_log=True,
-            ssl_certfile=settings.ssl_certfile,
-            ssl_keyfile=settings.ssl_keyfile,
-        )
-    else:
-        uvicorn.run(
-            "main:app",
-            host=settings.host,
-            port=settings.port,
-            log_level="info",
-            access_log=True,
-        )
+    run_uvicorn(
+        app,
+        host=settings.host,
+        port=settings.port,
+        log_level="info",
+        access_log=True,
+        ssl_options=RuntimeSSLOptions.from_settings(settings),
+    )

middleware/runtime_ssl.py

@@ -0,0 +1,49 @@
+"""
+Runtime SSL helpers for the Resolver service.
+
+Copyright (c) 2026 Stefan Kumarasinghe.
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the
+License. You may obtain a copy of the License at
+http://www.apache.org/licenses/LICENSE-2.0
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class RuntimeSSLOptions:
+    ssl_certfile: str
+    ssl_keyfile: str
+
+    @classmethod
+    def from_settings(cls, settings: object) -> RuntimeSSLOptions | None:
+        if not getattr(settings, "ssl_enabled"):
+            return None
+
+        certfile = str(getattr(settings, "ssl_certfile", "")).strip()
+        keyfile = str(getattr(settings, "ssl_keyfile", "")).strip()
+        if not certfile or not keyfile:
+            raise ValueError(
+                "RESOLVER_SSL_ENABLED=true requires RESOLVER_SSL_CERTFILE and RESOLVER_SSL_KEYFILE to be set"
+            )
+
+        return cls(ssl_certfile=certfile, ssl_keyfile=keyfile)
+
+    def to_uvicorn_kwargs(self) -> dict[str, str]:
+        return {
+            "ssl_certfile": self.ssl_certfile,
+            "ssl_keyfile": self.ssl_keyfile,
+        }
+
+
+def run_uvicorn(app: Any, *, ssl_options: RuntimeSSLOptions | None = None, **kwargs: Any) -> None:
+    if ssl_options is not None:
+        kwargs.update(ssl_options.to_uvicorn_kwargs())
+
+    import uvicorn  # pylint: disable=import-outside-toplevel
+
+    uvicorn.run(app=app, **kwargs)

tests/test_api_route_surface_edges.py

@@ -26,6 +26,7 @@
 from api.routes import metrics as metrics_route
 from api.routes import traces as traces_route
 from custom_types import json as json_types
+from middleware.runtime_ssl import RuntimeSSLOptions
 
 
 class DemoModel(NpModel):
@@ -491,8 +492,39 @@ def test_dunder_main_runs_uvicorn_with_ssl(monkeypatch):
     )
     runpy.run_module("main", run_name="__main__")
 
-    assert captured["app"] == "main:app"
+    assert captured["app"].title == "Resolver Analysis Engine"
     assert captured["host"] == "0.0.0.0"
     assert captured["port"] == 9443
     assert captured["ssl_certfile"] == "/tmp/cert.pem"
     assert captured["ssl_keyfile"] == "/tmp/key.pem"
+
+
+def test_dunder_main_runs_uvicorn_without_ssl(monkeypatch):
+    captured = {}
+
+    monkeypatch.delenv("RESOLVER_SSL_ENABLED", raising=False)
+    monkeypatch.delenv("RESOLVER_SSL_CERTFILE", raising=False)
+    monkeypatch.delenv("RESOLVER_SSL_KEYFILE", raising=False)
+    monkeypatch.setenv("RESOLVER_HOST", "127.0.0.1")
+    monkeypatch.setenv("RESOLVER_PORT", "4322")
+    import config as config_module
+
+    importlib.reload(config_module)
+    monkeypatch.setitem(
+        sys.modules, "uvicorn", types.SimpleNamespace(run=lambda app, **kwargs: captured.update({"app": app, **kwargs}))
+    )
+    runpy.run_module("main", run_name="__main__")
+
+    assert captured["app"].title == "Resolver Analysis Engine"
+    assert captured["host"] == "127.0.0.1"
+    assert captured["port"] == 4322
+    assert "ssl_certfile" not in captured
+    assert "ssl_keyfile" not in captured
+
+
+def test_runtime_ssl_options_requires_paths():
+    with pytest.raises(
+        ValueError,
+        match="RESOLVER_SSL_ENABLED=true requires RESOLVER_SSL_CERTFILE and RESOLVER_SSL_KEYFILE to be set",
+    ):
+        RuntimeSSLOptions.from_settings(types.SimpleNamespace(ssl_enabled=True, ssl_certfile="", ssl_keyfile=""))