feat: add dependency readiness checks

apps/api/app/config.py

@@ -14,6 +14,7 @@ class Settings(BaseSettings):
     official_records_url: str = "https://rf4game.de/records/region/RU/"
     official_records_region: str = "RU"
     official_records_category: str = "records"
+    official_import_required: bool = False
     import_interval_seconds: int = Field(default=3600, ge=3600)
     rate_limit_secret: str = "change-rate-limit-secret"
     model_config = SettingsConfigDict(env_file=".env", extra="ignore")

apps/api/app/main.py

@@ -10,6 +10,7 @@ from uuid import UUID
 import httpx
 from fastapi import Depends, FastAPI, File, Header, HTTPException, Query, Request, Response, UploadFile
 from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
 from sqlalchemy import delete, func, select, text
 from sqlalchemy.orm import Session, joinedload
 
@@ -19,8 +20,9 @@ from .config import settings
 from .community_review import ExternalReviewError, map_observation, publish_observation, reject_observation
 from .importer import ImportSourceError, import_records, normalize
 from .models import Bait, BaitKind, CatchReport, ExternalObservation, Fish, ModerationEvent, ModerationStatus, OfficialRecordImport, SourceType, Spot, SubmissionAttempt, Waterbody
+from .readiness import readiness_report
 from .schemas import ActivityOut, AdminCatchReportOut, BaitOut, CatchOut, CatchReportCreate, CatchReportCreated, ExternalObservationDecision, ExternalObservationMapping, ExternalObservationOut, ExternalObservationPublished, FishOut, ImportRunOut, ModerationUpdate, OfficialRecordOut, SpotOut, WaterbodyOut
-from .storage import ScreenshotError, delete_screenshot, signed_screenshot_url, upload_screenshot
+from .storage import ScreenshotError, client as storage_client, delete_screenshot, signed_screenshot_url, upload_screenshot
 
 
 app = FastAPI(title="RF4 Spotter API", version="0.1.0")
@@ -38,6 +40,18 @@ def health() -> dict[str, str]:
     return {"status": "ok"}
 
 
+@app.get("/ready")
+def ready(db: Db) -> JSONResponse:
+    is_ready, components = readiness_report(
+        db, storage_client(), import_required=settings.official_import_required,
+        import_interval_seconds=settings.import_interval_seconds,
+    )
+    return JSONResponse(
+        status_code=200 if is_ready else 503,
+        content={"status": "ready" if is_ready else "not_ready", "components": components},
+    )
+
+
 @app.get("/api/v1/fishes", response_model=list[FishOut])
 def fishes(db: Db) -> list[Fish]:
     return list(db.scalars(select(Fish).order_by(Fish.name_ru)))

apps/api/app/readiness.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+from typing import Any
+
+from sqlalchemy import select, text
+from sqlalchemy.orm import Session
+
+from .models import ImportStatus, OfficialRecordImport
+
+
+def readiness_report(
+    session: Session, s3: Any, *, import_required: bool,
+    import_interval_seconds: int, now: datetime | None = None,
+) -> tuple[bool, dict[str, dict[str, object]]]:
+    current = now or datetime.now(timezone.utc)
+    components: dict[str, dict[str, object]] = {}
+    ready = True
+
+    try:
+        session.execute(text("SELECT 1"))
+        components["postgresql"] = {"status": "ready"}
+    except Exception:
+        components["postgresql"] = {"status": "unavailable"}
+        ready = False
+
+    try:
+        s3.list_buckets()
+        components["minio"] = {"status": "ready"}
+    except Exception:
+        components["minio"] = {"status": "unavailable"}
+        ready = False
+
+    try:
+        latest = session.scalar(select(OfficialRecordImport).order_by(
+            OfficialRecordImport.started_at.desc(), OfficialRecordImport.id.desc(),
+        ).limit(1))
+        if not import_required:
+            components["official_import"] = {
+                "status": "optional",
+                "last_run_status": latest.status.value if latest else None,
+            }
+        elif latest is None:
+            components["official_import"] = {"status": "not_run"}
+            ready = False
+        else:
+            started = latest.started_at if latest.started_at.tzinfo else latest.started_at.replace(tzinfo=timezone.utc)
+            stale = started < current - timedelta(seconds=import_interval_seconds * 2)
+            healthy = latest.status == ImportStatus.success and not stale
+            components["official_import"] = {
+                "status": "ready" if healthy else ("stale" if stale else latest.status.value),
+                "last_run_status": latest.status.value,
+                "last_started_at": started.isoformat(),
+            }
+            ready = ready and healthy
+    except Exception:
+        components["official_import"] = {"status": "unknown"}
+        if import_required:
+            ready = False
+
+    return ready, components