diff --git a/.github/workflows/ci-cd.yml b/.github/workflows/ci-cd.yml index 847d3d2..8a21d22 100644 --- a/.github/workflows/ci-cd.yml +++ b/.github/workflows/ci-cd.yml @@ -35,19 +35,71 @@ jobs: python -m pip install --upgrade pip pip install flake8 pylint black isort mypy - - name: Run Black (Code Formatter Check) - run: black --check --line-length=120 src/ server.py + # HARD GATE. Syntax errors, undefined names and broken f-strings are + # always real bugs, never style opinions. An F821 shipped to production + # once already: a missing import meant v1 lap-times data silently failed + # to cache for months, because the NameError was swallowed by a broad + # `except Exception` and printed as a warning. + - name: Flake8 (errors that are always bugs) + run: flake8 src/ server.py --select=E9,F63,F7,F82 --show-source --statistics + + # HARD GATE, on the modules that have been cleaned. Keeping these at zero + # is cheap and stops the backlog growing. ADD FILES HERE as they are + # cleaned -- that is how the advisory full-repo run below eventually + # becomes the only run. + - name: Flake8 (strict, on cleaned modules) + run: | + flake8 --max-line-length=120 \ + src/api/app.py \ + src/api/deps.py \ + src/api/http_cache.py \ + src/api/admin_security.py \ + src/api/middleware/ \ + src/api/schemas/common.py \ + src/api/schemas/analysis.py \ + src/api/schemas/accounts.py \ + src/api/schemas/monitoring.py \ + src/api/schemas/seasonal.py \ + src/core/config.py \ + src/core/security/ \ + src/core/cache/redis_cache.py \ + src/core/observability/analytics.py \ + src/services/plotting/ \ + src/services/backup/ \ + src/domain/mappings.py \ + src/api/schemas/admin.py \ + src/api/schemas/batch.py \ + src/api/schemas/discovery.py \ + src/api/routers/admin_storage.py \ + src/api/routers/batch_v2.py \ + src/api/routers/discovery_v2.py \ + src/api/routers/telemetry_v2.py \ + src/api/schemas/telemetry.py \ + src/services/analysis/v2/lap_frames.py \ + src/services/storage_cleanup.py \ + src/services/circuit_derivation.py \ + src/ingestion/circuits_store.py \ + src/ingestion/circuits_loader.py \ + src/repositories/circuit_layouts.py \ + src/api/routers/admin_circuits.py \ + tests/unit/api/ + + # ADVISORY, for now. The repo still carries ~1200 whitespace-class + # findings; these run so the count is visible and shrinking, and should + # be promoted to hard gates once that backlog is cleared. + - name: Flake8 (full repo, advisory) + run: flake8 src/ server.py --max-line-length=120 --statistics continue-on-error: true - - name: Run isort (Import Sorting Check) - run: isort --check-only --profile black src/ server.py + - name: Black (advisory) + run: black --check --line-length=120 src/ server.py continue-on-error: true - - name: Run Flake8 - run: flake8 src/ server.py --max-line-length=120 --ignore=E203,W503,E501 --max-complexity=10 + - name: isort (advisory) + run: isort --check-only --profile black src/ server.py continue-on-error: true - - name: Run Pylint + - name: Pylint (advisory) run: pylint src/ server.py --max-line-length=120 --disable=C0111,R0903 continue-on-error: true @@ -70,7 +122,14 @@ jobs: python -m pip install --upgrade pip pip install bandit safety - - name: Run Bandit (Security Linter) + # HARD GATE at high severity + high confidence. The repo is currently + # clean at this level; a regression here means something like the + # tarfile-extractall traversal (CVE-2007-4559) that this gate was added + # after fixing. + - name: Bandit (high severity, hard gate) + run: bandit -r src/ server.py -lll -iii + + - name: Bandit (medium severity, advisory) run: bandit -r src/ server.py -ll continue-on-error: true diff --git a/Makefile b/Makefile index 41890f8..54c57ad 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,4 @@ -.PHONY: help install test test-unit test-integration test-fast test-cov lint clean build run deploy deploy-dev +.PHONY: help install test test-unit test-integration test-fast test-cov lint clean build run deploy deploy-dev backup backup-list backup-verify restore help: @echo "F1 Telemetry API - Available Commands" @@ -50,6 +50,7 @@ run-image: docker run --env-file .env -p 5000:5000 t1api:latest run: + .\.venv\Scripts\activate.ps1 python server.py deploy: @@ -57,3 +58,21 @@ deploy: deploy-dev: docker-compose -f docker-compose.dev.yml up --build + +# ── Backup / Restore ──────────────────────────────────────────────────── +# Manual one-off backup (uses the same config as the scheduled run). +backup: + python -c "from src.services.backup.runner import BackupRunner; r=BackupRunner().run_full(); print('OK', r.manifest.backup_id)" + +backup-list: + python -m src.workers.restore_cli --list + +# Verify checksums of a specific backup without restoring. +# make backup-verify BACKUP_ID=2026-06-06T02-00-00Z +backup-verify: + python -m src.workers.restore_cli --backup-id $(BACKUP_ID) --verify-only + +# Safe restore drill into a throwaway Mongo DB (does not touch production). +# make restore BACKUP_ID=2026-06-06T02-00-00Z TARGET_DB=T1API_DB_RESTORE_TEST +restore: + python -m src.workers.restore_cli --backup-id $(BACKUP_ID) --mongo-target-db $(TARGET_DB) diff --git a/assets/logos/ALP.avif b/assets/logos/ALP.avif new file mode 100644 index 0000000..b9aac4b Binary files /dev/null and b/assets/logos/ALP.avif differ diff --git a/assets/logos/AMR.avif b/assets/logos/AMR.avif new file mode 100644 index 0000000..3141775 Binary files /dev/null and b/assets/logos/AMR.avif differ diff --git a/assets/logos/AUD.avif b/assets/logos/AUD.avif new file mode 100644 index 0000000..c0b482f Binary files /dev/null and b/assets/logos/AUD.avif differ diff --git a/assets/logos/CAD.avif b/assets/logos/CAD.avif new file mode 100644 index 0000000..dbc0f20 Binary files /dev/null and b/assets/logos/CAD.avif differ diff --git a/assets/logos/FER.avif b/assets/logos/FER.avif new file mode 100644 index 0000000..0513054 Binary files /dev/null and b/assets/logos/FER.avif differ diff --git a/assets/logos/HAA.avif b/assets/logos/HAA.avif new file mode 100644 index 0000000..9c739ac Binary files /dev/null and b/assets/logos/HAA.avif differ diff --git a/assets/logos/MCL.avif b/assets/logos/MCL.avif new file mode 100644 index 0000000..4026798 Binary files /dev/null and b/assets/logos/MCL.avif differ diff --git a/assets/logos/MER.avif b/assets/logos/MER.avif new file mode 100644 index 0000000..774fb01 Binary files /dev/null and b/assets/logos/MER.avif differ diff --git a/assets/logos/RBR.avif b/assets/logos/RBR.avif new file mode 100644 index 0000000..a9407eb Binary files /dev/null and b/assets/logos/RBR.avif differ diff --git a/assets/logos/README.txt b/assets/logos/README.txt new file mode 100644 index 0000000..a621855 --- /dev/null +++ b/assets/logos/README.txt @@ -0,0 +1,3 @@ +Team logo PNGs go here, named by the constructor short_name from src/domain/data/teams.json. +Examples: RBR.png, FER.png, MER.png, MCL.png, AMR.png, ALP.png, WIL.png, VCARB.png, SAU.png, HAA.png +Recommended: square-ish transparent PNG, ~256x256. diff --git a/assets/logos/VCARB.avif b/assets/logos/VCARB.avif new file mode 100644 index 0000000..e619a76 Binary files /dev/null and b/assets/logos/VCARB.avif differ diff --git a/assets/logos/WIL.avif b/assets/logos/WIL.avif new file mode 100644 index 0000000..62e4f79 Binary files /dev/null and b/assets/logos/WIL.avif differ diff --git a/pyproject.toml b/pyproject.toml index 79acea8..2cb31cf 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -27,26 +27,31 @@ classifiers = [ ] dependencies = [ - "fastapi>=0.104.0", + # Keep in sync with requirements.txt -- `make install` installs both. + "fastapi>=0.115.0", "uvicorn[standard]>=0.24.0", "python-multipart>=0.0.6", - "aiofiles>=23.2.0", - "fastf1>=3.3.0", + "orjson>=3.9", + "jinja2>=3.1.0", + "fastf1>=3.8.3", + "timple>=0.1.8", "matplotlib>=3.7.0", "pandas>=2.1.0", "numpy>=1.24.0", - "seaborn>=0.12.0", - "plotly>=5.17.0", - "timple", - "Pillow", + "Pillow>=11.0.0", "pymongo>=4.5.0", + "redis>=5.0.0", "python-dotenv>=1.0.0", "pydantic>=2.0.0", "pydantic-settings>=2.0.0", "slowapi>=0.1.9", - "redis>=5.0.0", "python-jose[cryptography]>=3.3.0", + "bcrypt>=4.0.0", + "cryptography>=41.0.0", "sentry-sdk[fastapi]>=1.38.0", + "prometheus-client>=0.19.0", + "psutil>=5.9.0", + "boto3>=1.34.0", ] [project.optional-dependencies] diff --git a/requirements.txt b/requirements.txt index e18e164..0bb0e04 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,28 +1,43 @@ +# Runtime dependencies. Keep in sync with [project.dependencies] in +# pyproject.toml -- `make install` installs BOTH, so a divergence makes pip +# resolve the union non-deterministically. + +# --- Web framework --------------------------------------------------------- fastapi>=0.115.0 uvicorn[standard]>=0.24.0 -python-multipart>=0.0.6 -aiofiles>=23.2.0 +python-multipart>=0.0.6 # form parsing for the admin console login +orjson>=3.9 # backs default_response_class=ORJSONResponse +jinja2>=3.1.0 # admin console templates + +# --- F1 data --------------------------------------------------------------- fastf1>=3.8.3 +timple>=0.1.8 # timedelta tick formatting (v1 qualifying results) + +# --- Analysis & plotting --------------------------------------------------- matplotlib>=3.7.0 pandas>=2.1.0 numpy>=1.24.0 -seaborn>=0.12.0 -plotly>=5.17.0 -timple -Pillow +Pillow>=11.0.0 + +# --- Persistence ----------------------------------------------------------- pymongo>=4.5.0 +redis>=5.0.0 + +# --- Config & validation --------------------------------------------------- python-dotenv>=1.0.0 pydantic>=2.0.0 pydantic-settings>=2.0.0 + +# --- Security -------------------------------------------------------------- slowapi>=0.1.9 -redis>=5.0.0 python-jose[cryptography]>=3.3.0 -jinja2>=3.1.0 +bcrypt>=4.0.0 +cryptography>=41.0.0 + +# --- Observability --------------------------------------------------------- sentry-sdk[fastapi]>=1.38.0 prometheus-client>=0.19.0 psutil>=5.9.0 -starlette-prometheus>=0.9.0 -bcrypt + +# --- Backups --------------------------------------------------------------- boto3>=1.34.0 -cryptography>=41.0.0 -orjson>=3.9 diff --git a/src/api/admin_security.py b/src/api/admin_security.py index fc7bbb7..d3a6587 100644 --- a/src/api/admin_security.py +++ b/src/api/admin_security.py @@ -6,19 +6,29 @@ - ``NO_INDEX_HEADERS`` — applied to every admin response so search engines and well-behaved crawlers skip the surface. - ``apply_no_index`` — convenience to stamp those headers onto a Response. -- IP allowlist (env: ``ADMIN_IP_ALLOWLIST``) — when set, only listed IPs may - reach any /admin route. +- IP allowlist (``settings.admin_ip_allowlist``) — when set, only listed IPs + may reach any /admin route. - Per-IP UI rate limit (in-memory token bucket) — caps requests/min to /admin pages so unauthenticated probes can't fan out into per-key Mongo queries. - Login brute-force lockout (per-IP) — N failed attempts → lockout window. +- Session tokens (``create_session_token`` / ``verify_session_token``) — a + signed, expiring, per-login token (mirrors ``src/api/docs_auth.py``'s + scheme), so every login gets a distinct cookie and logout/expiry are + meaningful. - CSRF token (session-bound) — required on every state-changing admin POST. -- ``compare_cookie`` — constant-time session-cookie compare. +- ``compare_cookie`` — constant-time string compare, kept as a general + utility for callers that need one. + +``client_ip`` only honours ``X-Forwarded-For`` when the deployment has +explicitly opted in (``settings.trust_x_forwarded_for``) and, if a trusted +proxy list is configured, only when the direct TCP peer is one of those +proxies. Otherwise it is trivial to spoof the header and walk past the IP +allowlist, the UI rate limit and the login lockout in one shot. """ from __future__ import annotations import hashlib import hmac -import os import secrets import time from collections import deque @@ -47,26 +57,47 @@ def apply_no_index(response: Response) -> Response: def client_ip(request: Request) -> str: - # X-Forwarded-For first hop wins when present (reverse proxy deployments). + """Resolve the address that gates the IP allowlist, UI rate limit and + login lockout. + + ``X-Forwarded-For`` is attacker-controlled by default, so it is only + trusted when the operator has explicitly said a reverse proxy rewrites + it (``trust_x_forwarded_for``) and, when a trusted-proxy list is also + configured, only when the direct TCP peer is one of those proxies. + Otherwise the direct peer address is used, which cannot be spoofed. + """ + peer = request.client.host if request.client else "unknown" + if not settings.trust_x_forwarded_for: + return peer fwd = request.headers.get("x-forwarded-for") - if fwd: - return fwd.split(",")[0].strip() - return request.client.host if request.client else "unknown" + if not fwd: + return peer + trusted = settings.trusted_proxy_ips_list + if trusted and peer not in trusted: + return peer + return fwd.split(",")[0].strip() + + +def admin_api_gate(request: Request, response: Response) -> None: + """Apply IP allowlist + per-IP rate limit + noindex headers to an admin API call. + + Wired as a router-level ``dependencies=[Depends(admin_api_gate)]`` on every + ``/api/admin`` router. Lives here rather than in a router because all three + of its collaborators do, and because three routers had drifted into keeping + verbatim private copies of it. + """ + enforce_ip_allowlist(request) + enforce_ui_rate_limit(request) + for key, value in NO_INDEX_HEADERS.items(): + response.headers[key] = value # --------------------------------------------------------------------------- # IP allowlist # --------------------------------------------------------------------------- -def _allowlist() -> set[str]: - raw = os.getenv("ADMIN_IP_ALLOWLIST", "").strip() - if not raw: - return set() - return {p.strip() for p in raw.split(",") if p.strip()} - - def enforce_ip_allowlist(request: Request) -> None: - allowed = _allowlist() + allowed = settings.admin_ip_allowlist_list if not allowed: return if client_ip(request) not in allowed: @@ -77,7 +108,6 @@ def enforce_ip_allowlist(request: Request) -> None: # Per-IP rate limiting for admin UI (in-memory sliding window) # --------------------------------------------------------------------------- -_UI_RATE_PER_MINUTE = int(os.getenv("ADMIN_UI_RATE_PER_MINUTE", "60")) _ui_hits: Dict[str, Deque[float]] = {} _ui_lock = Lock() @@ -87,11 +117,12 @@ def enforce_ui_rate_limit(request: Request) -> None: ip = client_ip(request) now = time.monotonic() cutoff = now - 60.0 + limit = settings.admin_ui_rate_per_minute with _ui_lock: dq = _ui_hits.setdefault(ip, deque()) while dq and dq[0] < cutoff: dq.popleft() - if len(dq) >= _UI_RATE_PER_MINUTE: + if len(dq) >= limit: raise HTTPException( status_code=status.HTTP_429_TOO_MANY_REQUESTS, detail="Too many requests", @@ -109,10 +140,6 @@ def enforce_ui_rate_limit(request: Request) -> None: # Login brute-force lockout (per-IP) # --------------------------------------------------------------------------- -_LOGIN_MAX_ATTEMPTS = int(os.getenv("ADMIN_LOGIN_MAX_ATTEMPTS", "5")) -_LOGIN_LOCKOUT_SECONDS = int(os.getenv("ADMIN_LOGIN_LOCKOUT_SECONDS", "900")) -_LOGIN_WINDOW_SECONDS = int(os.getenv("ADMIN_LOGIN_WINDOW_SECONDS", "600")) - _login_attempts: Dict[str, Tuple[int, float, float]] = {} # ip -> (count, first_ts, locked_until) _login_lock = Lock() @@ -134,14 +161,17 @@ def check_login_allowed(request: Request) -> None: def record_login_failure(request: Request) -> None: ip = client_ip(request) now = time.time() + max_attempts = settings.admin_login_max_attempts + lockout_seconds = settings.admin_login_lockout_seconds + window_seconds = settings.admin_login_window_seconds with _login_lock: count, first_ts, locked_until = _login_attempts.get(ip, (0, now, 0.0)) # Reset window if too old. - if now - first_ts > _LOGIN_WINDOW_SECONDS: + if now - first_ts > window_seconds: count, first_ts = 0, now count += 1 - if count >= _LOGIN_MAX_ATTEMPTS: - locked_until = now + _LOGIN_LOCKOUT_SECONDS + if count >= max_attempts: + locked_until = now + lockout_seconds count, first_ts = 0, now # reset counter; lockout active _login_attempts[ip] = (count, first_ts, locked_until) @@ -152,23 +182,92 @@ def record_login_success(request: Request) -> None: _login_attempts.pop(ip, None) +# --------------------------------------------------------------------------- +# Session tokens (signed, expiring, per-login) +# --------------------------------------------------------------------------- +# Mirrors src/api/docs_auth.py's ``ts.nonce.sig`` scheme: a random nonce plus +# an issued-at timestamp, HMAC-SHA256 signed over settings.session_signing_secret +# and rejected once older than SESSION_TOKEN_TTL_SECONDS. Unlike the previous +# implementation (a single sha256 hash of the secret, identical for every +# login forever), every call to create_session_token() returns a distinct +# value: logins are distinguishable, logout is meaningful, and expiry is +# actually enforced rather than being a client-side cookie hint the server +# never checks. + +SESSION_TOKEN_TTL_SECONDS = 8 * 3600 + + +def _sign_payload(payload: str, secret: str) -> str: + return hmac.new(secret.encode(), payload.encode(), hashlib.sha256).hexdigest() + + +def create_session_token() -> str: + """Mint a fresh, random, expiring admin session token. + + Raises if no signing secret is configured rather than falling back to a + guessable constant — an admin session must never be issued unsigned. + """ + secret = settings.session_signing_secret + if not secret: + raise HTTPException( + status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, + detail="Admin session signing secret is not configured", + ) + ts = str(int(time.time())) + nonce = secrets.token_urlsafe(32) + payload = f"{ts}.{nonce}" + return f"{payload}.{_sign_payload(payload, secret)}" + + +def verify_session_token(token: Optional[str]) -> bool: + """Verify a token minted by ``create_session_token``. + + Fails closed: no configured secret, a missing/malformed token, a bad + signature, or a token older than ``SESSION_TOKEN_TTL_SECONDS`` are all + treated as "not authenticated". + """ + secret = settings.session_signing_secret + if not secret or not token: + return False + parts = token.split(".") + if len(parts) != 3: + return False + ts, nonce, sig = parts + payload = f"{ts}.{nonce}" + if not hmac.compare_digest(sig, _sign_payload(payload, secret)): + return False + try: + issued_at = int(ts) + except ValueError: + return False + return (time.time() - issued_at) <= SESSION_TOKEN_TTL_SECONDS + + # --------------------------------------------------------------------------- # CSRF token (session-bound, stateless) # --------------------------------------------------------------------------- def _csrf_secret() -> bytes: - base = settings.jwt_secret_key or settings.api_secret_key or "dev" - return f"admin-csrf::{base}".encode() + secret = settings.session_signing_secret + if not secret: + return b"" + return f"admin-csrf::{secret}".encode() def csrf_token_for(session_cookie: str) -> str: """Derive a deterministic CSRF token from the session cookie + secret. - Stateless (no server-side store) and rotates whenever the session does. + Stateless (no server-side store); rotates whenever the session does + since the cookie itself is now per-login. Returns "" when there is no + cookie or no configured signing secret, which verify_csrf always treats + as invalid. """ if not session_cookie: return "" - return hmac.new(_csrf_secret(), session_cookie.encode(), hashlib.sha256).hexdigest() + secret = _csrf_secret() + if not secret: + return "" + return hmac.new(secret, session_cookie.encode(), hashlib.sha256).hexdigest() def verify_csrf(request: Request, submitted: Optional[str]) -> None: diff --git a/src/api/app.py b/src/api/app.py index 4223e13..cf6595a 100644 --- a/src/api/app.py +++ b/src/api/app.py @@ -15,18 +15,21 @@ import asyncio # noqa: E402 from contextlib import asynccontextmanager # noqa: E402 -from datetime import datetime # noqa: E402 +from datetime import datetime, timezone # noqa: E402 +from pathlib import Path # noqa: E402 from fastapi import FastAPI, HTTPException, Request, status # noqa: E402 from fastapi.concurrency import run_in_threadpool # noqa: E402 from fastapi.middleware.cors import CORSMiddleware # noqa: E402 from fastapi.responses import JSONResponse, ORJSONResponse # noqa: E402 +from fastapi.staticfiles import StaticFiles # noqa: E402 from slowapi import _rate_limit_exceeded_handler # noqa: E402 from slowapi.errors import RateLimitExceeded # noqa: E402 from src.api.docs_auth import setup_docs_auth # noqa: E402 +from src.api.schemas.common import ErrorEnvelope # noqa: E402 from src.api.schemas.health import HealthCheckResponse # noqa: E402 -from src.core.config import settings # noqa: E402 +from src.core.config import check_production_safety, settings # noqa: E402 from src.core.exceptions import ( # noqa: E402 DataNotAvailableError, SessionNotFoundError, @@ -46,6 +49,19 @@ start_background_processor, stop_background_processor, ) +from src.workers.circuits_sync import ( # noqa: E402 + start_circuits_sync, + stop_circuits_sync, +) + + +def _now_iso() -> str: + """Timezone-aware UTC timestamp for error envelopes. + + ``datetime.utcnow()`` is deprecated from 3.12 and produced a *naive* + timestamp with no offset, which clients could not interpret unambiguously. + """ + return datetime.now(timezone.utc).isoformat() SWAGGER_UI_PARAMETERS = { @@ -58,65 +74,245 @@ } DESCRIPTION = """ -# T1API - Formula 1 Telemetry Analysis +# T1API — Formula 1 Telemetry Analysis + +Telemetry, timing and seasonal analysis for Formula 1 sessions, powering the +dashboards at **t1f1.com** and **turnonehub.com**. + +Most features are available two ways: a `-plot` endpoint returning a rendered +**PNG**, and a `-data` endpoint returning the same analysis as **JSON**. -This API provides advanced telemetry analysis for Formula 1 sessions. -It powers the dashboards at **t1f1.com** and **turnonehub.com**. +## Versions + +| | | +|---|---| +| **v2** (`/api/v2`) | Current. Built on the F1 live-timing feed. **Use this.** | +| **v1** (`/api/v1`) | Deprecated. FastF1-backed. Still served; every endpoint names its v2 replacement. | + +v2 falls back to the v1 data source automatically when live-timing lacks data, so +a v2 endpoint may still answer for older sessions. ## Authentication -All endpoints require an API key passed via the `X-API-Key` header. - -## Features -* **Daily Data**: High-level daily summary plots -* **Telemetry Comparison**: Throttle, brake, and speed comparisons between drivers -* **Qualifying Analysis**: Lap time distributions and top speed charts -* **Dashboards**: Aggregated data for specific race sessions - -## Rate Limits -The API implements tiered rate limiting: -- **Public**: 30 requests/minute (unauthenticated) -- **Standard**: 100 requests/minute (with API key) -- **Premium**: 300 requests/minute (premium API keys) -- **Data endpoints**: 60 requests/minute (separate counter) - -## Usage -All endpoints support both plot (PNG) and data (JSON) responses. + +Most endpoints require an API key in the `X-API-Key` header. + +* `/api/static/*` — currently served **without** authentication. +* `/api/auth/*`, `/api/keys/*`, `/api/me/*` — use a **JWT bearer token**, not an API key. + Sign up via `/api/auth/signup`, then mint keys at `/api/keys`. +* `/api/admin/*` and `/metrics` — require an **operator** key. Ordinary consumer keys are + rejected. + +A newly created key is shown **once** and stored hashed; it cannot be retrieved again. + +## Rate limits + +Applied per key (unauthenticated callers are bucketed by IP): + +| Tier | Per minute | Per hour | +|---|---|---| +| Public (no key) | 30 | 500 | +| Standard | 100 | 2,000 | +| Premium | 300 | 10,000 | + +Data-heavy endpoints carry a separate 60/min counter. Exceeding a limit returns +**429** with a `Retry-After` header. + +## Caching + +Historical session data never changes once processed, so those responses are +`private, max-age=86400, immutable` and carry a weak `ETag` — send `If-None-Match` +to get a **304** and skip the transfer. `/api/v2/dashboard` is the exception: it +tracks the latest session and is revalidated frequently. + +## CSV export + +Append `?format=csv` to any JSON endpoint under `/api/v1` or `/api/v2` to receive the +same payload as CSV, with a `Content-Disposition` filename for direct download. + +Without the parameter responses are unchanged. Per-driver series (for example +race gaps, which nest a `laps` array under each driver) are expanded to long +format, one row per element with the driver columns repeated. Endpoints whose +payload has no tabular shape — `/api/v2/dashboard`, for instance — return **400** +rather than a misleading partially-flattened file. + +## Errors + +Errors share a common envelope carrying `detail`, a `request_id` for correlating +with server logs, and a `timestamp`. Session-addressed endpoints add richer +shapes: **404** may include `valid_rounds`/`suggestions`, and **503** distinguishes +*data not yet available upstream* from *an upstream source being down*, both with +`Retry-After`. """ TAGS_METADATA = [ - {"name": "General", "description": "System health, welcome messages, and daily summaries"}, - {"name": "Monitoring", "description": "Observability, metrics, request tracing, and system monitoring"}, - {"name": "API v1", "description": "Version 1 API endpoints - Analysis and seasonal data"}, - {"name": "API v2", "description": "Version 2 API endpoints - Analysis and seasonal data"}, - {"name": "Latest Session", "description": "Aggregated data for the main frontend dashboard"}, - {"name": "Seasonal Data", "description": "Season-specific data including drivers, teams, and race schedules"}, - {"name": "Simple Analysis", "description": "Analysis focused on general session stats or single driver metrics"}, - {"name": "Driver Comparison", "description": "Head-to-head driver comparisons"}, - {"name": "Static", "description": "Static data endpoints for drivers, teams, and race schedules"}, + # Order here is the order Swagger renders the groups, so the surface reads + # top-down: what the API is, then the data, then operations, then the + # deprecated tail. Every tag a router actually uses must appear here -- + # undeclared tags render without a description and in arbitrary order. + { + "name": "General", + "description": "Service metadata: welcome payload and health checks.", + }, + { + "name": "Latest Session", + "description": ( + "Aggregated payload for the most recently completed session. " + "Powers the main dashboard. Unlike the rest of v2 this response is " + "**not** immutable -- it changes as a race weekend progresses." + ), + }, + { + "name": "Simple Analysis", + "description": ( + "Single-session, whole-field metrics: top speeds, throttle traces " + "and speed distributions." + ), + }, + { + "name": "Qualifying", + "description": "Qualifying results, lap-time analysis and track comparison.", + }, + { + "name": "Pace Analysis", + "description": "Driver and constructor race-pace comparisons.", + }, + { + "name": "Race Analysis", + "description": ( + "Race-only features: position changes, gaps, tyre degradation, pit " + "strategy, weather and race story." + ), + }, + { + "name": "Telemetry", + "description": ( + "Per-lap and per-corner telemetry: track maps, corner duels, " + "driver radars and full lap data." + ), + }, + { + "name": "Driver Comparison", + "description": "Head-to-head comparisons between two drivers.", + }, + { + "name": "Seasonal Data", + "description": ( + "Season-scoped data: event schedules, sessions, teammate battles " + "and form guides." + ), + }, + { + "name": "Static", + "description": ( + "Reference data that changes rarely: drivers, teams and circuits." + ), + }, + { + "name": "Auth", + "description": ( + "Account signup/login and self-service API key management. " + "These endpoints use a JWT bearer token, not an API key." + ), + }, + { + "name": "Monitoring", + "description": ( + "Observability: metrics, request tracing and system health. " + "Operator-only." + ), + }, + { + "name": "Admin", + "description": ( + "Operational endpoints for data backfill, cache and backups. " + "Requires an operator key from `ADMIN_API_KEYS`; ordinary consumer " + "keys are rejected." + ), + }, + { + "name": "Admin UI", + "description": "Cookie-authenticated HTML console. Hidden from this schema.", + }, + { + "name": "API v2", + "description": ( + "Current analysis API, backed by the F1 live-timing feed. " + "**Prefer these endpoints for all new integrations.**" + ), + }, + { + "name": "API v1", + "description": ( + "**Deprecated.** FastF1-backed predecessor to v2, retained for " + "compatibility. Every v1 endpoint has a v2 equivalent; see each " + "operation's description for its replacement." + ), + }, ] +def _init_sentry(logger) -> None: + """Initialise Sentry error tracking when a DSN is configured. + + The settings (``sentry_dsn``, ``sentry_environment``, + ``sentry_traces_sample_rate``) and the dependency have been present for a + long time, but ``sentry_sdk.init()`` was never actually called, so every + production error went unreported. No DSN means no-op, so this is safe in + development and in tests. + """ + if not settings.sentry_dsn: + return + try: + import sentry_sdk + from sentry_sdk.integrations.fastapi import FastApiIntegration + from sentry_sdk.integrations.starlette import StarletteIntegration + + sentry_sdk.init( + dsn=settings.sentry_dsn, + environment=settings.sentry_environment, + traces_sample_rate=settings.sentry_traces_sample_rate, + release=settings.app_version, + integrations=[StarletteIntegration(), FastApiIntegration()], + # Request bodies can carry API keys; headers are scrubbed by + # Sentry's default denylist but bodies are not. + send_default_pii=False, + ) + logger.info("Sentry initialised (environment=%s)", settings.sentry_environment) + except Exception as exc: # never let telemetry break startup + logger.warning("Sentry initialisation failed: %s", exc) + + def create_app() -> FastAPI: setup_logging(level=settings.log_level, log_file=settings.log_file) logger = get_logger(__name__) + _init_sentry(logger) + limiter = init_limiter() # Routers MUST be imported after init_limiter() (decorators bind at import). from src.api.routers.admin import router as admin_router + from src.api.routers.admin_cache import router as admin_cache_router + from src.api.routers.admin_circuits import router as admin_circuits_router + from src.api.routers.admin_data import router as admin_data_router + from src.api.routers.admin_storage import router as admin_storage_router from src.api.routers.admin_ui import router as admin_ui_router from src.api.routers.backup_admin import router as backup_admin_router from src.api.routers.analysis_v1 import router as analysis_router_v1 from src.api.routers.analysis_v2 import router as analysis_router_v2 from src.api.routers.auth import router as auth_router from src.api.routers.circuits_api import router as circuits_api_router + from src.api.routers.batch_v2 import router as batch_router + from src.api.routers.discovery_v2 import router as discovery_router from src.api.routers.drivers_api import router as drivers_api_router + from src.api.routers.media_api import router as media_api_router from src.api.routers.keys import router as keys_router, me_router from src.api.routers.monitoring import router as monitoring_router from src.api.routers.seasonal_v1 import router as seasonal_router_v1 from src.api.routers.seasonal_v2 import router as seasonal_router_v2 from src.api.routers.standings_v2 import router as standings_router_v2 from src.api.routers.teams_api import router as teams_api_router + from src.api.routers.telemetry_v2 import router as telemetry_router_v2 try: session_tracker = SessionTracker() @@ -129,6 +325,12 @@ def create_app() -> FastAPI: async def lifespan(app: FastAPI): logger.info(f"Starting {settings.app_name} v{settings.app_version}") logger.info(f"Environment: {settings.environment}") + + # Refuse to serve a production process that is configured to fail open + # (default secrets, dev auth bypass, wildcard CORS with credentials). + # Raises InsecureConfigurationError on a fatal finding. + for warning in check_production_safety(): + logger.warning("Configuration: %s", warning) logger.info(f"CORS Origins: {settings.cors_origins_list}") logger.info( "Rate limiting - " @@ -147,10 +349,23 @@ async def lifespan(app: FastAPI): try: from src.repositories.mongo import ensure_indexes created = ensure_indexes() - logger.info(f"MongoDB indexes ready: {sum(len(v) for v in created.values())} across {len(created)} collections") + total = sum(len(v) for v in created.values()) + logger.info(f"MongoDB indexes ready: {total} across {len(created)} collections") except Exception as e: logger.warning(f"ensure_indexes() failed: {e}") + # Re-materialise circuit layouts that exist only in MongoDB. docker-compose + # does not mount src/, so a layout written at runtime (circuits_sync, or a + # telemetry-derived one for a brand-new circuit) is lost on rebuild; the + # Mongo mirror is the durable copy. Never blocks startup. + try: + from src.ingestion.circuits_store import hydrate_from_mongo + restored = await asyncio.to_thread(hydrate_from_mongo) + if restored: + logger.info(f"Circuit layouts re-materialised from MongoDB: {restored}") + except Exception as e: + logger.warning(f"Circuit layout hydrate failed (continuing): {e}") + # Initialize Redis response cache (graceful no-op if unavailable). try: from src.core.cache.redis_cache import init_redis_cache @@ -165,6 +380,13 @@ async def lifespan(app: FastAPI): else: logger.info("Background processor disabled in configuration") + circuits_sync_task = None + if settings.enable_circuits_sync: + logger.info(f"Starting circuits sync worker (interval: {settings.circuits_sync_interval_seconds}s)") + circuits_sync_task = asyncio.create_task(start_circuits_sync()) + else: + logger.info("Circuits sync worker disabled in configuration") + backup_scheduler = None if settings.backup_enabled: try: @@ -188,6 +410,13 @@ async def lifespan(app: FastAPI): pass if backup_scheduler: await backup_scheduler.stop() + if circuits_sync_task: + await stop_circuits_sync() + circuits_sync_task.cancel() + try: + await circuits_sync_task + except asyncio.CancelledError: + pass try: from src.core.cache.redis_cache import close_redis_cache await close_redis_cache() @@ -207,11 +436,37 @@ async def lifespan(app: FastAPI): }, license_info={"name": "Proprietary / Internal Use"}, openapi_tags=TAGS_METADATA, + # Declared so "Try it out" targets the right host instead of whatever + # origin happens to be serving the docs page. + servers=[ + {"url": "https://api.t1f1.com", "description": "Production"}, + {"url": "http://localhost:5000", "description": "Local development"}, + ], docs_url=None, redoc_url=None, openapi_url=None, ) setup_docs_auth(app, settings, SWAGGER_UI_PARAMETERS) + + # Admin console assets (stylesheet + shared JS). Mounted rather than inlined + # so the ~500 lines of CSS are fetched once and cached, instead of being + # duplicated into every admin page render. Contains no sensitive data; the + # pages themselves stay behind the cookie-session + IP-allowlist gates. + _static_dir = Path(__file__).resolve().parent / "static" + if _static_dir.is_dir(): + app.mount("/static", StaticFiles(directory=str(_static_dir)), name="static") + else: # pragma: no cover - only if the package is installed without assets + logger.warning("Static assets directory missing at %s", _static_dir) + + # Curated media assets (driver portraits, team logos, fonts, logos) served + # read-only at /assets. The media_api router 302-redirects here; a CDN in + # front of the app can cache these bytes indefinitely. + _assets_dir = Path(__file__).resolve().parents[2] / "assets" + if _assets_dir.is_dir(): + app.mount("/assets", StaticFiles(directory=str(_assets_dir)), name="assets") + else: # pragma: no cover - repo always ships assets/ + logger.warning("Media assets directory missing at %s", _assets_dir) + app.state.limiter = limiter app.state.session_tracker = session_tracker app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler) @@ -228,7 +483,14 @@ async def lifespan(app: FastAPI): # Weak-ETag short-circuiting + immutable Cache-Control for cacheable V2 GET # endpoints (historical F1 session data never changes once processed). from src.api.http_cache import DEFAULT_MAX_AGE_SECONDS + from src.api.middleware.csv_export import CSVExportMiddleware from src.api.middleware.etag import ETagMiddleware + + # Order matters. Starlette applies the LAST-added middleware outermost, so + # adding CSV first and ETag second means ETag wraps CSV -- the ETag is + # therefore computed over the CSV bytes actually served, not over the JSON + # they were rendered from. + app.add_middleware(CSVExportMiddleware, path_prefixes=("/api/v1/", "/api/v2/")) app.add_middleware( ETagMiddleware, path_prefixes=("/api/v2/",), @@ -247,7 +509,7 @@ async def global_exception_handler(request: Request, exc: Exception): content={ "detail": "Internal server error", "request_id": request_id, - "timestamp": datetime.utcnow().isoformat(), + "timestamp": _now_iso(), }, ) @@ -274,7 +536,7 @@ async def http_exception_handler(request: Request, exc: HTTPException): content={ "detail": exc.detail, "request_id": request_id, - "timestamp": datetime.utcnow().isoformat(), + "timestamp": _now_iso(), }, ) @@ -298,7 +560,7 @@ async def data_not_available_handler(request: Request, exc: DataNotAvailableErro "sources_tried": exc.sources_tried, "retry_after_seconds": 300, "request_id": request_id, - "timestamp": datetime.utcnow().isoformat(), + "timestamp": _now_iso(), }, ) @@ -318,7 +580,7 @@ async def upstream_unavailable_handler(request: Request, exc: UpstreamUnavailabl "source": exc.source, "retry_after_seconds": 60, "request_id": request_id, - "timestamp": datetime.utcnow().isoformat(), + "timestamp": _now_iso(), }, ) @@ -336,7 +598,7 @@ async def session_not_found_handler(request: Request, exc: SessionNotFoundError) "gp": exc.gp, "session": exc.session, "request_id": request_id, - "timestamp": datetime.utcnow().isoformat(), + "timestamp": _now_iso(), } if exc.valid_rounds: payload["valid_rounds"] = exc.valid_rounds @@ -356,7 +618,7 @@ async def value_error_handler(request: Request, exc: ValueError): content={ "detail": str(exc), "request_id": request_id, - "timestamp": datetime.utcnow().isoformat(), + "timestamp": _now_iso(), }, ) @@ -369,7 +631,16 @@ async def robots_txt(): headers={"Cache-Control": "public, max-age=86400", "X-Robots-Tag": "noindex"}, ) - @app.get("/", tags=["General"]) + @app.get( + "/", + tags=["General"], + summary="Service banner", + operation_id="root_welcome", + description=( + "Unauthenticated service banner: name, running version, and where to " + "find the documentation and health check." + ), + ) async def welcome(): return { "message": "Welcome to the T1API", @@ -378,7 +649,23 @@ async def welcome(): "health": "/api/health", } - @app.get("/api/health", tags=["General"], response_model=HealthCheckResponse) + @app.get( + "/api/health", + tags=["General"], + response_model=HealthCheckResponse, + summary="Health check", + operation_id="health_check", + description=( + "Liveness and dependency check. Unauthenticated, so it can be used as " + "a container or load-balancer probe. " + "Returns `status: healthy` when MongoDB is reachable, `degraded` when " + "it is not (the API can still serve cached responses), and **503** if " + "the check itself fails." + ), + responses={ + 503: {"model": ErrorEnvelope, "description": "Service unhealthy."}, + }, + ) @limiter.limit(f"{settings.rate_limit_public_per_minute}/minute") async def health_check(request: Request): try: @@ -414,6 +701,10 @@ def _mongo_ping(): app.include_router(monitoring_router) app.include_router(admin_router) + app.include_router(admin_cache_router) + app.include_router(admin_data_router) + app.include_router(admin_storage_router) + app.include_router(admin_circuits_router) app.include_router(admin_ui_router) app.include_router(backup_admin_router) app.include_router(auth_router) @@ -426,6 +717,10 @@ def _mongo_ping(): app.include_router(standings_router_v2) app.include_router(drivers_api_router) app.include_router(teams_api_router) + app.include_router(media_api_router) app.include_router(circuits_api_router) + app.include_router(discovery_router) + app.include_router(batch_router) + app.include_router(telemetry_router_v2) return app diff --git a/src/api/deps.py b/src/api/deps.py new file mode 100644 index 0000000..fd4a5b9 --- /dev/null +++ b/src/api/deps.py @@ -0,0 +1,217 @@ +"""Reusable request-parameter dependencies for the analysis endpoints. + +Two problems this solves. + +**Validation.** ``session`` used to be declared as a bare ``str`` with no +pattern and no length bound, yet it is interpolated into a filesystem path by +every V2 analysis module (``outputs/plots/{year}/{event}/{session}``). A value +of ``../../..`` therefore escaped the output directory. ``settings.valid_sessions_list`` +already existed to describe the legal values but was never used for validation +anywhere. These dependencies close that gap at the edge; the containment guard +in ``src/services/plotting/output.py`` closes it at the sink. + +**Duplication.** ~100 endpoints re-declared identical ``year``/``gp``/``session`` +``Query(...)`` triples, so the constraints drifted and Swagger documented them +inconsistently. Depending on ``SessionQuery`` gives one definition and one set +of docs. + +These supersede the never-referenced ``SessionParams`` / ``DriverComparisonParams`` +/ ``DriverSessionParams`` models in ``schemas/health.py``. +""" +from __future__ import annotations + +import re +from dataclasses import dataclass +from typing import Optional, Union + +from fastapi import Depends, HTTPException, Query, Request, status + +from src.core.config import settings + +#: Driver three-letter abbreviation, e.g. ``VER``. Also the safe alphabet for +#: the driver segment of a generated filename. +_TLA_RE = re.compile(r"^[A-Za-z]{3}$") + +_GP_NAME_RE = re.compile(r"^[A-Za-z0-9 ._'-]{1,80}$") + + +def _reject(detail: str) -> None: + raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=detail) + + +def validate_session(session: str) -> str: + """Return ``session`` if it is a known session identifier, else 400. + + Membership in ``valid_sessions_list`` is the whole check: the list is a + closed set of literals, so nothing containing a path separator, ``..`` or a + NUL byte can pass. Matching is case-insensitive because callers send both + ``Q`` and ``q``; the canonical spelling from the settings list is returned + so downstream path building is deterministic. + """ + if not session: + _reject("session is required") + for allowed in settings.valid_sessions_list: + if session.strip().lower() == allowed.lower(): + return allowed + _reject( + f"Invalid session '{session}'. Valid values: " + f"{', '.join(settings.valid_sessions_list)}" + ) + + +def validate_driver(driver: Optional[str]) -> Optional[str]: + """Return the upper-cased TLA, or ``None``. Rejects anything else. + + ``driver`` is interpolated into generated filenames, so it must not carry + separators or dots. + """ + if driver is None or driver == "": + return None + if not _TLA_RE.match(driver.strip()): + _reject(f"Invalid driver '{driver}'. Expected a 3-letter code such as 'VER'.") + return driver.strip().upper() + + +def validate_gp(gp: Union[int, str]) -> Union[int, str]: + """Round number, event key, or official event name. + + Integers are range-checked against the season bounds. Strings are resolved + upstream by ``F1StaticClient.get_event_info`` — which returns a + server-controlled name — but are still constrained here so an unresolvable + value fails fast and cannot reach a path builder if a future caller skips + that resolution. + """ + if isinstance(gp, bool): # bool is an int subclass; reject explicitly. + _reject("gp must be a round number or event name") + if isinstance(gp, int): + if not (settings.min_round <= gp <= settings.max_round): + _reject( + f"gp round must be between {settings.min_round} and {settings.max_round}" + ) + return gp + text = str(gp).strip() + if not _GP_NAME_RE.match(text): + _reject(f"Invalid gp '{gp}'.") + return text + + +@dataclass(frozen=True) +class SessionQuery: + """The (year, gp, session) triple every analysis endpoint is addressed by.""" + + year: int + gp: Union[int, str] + session: str + + +@dataclass(frozen=True) +class DriverQuery: + """A session plus a single driver.""" + + year: int + gp: Union[int, str] + session: str + driver: Optional[str] + + +@dataclass(frozen=True) +class DriverPairQuery: + """A session plus two drivers, for head-to-head comparisons.""" + + year: int + gp: Union[int, str] + session: str + driver1: str + driver2: str + + +def session_query( + year: int = Query( + 2025, + ge=settings.min_year, + le=settings.max_year, + description="Season year.", + ), + gp: Union[int, str] = Query( + 1, description="Round number, event key, or official event name." + ), + session: str = Query( + "Q", + description="Session identifier, e.g. FP1, Q, SQ, S, R.", + ), +) -> SessionQuery: + return SessionQuery(year=year, gp=validate_gp(gp), session=validate_session(session)) + + +def driver_query( + base: SessionQuery = Depends(session_query), + driver: Optional[str] = Query( + None, description="Driver three-letter code, e.g. VER. Omit for all drivers." + ), +) -> DriverQuery: + return DriverQuery( + year=base.year, + gp=base.gp, + session=base.session, + driver=validate_driver(driver), + ) + + +def driver_pair_query( + base: SessionQuery = Depends(session_query), + driver1: str = Query(..., description="First driver's three-letter code."), + driver2: str = Query(..., description="Second driver's three-letter code."), +) -> DriverPairQuery: + d1 = validate_driver(driver1) + d2 = validate_driver(driver2) + if d1 is None or d2 is None: + _reject("driver1 and driver2 are both required") + return DriverPairQuery( + year=base.year, gp=base.gp, session=base.session, driver1=d1, driver2=d2 + ) + + +# --------------------------------------------------------------------------- +# Router-level guards +# --------------------------------------------------------------------------- +# +# The dataclass dependencies above are the clean way to declare parameters, but +# retrofitting them across ~100 existing endpoints would rewrite every +# signature -- and the query-parameter names are part of a frozen public +# contract. These guards give the same validation with zero signature churn: +# they read the raw query string, so they add no OpenAPI parameters and change +# no schema. + + +async def guard_session_params(request: Request) -> None: + """Reject malformed ``session``/``driver`` query values with a 400. + + Without this, a bad ``session`` propagated all the way to the upstream + session lookup and surfaced as an opaque **500**, even though it is plainly + a client error. It is also the outer half of the path-traversal defence: + ``session`` is interpolated into ``outputs/plots/{year}/{event}/{session}``, + with :func:`src.services.plotting.output.resolve_within` as the inner half. + """ + session = request.query_params.get("session") + if session is not None and session != "": + validate_session(session) + + # Single-TLA parameters. The API spells this several ways across versions + # (`driver`, `driver1`/`driver2`, and `d1`/`d2` on the comparison + # endpoints); all of them are frozen public names, so validate each rather + # than renaming. + for name in ("driver", "driver1", "driver2", "d1", "d2"): + value = request.query_params.get(name) + if value: + validate_driver(value) + + # `drivers` is a comma-separated TLA list. + drivers = request.query_params.get("drivers") + if drivers: + for tla in drivers.split(","): + if tla.strip(): + validate_driver(tla) + + # NOTE: `driver_name` is deliberately excluded -- it carries a full name + # ("Max Verstappen"), not a TLA, so the 3-letter rule would reject valid + # input. diff --git a/src/api/docs_auth.py b/src/api/docs_auth.py index 4be9e71..27cf01c 100644 --- a/src/api/docs_auth.py +++ b/src/api/docs_auth.py @@ -242,7 +242,7 @@ def _login_page(error: bool = False, app_version: str = "2.0.0") -> str:
Endpoints active
-
247
+
190+
@@ -319,8 +319,8 @@ def _login_page(error: bool = False, app_version: str = "2.0.0") -> str:
Endpoints
-
GET/api/v2/analysis
-
GET/api/v2/seasonal
+
GET/api/v2/dashboard
+
GET/api/v2/qualifying-results-data
GET/api/health
diff --git a/src/api/http_cache.py b/src/api/http_cache.py index 210a89d..0755943 100644 --- a/src/api/http_cache.py +++ b/src/api/http_cache.py @@ -20,10 +20,31 @@ DEFAULT_MAX_AGE_SECONDS = 86400 +#: How long a *mutable* response (live/current-season data) may be reused. +#: Short, and always revalidated -- the latest-session dashboard changes while +#: a session is running. +VOLATILE_MAX_AGE_SECONDS = 30 + def immutable_cache_control(max_age: int = DEFAULT_MAX_AGE_SECONDS) -> str: - """Return a ``Cache-Control`` header value for immutable historical data.""" - return f"public, max-age={max_age}, immutable" + """``Cache-Control`` for genuinely immutable historical data. + + ``private`` rather than ``public``: these responses are gated by an API key, + so a shared proxy or CDN must not hand one caller's payload to another. + ``immutable`` tells clients never to revalidate, which is only safe for a + completed session whose data can no longer change. + """ + return f"private, max-age={max_age}, immutable" + + +def volatile_cache_control(max_age: int = VOLATILE_MAX_AGE_SECONDS) -> str: + """``Cache-Control`` for responses whose content can still change. + + Used for the latest-session dashboard and current-season data. Without this + the ETag middleware stamped ``immutable, max-age=86400`` on the live + dashboard, freezing it for 24h in every browser and CDN. + """ + return f"private, max-age={max_age}, must-revalidate" def compute_etag( @@ -44,7 +65,11 @@ def compute_etag( if params: for key in sorted(params): parts.append(f"{key}={params[key]}") - digest = hashlib.sha1("|".join(parts).encode("utf-8")).hexdigest() + # Cache-key digest, not a security primitive -- collision resistance is + # irrelevant here and SHA-1 is the cheapest adequate option. + digest = hashlib.sha1( + "|".join(parts).encode("utf-8"), usedforsecurity=False + ).hexdigest() return f'W/"{digest}"' @@ -69,3 +94,20 @@ def cache_headers( "Cache-Control": immutable_cache_control(max_age), "ETag": compute_etag(year, gp, session, data_type, params), } + + +#: Path suffixes under ``/api/v2/`` whose content is not immutable. +#: ``/standings/drivers`` and ``/standings/constructors`` cover both the cached +#: current-season endpoints and their ``/live`` variants; the per-year and +#: per-round standings paths (``/seasons/{year}/drivers-standings``) are not +#: matched and stay immutable. +VOLATILE_PATH_MARKERS = ("/dashboard", "/standings/drivers", "/standings/constructors") + + +def is_volatile_path(path: str) -> bool: + """True when a response body for ``path`` can still change. + + The latest-session dashboard resolves whichever session is most recent, so + its payload changes as a race unfolds. + """ + return any(marker in path for marker in VOLATILE_PATH_MARKERS) diff --git a/src/api/middleware/csv_export.py b/src/api/middleware/csv_export.py new file mode 100644 index 0000000..d233b09 --- /dev/null +++ b/src/api/middleware/csv_export.py @@ -0,0 +1,160 @@ +"""Opt-in CSV rendering for JSON analysis responses. + +Analysts consuming this API mostly want the `-data` payloads in a spreadsheet +or a dataframe, and were previously left to convert JSON themselves. Adding a +``format`` parameter to ~50 endpoint signatures would have churned every one of +them (and the frozen public parameter list), so the conversion lives here +instead: append ``?format=csv`` to any JSON endpoint under a configured prefix +and the same payload is rendered as CSV. + +Design notes: + +* **Opt-in only.** Without ``format=csv`` the response is byte-identical to + before, so no existing client can be affected. +* **Honest failure.** Not every payload is tabular -- some are nested objects + with no natural row shape. Rather than emit a misleading half-flattened file + or silently fall back to JSON (which would break a client that asked for CSV + and got something else), those return **400** explaining that the endpoint is + not tabular. +* Placed *inside* the ETag middleware so the validator is computed over the CSV + body actually served, not the JSON it was derived from. +""" +from __future__ import annotations + +import csv +import io +import json +from typing import Any, Iterable, List, Optional, Sequence + +from starlette.middleware.base import BaseHTTPMiddleware +from starlette.requests import Request +from starlette.responses import JSONResponse, Response + +#: Scalars that can sit in a CSV cell as-is. +_SCALARS = (str, int, float, bool, type(None)) + + +def _is_flat_row(item: Any) -> bool: + return isinstance(item, dict) and all( + isinstance(v, _SCALARS) for v in item.values() + ) + + +def _explode(rows: Sequence[dict]) -> Optional[List[dict]]: + """Flatten one level of nesting into long format. + + Several V2 payloads are shaped as one object per driver carrying a series, + e.g. ``{"driver": "VER", "team": "...", "laps": [{"lap": 1, "gap_s": 2.1}]}``. + The natural tabular form repeats the parent columns against each element of + the series, which is exactly what a dataframe user wants. + """ + exploded: List[dict] = [] + for row in rows: + scalars = {k: v for k, v in row.items() if isinstance(v, _SCALARS)} + series = [ + (k, v) for k, v in row.items() + if isinstance(v, list) and v and all(isinstance(e, dict) for e in v) + ] + if len(series) != 1: + return None + name, entries = series[0] + for entry in entries: + if not _is_flat_row(entry): + return None + merged = dict(scalars) + for k, v in entry.items(): + # Prefix on collision so a parent column is never overwritten. + merged[f"{name}_{k}" if k in scalars else k] = v + exploded.append(merged) + return exploded or None + + +def _to_rows(payload: Any) -> Optional[List[dict]]: + """Coerce a decoded JSON payload into a list of flat dict rows.""" + if isinstance(payload, list): + if not payload: + return [] + if all(_is_flat_row(i) for i in payload): + return list(payload) + if all(isinstance(i, dict) for i in payload): + return _explode(payload) + return None + if isinstance(payload, dict): + # A wrapper object with exactly one list-of-objects value (e.g. + # {"data": [...]}) is unambiguous; anything else is not. + lists = [ + v for v in payload.values() + if isinstance(v, list) and v and all(isinstance(e, dict) for e in v) + ] + if len(lists) == 1: + return _to_rows(lists[0]) + return None + + +def _render_csv(rows: Iterable[dict]) -> str: + rows = list(rows) + if not rows: + return "" + # Union of keys, preserving first-seen order so columns stay stable. + columns: List[str] = [] + for row in rows: + for key in row: + if key not in columns: + columns.append(key) + buf = io.StringIO() + writer = csv.DictWriter(buf, fieldnames=columns, extrasaction="ignore") + writer.writeheader() + writer.writerows(rows) + return buf.getvalue() + + +class CSVExportMiddleware(BaseHTTPMiddleware): + def __init__(self, app, *, path_prefixes: Iterable[str] = ("/api/v1/", "/api/v2/")): + super().__init__(app) + self._prefixes = tuple(path_prefixes) + + async def dispatch(self, request: Request, call_next): + wants_csv = request.query_params.get("format", "").lower() == "csv" + if not wants_csv or request.method not in ("GET", "HEAD"): + return await call_next(request) + if not request.url.path.startswith(self._prefixes): + return await call_next(request) + + response = await call_next(request) + content_type = (response.headers.get("content-type") or "").lower() + if response.status_code != 200 or "json" not in content_type: + return response + if not hasattr(response, "body_iterator"): + return response + + body = b"".join([chunk async for chunk in response.body_iterator]) # type: ignore[attr-defined] + try: + payload = json.loads(body) + except (ValueError, UnicodeDecodeError): + return Response( + content=body, status_code=response.status_code, + headers=dict(response.headers), media_type=response.media_type, + ) + + rows = _to_rows(payload) + if rows is None: + return JSONResponse( + status_code=400, + content={ + "detail": ( + "This endpoint's payload is not tabular, so it cannot be " + "rendered as CSV. Request it without ?format=csv." + ), + "path": request.url.path, + }, + ) + + text = _render_csv(rows) + headers = { + k: v for k, v in response.headers.items() + if k.lower() not in ("content-length", "content-type") + } + name = request.url.path.rstrip("/").split("/")[-1] or "export" + headers["Content-Disposition"] = f'attachment; filename="{name}.csv"' + return Response(content=text, status_code=200, + headers=headers, media_type="text/csv; charset=utf-8") diff --git a/src/api/middleware/etag.py b/src/api/middleware/etag.py index 34bcb75..abca343 100644 --- a/src/api/middleware/etag.py +++ b/src/api/middleware/etag.py @@ -1,15 +1,23 @@ """Weak-ETag middleware for cacheable GET endpoints. -For GET responses under selected path prefixes (default ``/api/v1/`` and -``/api/v2/``) we compute a SHA-1 of the body and emit a weak ETag header, -plus an immutable ``Cache-Control`` header (historical F1 session data never -changes once processed). On the next request, if the client sends -``If-None-Match`` with the same tag, we short-circuit with a 304 and an -empty body. - -Non-breaking: clients that don't send ``If-None-Match`` see the same -response shape as before, aside from the added headers. Conditional GET is -an enhancement, not a change. +For GET responses under selected path prefixes we compute a SHA-1 of the body, +emit a weak ETag, and short-circuit the next matching request with a 304. + +Two things this middleware must get right, both of which it previously got +wrong: + +* **Not everything under a prefix is immutable.** It used to stamp + ``public, max-age=86400, immutable`` on *every* 200, including + ``/api/v2/dashboard`` — which resolves the *latest* session and changes while + a race runs. ``immutable`` instructs clients never to revalidate, so the live + dashboard froze for 24 hours in every browser and CDN. Volatile paths now get + a short ``must-revalidate`` policy instead. +* **These responses are API-key gated**, so the policy is ``private``: a shared + proxy must never hand one caller's payload to another. + +Binary file responses (the PNG plot endpoints) are passed through untouched — +hashing them would buffer multi-megabyte images into memory for no benefit, +since they are already served from disk with their own validators. """ from __future__ import annotations @@ -20,7 +28,17 @@ from starlette.requests import Request from starlette.responses import Response -from src.api.http_cache import DEFAULT_MAX_AGE_SECONDS, immutable_cache_control, is_not_modified +from src.api.http_cache import ( + DEFAULT_MAX_AGE_SECONDS, + immutable_cache_control, + is_not_modified, + is_volatile_path, + volatile_cache_control, +) + +#: Only these content types are worth hashing; everything else (images, octet +#: streams) is streamed through untouched. +_HASHABLE_TYPES = ("application/json", "text/") class ETagMiddleware(BaseHTTPMiddleware): @@ -35,6 +53,10 @@ def __init__( self._prefixes = tuple(path_prefixes) self._cache_control_max_age = cache_control_max_age + def _is_hashable(self, response: Response) -> bool: + content_type = (response.headers.get("content-type") or "").lower() + return any(content_type.startswith(t) or t in content_type for t in _HASHABLE_TYPES) + async def dispatch(self, request: Request, call_next): if request.method not in ("GET", "HEAD"): return await call_next(request) @@ -45,13 +67,21 @@ async def dispatch(self, request: Request, call_next): if response.status_code != 200: return response - # Consume the streaming body so we can hash it. + # Leave binary payloads (PNG plots) alone rather than buffering them. + if not self._is_hashable(response): + return response + if not hasattr(response, "body_iterator"): + return response + body_chunks: list[bytes] = [] async for chunk in response.body_iterator: # type: ignore[attr-defined] body_chunks.append(chunk) body = b"".join(body_chunks) - etag = 'W/"' + hashlib.sha1(body).hexdigest() + '"' + # Weak validator -- an ETag is a change detector, not a security + # primitive, so SHA-1 is appropriate here. + digest = hashlib.sha1(body, usedforsecurity=False).hexdigest() + etag = 'W/"' + digest + '"' if_none_match = request.headers.get("if-none-match") if is_not_modified(if_none_match, etag): headers = dict(response.headers) @@ -61,8 +91,13 @@ async def dispatch(self, request: Request, call_next): headers = dict(response.headers) headers["ETag"] = etag - if self._cache_control_max_age > 0 and "cache-control" not in {k.lower() for k in headers}: - headers["Cache-Control"] = immutable_cache_control(self._cache_control_max_age) + if "cache-control" not in {k.lower() for k in headers}: + if is_volatile_path(request.url.path): + headers["Cache-Control"] = volatile_cache_control() + elif self._cache_control_max_age > 0: + headers["Cache-Control"] = immutable_cache_control( + self._cache_control_max_age + ) return Response( content=body, status_code=response.status_code, diff --git a/src/api/routers/admin.py b/src/api/routers/admin.py index 4b81149..108e4bb 100644 --- a/src/api/routers/admin.py +++ b/src/api/routers/admin.py @@ -1,17 +1,40 @@ -from fastapi import APIRouter, Request, Response, HTTPException, Depends, Query +from fastapi import APIRouter, Request, HTTPException, Depends, Query from fastapi.concurrency import run_in_threadpool from pymongo import MongoClient from urllib.parse import quote_plus from typing import Dict, Any, Optional, List +import hmac import re -from fastapi.concurrency import run_in_threadpool - -from src.api.admin_security import ( - NO_INDEX_HEADERS, - enforce_ip_allowlist, - enforce_ui_rate_limit, +from src.api.admin_security import admin_api_gate +from src.api.schemas.admin import ( + AdminDashboardResponse, + JobCancelResponse, + JobRecord, + JobsListResponse, + KeyAnalyticsResponse, + KeyRevokeResponse, + KeysListResponse, + KeyVerifyResponse, + MongoOverviewResponse, + MongoSessionsCoverageResponse, + PeakHoursResponse, + PerformanceResponse, + PlanEstimateResponse, + PlotCatalogResponse, + PlotGenJobResponse, + PlotInventoryResponse, + ProcessLatestResponse, + ProcessorStatusResponse, + QuotaUsageResponse, + SeasonInventoryResponse, + SessionDriversResponse, + UsageForKeyResponse, + UsageTopResponse, + UsersListResponse, + UserUsageResponse, ) +from src.api.schemas.common import COMMON_ERROR_RESPONSES, ErrorEnvelope from src.core.logging import get_logger from src.core.security.api_keys import invalidate_key_cache, verify_api_key from src.core.security.rate_limiting import apply_tiered_limit, limits_for_tier @@ -22,31 +45,37 @@ from src.repositories import api_keys as _keys from src.repositories import users as _users import src.repositories.populate_seasons +from src.services.analysis.v2 import registry +from src.workers import plot_inventory logger = get_logger(__name__) -def _admin_api_gate(request: Request, response: Response) -> None: - """Apply IP allowlist + per-IP rate limit + noindex headers to every admin API call.""" - enforce_ip_allowlist(request) - enforce_ui_rate_limit(request) - for k, v in NO_INDEX_HEADERS.items(): - response.headers[k] = v + +router = APIRouter(dependencies=[Depends(admin_api_gate)]) -router = APIRouter(dependencies=[Depends(_admin_api_gate)]) +def _in_constant_time(candidate: str, allowed: List[str]) -> bool: + """Membership test that does not short-circuit on the first differing byte.""" + found = False + for k in allowed: + if hmac.compare_digest(candidate, k): + found = True # keep iterating; do not early-return + return found async def require_admin_key(api_key: str = Depends(verify_api_key)) -> str: """Admin gate. - Env keys are operator-level (treated as admin). A user-generated key - is allowed only if it belongs to a user whose ``is_admin`` is true. + A key is admin if and only if: + 1. it appears in the operator-provisioned ``ADMIN_API_KEYS`` list, or + 2. it is a database-issued key whose owner has ``is_admin`` set, or + 3. ``ADMIN_ALLOW_LEGACY_ENV_KEYS`` is enabled and the key is one of the + legacy consumer/website env keys (``ALLOWED_API_KEYS`` / + ``PREMIUM_API_KEYS``) — a transitional escape hatch only. """ - # Env keys always pass. - if api_key in settings.allowed_api_keys_list or api_key in settings.premium_api_keys_list: - return api_key - # Dev bypass keeps working. - if api_key == "dev-key" and settings.environment == "development": + # Operator keys always pass. Constant-time to avoid leaking key material + # via timing on the membership check. + if _in_constant_time(api_key, settings.admin_api_keys_list): return api_key def _is_admin_db_key() -> bool: @@ -58,8 +87,49 @@ def _is_admin_db_key() -> bool: if await run_in_threadpool(_is_admin_db_key): return api_key + + # Transitional escape hatch: every consumer/website env key is admin. + if settings.admin_allow_legacy_env_keys and ( + _in_constant_time(api_key, settings.allowed_api_keys_list) + or _in_constant_time(api_key, settings.premium_api_keys_list) + ): + logger.warning( + "Admin access granted via legacy consumer key because " + "ADMIN_ALLOW_LEGACY_ENV_KEYS is enabled. Provision ADMIN_API_KEYS " + "and disable this setting." + ) + return api_key + + # Dev bypass keeps working, but only when explicitly opted into. + if api_key == "dev-key" and settings.allow_insecure_dev_auth: + return api_key + raise HTTPException(status_code=403, detail="Admin privileges required") + +#: 403 as ``require_admin_key`` actually raises it — spelled out so Swagger +#: documents the operator-key requirement, not just a generic "forbidden". +_ADMIN_KEY_REQUIRED = { + "model": ErrorEnvelope, + "description": ( + "Admin privileges required. The API key must be listed in `ADMIN_API_KEYS`, or be a " + "database-issued key whose owner has `is_admin` set. Ordinary `ALLOWED_API_KEYS` / " + "`PREMIUM_API_KEYS` consumer keys are rejected unless the transitional " + "`ADMIN_ALLOW_LEGACY_ENV_KEYS` escape hatch is enabled." + ), +} + +#: Baseline for every `/api/admin/*` endpoint: the common set with the 403 +#: description above substituted in. +ADMIN_ERROR_RESPONSES = {**COMMON_ERROR_RESPONSES, 403: _ADMIN_KEY_REQUIRED} + + +def _err(description: str) -> Dict[str, Any]: + """An ``ErrorEnvelope``-shaped response entry (every raw ``HTTPException`` + in this router is rendered through that envelope by ``app.py``).""" + return {"model": ErrorEnvelope, "description": description} + + SUPPORTED_MONGO_VERSIONS = {"v1", "v2"} @@ -274,13 +344,21 @@ def _query_mongodb_overview(version: str) -> Dict[str, Any]: if client: client.close() + # ============================================================================ # ADMIN & UTILITY ENDPOINTS # ============================================================================ -@router.post('/api/admin/populate-sessions', tags=["General"]) +@router.post( + '/api/admin/populate-sessions', + tags=["Admin"], + summary="Repopulate season reference data", + operation_id="admin_populate_sessions", + responses={200: {"description": "Population ran; always returns `null` (no summary value)."}, + **ADMIN_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") -async def admin_populate_sessions(request: Request, api_key: str = Depends(verify_api_key)): +async def admin_populate_sessions(request: Request, api_key: str = Depends(require_admin_key)): """ Admin endpoint to populate session database from existing telemetry files Useful for initial setup or re-populating missing data @@ -293,9 +371,16 @@ async def admin_populate_sessions(request: Request, api_key: str = Depends(verif logger.error(f"Error populating sessions: {e}", exc_info=True) raise HTTPException(status_code=500, detail="Failed to populate sessions") -@router.post('/api/admin/process-latest', tags=["General"]) + +@router.post( + '/api/admin/process-latest', + tags=["Admin"], + summary="Force-process the latest completed session", + operation_id="admin_process_latest", + responses={200: {"model": ProcessLatestResponse}, **ADMIN_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") -async def admin_process_latest(request: Request, api_key: str = Depends(verify_api_key)): +async def admin_process_latest(request: Request, api_key: str = Depends(require_admin_key)): """ Admin endpoint to manually trigger processing of the latest session Useful for testing or forcing immediate processing @@ -309,9 +394,16 @@ async def admin_process_latest(request: Request, api_key: str = Depends(verify_a logger.error(f"Error in manual processing: {e}", exc_info=True) raise HTTPException(status_code=500, detail="Failed to process latest session") -@router.get('/api/admin/processor-status', tags=["General"]) + +@router.get( + '/api/admin/processor-status', + tags=["Admin"], + summary="Background processor status", + operation_id="admin_processor_status", + responses={200: {"model": ProcessorStatusResponse}, **ADMIN_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") -async def admin_processor_status(request: Request, api_key: str = Depends(verify_api_key)): +async def admin_processor_status(request: Request, api_key: str = Depends(require_admin_key)): """ Get detailed status of the background processor Shows what sessions have been processed and processor state @@ -330,12 +422,22 @@ async def admin_processor_status(request: Request, api_key: str = Depends(verify raise HTTPException(status_code=500, detail="Failed to get processor status") -@router.get('/api/admin/mongodb/overview', tags=["General"]) +@router.get( + '/api/admin/mongodb/overview', + tags=["Admin"], + summary="MongoDB collection overview", + operation_id="admin_mongodb_overview", + responses={ + 200: {"model": MongoOverviewResponse}, + 400: _err("version was not 'v1' or 'v2'."), + **ADMIN_ERROR_RESPONSES, + }, +) @apply_tiered_limit("standard") async def admin_mongodb_overview( request: Request, version: str = Query("v2", description="Mongo data source version: v1 or v2"), - api_key: str = Depends(verify_api_key), + api_key: str = Depends(require_admin_key), ): """ Get high-level MongoDB coverage stats by year/collection for admin visibility. @@ -352,7 +454,17 @@ async def admin_mongodb_overview( raise HTTPException(status_code=500, detail="Failed to fetch MongoDB overview") -@router.get('/api/admin/mongodb/sessions-with-data', tags=["General"]) +@router.get( + '/api/admin/mongodb/sessions-with-data', + tags=["Admin"], + summary="MongoDB session/plot-type coverage", + operation_id="admin_mongodb_sessions_with_data", + responses={ + 200: {"model": MongoSessionsCoverageResponse}, + 400: _err("version was not 'v1' or 'v2'."), + **ADMIN_ERROR_RESPONSES, + }, +) @apply_tiered_limit("standard") async def admin_mongodb_sessions_with_data( request: Request, @@ -361,8 +473,10 @@ async def admin_mongodb_sessions_with_data( gp_id: Optional[str] = Query(None, description="Filter by GP ID (example: 2025_AUS)"), session_type: Optional[str] = Query(None, description="Filter by session type (FP1, FP2, Q, S, R, etc.)"), include_empty: bool = Query(False, description="Include sessions that exist but have no stored plot data"), - limit_per_year: int = Query(200, ge=1, le=1000, description="Max GP documents to scan per year when gp_id is not provided"), - api_key: str = Depends(verify_api_key), + limit_per_year: int = Query( + 200, ge=1, le=1000, description="Max GP documents to scan per year when gp_id is not provided" + ), + api_key: str = Depends(require_admin_key), ): """ Inspect MongoDB and list which sessions contain data, and which plot/data types exist per session. @@ -390,11 +504,381 @@ async def admin_mongodb_sessions_with_data( raise HTTPException(status_code=500, detail="Failed to fetch MongoDB session coverage") +# ============================================================================ +# PLOT INVENTORY & BACKFILL (V2) +# ============================================================================ + +@router.get( + '/api/admin/plots/missing', + tags=["Admin"], + summary="Ungenerated V2 plots for a scope", + operation_id="admin_plots_missing", + responses={200: {"model": PlotInventoryResponse}, **ADMIN_ERROR_RESPONSES}, +) +@apply_tiered_limit("standard") +async def admin_plots_missing( + request: Request, + year: Optional[int] = Query(None, ge=2018, le=2030, description="Season; all v2 years if omitted"), + gp: Optional[str] = Query(None, description="Round number, Event Key, or Event Name"), + session: Optional[str] = Query(None, description="Session name/abbrev (e.g. R, Q, FP1)"), + api_key: str = Depends(require_admin_key), +): + """Report which singleton V2 plots/data are still ungenerated in MongoDB. + + Schedule-driven, so entirely-absent sessions/GPs are flagged too. Read-only. + """ + try: + return await run_in_threadpool( + plot_inventory.compute_missing, year=year, identifier=gp, session=session + ) + except Exception as e: + logger.error(f"Error computing missing plots: {e}", exc_info=True) + raise HTTPException(status_code=500, detail="Failed to compute missing plots") + + +@router.get( + '/api/admin/plots/catalog', + tags=["Admin"], + summary="Every generatable V2 feature", + operation_id="admin_plots_catalog", + responses={200: {"model": PlotCatalogResponse}, **ADMIN_ERROR_RESPONSES}, +) +@apply_tiered_limit("standard") +async def admin_plots_catalog( + request: Request, + session: Optional[str] = Query(None, description="Filter to one session (e.g. R, Q, FP1)"), + api_key: str = Depends(require_admin_key), +): + """Every generatable V2 feature, so clients build selectors from the registry. + + Grouped by ``kind`` (singleton / per_driver / per_pair / per_driver_lap / + season / career). ``cost`` flags how expensive a family is to expand. + """ + entries = ( + registry.catalog_for_session(session) if session else list(registry.FEATURE_CATALOG) + ) + return { + "count": len(entries), + "features": [e.as_dict() for e in entries], + "session": session, + } + + +@router.get( + '/api/admin/plots/season', + tags=["Admin"], + summary="Season-scope payload inventory", + operation_id="admin_plots_season", + responses={200: {"model": SeasonInventoryResponse}, **ADMIN_ERROR_RESPONSES}, +) +@apply_tiered_limit("standard") +async def admin_plots_season( + request: Request, + year: int = Query(..., ge=2018, le=2030), + api_key: str = Depends(require_admin_key), +): + """Which season-scope payloads exist for a year (separate from GP sessions).""" + return await run_in_threadpool(plot_inventory.season_inventory, year) + + +@router.get( + '/api/admin/sessions/{year}/{gp}/{session}/drivers', + tags=["Admin"], + summary="Driver list for the admin pickers", + operation_id="admin_session_drivers", + responses={ + 200: {"model": SessionDriversResponse}, + 502: _err("Could not resolve session drivers (upstream/livetiming failure)."), + **ADMIN_ERROR_RESPONSES, + }, +) +@apply_tiered_limit("standard") +async def admin_session_drivers( + request: Request, + year: int, + gp: str, + session: str, + include_laps: bool = Query(False, description="Also return each driver's lap numbers"), + api_key: str = Depends(require_admin_key), +): + """Driver list (and optionally lap numbers) for the admin pickers.""" + try: + drivers = await run_in_threadpool(registry.session_drivers, year, gp, session) + payload: Dict[str, Any] = {"year": year, "gp": gp, "session": session, + "drivers": drivers} + if include_laps: + laps = await run_in_threadpool(registry.session_driver_laps, year, gp, session) + payload["laps"] = laps + all_laps = [lap for values in laps.values() for lap in values] + payload["lap_range"] = ( + {"min": min(all_laps), "max": max(all_laps)} if all_laps else None + ) + return payload + except Exception as e: + logger.error(f"Error resolving session drivers: {e}", exc_info=True) + raise HTTPException(status_code=502, detail="Could not resolve session drivers") + + +def _selection_from_request( + features: Optional[List[str]], + kinds: Optional[List[str]], + drivers: Optional[List[str]], + pairs: Optional[List[str]], + lap_from: Optional[int], + lap_to: Optional[int], + windows: Optional[List[int]], + career_years: Optional[List[int]], + include_comparisons: bool, +) -> plot_inventory.Selection: + """Build a Selection from query params, or fall back to the legacy flag.""" + if not any([features, kinds, drivers, pairs, windows, career_years]): + return plot_inventory.Selection.from_legacy(include_comparisons) + + parsed_pairs = None + if pairs: + parsed_pairs = [] + for raw in pairs: + parts = [p.strip().upper() for p in str(raw).split(",") if p.strip()] + if len(parts) != 2: + raise HTTPException( + status_code=422, + detail=f"pair must be two comma-separated TLAs, got {raw!r}", + ) + parsed_pairs.append((parts[0], parts[1])) + + return plot_inventory.Selection( + features=list(features) if features else None, + include_kinds=set(kinds) if kinds else None, + drivers=[d.strip().upper() for d in drivers] if drivers else None, + pairs=parsed_pairs, + lap_from=lap_from, + lap_to=lap_to, + windows=list(windows) if windows else None, + career_years=list(career_years) if career_years else None, + ) + + +@router.post( + '/api/admin/plots/estimate', + tags=["Admin"], + summary="Cost a backfill selection (dry run)", + operation_id="admin_plots_estimate", + responses={ + 200: {"model": PlanEstimateResponse}, + 422: _err('A `pairs` entry was not exactly two comma-separated TLAs (e.g. "VER,NOR").'), + **ADMIN_ERROR_RESPONSES, + }, +) +@apply_tiered_limit("standard") +async def admin_plots_estimate( + request: Request, + year: Optional[int] = Query(None, ge=2018, le=2030), + gp: Optional[str] = Query(None, description="Round number, Event Key, or Event Name"), + session: Optional[str] = Query(None, description="Session name/abbrev (e.g. R, Q, FP1)"), + features: Optional[List[str]] = Query(None, description="Feature keys from /plots/catalog"), + kinds: Optional[List[str]] = Query(None, description="Select whole groups (e.g. per_driver)"), + drivers: Optional[List[str]] = Query(None, description="Restrict to these TLAs"), + pairs: Optional[List[str]] = Query(None, description='Driver pairs as "VER,NOR"'), + lap_from: Optional[int] = Query(None, ge=1, description="Required for per-lap features"), + lap_to: Optional[int] = Query(None, ge=1), + windows: Optional[List[int]] = Query(None, description="season_form rolling windows"), + career_years: Optional[List[int]] = Query(None, description="Years for the career radar"), + include_comparisons: bool = Query(False, description="Legacy: all per-driver + per-pair"), + api_key: str = Depends(require_admin_key), +): + """Cost a selection **without generating anything**. + + A full-catalog backfill of a single race is thousands of units, so the unit + count and per-feature breakdown belong in front of the operator before they + commit — not discovered from a progress bar. + """ + selection = _selection_from_request( + features, kinds, drivers, pairs, lap_from, lap_to, + windows, career_years, include_comparisons, + ) + try: + return await run_in_threadpool( + plot_inventory.estimate_plan, + year=year, identifier=gp, session=session, selection=selection, + ) + except Exception as e: + logger.error(f"Error estimating plot generation: {e}", exc_info=True) + raise HTTPException(status_code=500, detail="Failed to estimate plot generation") + + +@router.post( + '/api/admin/plots/generate', + tags=["Admin"], + summary="Start a V2 plot backfill job", + operation_id="admin_plots_generate", + responses={ + 200: {"model": PlotGenJobResponse}, + 409: _err( + "A live job already covers an overlapping (year, gp, session) scope. The detail " + "payload carries the conflicting job_id/scope; pass force_concurrent=true to run anyway." + ), + 422: _err('A `pairs` entry was not exactly two comma-separated TLAs (e.g. "VER,NOR").'), + **ADMIN_ERROR_RESPONSES, + }, +) +@apply_tiered_limit("standard") +async def admin_plots_generate( + request: Request, + year: int = Query(..., ge=2018, le=2030, description="Season to backfill"), + gp: Optional[str] = Query(None, description="Round number, Event Key, or Event Name"), + session: Optional[str] = Query(None, description="Session name/abbrev (e.g. R, Q, FP1)"), + force: bool = Query(False, description="Regenerate even if already present"), + include_comparisons: bool = Query( + False, description="Legacy: generate every per-driver and per-pair comparison" + ), + features: Optional[List[str]] = Query(None, description="Feature keys from /plots/catalog"), + kinds: Optional[List[str]] = Query(None, description="Select whole groups (e.g. per_driver)"), + drivers: Optional[List[str]] = Query(None, description="Restrict to these TLAs"), + pairs: Optional[List[str]] = Query(None, description='Driver pairs as "VER,NOR"'), + lap_from: Optional[int] = Query(None, ge=1, description="Required for per-lap features"), + lap_to: Optional[int] = Query(None, ge=1), + windows: Optional[List[int]] = Query(None, description="season_form rolling windows"), + career_years: Optional[List[int]] = Query(None, description="Years for the career radar"), + concurrency: int = Query(1, ge=1, le=plot_inventory.MAX_CONCURRENCY, + description="Parallel sessions (never parallel within a session)"), + force_concurrent: bool = Query(False, description="Allow overlapping an in-flight job"), + api_key: str = Depends(require_admin_key), +): + """Kick off a background job that generates the selected V2 data into MongoDB. + + Returns immediately with a ``job_id``; poll ``/api/admin/plots/jobs/{job_id}``. + Rejects with 409 when a live job already covers an overlapping scope, since + two backfills over the same sessions duplicate every upstream fetch. + """ + selection = _selection_from_request( + features, kinds, drivers, pairs, lap_from, lap_to, + windows, career_years, include_comparisons, + ) + scope = {"year": year, "gp": gp, "session": session} + + if not force_concurrent: + conflict = await run_in_threadpool(plot_inventory.find_conflicting_job, scope) + if conflict: + raise HTTPException( + status_code=409, + detail={ + "message": "A backfill covering this scope is already running", + "job_id": conflict["job_id"], + "scope": conflict.get("scope"), + "hint": "Pass force_concurrent=true to run anyway", + }, + ) + + try: + job = plot_inventory.start_generation_job( + year=year, + identifier=gp, + session=session, + force=force, + include_comparisons=include_comparisons, + selection=selection, + concurrency=concurrency, + ) + return job.as_dict() + except Exception as e: + logger.error(f"Error starting plot generation: {e}", exc_info=True) + raise HTTPException(status_code=500, detail="Failed to start plot generation") + + +@router.get( + '/api/admin/plots/jobs', + tags=["Admin"], + summary="Backfill job history", + operation_id="admin_plots_jobs", + responses={200: {"model": JobsListResponse}, **ADMIN_ERROR_RESPONSES}, +) +@apply_tiered_limit("standard") +async def admin_plots_jobs( + request: Request, + limit: int = Query(50, ge=1, le=500), + status: Optional[str] = Query(None, description="queued|running|completed|failed|cancelled"), + api_key: str = Depends(require_admin_key), +): + """Durable job history, newest first (survives restarts and spans workers). + + Part of the backfill workflow: cost a selection with ``POST + /api/admin/plots/estimate``, start it with ``POST /api/admin/plots/generate`` + (returns a ``job_id``), then poll progress here or at + ``GET /api/admin/plots/jobs/{job_id}``, and optionally + ``POST /api/admin/plots/jobs/{job_id}/cancel`` to stop it early. + """ + jobs = await run_in_threadpool(plot_inventory.list_jobs, limit, status) + return {"count": len(jobs), "jobs": jobs} + + +@router.get( + '/api/admin/plots/jobs/{job_id}', + tags=["Admin"], + summary="Single backfill job status", + operation_id="admin_plots_job_status", + responses={ + 200: {"model": JobRecord}, + 404: _err("No job with that id, in memory or in MongoDB."), + **ADMIN_ERROR_RESPONSES, + }, +) +@apply_tiered_limit("standard") +async def admin_plots_job_status( + request: Request, + job_id: str, + api_key: str = Depends(require_admin_key), +): + """Status/progress of a single job, from memory or MongoDB.""" + job = await run_in_threadpool(plot_inventory.get_job_dict, job_id) + if job is None: + raise HTTPException(status_code=404, detail="Job not found") + return job + + +@router.post( + '/api/admin/plots/jobs/{job_id}/cancel', + tags=["Admin"], + summary="Cancel a running backfill job", + operation_id="admin_plots_job_cancel", + responses={ + 200: {"model": JobCancelResponse}, + 404: _err("No job with that id, in memory or in MongoDB."), + 409: _err("Job is already in a terminal state (completed/failed/cancelled)."), + **ADMIN_ERROR_RESPONSES, + }, +) +@apply_tiered_limit("standard") +async def admin_plots_job_cancel( + request: Request, + job_id: str, + api_key: str = Depends(require_admin_key), +): + """Request cancellation. + + Sets a flag only — the worker notices and stops at its next progress + flush, which happens at most every ~2 seconds or every 25 completed units, + whichever comes first. Not synchronous with this call. + """ + job = await run_in_threadpool(plot_inventory.get_job_dict, job_id) + if job is None: + raise HTTPException(status_code=404, detail="Job not found") + cancelled = await run_in_threadpool(plot_inventory.cancel_job, job_id) + if not cancelled: + raise HTTPException(status_code=409, detail=f"Job is already {job['status']}") + return {"job_id": job_id, "cancel_requested": True} + + # ============================================================================ # USER / API-KEY MANAGEMENT # ============================================================================ -@router.get('/api/admin/users', tags=["General"]) +@router.get( + '/api/admin/users', + tags=["Admin"], + summary="List registered users", + operation_id="admin_list_users", + responses={200: {"model": UsersListResponse}, **ADMIN_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") async def admin_list_users( request: Request, @@ -402,11 +886,18 @@ async def admin_list_users( skip: int = Query(0, ge=0), api_key: str = Depends(require_admin_key), ): + """Page through the ``users`` collection, newest first. ``password_hash`` is never returned.""" users = await run_in_threadpool(_users.list_users, limit, skip) return {"count": len(users), "users": users} -@router.get('/api/admin/keys', tags=["General"]) +@router.get( + '/api/admin/keys', + tags=["Admin"], + summary="List API keys", + operation_id="admin_list_keys", + responses={200: {"model": KeysListResponse}, **ADMIN_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") async def admin_list_keys( request: Request, @@ -414,11 +905,18 @@ async def admin_list_keys( limit: int = Query(200, ge=1, le=1000), api_key: str = Depends(require_admin_key), ): + """List issued API keys, optionally scoped to one owner. ``key_hash`` and the raw key are never returned.""" keys = await run_in_threadpool(_keys.list_all, owner_id, limit) return {"count": len(keys), "keys": keys} -@router.get('/api/admin/keys/verify', tags=["General"]) +@router.get( + '/api/admin/keys/verify', + tags=["Admin"], + summary="Verify a raw API key against MongoDB", + operation_id="admin_verify_key", + responses={200: {"model": KeyVerifyResponse}, **ADMIN_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") async def admin_verify_key( request: Request, @@ -471,13 +969,28 @@ def _lookup(): } -@router.post('/api/admin/keys/{key_id}/revoke', tags=["General"]) +@router.post( + '/api/admin/keys/{key_id}/revoke', + tags=["Admin"], + summary="Revoke an API key (destructive)", + operation_id="admin_revoke_key", + responses={ + 200: {"model": KeyRevokeResponse}, + 404: _err("No key with that id."), + **ADMIN_ERROR_RESPONSES, + }, +) @apply_tiered_limit("standard") async def admin_revoke_key( request: Request, key_id: str, api_key: str = Depends(require_admin_key), ): + """Permanently revoke an API key. Not reversible — a new key must be issued to replace it. + + Also evicts the key's entry from the Redis auth cache so the revocation + takes effect immediately rather than waiting out the cache TTL. + """ existing = await run_in_threadpool(_keys.find_by_id, key_id) if not existing: raise HTTPException(status_code=404, detail="Key not found") @@ -487,7 +1000,13 @@ async def admin_revoke_key( return {"id": key_id, "revoked": bool(revoked)} -@router.get('/api/admin/usage/top', tags=["General"]) +@router.get( + '/api/admin/usage/top', + tags=["Admin"], + summary="Top API keys by request volume", + operation_id="admin_usage_top", + responses={200: {"model": UsageTopResponse}, **ADMIN_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") async def admin_usage_top( request: Request, @@ -495,6 +1014,7 @@ async def admin_usage_top( limit: int = Query(20, ge=1, le=200), api_key: str = Depends(require_admin_key), ): + """Busiest keys in the trailing window, joined with key metadata (prefix/owner/tier/label).""" rows = await run_in_threadpool(_key_usage.top_keys, hours, limit) # Attach key metadata (prefix, owner, tier, label) by joining on key_hash. enriched: List[Dict[str, Any]] = [] @@ -510,7 +1030,17 @@ async def admin_usage_top( return {"window_hours": hours, "count": len(enriched), "rows": enriched} -@router.get('/api/admin/usage/keys/{key_id}', tags=["General"]) +@router.get( + '/api/admin/usage/keys/{key_id}', + tags=["Admin"], + summary="Usage summary for one key", + operation_id="admin_usage_for_key", + responses={ + 200: {"model": UsageForKeyResponse}, + 404: _err("No key with that id."), + **ADMIN_ERROR_RESPONSES, + }, +) @apply_tiered_limit("standard") async def admin_usage_for_key( request: Request, @@ -518,6 +1048,7 @@ async def admin_usage_for_key( hours: int = Query(24, ge=1, le=720), api_key: str = Depends(require_admin_key), ): + """Hourly-bucketed request/error summary for one key over the trailing window.""" doc = await run_in_threadpool(_keys.find_by_id, key_id) if not doc: raise HTTPException(status_code=404, detail="Key not found") @@ -532,7 +1063,13 @@ async def admin_usage_for_key( } -@router.get('/api/admin/dashboard', tags=["General"]) +@router.get( + '/api/admin/dashboard', + tags=["Admin"], + summary="Platform-wide usage dashboard", + operation_id="admin_dashboard", + responses={200: {"model": AdminDashboardResponse}, **ADMIN_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") async def admin_dashboard( request: Request, @@ -564,7 +1101,13 @@ async def admin_dashboard( } -@router.get('/api/admin/peak-hours', tags=["General"]) +@router.get( + '/api/admin/peak-hours', + tags=["Admin"], + summary="Platform-wide hour-of-day request distribution", + operation_id="admin_peak_hours", + responses={200: {"model": PeakHoursResponse}, **ADMIN_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") async def admin_peak_hours( request: Request, @@ -577,7 +1120,13 @@ async def admin_peak_hours( return {"days": days, "peak_hour_utc": peak, "by_hour": series} -@router.get('/api/admin/quota-usage', tags=["General"]) +@router.get( + '/api/admin/quota-usage', + tags=["Admin"], + summary="Per-key monthly quota usage", + operation_id="admin_quota_usage", + responses={200: {"model": QuotaUsageResponse}, **ADMIN_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") async def admin_quota_usage( request: Request, @@ -615,7 +1164,17 @@ async def admin_quota_usage( return {"count": len(rows), "rows": rows} -@router.get('/api/admin/users/{user_id}/usage', tags=["General"]) +@router.get( + '/api/admin/users/{user_id}/usage', + tags=["Admin"], + summary="Per-user usage across all their keys", + operation_id="admin_user_usage", + responses={ + 200: {"model": UserUsageResponse}, + 404: _err("No user with that id."), + **ADMIN_ERROR_RESPONSES, + }, +) @apply_tiered_limit("standard") async def admin_user_usage( request: Request, @@ -664,7 +1223,17 @@ async def admin_user_usage( } -@router.get('/api/admin/keys/{key_id}/analytics', tags=["General"]) +@router.get( + '/api/admin/keys/{key_id}/analytics', + tags=["Admin"], + summary="Single-key analytics and quota", + operation_id="admin_key_analytics", + responses={ + 200: {"model": KeyAnalyticsResponse}, + 404: _err("No key with that id."), + **ADMIN_ERROR_RESPONSES, + }, +) @apply_tiered_limit("standard") async def admin_key_analytics( request: Request, @@ -710,12 +1279,19 @@ async def admin_key_analytics( } -@router.get('/api/admin/performance', tags=["General"]) +@router.get( + '/api/admin/performance', + tags=["Admin"], + summary="In-process request performance stats", + operation_id="admin_performance", + responses={200: {"model": PerformanceResponse}, **ADMIN_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") async def admin_performance( request: Request, api_key: str = Depends(require_admin_key), ): + """Summary + per-endpoint counters from the in-memory RequestTracker (resets on restart).""" tracker = get_request_tracker() return { "summary": tracker.get_summary(), diff --git a/src/api/routers/admin_cache.py b/src/api/routers/admin_cache.py new file mode 100644 index 0000000..f4a86aa --- /dev/null +++ b/src/api/routers/admin_cache.py @@ -0,0 +1,139 @@ +"""Admin API for the durable V2 caches. + +Two caches sit under the V2 pipeline and, until this router, neither had any +admin visibility at all: no size, no age, no way to purge a poisoned entry. + +* **Raw streams** — GridFS bucket ``v2_raw_cache``, one gzipped blob per + ``(session, stream)``. This is where the multi-megabyte ``CarData.z`` and + ``Position.z`` payloads live. +* **Derived bundles** — collection ``v2_session_cache``, one small document per + session holding the lap-indexed structures the race features consume. + +Purging matters because both are keyed by a ``SCHEMA_VERSION``: after a bump, +old entries are silently unreadable but still occupy storage. The inventory +surfaces that as ``schema_drift``. +""" +from __future__ import annotations + +from typing import Optional + +from fastapi import APIRouter, Depends, HTTPException, Query, Request +from fastapi.concurrency import run_in_threadpool + +from src.api.admin_security import admin_api_gate +from src.api.routers.admin import ADMIN_ERROR_RESPONSES, _err, require_admin_key +from src.api.schemas.admin import ( + CacheInventoryResponse, + CachePrewarmResponse, + CachePurgeBundleResponse, + CachePurgeRawResponse, +) +from src.core.logging import get_logger +from src.core.security.rate_limiting import apply_tiered_limit +from src.repositories import raw_stream_cache, session_cache +from src.services.admin_views import cache_inventory + +logger = get_logger(__name__) + + +router = APIRouter(prefix="/api/admin/cache", tags=["Admin"], + dependencies=[Depends(admin_api_gate)]) + + +@router.get( + "/inventory", + summary="V2 cache inventory (raw + derived)", + operation_id="admin_cache_inventory", + responses={200: {"model": CacheInventoryResponse}, **ADMIN_ERROR_RESPONSES}, +) +@apply_tiered_limit("standard") +async def admin_cache_inventory( + request: Request, + year: Optional[int] = Query(None, ge=2018, le=2030), + api_key: str = Depends(require_admin_key), +): + """What the durable V2 caches currently hold: sizes, ages, schema drift.""" + return await run_in_threadpool(cache_inventory, year) + + +@router.post( + "/purge/raw/{session_key}", + summary="Delete cached raw streams for a session (destructive)", + operation_id="admin_cache_purge_raw", + responses={ + 200: {"model": CachePurgeRawResponse}, + 404: _err("No cached raw streams for that session key."), + **ADMIN_ERROR_RESPONSES, + }, +) +@apply_tiered_limit("standard") +async def admin_cache_purge_raw( + request: Request, + session_key: str, + api_key: str = Depends(require_admin_key), +): + """Permanently drop every raw stream blob (GridFS) for one session + (``{year}_{round}_{session}``). Not reversible — the streams are re-fetched + from livetiming the next time something needs them.""" + removed = await run_in_threadpool(raw_stream_cache.delete_raw_streams, session_key) + if not removed: + raise HTTPException(status_code=404, detail="No cached streams for that session") + return {"session_key": session_key, "removed": removed} + + +@router.post( + "/purge/bundle/{doc_id}", + summary="Delete one derived session bundle (destructive)", + operation_id="admin_cache_purge_bundle", + responses={ + 200: {"model": CachePurgeBundleResponse}, + 404: _err("No derived bundle with that document id."), + **ADMIN_ERROR_RESPONSES, + }, +) +@apply_tiered_limit("standard") +async def admin_cache_purge_bundle( + request: Request, + doc_id: str, + api_key: str = Depends(require_admin_key), +): + """Permanently drop one derived bundle. Not reversible — it is recomputed + from the raw streams (or re-fetched, if those are also gone) on next read.""" + if not await run_in_threadpool(session_cache.delete_bundle, doc_id): + raise HTTPException(status_code=404, detail="No bundle with that id") + return {"doc_id": doc_id, "removed": True} + + +@router.post( + "/prewarm", + summary="Prewarm both cache tiers for a session", + operation_id="admin_cache_prewarm", + responses={ + 200: {"model": CachePrewarmResponse}, + 502: _err("Prewarm failed (upstream/livetiming fetch error)."), + **ADMIN_ERROR_RESPONSES, + }, +) +@apply_tiered_limit("standard") +async def admin_cache_prewarm( + request: Request, + year: int = Query(..., ge=2018, le=2030), + gp: str = Query(..., description="Round number, Event Key, or Event Name"), + session: str = Query(..., description="Session name/abbrev (e.g. R, Q, FP1)"), + api_key: str = Depends(require_admin_key), +): + """Populate both cache tiers for a session up front. + + Reuses the background processor's prewarm so the admin path and the + automatic post-session path warm exactly the same streams. + """ + from src.workers.processor import get_processor + + try: + await run_in_threadpool( + get_processor().prewarm_session_streams, year, gp, session, gp + ) + except Exception as exc: + logger.error("Prewarm failed for %s %s %s: %s", year, gp, session, exc, exc_info=True) + raise HTTPException(status_code=502, detail="Prewarm failed") + return {"year": year, "gp": gp, "session": session, "prewarmed": True} diff --git a/src/api/routers/admin_circuits.py b/src/api/routers/admin_circuits.py new file mode 100644 index 0000000..d368c40 --- /dev/null +++ b/src/api/routers/admin_circuits.py @@ -0,0 +1,127 @@ +"""Admin API for tracing and inspecting derived circuit layouts. + +Circuit geometry is normally seeded from api.multiviewer.app. A brand-new +circuit -- Madring in 2026 was the first -- can run a whole weekend before +multiviewer publishes it, and until then every map-shaped feature degrades +(``/api/v2/telemetry/track-map`` 404s, the track-map plot renders unrotated, +corner-duel falls back to sequential numbers). :mod:`src.services.circuit_derivation` +fills that gap by tracing the outline from one lap of livetiming position data. + +``GET /status`` reports, per scheduled event in a season, whether a layout is + stored and where it came from (schedule-driven, so a circuit + multiviewer hasn't listed yet shows up as missing rather than + silently absent). +``POST /derive`` runs the derivation. It defaults to ``dry_run=true`` so an + operator can inspect the traced outline and corner count + before anything is written; the written result is provisional + (``source="telemetry"``) and gets replaced once ``circuits_sync`` + picks up multiviewer's real layout. + +**No ``from __future__ import annotations`` in this module.** These endpoints +combine a Pydantic body with ``@apply_tiered_limit``; PEP 563 stringifies the +annotation, slowapi's wrapper stops FastAPI resolving it, and the body silently +degrades into a required *query* parameter (422 ``Field required, loc: +['query', 'body']``). See the trap documented in ``CLAUDE.md``. +""" +from typing import Any, Dict + +from fastapi import APIRouter, Depends, HTTPException, Query, Request +from fastapi.concurrency import run_in_threadpool + +from src.api.admin_security import admin_api_gate +from src.api.deps import validate_driver, validate_gp, validate_session +from src.api.routers.admin import ADMIN_ERROR_RESPONSES, _err, require_admin_key +from src.api.schemas.admin import ( + CircuitDeriveRequest, + CircuitDeriveResponse, + CircuitLayoutStatusResponse, +) +from src.core.logging import get_logger +from src.core.security.rate_limiting import apply_tiered_limit +from src.services.admin_views import circuit_layout_status +from src.services.circuit_derivation import ( + CircuitDerivationError, + DeriveOptions, + LayoutExistsError, + derive_and_store, +) + +logger = get_logger(__name__) + +router = APIRouter(prefix="/api/admin/circuits", tags=["Admin"], + dependencies=[Depends(admin_api_gate)]) + + +@router.get( + "/status", + summary="List which circuits in a season have a stored layout", + operation_id="admin_circuits_status", + responses={200: {"model": CircuitLayoutStatusResponse}, **ADMIN_ERROR_RESPONSES}, +) +@apply_tiered_limit("standard") +async def admin_circuits_status( + request: Request, + year: int = Query(..., ge=2018, le=2030, description="Season year."), + api_key: str = Depends(require_admin_key), +) -> Dict[str, Any]: + """Per-event layout coverage for a season. + + Schedule-driven (enumerates every event on the calendar) rather than a + directory scan, so a brand-new circuit with no file at all is reported as + *missing* instead of not existing at all. Read-only. + """ + return await run_in_threadpool(circuit_layout_status, year) + + +@router.post( + "/derive", + summary="Derive a circuit layout from a session's fastest lap", + operation_id="admin_circuits_derive", + responses={ + 200: {"model": CircuitDeriveResponse}, + 400: _err("Invalid gp/session/driver."), + 404: _err("Event or session not found upstream."), + 409: _err("A layout already exists for this circuit/year; pass overwrite=true."), + 422: _err("No candidate lap produced a closed outline."), + 503: _err("Telemetry not published upstream yet."), + **ADMIN_ERROR_RESPONSES, + }, +) +@apply_tiered_limit("standard") +async def admin_circuits_derive( + request: Request, + body: CircuitDeriveRequest, + api_key: str = Depends(require_admin_key), +) -> Dict[str, Any]: + """Trace a track outline and corners from one lap of ``Position.z``. + + Defaults to ``dry_run=true`` -- inspect the traced outline and corner + count before writing anything. The stored result is provisional + (``source="telemetry"``) and is replaced once ``circuits_sync`` picks up + multiviewer's published layout for this circuit. ``Position.z`` and + ``CarData.z`` are multi-megabyte livetiming streams, so a cold call + (nothing cached yet) takes roughly 30 seconds. + """ + year = body.year + gp = validate_gp(body.gp) + session = validate_session(body.session) + driver = validate_driver(body.driver) + + options = DeriveOptions(driver=driver, rotation=body.rotation, min_turn_deg=body.min_turn_deg) + try: + result = await run_in_threadpool( + derive_and_store, year, gp, session, options, + overwrite=body.overwrite, dry_run=body.dry_run, + ) + except LayoutExistsError as exc: + raise HTTPException(status_code=409, detail=str(exc)) from exc + except CircuitDerivationError as exc: + raise HTTPException(status_code=422, detail=str(exc)) from exc + + result.pop("layout", None) + if result["written"]: + logger.warning( + "Admin circuit layout written: %s %s -> %s", + result["year"], result["circuit_id"], result["path"], + ) + return result diff --git a/src/api/routers/admin_data.py b/src/api/routers/admin_data.py new file mode 100644 index 0000000..894d9df --- /dev/null +++ b/src/api/routers/admin_data.py @@ -0,0 +1,83 @@ +"""Admin API for browsing and pruning stored V2 plot data. + +The plot inventory answers "what is *missing*" against the singleton +expectation set. It cannot answer "what is actually *stored*", which is what you +need when a payload was generated from bad upstream data: the inventory reports +it as present, so the backfill skips it, and nothing regenerates it until the +document is removed. Deleting stored plot data was not possible anywhere in the +repositories layer before this. +""" +from __future__ import annotations + +from typing import Optional + +from fastapi import APIRouter, Depends, HTTPException, Query, Request +from fastapi.concurrency import run_in_threadpool + +from src.api.admin_security import admin_api_gate +from src.api.routers.admin import ADMIN_ERROR_RESPONSES, _err, require_admin_key +from src.api.schemas.admin import DataBrowseResponse, DataDeleteResponse +from src.core.logging import get_logger +from src.core.security.rate_limiting import apply_tiered_limit +from src.repositories.mongo import MongoDBManager +from src.services.admin_views import browse_stored_data + +logger = get_logger(__name__) + + +router = APIRouter(prefix="/api/admin/data", tags=["Admin"], + dependencies=[Depends(admin_api_gate)]) + + +@router.get( + "/browse", + summary="Browse stored V2 data types for a scope", + operation_id="admin_data_browse", + responses={200: {"model": DataBrowseResponse}, **ADMIN_ERROR_RESPONSES}, +) +@apply_tiered_limit("standard") +async def admin_data_browse( + request: Request, + year: int = Query(..., ge=2018, le=2030), + gp: Optional[str] = Query(None, description="Event name or gp_id"), + session: Optional[str] = Query(None, description="Session abbrev (e.g. R, Q, FP1)"), + api_key: str = Depends(require_admin_key), +): + """Everything stored for a scope, including legacy/orphan keys.""" + return await run_in_threadpool(browse_stored_data, year, gp, session) + + +@router.delete( + "/{year}/{gp_id}/{session_type}/{data_type}", + summary="Delete stored analysis data (destructive)", + operation_id="admin_data_delete", + responses={ + 200: {"model": DataDeleteResponse}, + 404: _err("No such stored data_type for that year/gp/session."), + **ADMIN_ERROR_RESPONSES, + }, +) +@apply_tiered_limit("standard") +async def admin_data_delete( + request: Request, + year: int, + gp_id: str, + session_type: str, + data_type: str, + api_key: str = Depends(require_admin_key), +): + """Permanently delete one stored ``data_type`` entry so it can be + regenerated from scratch (e.g. via ``/api/admin/plots/generate?force=true``). + Not reversible — only this entry is removed, the rest of the session's + stored data is untouched.""" + manager = MongoDBManager(year=year, version="v2") + removed = await run_in_threadpool( + manager.delete_session_data, gp_id, session_type.upper(), data_type, year + ) + if not removed: + raise HTTPException(status_code=404, detail="No such stored data_type") + logger.info("Admin deleted %s from %s %s (%s)", data_type, gp_id, session_type, year) + return { + "year": year, "gp_id": gp_id, "session_type": session_type, + "data_type": data_type, "deleted": True, + } diff --git a/src/api/routers/admin_storage.py b/src/api/routers/admin_storage.py new file mode 100644 index 0000000..a814d88 --- /dev/null +++ b/src/api/routers/admin_storage.py @@ -0,0 +1,209 @@ +"""Admin API for scoped, preview-first cleanup of stored data. + +``admin_data.py`` can delete exactly one ``data_type`` from one session, and +``admin_cache.py`` can drop one raw-stream session or one bundle. Neither can +answer the operator's actual question -- "reclaim everything for the 2023 +season", or "drop every stored ``speed_distribution`` so it regenerates" -- and +neither touches the rendered PNGs under ``outputs/plots``, which had no delete +path at all and therefore grew without bound. + +This router exposes :mod:`src.services.storage_cleanup` over HTTP in two steps: + +``POST /preview`` enumerates what would be deleted and returns a + ``confirm_token`` fingerprinting that exact item set. +``POST /purge`` re-plans, and refuses unless the token still matches. + +The token is what makes the destructive endpoint safe to expose: a purge can +only ever delete something the caller has already seen listed. It is the same +double-confirmation shape the backup restore uses. + +**No ``from __future__ import annotations`` in this module.** These endpoints +combine a Pydantic body with ``@apply_tiered_limit``; PEP 563 stringifies the +annotation, slowapi's wrapper stops FastAPI resolving it, and the body silently +degrades into a required *query* parameter (422 ``Field required, loc: +['query', 'body']``). See the trap documented in ``CLAUDE.md``. +""" +from typing import Any, Dict, List, Optional + +from fastapi import APIRouter, Depends, HTTPException, Query, Request +from fastapi.concurrency import run_in_threadpool + +from src.api.admin_security import admin_api_gate +from src.api.routers.admin import ADMIN_ERROR_RESPONSES, _err, require_admin_key +from src.api.schemas.admin import ( + StorageOrphansResponse, + StoragePreviewResponse, + StoragePurgeRequest, + StoragePurgeResponse, + StorageTotalsResponse, +) +from src.core.logging import get_logger +from src.core.security.rate_limiting import apply_tiered_limit +from src.services.storage_cleanup import ( + ALL_LAYERS, + CleanupError, + CleanupScope, + execute_cleanup, + find_orphan_plot_dirs, + plan_cleanup, + storage_totals, +) + +logger = get_logger(__name__) + +router = APIRouter(prefix="/api/admin/storage", tags=["Admin"], + dependencies=[Depends(admin_api_gate)]) + + +def _build_scope( + year: Optional[int], + gp: Optional[str], + session: Optional[str], + data_type: Optional[str], + layers: Optional[List[str]], +) -> CleanupScope: + """Validate a caller-supplied scope into a :class:`CleanupScope`. + + An unknown layer name is a 400 rather than a silent no-op, because silently + ignoring it would make a purge look narrower than the caller intended. + """ + try: + return CleanupScope( + year=year, + gp=gp, + session=session, + data_type=data_type, + layers=tuple(layers) if layers else ALL_LAYERS, + ) + except ValueError as exc: + raise HTTPException(status_code=400, detail=str(exc)) from exc + + +@router.get( + "/totals", + summary="Summarise what stored data is costing", + operation_id="admin_storage_totals", + responses={200: {"model": StorageTotalsResponse}, **ADMIN_ERROR_RESPONSES}, +) +@apply_tiered_limit("standard") +async def admin_storage_totals( + request: Request, + api_key: str = Depends(require_admin_key), +) -> Dict[str, Any]: + """Headline figures across every storage layer, plus how much is + recoverable from duplicate plot directories alone. Read-only.""" + return await run_in_threadpool(storage_totals) + + +@router.get( + "/orphans", + summary="List duplicate Grand Prix plot directories", + operation_id="admin_storage_orphans", + responses={200: {"model": StorageOrphansResponse}, **ADMIN_ERROR_RESPONSES}, +) +@apply_tiered_limit("standard") +async def admin_storage_orphans( + request: Request, + api_key: str = Depends(require_admin_key), +) -> Dict[str, Any]: + """Find Grand Prix directories stored twice under different spellings. + + ``outputs/plots`` accumulated both ``2025/Abu Dhabi Grand Prix`` and + ``2025/AbuDhabiGrandPrix`` because the writer's naming convention changed + without a migration. Only one spelling is read, so the other is dead + weight. Read-only -- deciding which spelling is canonical is an operator + call, so this reports and never deletes. Feed the loser's directory name + back as a ``gp`` scope to remove it. + """ + groups = await run_in_threadpool(find_orphan_plot_dirs) + return { + "groups": groups, + "total_groups": len(groups), + "total_reclaimable_bytes": sum(g["reclaimable_bytes"] for g in groups), + } + + +@router.post( + "/preview", + summary="Preview a cleanup without deleting anything", + operation_id="admin_storage_preview", + responses={ + 200: {"model": StoragePreviewResponse}, + 400: _err("Unknown storage layer name."), + **ADMIN_ERROR_RESPONSES, + }, +) +@apply_tiered_limit("standard") +async def admin_storage_preview( + request: Request, + year: Optional[int] = Query(None, description="Season year, e.g. 2025."), + gp: Optional[str] = Query(None, description="Grand Prix: gp_id, round number or event name."), + session: Optional[str] = Query(None, description="Session type; `R` also matches legacy `Race`."), + data_type: Optional[str] = Query(None, description="A single stored feature key."), + layers: Optional[List[str]] = Query( + None, + description="Layers to include. Defaults to all: mongo, raw_streams, bundles, plots, redis.", + ), + api_key: str = Depends(require_admin_key), +) -> Dict[str, Any]: + """Enumerate every item the equivalent purge would delete. + + Strictly read-only. The returned ``confirm_token`` fingerprints this exact + item set and is required by ``/purge``; if storage changes in between, the + purge is refused rather than deleting something never previewed. + + Scoping by ``data_type`` deliberately returns no raw-stream or bundle + items: those layers are per-session, so removing them for one feature would + force every other feature of that session to re-download. + """ + scope = _build_scope(year, gp, session, data_type, layers) + return await run_in_threadpool(plan_cleanup, scope) + + +@router.post( + "/purge", + summary="Delete stored data for a scope (destructive)", + operation_id="admin_storage_purge", + responses={ + 200: {"model": StoragePurgeResponse}, + 400: _err("Unknown layer, or an unscoped purge without `allow_full_purge`."), + 409: _err("Storage changed since the preview; re-run `/preview` and confirm the new plan."), + **ADMIN_ERROR_RESPONSES, + }, +) +@apply_tiered_limit("standard") +async def admin_storage_purge( + request: Request, + body: StoragePurgeRequest, + api_key: str = Depends(require_admin_key), +) -> Dict[str, Any]: + """Permanently delete everything in scope. Not reversible. + + Requires the ``confirm_token`` from a matching ``/preview``. A scope with + no filters at all means "delete every stored year", so it additionally + requires ``allow_full_purge`` -- an accidental empty body cannot wipe the + database. + + Layers are processed durable-first and Redis last, so an interrupted run + degrades toward "the cache is cold" rather than "the payload is gone but + the cache still serves it". Per-item failures are collected and returned + rather than aborting the run. + """ + scope = _build_scope( + body.scope.year, body.scope.gp, body.scope.session, + body.scope.data_type, body.scope.layers, + ) + try: + result = await run_in_threadpool( + execute_cleanup, scope, body.confirm_token, + allow_full_purge=body.allow_full_purge, + ) + except CleanupError as exc: + message = str(exc) + status = 409 if "changed since the preview" in message else 400 + raise HTTPException(status_code=status, detail=message) from exc + logger.warning( + "Admin storage purge: scope=%s deleted=%s bytes=%s", + scope.to_dict(), result["total_deleted"], result["bytes_reclaimed"], + ) + return result diff --git a/src/api/routers/admin_ui.py b/src/api/routers/admin_ui.py index 32bbf82..14217a5 100644 --- a/src/api/routers/admin_ui.py +++ b/src/api/routers/admin_ui.py @@ -9,32 +9,65 @@ """ from __future__ import annotations +import re +from datetime import datetime, timezone +from urllib.parse import quote_plus from pathlib import Path +from typing import List, Optional -from fastapi import APIRouter, Depends, Form, HTTPException, Query, Request, status +from fastapi import APIRouter, Depends, Form, HTTPException, Path as PathParam, Query, Request, status from fastapi.concurrency import run_in_threadpool -from fastapi.responses import HTMLResponse, RedirectResponse +from fastapi.responses import FileResponse, HTMLResponse, JSONResponse, RedirectResponse from fastapi.templating import Jinja2Templates from src.api.admin_security import ( - NO_INDEX_HEADERS, apply_no_index, check_login_allowed, - compare_cookie, + create_session_token, csrf_token_for, enforce_ip_allowlist, enforce_ui_rate_limit, record_login_failure, record_login_success, verify_csrf, + verify_session_token, ) from src.core.config import settings +from src.core.exceptions import DataNotAvailableError, SessionNotFoundError, UpstreamUnavailableError +from src.core.logging import get_logger from src.core.observability.monitoring import get_request_tracker from src.core.security.api_keys import invalidate_key_cache from src.core.security.rate_limiting import limits_for_tier +from src.ingestion.circuits_store import find_circuit_file from src.repositories import api_key_usage as _key_usage from src.repositories import api_keys as _keys +from src.repositories import raw_stream_cache, session_cache from src.repositories import users as _users +from src.repositories.mongo import MongoDBManager +from src.services.admin_views import browse_stored_data, cache_inventory, circuit_layout_status +from src.services.circuit_derivation import ( + CircuitDerivationError, + DeriveOptions, + LayoutExistsError, + build_preview_geometry, + derive_and_store, +) +from src.services.storage_cleanup import ( + ALL_LAYERS, + CleanupError, + CleanupScope, + execute_cleanup, + find_orphan_plot_dirs, + plan_cleanup, + storage_totals, +) +from src.services.analysis.v2 import registry +from src.domain.models.circuits import CircuitLayout +from src.workers import plot_inventory + +logger = get_logger(__name__) + +_SESSION_CHOICES = ["FP1", "FP2", "FP3", "Q", "SQ", "S", "R"] def _admin_gate(request: Request) -> None: @@ -52,16 +85,7 @@ def _admin_gate(request: Request) -> None: def _is_admin_session(request: Request) -> bool: - return compare_cookie(request.cookies.get(_COOKIE, ""), _expected_token()) - - -def _expected_token() -> str: - # Derive a stable per-process token from the JWT secret. This is fine for - # a small operator-only dashboard; rotating the secret invalidates it. - import hashlib - - secret = settings.jwt_secret_key or settings.api_secret_key or "dev" - return hashlib.sha256(f"admin-ui::{secret}".encode()).hexdigest() + return verify_session_token(request.cookies.get(_COOKIE)) def _check_credentials(username: str, password: str) -> bool: @@ -87,10 +111,6 @@ def _render(request: Request, template: str, context: dict) -> HTMLResponse: return apply_no_index(resp) -def _is_prod_cookie() -> bool: - return (settings.environment or "").lower() == "production" - - def _set_session_cookie(resp, token: str) -> None: resp.set_cookie( _COOKIE, @@ -98,7 +118,7 @@ def _set_session_cookie(resp, token: str) -> None: max_age=8 * 3600, httponly=True, samesite="strict", - secure=_is_prod_cookie(), + secure=settings.is_production, path="/", ) @@ -125,8 +145,9 @@ async def admin_login_submit( resp = RedirectResponse("/admin/login?error=true", status_code=302) return apply_no_index(resp) record_login_success(request) + token = create_session_token() resp = RedirectResponse("/admin", status_code=302) - _set_session_cookie(resp, _expected_token()) + _set_session_cookie(resp, token) return apply_no_index(resp) @@ -170,10 +191,23 @@ async def admin_dashboard(request: Request, q: str = Query("", description="sear reverse=True, )[:30] - # Decorate top-usage rows with key metadata. + # Resolve every key's hash in ONE threadpool hop rather than a round-trip + # per row. The previous shape issued a find_active_by_hash per top-usage row + # plus find_by_id + dashboard_for_key per key — up to ~400 sequential calls + # for a 200-key install, which dominated the page's render time. + def _key_meta_by_hash() -> dict: + meta: dict = {} + for key in keys: + raw = _keys.find_by_id(key["id"]) + if raw and raw.get("key_hash"): + meta[raw["key_hash"]] = key + return meta + + meta_by_hash = await run_in_threadpool(_key_meta_by_hash) + top_rows = [] for row in top: - meta = await run_in_threadpool(_keys.find_active_by_hash, row["key_hash"]) + meta = meta_by_hash.get(row["key_hash"]) top_rows.append({ **row, "key_prefix": meta.get("key_prefix") if meta else None, @@ -181,23 +215,26 @@ async def admin_dashboard(request: Request, q: str = Query("", description="sear "tier": meta.get("tier") if meta else None, }) - # Quota-usage table: per active key, % of monthly cap used. + # Quota-usage table: per active key, % of monthly cap used. One batched + # aggregation instead of a dashboard_for_key call per key. + active_hashes = [ + key_hash for key_hash, key in meta_by_hash.items() if not key.get("revoked_at") + ] + per_key_stats = await run_in_threadpool( + _key_usage.dashboard_for_each_key, active_hashes + ) + quota_rows = [] - for k in keys: - if k.get("revoked_at"): - continue - raw = await run_in_threadpool(_keys.find_by_id, k["id"]) - key_hash = raw.get("key_hash") if raw else None - if not key_hash: - continue - stats = await run_in_threadpool(_key_usage.dashboard_for_key, key_hash) - tier = k.get("tier") or "standard" + for key_hash in active_hashes: + key = meta_by_hash[key_hash] + stats = per_key_stats.get(key_hash) or {"current_month": {"requests": 0}} + tier = key.get("tier") or "standard" monthly_limit = limits_for_tier(tier)["monthly_quota"] used = stats["current_month"]["requests"] percent = round(min(100.0, (used / monthly_limit * 100)), 2) if monthly_limit else 0.0 quota_rows.append({ - "key_prefix": k.get("key_prefix"), - "label": k.get("label"), + "key_prefix": key.get("key_prefix"), + "label": key.get("label"), "tier": tier, "monthly_limit": monthly_limit, "used_this_month": used, @@ -350,6 +387,636 @@ async def admin_key_analytics(request: Request, key_id: str, hours: int = Query( ) +@router.get("/admin/plots", include_in_schema=False) +async def admin_plots( + request: Request, + year: int = Query(None, ge=2018, le=2030), + gp: str = Query("", max_length=80), + session: str = Query("", max_length=20), +): + """Inventory of ungenerated V2 data, with a scoped, selectable backfill.""" + if not _is_admin_session(request): + return apply_no_index(RedirectResponse("/admin/login", status_code=302)) + + years = plot_inventory.available_years() + if year is None: + year = years[0] if years else None + + gp = (gp or "").strip() + session = (session or "").strip().upper() + + events = await run_in_threadpool(plot_inventory.available_events, year) if year else [] + # Ignore a GP selection that isn't part of the chosen year (e.g. after + # switching years) so the scope can't point at a stale/foreign event. + if gp and gp not in {e["name"] for e in events}: + gp = "" + + report = await run_in_threadpool( + plot_inventory.compute_missing, + year=year, + identifier=gp or None, + session=session or None, + ) + season = await run_in_threadpool(plot_inventory.season_inventory, year) if year else None + + # The catalog drives the feature selector, so the UI never hardcodes a + # feature list. Narrow it to the chosen session when there is one. + catalog = ( + registry.catalog_for_session(session) if session else list(registry.FEATURE_CATALOG) + ) + + jobs = await run_in_threadpool(plot_inventory.list_jobs, 8, None) + running = next( + (j["job_id"] for j in jobs if j.get("status") in ("queued", "running")), None + ) + + return _render( + request, + "admin/plots.html", + { + "version": settings.app_version, + "report": report, + "season": season, + "years": years, + "events": events, + "session_choices": _SESSION_CHOICES, + "scope": {"year": year, "gp": gp, "session": session}, + "catalog": [entry.as_dict() for entry in catalog], + "jobs": jobs, + # Lets the page re-attach its progress bar after a refresh; before + # this a reload orphaned any running job. + "running_job_id": running, + }, + ) + + +def _selection_from_form( + features: List[str], + drivers: List[str], + lap_from: Optional[int], + lap_to: Optional[int], +) -> plot_inventory.Selection: + return plot_inventory.Selection( + features=[f for f in features if f] or None, + drivers=[d.strip().upper() for d in drivers if d.strip()] or None, + lap_from=lap_from, + lap_to=lap_to, + ) + + +@router.get("/admin/plots/drivers", include_in_schema=False) +async def admin_plots_drivers( + request: Request, + year: int = Query(..., ge=2018, le=2030), + gp: str = Query(..., max_length=80), + session: str = Query(..., max_length=20), + include_laps: bool = Query(False), +): + """Driver list (and lap numbers) for the selector's pickers.""" + if not _is_admin_session(request): + raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED) + try: + drivers = await run_in_threadpool(registry.session_drivers, year, gp, session.upper()) + payload: dict = {"drivers": drivers} + if include_laps: + laps = await run_in_threadpool( + registry.session_driver_laps, year, gp, session.upper() + ) + all_laps = [lap for values in laps.values() for lap in values] + payload["laps"] = laps + payload["lap_range"] = ( + {"min": min(all_laps), "max": max(all_laps)} if all_laps else None + ) + return apply_no_index(JSONResponse(payload)) + except Exception as exc: + raise HTTPException(status_code=502, detail=f"Could not resolve drivers: {exc}") + + +@router.post("/admin/plots/estimate", include_in_schema=False) +async def admin_plots_estimate( + request: Request, + year: int = Form(None), + gp: str = Form(""), + session: str = Form(""), + features: List[str] = Form([]), + drivers: List[str] = Form([]), + lap_from: Optional[int] = Form(None), + lap_to: Optional[int] = Form(None), + csrf_token: str = Form(...), +): + """Cost a selection without generating anything, for the live estimate panel.""" + if not _is_admin_session(request): + raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED) + verify_csrf(request, csrf_token) + + summary = await run_in_threadpool( + plot_inventory.estimate_plan, + year=year, + identifier=(gp or "").strip() or None, + session=(session or "").strip().upper() or None, + selection=_selection_from_form(features, drivers, lap_from, lap_to), + ) + return apply_no_index(JSONResponse(summary)) + + +@router.post("/admin/plots/generate", include_in_schema=False) +async def admin_plots_generate( + request: Request, + year: int = Form(...), + gp: str = Form(""), + session: str = Form(""), + force: bool = Form(False), + include_comparisons: bool = Form(False), + features: List[str] = Form([]), + drivers: List[str] = Form([]), + lap_from: Optional[int] = Form(None), + lap_to: Optional[int] = Form(None), + concurrency: int = Form(1), + csrf_token: str = Form(...), +): + """Start a background backfill job; returns JSON for the JS progress poller.""" + if not _is_admin_session(request): + raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED) + verify_csrf(request, csrf_token) + + identifier = (gp or "").strip() or None + session_abbrev = (session or "").strip().upper() or None + scope = {"year": year, "gp": identifier, "session": session_abbrev} + + conflict = await run_in_threadpool(plot_inventory.find_conflicting_job, scope) + if conflict: + raise HTTPException( + status_code=409, + detail=f"Job {conflict['job_id']} is already running over this scope", + ) + + selection = _selection_from_form(features, drivers, lap_from, lap_to) + job = plot_inventory.start_generation_job( + year=year, + identifier=identifier, + session=session_abbrev, + force=force, + include_comparisons=include_comparisons, + selection=selection if selection.features else None, + concurrency=max(1, min(int(concurrency or 1), plot_inventory.MAX_CONCURRENCY)), + ) + return apply_no_index(JSONResponse(job.as_dict())) + + +@router.get("/admin/plots/jobs/{job_id}/status", include_in_schema=False) +async def admin_plots_job_status(request: Request, job_id: str): + """Session-protected job status for the live progress bar.""" + if not _is_admin_session(request): + raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED) + job = await run_in_threadpool(plot_inventory.get_job_dict, job_id) + if job is None: + raise HTTPException(status_code=404, detail="Job not found") + return apply_no_index(JSONResponse(job)) + + +@router.post("/admin/plots/jobs/{job_id}/cancel", include_in_schema=False) +async def admin_plots_job_cancel(request: Request, job_id: str, csrf_token: str = Form(...)): + if not _is_admin_session(request): + raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED) + verify_csrf(request, csrf_token) + if not await run_in_threadpool(plot_inventory.cancel_job, job_id): + raise HTTPException(status_code=409, detail="Job is not cancellable") + return apply_no_index(JSONResponse({"job_id": job_id, "cancel_requested": True})) + + +# --------------------------------------------------------------------------- # +# Jobs +# --------------------------------------------------------------------------- # +@router.get("/admin/jobs", include_in_schema=False) +async def admin_jobs_page(request: Request, status_filter: str = Query("", alias="status")): + if not _is_admin_session(request): + return apply_no_index(RedirectResponse("/admin/login", status_code=302)) + + wanted = (status_filter or "").strip().lower() or None + jobs = await run_in_threadpool(plot_inventory.list_jobs, 100, wanted) + return _render( + request, + "admin/jobs.html", + {"version": settings.app_version, "jobs": jobs, "status": wanted or ""}, + ) + + +def _job_duration(job: dict) -> str: + started, finished = job.get("started_at"), job.get("finished_at") + if not started: + return "—" + try: + start = datetime.fromisoformat(started) + end = datetime.fromisoformat(finished) if finished else datetime.now(timezone.utc) + if start.tzinfo is None: + start = start.replace(tzinfo=timezone.utc) + if end.tzinfo is None: + end = end.replace(tzinfo=timezone.utc) + except ValueError: + return "—" + seconds = int((end - start).total_seconds()) + if seconds < 60: + return f"{seconds}s" + if seconds < 3600: + return f"{seconds // 60}m {seconds % 60}s" + return f"{seconds // 3600}h {(seconds % 3600) // 60}m" + + +@router.get("/admin/jobs/{job_id}", include_in_schema=False) +async def admin_job_detail(request: Request, job_id: str): + if not _is_admin_session(request): + return apply_no_index(RedirectResponse("/admin/login", status_code=302)) + + job = await run_in_threadpool(plot_inventory.get_job_dict, job_id) + if job is None: + raise HTTPException(status_code=404, detail="Job not found") + job.setdefault("scope", {}) + job.setdefault("errors", []) + return _render( + request, + "admin/job_detail.html", + {"version": settings.app_version, "job": job, "duration": _job_duration(job)}, + ) + + +@router.post("/admin/jobs/{job_id}/cancel", include_in_schema=False) +async def admin_job_cancel(request: Request, job_id: str, csrf_token: str = Form(...)): + if not _is_admin_session(request): + raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED) + verify_csrf(request, csrf_token) + await run_in_threadpool(plot_inventory.cancel_job, job_id) + return apply_no_index(RedirectResponse(f"/admin/jobs/{job_id}", status_code=302)) + + +# --------------------------------------------------------------------------- # +# Cache +# --------------------------------------------------------------------------- # +@router.get("/admin/cache", include_in_schema=False) +async def admin_cache_page(request: Request, year: int = Query(None, ge=2018, le=2030)): + if not _is_admin_session(request): + return apply_no_index(RedirectResponse("/admin/login", status_code=302)) + + inventory = await run_in_threadpool(cache_inventory, year) + return _render( + request, + "admin/cache.html", + { + "version": settings.app_version, + "inventory": inventory, + "year": year, + "years": plot_inventory.available_years(), + "session_choices": _SESSION_CHOICES, + }, + ) + + +@router.post("/admin/cache/purge/raw", include_in_schema=False) +async def admin_cache_purge_raw(request: Request, session_key: str = Form(...), + csrf_token: str = Form(...)): + if not _is_admin_session(request): + raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED) + verify_csrf(request, csrf_token) + await run_in_threadpool(raw_stream_cache.delete_raw_streams, session_key) + return apply_no_index(RedirectResponse("/admin/cache", status_code=302)) + + +@router.post("/admin/cache/purge/bundle", include_in_schema=False) +async def admin_cache_purge_bundle(request: Request, doc_id: str = Form(...), + csrf_token: str = Form(...)): + if not _is_admin_session(request): + raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED) + verify_csrf(request, csrf_token) + await run_in_threadpool(session_cache.delete_bundle, doc_id) + return apply_no_index(RedirectResponse("/admin/cache", status_code=302)) + + +@router.post("/admin/cache/prewarm", include_in_schema=False) +async def admin_cache_prewarm(request: Request, year: int = Form(...), gp: str = Form(...), + session: str = Form(...), csrf_token: str = Form(...)): + if not _is_admin_session(request): + raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED) + verify_csrf(request, csrf_token) + from src.workers.processor import get_processor + + try: + await run_in_threadpool( + get_processor().prewarm_session_streams, year, gp, session.upper(), gp + ) + except Exception as exc: # surfaced on the page rather than as a 500 + logger.warning("Admin prewarm failed for %s %s %s: %s", year, gp, session, exc) + return apply_no_index(RedirectResponse(f"/admin/cache?year={year}", status_code=302)) + + +# --------------------------------------------------------------------------- # +# Stored data browser +# --------------------------------------------------------------------------- # +@router.get("/admin/data", include_in_schema=False) +async def admin_data_page( + request: Request, + year: int = Query(None, ge=2018, le=2030), + gp: str = Query("", max_length=80), + session: str = Query("", max_length=20), +): + if not _is_admin_session(request): + return apply_no_index(RedirectResponse("/admin/login", status_code=302)) + + years = plot_inventory.available_years() + if year is None: + year = years[0] if years else datetime.now(timezone.utc).year + + session = (session or "").strip().upper() + browse = await run_in_threadpool( + browse_stored_data, year, gp.strip() or None, session or None + ) + return _render( + request, + "admin/data.html", + { + "version": settings.app_version, + "browse": browse, + "years": years, + "year": year, + "gp": gp, + "session": session, + "session_choices": _SESSION_CHOICES, + }, + ) + + +@router.post("/admin/data/delete", include_in_schema=False) +async def admin_data_delete( + request: Request, + year: int = Form(...), + gp_id: str = Form(...), + session_type: str = Form(...), + data_type: str = Form(...), + csrf_token: str = Form(...), +): + if not _is_admin_session(request): + raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED) + verify_csrf(request, csrf_token) + + manager = MongoDBManager(year=year, version="v2") + await run_in_threadpool( + manager.delete_session_data, gp_id, session_type.upper(), data_type, year + ) + logger.info("Admin UI deleted %s from %s %s (%s)", data_type, gp_id, session_type, year) + return apply_no_index(RedirectResponse(f"/admin/data?year={year}", status_code=302)) + + +# --------------------------------------------------------------------------- # +# Backups +# --------------------------------------------------------------------------- # +@router.get("/admin/backups", include_in_schema=False) +async def admin_backups_page(request: Request, tier: str = Query("daily", max_length=16)): + if not _is_admin_session(request): + return apply_no_index(RedirectResponse("/admin/login", status_code=302)) + + tier = tier if tier in ("daily", "weekly", "monthly") else "daily" + status_payload, backup_ids = await run_in_threadpool(_backup_overview, tier) + return _render( + request, + "admin/backups.html", + { + "version": settings.app_version, + "status": status_payload, + "tier": tier, + "backup_ids": backup_ids, + "verify_report": None, + "restore_report": None, + }, + ) + + +def _backup_overview(tier: str): + """Scheduler/S3 status plus the backup ids in one tier. Fails soft: the page + must still render when the subsystem is off or S3 is unreachable. + """ + from src.core.config import settings as _settings + + status_payload = { + "enabled": bool(_settings.backup_enabled), + "scheduler_running": False, + "manual_in_progress": False, + "s3_ok": None, + } + backup_ids: List[str] = [] + if not _settings.backup_enabled: + return status_payload, backup_ids + + try: + from src.services.backup.scheduler import get_scheduler + + sched = get_scheduler() + status_payload["scheduler_running"] = bool(sched.running) + status_payload["manual_in_progress"] = bool(sched._manual_in_progress) + except Exception as exc: + logger.warning("Backup scheduler unavailable: %s", exc) + + try: + from src.services.backup.storage import S3Storage + + storage = S3Storage() + status_payload["s3_ok"] = bool(storage.ping()) + backup_ids = list(storage.list_backups(tier)) + except Exception as exc: + logger.warning("Backup storage unavailable: %s", exc) + status_payload["s3_ok"] = False + + return status_payload, backup_ids + + +@router.post("/admin/backups/run", include_in_schema=False) +async def admin_backups_run(request: Request, csrf_token: str = Form(...)): + if not _is_admin_session(request): + raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED) + verify_csrf(request, csrf_token) + try: + from src.services.backup.scheduler import get_scheduler + + get_scheduler().trigger_now() + except Exception as exc: + logger.error("Could not trigger backup: %s", exc) + return apply_no_index(RedirectResponse("/admin/backups", status_code=302)) + + +@router.post("/admin/backups/verify", include_in_schema=False) +async def admin_backups_verify(request: Request, backup_id: str = Form(...), + csrf_token: str = Form(...)): + if not _is_admin_session(request): + raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED) + verify_csrf(request, csrf_token) + + report = None + try: + from src.services.backup.restore import RestoreRunner + + result = await run_in_threadpool(lambda: RestoreRunner().verify(backup_id)) + report = {"backup_id": result.backup_id, "tier": result.tier, + "verified": list(result.verified)} + except Exception as exc: + logger.error("Backup verify failed for %s: %s", backup_id, exc) + + status_payload, backup_ids = await run_in_threadpool(_backup_overview, "daily") + return _render( + request, + "admin/backups.html", + { + "version": settings.app_version, + "status": status_payload, + "tier": "daily", + "backup_ids": backup_ids, + "verify_report": report, + "restore_report": None, + }, + ) + + +@router.post("/admin/backups/restore", include_in_schema=False) +async def admin_backups_restore( + request: Request, + backup_id: str = Form(...), + mongo_target_db: str = Form(""), + confirm_text: str = Form(""), + csrf_token: str = Form(...), +): + """Restore, with a drill target strongly preferred. + + Without a target database this overwrites live data, so it additionally + requires the operator to type RESTORE — matching the API's + ``confirm=true`` + ``i_understand=true`` double gate. + """ + if not _is_admin_session(request): + raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED) + verify_csrf(request, csrf_token) + + target = (mongo_target_db or "").strip() or None + if not target and confirm_text.strip().upper() != "RESTORE": + raise HTTPException( + status_code=400, + detail="A destructive restore requires typing RESTORE, or set a drill target database.", + ) + + report = None + try: + from src.services.backup.restore import RestoreRunner + + result = await run_in_threadpool( + lambda: RestoreRunner().restore(backup_id, mongo_target_db=target) + ) + report = { + "backup_id": result.backup_id, + "restored": list(result.restored), + "skipped": list(result.skipped), + "mongo_target_db": target, + } + except Exception as exc: + logger.error("Backup restore failed for %s: %s", backup_id, exc) + raise HTTPException(status_code=500, detail=f"Restore failed: {exc}") + + status_payload, backup_ids = await run_in_threadpool(_backup_overview, "daily") + return _render( + request, + "admin/backups.html", + { + "version": settings.app_version, + "status": status_payload, + "tier": "daily", + "backup_ids": backup_ids, + "verify_report": None, + "restore_report": report, + }, + ) + + +# --------------------------------------------------------------------------- # +# Ops +# --------------------------------------------------------------------------- # +def _ops_health() -> dict: + """Mongo + Redis reachability. Both checks fail soft to a boolean.""" + health = {"mongo": False, "redis": None} + try: + from src.repositories.mongo import test_connection + + health["mongo"] = bool(test_connection()) + except Exception as exc: + logger.debug("Mongo health check failed: %s", exc) + try: + from src.core.cache.redis_cache import get_sync_cache + + cache = get_sync_cache() + health["redis"] = bool(cache.enabled) if cache.enabled else None + except Exception as exc: + logger.debug("Redis health check failed: %s", exc) + health["redis"] = False + return health + + +def _ops_context(action_result: Optional[dict] = None) -> dict: + from src.core.observability.monitoring import get_system_monitor + from src.workers.processor import get_processor + + processor = get_processor() + tracker = get_request_tracker() + return { + "version": settings.app_version, + "environment": settings.environment, + "processor": { + "running": bool(getattr(processor, "running", False)), + "check_interval": getattr(processor, "check_interval", 0), + "processed_sessions_count": len(getattr(processor, "processed_sessions", []) or []), + "processed_sessions": list(getattr(processor, "processed_sessions", []) or [])[-20:], + }, + "system": get_system_monitor().get_metrics(), + "health": _ops_health(), + "summary": tracker.get_summary(), + "recent_errors": tracker.get_recent_errors(20), + "action_result": action_result, + } + + +@router.get("/admin/ops", include_in_schema=False) +async def admin_ops_page(request: Request): + if not _is_admin_session(request): + return apply_no_index(RedirectResponse("/admin/login", status_code=302)) + context = await run_in_threadpool(_ops_context, None) + return _render(request, "admin/ops.html", context) + + +@router.post("/admin/ops/process-latest", include_in_schema=False) +async def admin_ops_process_latest(request: Request, csrf_token: str = Form(...)): + if not _is_admin_session(request): + raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED) + verify_csrf(request, csrf_token) + + from src.workers.processor import get_processor + + try: + result = await get_processor().force_process_latest() + except Exception as exc: + logger.error("Force-process failed: %s", exc) + result = {"status": "error", "error": str(exc)} + context = await run_in_threadpool(_ops_context, result) + return _render(request, "admin/ops.html", context) + + +@router.post("/admin/ops/ensure-indexes", include_in_schema=False) +async def admin_ops_ensure_indexes(request: Request, csrf_token: str = Form(...)): + if not _is_admin_session(request): + raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED) + verify_csrf(request, csrf_token) + + from src.repositories.mongo import ensure_indexes + + try: + created = await run_in_threadpool(ensure_indexes) + except Exception as exc: + logger.error("ensure_indexes failed: %s", exc) + created = {"error": str(exc)} + context = await run_in_threadpool(_ops_context, created) + return _render(request, "admin/ops.html", context) + + @router.post("/admin/keys/{key_id}/revoke", include_in_schema=False) async def admin_ui_revoke(request: Request, key_id: str, csrf_token: str = Form(...)): if not _is_admin_session(request): @@ -368,13 +1035,328 @@ async def admin_ui_promote(request: Request, user_id: str, csrf_token: str = For if not _is_admin_session(request): raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED) verify_csrf(request, csrf_token) - import os - from bson import ObjectId - from src.repositories.mongo import get_mongo_client - - db = get_mongo_client()[os.getenv("MONGODB_DATABASE", "T1API_DB")] try: - db["users"].update_one({"_id": ObjectId(user_id)}, {"$set": {"is_admin": True}}) - except Exception: - pass + await run_in_threadpool(_users.set_admin, user_id, True) + except Exception as exc: + # A failed promotion must be visible, not silently swallowed. + logger.error("Could not promote user %s: %s", user_id, exc) + raise HTTPException(status_code=500, detail="Could not promote user") return apply_no_index(RedirectResponse("/admin", status_code=302)) + + +# --------------------------------------------------------------------------- # +# Storage cleanup +# --------------------------------------------------------------------------- # +@router.get("/admin/cleanup", include_in_schema=False) +async def admin_cleanup_page( + request: Request, + year: int = Query(None, ge=2018, le=2030), + gp: str = Query("", max_length=80), + session: str = Query("", max_length=20), + data_type: str = Query("", max_length=80), + layers: List[str] = Query(None), + preview: bool = Query(False), + error: str = Query("", max_length=300), + purged: int = Query(None), + reclaimed: int = Query(None), +): + """Storage overview, plus an optional dry-run preview of a scoped cleanup. + + The preview is a GET so it is shareable and re-runnable; only the purge + (POST, CSRF-verified) mutates anything. + """ + if not _is_admin_session(request): + return apply_no_index(RedirectResponse("/admin/login", status_code=302)) + + totals = await run_in_threadpool(storage_totals) + orphans = await run_in_threadpool(find_orphan_plot_dirs) + + plan = None + selected_layers = tuple(layers) if layers else ALL_LAYERS + if preview: + try: + scope = CleanupScope( + year=year, + gp=gp.strip() or None, + session=(session or "").strip().upper() or None, + data_type=data_type.strip() or None, + layers=selected_layers, + ) + plan = await run_in_threadpool(plan_cleanup, scope) + except ValueError as exc: + error = str(exc) + + return _render( + request, + "admin/cleanup.html", + { + "version": settings.app_version, + "totals": totals, + "orphans": orphans, + "plan": plan, + "error": error or None, + "purged": purged, + "reclaimed": reclaimed, + "years": plot_inventory.available_years(), + "year": year, + "gp": gp, + "session": (session or "").strip().upper(), + "data_type": data_type, + "all_layers": ALL_LAYERS, + "selected_layers": list(selected_layers), + "session_choices": _SESSION_CHOICES, + }, + ) + + +@router.post("/admin/cleanup/purge", include_in_schema=False) +async def admin_cleanup_purge( + request: Request, + confirm_token: str = Form(...), + csrf_token: str = Form(...), + year: Optional[int] = Form(None), + gp: str = Form(""), + session: str = Form(""), + data_type: str = Form(""), + layers: List[str] = Form(None), + allow_full_purge: bool = Form(False), + typed_confirmation: str = Form(""), +): + """Execute a previewed cleanup. Destructive, and gated three ways. + + ``verify_csrf`` proves the request came from this admin session; + ``confirm_token`` proves the item set is still exactly what the preview + displayed; and an unscoped purge additionally requires the operator to type + DELETE EVERYTHING, mirroring the backup restore's typed confirmation. The + checkbox alone is too easy to leave set from a previous run. + """ + if not _is_admin_session(request): + raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED) + verify_csrf(request, csrf_token) + + try: + scope = CleanupScope( + year=year, + gp=gp.strip() or None, + session=(session or "").strip().upper() or None, + data_type=data_type.strip() or None, + layers=tuple(layers) if layers else ALL_LAYERS, + ) + except ValueError as exc: + return apply_no_index(RedirectResponse( + f"/admin/cleanup?error={quote_plus(str(exc))}", status_code=302 + )) + + if scope.is_unscoped and typed_confirmation.strip() != "DELETE EVERYTHING": + logger.warning("Admin cleanup: unscoped purge rejected, confirmation not typed") + return apply_no_index(RedirectResponse( + "/admin/cleanup?error=" + + quote_plus("Type DELETE EVERYTHING to confirm an unscoped purge."), + status_code=302, + )) + + try: + result = await run_in_threadpool( + execute_cleanup, scope, confirm_token, + allow_full_purge=bool(allow_full_purge and scope.is_unscoped), + ) + except CleanupError as exc: + logger.warning("Admin cleanup refused: %s", exc) + return apply_no_index(RedirectResponse( + f"/admin/cleanup?error={quote_plus(str(exc))}", status_code=302 + )) + + logger.warning( + "Admin cleanup purged %s item(s), %s byte(s); scope=%s", + result["total_deleted"], result["bytes_reclaimed"], scope.to_dict(), + ) + return apply_no_index(RedirectResponse( + f"/admin/cleanup?purged={result['total_deleted']}" + f"&reclaimed={result['bytes_reclaimed']}", + status_code=302, + )) + + +# --------------------------------------------------------------------------- # +# Circuit derivation +# --------------------------------------------------------------------------- # +# Exceptions the derivation service can raise for a bad/unusable request, as +# opposed to a genuine bug -- these must render as an operator-facing message, +# never a 500. LayoutExistsError is a CircuitDerivationError subclass; it is +# listed anyway so the set is self-documenting at the call site. +_DERIVE_ERRORS = ( + LayoutExistsError, CircuitDerivationError, + SessionNotFoundError, DataNotAvailableError, UpstreamUnavailableError, + ValueError, +) +_CIRCUIT_ID_RE = re.compile(r"^[0-9]{1,6}$") + + +def _circuits_form( + year: int, gp: str, session: str, driver: str = "", rotation: str = "", min_turn_deg: float = 25.0, +) -> dict: + return { + "year": year, + "gp": gp, + "session": session or "Q", + "driver": driver, + "rotation": rotation, + "min_turn_deg": min_turn_deg, + } + + +def _circuits_context( + year: int, + form: dict, + *, + saved: str = "", + error: str = "", + preview: Optional[dict] = None, + result: Optional[dict] = None, + existing_source: Optional[str] = None, +) -> dict: + return { + "version": settings.app_version, + "status": circuit_layout_status(year), + "years": plot_inventory.available_years(), + "session_choices": _SESSION_CHOICES, + "form": form, + "saved": saved, + "error": error, + "preview": preview, + "result": result, + "existing_source": existing_source, + } + + +@router.get("/admin/circuits", include_in_schema=False) +async def admin_circuits_page( + request: Request, + year: int = Query(None, ge=2018, le=2030), + saved: str = Query("", max_length=40), + error: str = Query("", max_length=300), + gp: str = Query("", max_length=80), + session: str = Query("", max_length=20), +): + """Circuit-layout status board, plus a derive-from-telemetry workflow. + + Sessions like Madring 2026 can run a whole weekend before multiviewer + publishes a layout; this lets an operator trace one from a session's + fastest lap instead of waiting. + """ + if not _is_admin_session(request): + return apply_no_index(RedirectResponse("/admin/login", status_code=302)) + + if year is None: + year = datetime.now(timezone.utc).year + + form = _circuits_form(year, gp, session) + context = await run_in_threadpool(_circuits_context, year, form, saved=saved, error=error) + return _render(request, "admin/circuits.html", context) + + +@router.post("/admin/circuits/preview", include_in_schema=False) +async def admin_circuits_preview( + request: Request, + year: int = Form(...), + gp: str = Form(...), + session: str = Form(...), + driver: str = Form(""), + rotation: str = Form(""), + min_turn_deg: float = Form(25.0), + csrf_token: str = Form(...), +): + """Dry-run a derivation and render the traced outline for review. + + Nothing is written here -- ``derive_and_store`` is called with + ``dry_run=True`` so the operator can inspect the outline and corners + before committing anything to disk or MongoDB. + """ + if not _is_admin_session(request): + raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED) + verify_csrf(request, csrf_token) + + form = _circuits_form(year, gp, session, driver, rotation, min_turn_deg) + try: + result = await run_in_threadpool( + derive_and_store, + year, gp.strip(), session.strip().upper(), + DeriveOptions( + driver=driver.strip().upper() or None, + rotation=float(rotation) if rotation.strip() else None, + min_turn_deg=min_turn_deg, + ), + dry_run=True, + ) + except _DERIVE_ERRORS as exc: + context = await run_in_threadpool(_circuits_context, year, form, error=str(exc)) + return _render(request, "admin/circuits.html", context) + + preview = build_preview_geometry(CircuitLayout(**result["layout"])) + context = await run_in_threadpool( + _circuits_context, year, form, + preview=preview, result=result, existing_source=result["existing_source"], + ) + return _render(request, "admin/circuits.html", context) + + +@router.post("/admin/circuits/save", include_in_schema=False) +async def admin_circuits_save( + request: Request, + year: int = Form(...), + gp: str = Form(...), + session: str = Form(...), + driver: str = Form(""), + rotation: str = Form(""), + min_turn_deg: float = Form(25.0), + overwrite: bool = Form(False), + csrf_token: str = Form(...), +): + """Persist a previewed derivation to disk and MongoDB.""" + if not _is_admin_session(request): + raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED) + verify_csrf(request, csrf_token) + + try: + result = await run_in_threadpool( + derive_and_store, + year, gp.strip(), session.strip().upper(), + DeriveOptions( + driver=driver.strip().upper() or None, + rotation=float(rotation) if rotation.strip() else None, + min_turn_deg=min_turn_deg, + ), + dry_run=False, + overwrite=overwrite, + ) + except _DERIVE_ERRORS as exc: + return apply_no_index(RedirectResponse( + f"/admin/circuits?year={year}&error={quote_plus(str(exc))}", status_code=302 + )) + + logger.warning( + "Admin circuit layout written: %s %s (%s) from %s", + result["circuit_id"], result["circuit_name"], result["session"], + result["stats"].get("source_driver"), + ) + return apply_no_index(RedirectResponse( + f"/admin/circuits?year={year}&saved={result['circuit_id']}", status_code=302 + )) + + +@router.get("/admin/circuits/{year}/{circuit_id}/download", include_in_schema=False) +async def admin_circuits_download( + request: Request, + year: int = PathParam(..., ge=2018, le=2030), + circuit_id: str = PathParam(...), +): + """Serve a derived layout file so the operator can commit it to the repo.""" + if not _is_admin_session(request): + return apply_no_index(RedirectResponse("/admin/login", status_code=302)) + if not _CIRCUIT_ID_RE.match(circuit_id): + raise HTTPException(status_code=404, detail="Circuit not found") + + path = await run_in_threadpool(find_circuit_file, year, circuit_id) + if path is None: + raise HTTPException(status_code=404, detail="Circuit layout not found") + return apply_no_index(FileResponse(path, media_type="application/json", filename=path.name)) diff --git a/src/api/routers/analysis_v1.py b/src/api/routers/analysis_v1.py index 9f74f05..f6a4aac 100644 --- a/src/api/routers/analysis_v1.py +++ b/src/api/routers/analysis_v1.py @@ -1,4 +1,4 @@ -from fastapi import APIRouter, Request, HTTPException, Depends, Query +from fastapi import APIRouter, Request, HTTPException, Depends, Query, Response from fastapi.responses import FileResponse, JSONResponse from fastapi.concurrency import run_in_threadpool @@ -31,10 +31,6 @@ from src.services.analysis.v2.qualifying_results import ( QualiResultsPlot as V2_QualiResultsPlot, ) -from src.services.analysis.v2.speed_distribution import ( - SpeedDistributionPlot as V2_SpeedDistributionPlot, - SpeedDistributionData as V2_SpeedDistributionData, -) from src.services.analysis.v2.driver_pace import ( DriverPacePlot as V2_DriverPacePlot, DriverPaceData as V2_DriverPaceData, @@ -53,6 +49,23 @@ ) from src.services.analysis.base import with_fallback from src.core.exceptions import T1APIError +from src.api.schemas.common import ANALYSIS_ERROR_RESPONSES, COMMON_ERROR_RESPONSES, ErrorEnvelope +from src.api.schemas.legacy_v1 import ( + LegacyDashboardResponse, + LegacyDailyDataResponse, + LegacyDailyStatsResponse, + LegacyTopSpeedDataResponse, + LegacyThrottleComparisonDataResponse, + LegacySpeedDistributionDataResponse, + LegacyLaptimesDataResponse, + LegacyQualifyingResultsDataResponse, + LegacyTrackComparisonResponse, + LegacyThrottleBrakeComparisonResponse, + LegacyLapTimeAnalysisResponse, + LegacyDriverPaceDataResponse, + LegacyTeamsPaceDataResponse, + LegacyTyreStintUsageDataResponse, +) logger = get_logger(__name__) @@ -65,16 +78,45 @@ def _track(event_name, *args): except Exception: pass -router = APIRouter(prefix="/api/v1") + +def _sunset_headers(response: Response) -> None: + """RFC 8594 retirement notice, applied to every ``/api/v1`` response. + + A router-level dependency rather than per-endpoint code: it takes the framework's + ``Response`` object (excluded from OpenAPI parameter generation like ``Request``), so + no endpoint signature or documented parameter changes. + """ + response.headers["Deprecation"] = "true" + response.headers["Sunset"] = "Sun, 01 Sep 2027 00:00:00 GMT" + + +#: Documentation-only shape for every ``-plot`` endpoint: a PNG body, no JSON schema. +_PNG_RESPONSE = {"content": {"image/png": {}}, "description": "PNG plot."} + +router = APIRouter(prefix="/api/v1", dependencies=[Depends(_sunset_headers)]) # ============================================================================ # ANALYSIS ENDPOINTS # ============================================================================ -@router.get('/daily-data', tags=["API v1", "General"]) + +@router.get( + '/daily-data', + tags=["API v1"], + deprecated=True, + summary="Random daily featured plot bundle", + operation_id="v1_daily_data", + description=( + "Generate a daily 'featured session' data bundle (top speed + throttle comparison " + "for a randomly chosen round/session, cached for the day). **Deprecated, no V2 " + "equivalent** — this was a novelty endpoint for a rotating daily highlight, not a " + "stable data contract; callers should request `top-speed-data` / " + "`throttle-comparison-data` for a specific session instead." + ), + responses={200: {"model": LegacyDailyDataResponse}, **COMMON_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") async def daily_data(request: Request, api_key: str = Depends(verify_api_key)): - """Generate daily data summary plot (Standard rate limit)""" try: logger.info("Generating daily data plot") from src.workers.daily import DailyPlotData @@ -84,24 +126,36 @@ async def daily_data(request: Request, api_key: str = Depends(verify_api_key)): logger.error(f"Error generating daily data: {e}", exc_info=True) raise HTTPException(status_code=500, detail="Failed to generate daily data") -@router.get('/dashboard', tags=["API v1", "Latest Session"]) + +@router.get( + '/dashboard', + tags=["API v1"], + deprecated=True, + summary="Latest session dashboard (FastF1)", + operation_id="v1_dashboard_latest_session", + description=( + "Get main latest session data. Automatically detects the most recent completed " + "session. **Deprecated** — use `GET /api/v2/dashboard` instead." + ), + responses={ + 200: {"model": LegacyDashboardResponse}, + 404: {"model": ErrorEnvelope, "description": "No finished sessions found in the schedule."}, + **COMMON_ERROR_RESPONSES, + }, +) @apply_tiered_limit("data") async def get_dashboard_data(request: Request, api_key: str = Depends(verify_api_key)): - """ - Get main latest session data. - Automatically detects the most recent completed session. - """ try: logger.info("Fetching dashboard data for latest session") latest_session = await run_in_threadpool(get_latest_finished_session) - + if not latest_session: logger.warning("No finished sessions found") raise HTTPException(status_code=404, detail="No finished sessions found") - + result = await run_in_threadpool(latest_session_analised, latest_session) return result - + except HTTPException: raise except Exception as e: @@ -110,7 +164,20 @@ async def get_dashboard_data(request: Request, api_key: str = Depends(verify_api # --- Simple Analysis --- -@router.get('/top-speed-plot', tags=["API v1", "Simple Analysis"]) + +@router.get( + '/top-speed-plot', + tags=["API v1"], + deprecated=True, + summary="Top speed per team (FastF1) plot", + operation_id="v1_top_speed_plot", + description=( + "Generate PNG plot of top speeds (max CarData telemetry speed per team). Falls " + "back to V2 if FastF1 lacks data. **Deprecated** — use " + "`GET /api/v2/top-speed-telemetry-plot` instead (same CarData-telemetry source)." + ), + responses={200: _PNG_RESPONSE, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") async def quali_top_speed_plot( request: Request, @@ -119,7 +186,6 @@ async def quali_top_speed_plot( session: str = Query('Q'), api_key: str = Depends(verify_api_key) ): - """Generate PNG plot of top speeds. Falls back to V2 if FastF1 lacks data.""" logger.info(f"Generating top speed plot: Y{year} GP{gp} {session}") try: output_path = await run_in_threadpool( @@ -137,7 +203,20 @@ async def quali_top_speed_plot( logger.error(f"Plot file not found: Y{year} GP{gp} {session}") raise HTTPException(status_code=404, detail="Plot not found") -@router.get('/top-speed-data', tags=["API v1", "Simple Analysis"]) + +@router.get( + '/top-speed-data', + tags=["API v1"], + deprecated=True, + summary="Top speed per team (FastF1) data", + operation_id="v1_top_speed_data", + description=( + "Get raw JSON data for top speed analysis (max CarData telemetry speed per team). " + "Falls back to V2 if FastF1 lacks data. **Deprecated** — use " + "`GET /api/v2/top-speed-telemetry-data` instead (same CarData-telemetry source)." + ), + responses={200: {"model": LegacyTopSpeedDataResponse}, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("data") async def quali_top_speed_data( request: Request, @@ -146,7 +225,6 @@ async def quali_top_speed_data( session: str = Query('Q'), api_key: str = Depends(verify_api_key) ): - """Get raw JSON data for top speed analysis. Falls back to V2 if FastF1 lacks data.""" logger.info(f"Fetching top speed data: Y{year} GP{gp} {session}") try: result = await run_in_threadpool( @@ -166,7 +244,19 @@ async def quali_top_speed_data( logger.error(f"Data file not found: Y{year} GP{gp} {session}") raise HTTPException(status_code=404, detail="Data not found") -@router.get('/throttle-comparison-plot', tags=["API v1", "Simple Analysis"]) + +@router.get( + '/throttle-comparison-plot', + tags=["API v1"], + deprecated=True, + summary="Throttle comparison plot", + operation_id="v1_throttle_comparison_plot", + description=( + "Generate PNG plot comparing throttle application. Falls back to V2 if FastF1 " + "lacks data. **Deprecated** — use `GET /api/v2/throttle-comparison-plot` instead." + ), + responses={200: _PNG_RESPONSE, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") async def throttle_comparison_plot( request: Request, @@ -175,7 +265,6 @@ async def throttle_comparison_plot( session: str = Query('Q'), api_key: str = Depends(verify_api_key) ): - """Generate PNG plot comparing throttle application. Falls back to V2 if FastF1 lacks data.""" logger.info(f"Generating throttle comparison plot: Y{year} GP{gp} {session}") try: output_path = await run_in_threadpool( @@ -190,7 +279,19 @@ async def throttle_comparison_plot( except T1APIError: raise -@router.get('/throttle-comparison-data', tags=["API v1", "Simple Analysis"]) + +@router.get( + '/throttle-comparison-data', + tags=["API v1"], + deprecated=True, + summary="Throttle comparison data", + operation_id="v1_throttle_comparison_data", + description=( + "Get raw JSON data for throttle comparison. Falls back to V2 if FastF1 lacks " + "data. **Deprecated** — use `GET /api/v2/throttle-comparison-data` instead." + ), + responses={200: {"model": LegacyThrottleComparisonDataResponse}, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("data") async def throttle_comparison_data( request: Request, @@ -199,7 +300,6 @@ async def throttle_comparison_data( session: str = Query('Q'), api_key: str = Depends(verify_api_key) ): - """Get raw JSON data for throttle comparison. Falls back to V2 if FastF1 lacks data.""" logger.info(f"Fetching throttle comparison data: Y{year} GP{gp} {session}") try: result = await run_in_threadpool( @@ -216,7 +316,19 @@ async def throttle_comparison_data( except T1APIError: raise -@router.get('/qualifying-results-plot', tags=["API v1", "Simple Analysis"]) + +@router.get( + '/qualifying-results-plot', + tags=["API v1"], + deprecated=True, + summary="Qualifying results plot", + operation_id="v1_qualifying_results_plot", + description=( + "Generate PNG plot of qualifying results. Falls back to V2 if FastF1 lacks data. " + "**Deprecated** — use `GET /api/v2/qualifying-results-plot` instead." + ), + responses={200: _PNG_RESPONSE, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") async def qualifying_results_plot( request: Request, @@ -225,7 +337,6 @@ async def qualifying_results_plot( session: str = Query('Q'), api_key: str = Depends(verify_api_key) ): - """Generate PNG plot of qualifying results. Falls back to V2 if FastF1 lacks data.""" logger.info(f"Generating qualifying results plot: Y{year} GP{gp} {session}") try: output_path = await run_in_threadpool( @@ -240,7 +351,19 @@ async def qualifying_results_plot( except T1APIError: raise -@router.get('/qualifying-results-data', tags=["API v1", "Simple Analysis"]) + +@router.get( + '/qualifying-results-data', + tags=["API v1"], + deprecated=True, + summary="Qualifying results data", + operation_id="v1_qualifying_results_data", + description=( + "Get raw JSON data for qualifying results. **Deprecated** — use " + "`GET /api/v2/qualifying-results-data` instead." + ), + responses={200: {"model": LegacyQualifyingResultsDataResponse}, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("data") async def qualifying_results_data( request: Request, @@ -249,19 +372,11 @@ async def qualifying_results_data( session: str = Query('Q'), api_key: str = Depends(verify_api_key) ): - """Get raw JSON data for qualifying results""" try: logger.info(f"Fetching qualifying results data: Y{year} GP{gp} {session}") result = await run_in_threadpool(QualiResultsData, year, gp, session) - - # Track session if tracker is available - try: - from src.core.observability.analytics import SessionTracker - session_tracker = SessionTracker() - session_tracker.track_session('qualifying-results', year, gp, session) - except: - pass - + _track('qualifying-results', year, gp, session) + # Check if result is cached data (dict/list) or file path (str) if isinstance(result, (dict, list)): return result @@ -273,7 +388,19 @@ async def qualifying_results_data( logger.error(f"Error fetching qualifying data: {e}", exc_info=True) raise HTTPException(status_code=500, detail="Failed to fetch data") -@router.get('/laptimes', tags=["API v1", "Simple Analysis"]) + +@router.get( + '/laptimes', + tags=["API v1"], + deprecated=True, + summary="Lap time distribution for a driver", + operation_id="v1_laptimes", + description=( + "Get laptime distribution data for a specific driver. **Deprecated** — use " + "`GET /api/v2/laptimes-distribution-data` instead." + ), + responses={200: {"model": LegacyLaptimesDataResponse}, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") async def get_laptimes( request: Request, @@ -283,19 +410,11 @@ async def get_laptimes( driver: str = Query('VER', min_length=3, max_length=3), api_key: str = Depends(verify_api_key) ): - """Get laptime distribution data for a specific driver""" try: logger.info(f"Fetching lap times: Y{year} GP{gp} {session} Driver:{driver}") result = await run_in_threadpool(LatimesDistribution, year, gp, session, driver) - - # Track session if tracker is available - try: - from src.core.observability.analytics import SessionTracker - session_tracker = SessionTracker() - session_tracker.track_session('laptimes', year, gp, session, driver) - except: - pass - + _track('laptimes', year, gp, session, driver) + # Handle both cached data (list) and file path (string) if isinstance(result, list): return JSONResponse(content=result) @@ -307,7 +426,19 @@ async def get_laptimes( logger.error(f"Error fetching lap times: {e}", exc_info=True) raise HTTPException(status_code=500, detail="Failed to fetch lap times") -@router.get('/speed-distribution-plot', tags=["API v1", "Simple Analysis"]) + +@router.get( + '/speed-distribution-plot', + tags=["API v1"], + deprecated=True, + summary="Speed distribution plot", + operation_id="v1_speed_distribution_plot", + description=( + "Generate PNG plot of speed distribution. **Deprecated** — use " + "`GET /api/v2/speed-distribution-plot` instead." + ), + responses={200: _PNG_RESPONSE, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") async def speed_distribution_plot( request: Request, @@ -317,19 +448,10 @@ async def speed_distribution_plot( driver: str = Query(None, description="Optional driver TLA (e.g., VER)"), api_key: str = Depends(verify_api_key) ): - """Generate PNG plot of speed distribution""" try: logger.info(f"Generating speed distribution plot: Y{year} GP{gp} {session} Driver={driver}") output_path = await run_in_threadpool(SpeedDistributionPlot, year, gp, session, driver) - - # Track session if tracker is available - try: - from src.core.observability.analytics import SessionTracker - session_tracker = SessionTracker() - session_tracker.track_session('speed-distribution', year, gp, session) - except: - pass - + _track('speed-distribution', year, gp, session) return FileResponse(output_path, media_type='image/png') except ValueError as ve: logger.warning(f"Data error in speed distribution plot: {ve}") @@ -340,7 +462,19 @@ async def speed_distribution_plot( logger.error(f"Error generating speed distribution plot: {e}", exc_info=True) raise HTTPException(status_code=500, detail="Failed to generate plot") -@router.get('/speed-distribution-data', tags=["API v1", "Simple Analysis"]) + +@router.get( + '/speed-distribution-data', + tags=["API v1"], + deprecated=True, + summary="Speed distribution data", + operation_id="v1_speed_distribution_data", + description=( + "Get raw JSON data for speed distribution. **Deprecated** — use " + "`GET /api/v2/speed-distribution-data` instead." + ), + responses={200: {"model": LegacySpeedDistributionDataResponse}, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("data") async def speed_distribution_data( request: Request, @@ -350,19 +484,11 @@ async def speed_distribution_data( driver: str = Query(None, description="Optional driver TLA (e.g., VER)"), api_key: str = Depends(verify_api_key) ): - """Get raw JSON data for speed distribution""" try: logger.info(f"Fetching speed distribution data: Y{year} GP{gp} {session} Driver={driver}") result = await run_in_threadpool(SpeedDistributionData, year, gp, session, driver) - - # Track session if tracker is available - try: - from src.core.observability.analytics import SessionTracker - session_tracker = SessionTracker() - session_tracker.track_session('speed-distribution', year, gp, session) - except: - pass - + _track('speed-distribution', year, gp, session) + if isinstance(result, (dict, list)): return result else: @@ -378,7 +504,19 @@ async def speed_distribution_data( # --- Driver Comparison --- -@router.get('/track-comparison-2drivers-plot', tags=["API v1", "Driver Comparison"]) + +@router.get( + '/track-comparison-2drivers-plot', + tags=["API v1"], + deprecated=True, + summary="Track map comparison (2 drivers) plot", + operation_id="v1_track_comparison_2drivers_plot", + description=( + "Generate track map comparing two drivers. **Deprecated** — use " + "`GET /api/v2/track-comparison-plot` instead." + ), + responses={200: _PNG_RESPONSE, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") async def track_comparison_2drivers_plot( request: Request, @@ -389,19 +527,10 @@ async def track_comparison_2drivers_plot( driver2: str = Query('HAM', min_length=3, max_length=3), api_key: str = Depends(verify_api_key) ): - """Generate track map comparing two drivers""" try: logger.info(f"Generating track comparison: Y{year} GP{gp} {session} {driver1} vs {driver2}") output_path = await run_in_threadpool(TrackComparisonPlot, year, gp, session, driver1, driver2) - - # Track session if tracker is available - try: - from src.core.observability.analytics import SessionTracker - session_tracker = SessionTracker() - session_tracker.track_session('track-comparison-2drivers', year, gp, session, driver1, driver2) - except: - pass - + _track('track-comparison-2drivers', year, gp, session, driver1, driver2) return FileResponse(output_path, media_type='image/png') except T1APIError: raise @@ -409,7 +538,19 @@ async def track_comparison_2drivers_plot( logger.error(f"Error generating track comparison: {e}", exc_info=True) raise HTTPException(status_code=500, detail="Failed to generate plot") -@router.get('/track-comparison-2drivers-data', tags=["API v1", "Driver Comparison"]) + +@router.get( + '/track-comparison-2drivers-data', + tags=["API v1"], + deprecated=True, + summary="Track map comparison (2 drivers) data", + operation_id="v1_track_comparison_2drivers_data", + description=( + "Get raw data for 2-driver track comparison. **Deprecated** — use " + "`GET /api/v2/track-comparison-data` instead." + ), + responses={200: {"model": LegacyTrackComparisonResponse}, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("data") async def track_comparison_2drivers_data( request: Request, @@ -420,19 +561,11 @@ async def track_comparison_2drivers_data( driver2: str = Query('HAM', min_length=3, max_length=3), api_key: str = Depends(verify_api_key) ): - """Get raw data for 2-driver track comparison""" try: logger.info(f"Fetching track comparison data: Y{year} GP{gp} {session} {driver1} vs {driver2}") result = await run_in_threadpool(TrackComparisonData, year, gp, session, driver1, driver2) - - # Track session if tracker is available - try: - from src.core.observability.analytics import SessionTracker - session_tracker = SessionTracker() - session_tracker.track_session('track-comparison-2drivers', year, gp, session, driver1, driver2) - except: - pass - + _track('track-comparison-2drivers', year, gp, session, driver1, driver2) + # Check if result is cached data (dict/list) or file path (str) if isinstance(result, (dict, list)): return result @@ -444,7 +577,19 @@ async def track_comparison_2drivers_data( logger.error(f"Error fetching track comparison data: {e}", exc_info=True) raise HTTPException(status_code=500, detail="Failed to fetch data") -@router.get('/throttleBrake-comparison-2drivers-plot', tags=["API v1", "Driver Comparison"]) + +@router.get( + '/throttleBrake-comparison-2drivers-plot', + tags=["API v1"], + deprecated=True, + summary="Throttle/brake comparison (2 drivers) plot", + operation_id="v1_throttle_brake_comparison_2drivers_plot", + description=( + "Generate throttle/brake telemetry graph for 2 drivers. **Deprecated** — use " + "`GET /api/v2/throttle-brake-comparison-plot` instead." + ), + responses={200: _PNG_RESPONSE, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") async def throttle_brake_comparison_2drivers_plot( request: Request, @@ -455,7 +600,6 @@ async def throttle_brake_comparison_2drivers_plot( driver2: str = Query('HAM', min_length=3, max_length=3), api_key: str = Depends(verify_api_key) ): - """Generate throttle/brake telemetry graph for 2 drivers""" try: logger.info(f"Generating throttle/brake comparison: Y{year} GP{gp} {session} {driver1} vs {driver2}") output_path = await run_in_threadpool(throttle_graph, year, gp, session, driver1, driver2) @@ -466,7 +610,19 @@ async def throttle_brake_comparison_2drivers_plot( logger.error(f"Error generating throttle/brake plot: {e}", exc_info=True) raise HTTPException(status_code=500, detail="Failed to generate plot") -@router.get('/throttleBrake-comparison-2drivers-data', tags=["API v1", "Driver Comparison"]) + +@router.get( + '/throttleBrake-comparison-2drivers-data', + tags=["API v1"], + deprecated=True, + summary="Throttle/brake comparison (2 drivers) data", + operation_id="v1_throttle_brake_comparison_2drivers_data", + description=( + "Get raw data for 2-driver throttle/brake comparison. **Deprecated** — use " + "`GET /api/v2/throttle-brake-comparison-data` instead." + ), + responses={200: {"model": LegacyThrottleBrakeComparisonResponse}, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("data") async def throttle_brake_comparison_2drivers_data( request: Request, @@ -477,19 +633,11 @@ async def throttle_brake_comparison_2drivers_data( driver2: str = Query('HAM', min_length=3, max_length=3), api_key: str = Depends(verify_api_key) ): - """Get raw data for 2-driver throttle/brake comparison""" try: logger.info(f"Fetching throttle/brake data: Y{year} GP{gp} {session} {driver1} vs {driver2}") result = await run_in_threadpool(throttle_graph_data, year, gp, session, driver1, driver2) - - # Track session if tracker is available - try: - from src.core.observability.analytics import SessionTracker - session_tracker = SessionTracker() - session_tracker.track_session('track-comparison-2drivers', year, gp, session, driver1, driver2) - except: - pass - + _track('track-comparison-2drivers', year, gp, session, driver1, driver2) + # Check if result is cached data (dict/list) or file path (str) if isinstance(result, (dict, list)): return result @@ -501,7 +649,19 @@ async def throttle_brake_comparison_2drivers_data( logger.error(f"Error fetching throttle/brake data: {e}", exc_info=True) raise HTTPException(status_code=500, detail="Failed to fetch data") -@router.get('/lap-time-analysis-plot', tags=["API v1", "Driver Comparison"]) + +@router.get( + '/lap-time-analysis-plot', + tags=["API v1"], + deprecated=True, + summary="Lap time analysis plot", + operation_id="v1_lap_time_analysis_plot", + description=( + "Speed / Delta time / Throttle comparison for two drivers' fastest laps. Falls " + "back to V2. **Deprecated** — use `GET /api/v2/lap-time-analysis-plot` instead." + ), + responses={200: _PNG_RESPONSE, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") async def lap_time_analysis_plot( request: Request, @@ -512,7 +672,6 @@ async def lap_time_analysis_plot( driver2: str = Query('HAM', min_length=3, max_length=3), api_key: str = Depends(verify_api_key) ): - """Speed / Delta time / Throttle comparison for two drivers' fastest laps. Falls back to V2.""" logger.info(f"Generating lap time analysis plot: Y{year} GP{gp} {session} {driver1} vs {driver2}") try: output_path = await run_in_threadpool( @@ -530,7 +689,19 @@ async def lap_time_analysis_plot( raise HTTPException(status_code=404, detail="Plot not found") -@router.get('/lap-time-analysis-data', tags=["API v1", "Driver Comparison"]) +@router.get( + '/lap-time-analysis-data', + tags=["API v1"], + deprecated=True, + summary="Lap time analysis data", + operation_id="v1_lap_time_analysis_data", + description=( + "Speed/Throttle telemetry + delta-time series for two drivers' fastest laps. " + "Falls back to V2. **Deprecated** — use `GET /api/v2/lap-time-analysis-data` " + "instead." + ), + responses={200: {"model": LegacyLapTimeAnalysisResponse}, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("data") async def lap_time_analysis_data( request: Request, @@ -541,7 +712,6 @@ async def lap_time_analysis_data( driver2: str = Query('HAM', min_length=3, max_length=3), api_key: str = Depends(verify_api_key) ): - """Speed/Throttle telemetry + delta-time series for two drivers' fastest laps. Falls back to V2.""" logger.info(f"Fetching lap time analysis data: Y{year} GP{gp} {session} {driver1} vs {driver2}") try: result = await run_in_threadpool( @@ -559,31 +729,48 @@ async def lap_time_analysis_data( raise -@router.get('/analytics/daily', tags=["API v1", "General"]) +@router.get( + '/analytics/daily', + tags=["API v1"], + deprecated=True, + summary="Daily session-tracker analytics", + operation_id="v1_analytics_daily", + description=( + "Get daily session analytics. **Deprecated, no V2 equivalent** — this is internal " + "request-tracking telemetry (`SessionTracker`, SQLite-backed), not an analysis " + "feature; it has no V2 counterpart and none is planned." + ), + responses={ + 200: {"model": LegacyDailyStatsResponse}, + 400: {"model": ErrorEnvelope, "description": "`date_str` is not in YYYY-MM-DD format."}, + 503: {"model": ErrorEnvelope, "description": "Session tracker unavailable."}, + **COMMON_ERROR_RESPONSES, + }, +) @apply_tiered_limit("standard") async def get_daily_analytics( request: Request, date_str: str = Query(None, description='Date in YYYY-MM-DD format'), api_key: str = Depends(verify_api_key) ): - """Get daily session analytics""" try: from src.core.observability.analytics import SessionTracker from datetime import datetime - + if date_str: target_date = datetime.strptime(date_str, '%Y-%m-%d').date() else: target_date = None - + try: session_tracker = SessionTracker() - except: + except Exception as tracker_err: + logger.warning(f"Session tracker unavailable: {tracker_err}") raise HTTPException(status_code=503, detail="Session tracker unavailable") - + stats = session_tracker.get_daily_stats(target_date) return stats - except ValueError as e: + except ValueError: raise HTTPException(status_code=400, detail="Invalid date format. Use YYYY-MM-DD") except HTTPException: raise @@ -591,21 +778,38 @@ async def get_daily_analytics( logger.error(f"Error fetching daily analytics: {e}", exc_info=True) raise HTTPException(status_code=500, detail="Failed to fetch analytics") -@router.get('/analytics/total', tags=["API v1", "General"]) + +@router.get( + '/analytics/total', + tags=["API v1"], + deprecated=True, + summary="Total session-tracker analytics", + operation_id="v1_analytics_total", + description=( + "Get total session analytics. **Deprecated, no V2 equivalent** — this is internal " + "request-tracking telemetry (`SessionTracker`, SQLite-backed), not an analysis " + "feature; it has no V2 counterpart and none is planned." + ), + responses={ + 200: {"model": LegacyDailyStatsResponse}, + 503: {"model": ErrorEnvelope, "description": "Session tracker unavailable."}, + **COMMON_ERROR_RESPONSES, + }, +) @apply_tiered_limit("standard") async def get_total_analytics( request: Request, api_key: str = Depends(verify_api_key) ): - """Get total session analytics""" try: from src.core.observability.analytics import SessionTracker - + try: session_tracker = SessionTracker() - except: + except Exception as tracker_err: + logger.warning(f"Session tracker unavailable: {tracker_err}") raise HTTPException(status_code=503, detail="Session tracker unavailable") - + stats = session_tracker.get_total_stats() return stats except HTTPException: @@ -617,7 +821,18 @@ async def get_total_analytics( # --- Pace Analysis --- -@router.get('/driver-pace-plot', tags=["API v1", "Pace Analysis"]) +@router.get( + '/driver-pace-plot', + tags=["API v1"], + deprecated=True, + summary="Driver pace distribution plot", + operation_id="v1_driver_pace_plot", + description=( + "Box-and-whisker pace plot per driver (107% quicklap filter). Falls back to V2. " + "**Deprecated** — use `GET /api/v2/driver-pace-plot` instead." + ), + responses={200: _PNG_RESPONSE, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") async def driver_pace_plot( request: Request, @@ -626,7 +841,6 @@ async def driver_pace_plot( session: str = Query('R'), api_key: str = Depends(verify_api_key) ): - """Box-and-whisker pace plot per driver (107% quicklap filter). Falls back to V2.""" logger.info(f"Generating driver pace plot: Y{year} GP{gp} {session}") try: output_path = await run_in_threadpool( @@ -644,7 +858,18 @@ async def driver_pace_plot( raise HTTPException(status_code=404, detail="Plot not found") -@router.get('/driver-pace-data', tags=["API v1", "Pace Analysis"]) +@router.get( + '/driver-pace-data', + tags=["API v1"], + deprecated=True, + summary="Driver pace distribution data", + operation_id="v1_driver_pace_data", + description=( + "JSON pace distribution per driver: lap times + min/q1/median/q3/max. Falls back " + "to V2. **Deprecated** — use `GET /api/v2/driver-pace-data` instead." + ), + responses={200: {"model": LegacyDriverPaceDataResponse}, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("data") async def driver_pace_data( request: Request, @@ -653,7 +878,6 @@ async def driver_pace_data( session: str = Query('R'), api_key: str = Depends(verify_api_key) ): - """JSON pace distribution per driver: lap times + min/q1/median/q3/max. Falls back to V2.""" logger.info(f"Fetching driver pace data: Y{year} GP{gp} {session}") try: result = await run_in_threadpool( @@ -671,7 +895,18 @@ async def driver_pace_data( raise -@router.get('/teams-pace-plot', tags=["API v1", "Pace Analysis"]) +@router.get( + '/teams-pace-plot', + tags=["API v1"], + deprecated=True, + summary="Team pace distribution plot", + operation_id="v1_teams_pace_plot", + description=( + "Box-and-whisker pace plot per team (laps from both drivers aggregated). Falls " + "back to V2. **Deprecated** — use `GET /api/v2/teams-pace-plot` instead." + ), + responses={200: _PNG_RESPONSE, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") async def teams_pace_plot( request: Request, @@ -680,7 +915,6 @@ async def teams_pace_plot( session: str = Query('R'), api_key: str = Depends(verify_api_key) ): - """Box-and-whisker pace plot per team (laps from both drivers aggregated). Falls back to V2.""" logger.info(f"Generating teams pace plot: Y{year} GP{gp} {session}") try: output_path = await run_in_threadpool( @@ -698,7 +932,18 @@ async def teams_pace_plot( raise HTTPException(status_code=404, detail="Plot not found") -@router.get('/teams-pace-data', tags=["API v1", "Pace Analysis"]) +@router.get( + '/teams-pace-data', + tags=["API v1"], + deprecated=True, + summary="Team pace distribution data", + operation_id="v1_teams_pace_data", + description=( + "JSON pace distribution per team. Falls back to V2. **Deprecated** — use " + "`GET /api/v2/teams-pace-data` instead." + ), + responses={200: {"model": LegacyTeamsPaceDataResponse}, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("data") async def teams_pace_data( request: Request, @@ -707,7 +952,6 @@ async def teams_pace_data( session: str = Query('R'), api_key: str = Depends(verify_api_key) ): - """JSON pace distribution per team. Falls back to V2.""" logger.info(f"Fetching teams pace data: Y{year} GP{gp} {session}") try: result = await run_in_threadpool( @@ -725,7 +969,18 @@ async def teams_pace_data( raise -@router.get('/tyre-stint-usage-plot', tags=["API v1", "Race Analysis"]) +@router.get( + '/tyre-stint-usage-plot', + tags=["API v1"], + deprecated=True, + summary="Tyre stint usage plot", + operation_id="v1_tyre_stint_usage_plot", + description=( + "Stint strategy timeline: per-driver compound stints across the race. Falls back " + "to V2. **Deprecated** — use `GET /api/v2/tyre-stint-usage-plot` instead." + ), + responses={200: _PNG_RESPONSE, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") async def tyre_stint_usage_plot( request: Request, @@ -734,7 +989,6 @@ async def tyre_stint_usage_plot( session: str = Query('R'), api_key: str = Depends(verify_api_key) ): - """Stint strategy timeline: per-driver compound stints across the race. Falls back to V2.""" logger.info(f"Generating tyre stint usage plot: Y{year} GP{gp} {session}") try: output_path = await run_in_threadpool( @@ -752,7 +1006,18 @@ async def tyre_stint_usage_plot( raise HTTPException(status_code=404, detail="Plot not found") -@router.get('/tyre-stint-usage-data', tags=["API v1", "Race Analysis"]) +@router.get( + '/tyre-stint-usage-data', + tags=["API v1"], + deprecated=True, + summary="Tyre stint usage data", + operation_id="v1_tyre_stint_usage_data", + description=( + "JSON per-stint records (driver, compound, start_lap, end_lap, lap_count). Falls " + "back to V2. **Deprecated** — use `GET /api/v2/tyre-stint-usage-data` instead." + ), + responses={200: {"model": LegacyTyreStintUsageDataResponse}, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("data") async def tyre_stint_usage_data( request: Request, @@ -761,7 +1026,6 @@ async def tyre_stint_usage_data( session: str = Query('R'), api_key: str = Depends(verify_api_key) ): - """JSON per-stint records (driver, compound, start_lap, end_lap, lap_count). Falls back to V2.""" logger.info(f"Fetching tyre stint usage data: Y{year} GP{gp} {session}") try: result = await run_in_threadpool( diff --git a/src/api/routers/analysis_v2.py b/src/api/routers/analysis_v2.py index 06b563c..44700aa 100644 --- a/src/api/routers/analysis_v2.py +++ b/src/api/routers/analysis_v2.py @@ -2,11 +2,41 @@ from fastapi.responses import FileResponse, JSONResponse from fastapi.concurrency import run_in_threadpool from typing import Optional, Union +from src.api.deps import guard_session_params from src.core.logging import get_logger from src.core.security.api_keys import verify_api_key from src.core.security.rate_limiting import apply_tiered_limit from src.services.orchestrator_helpers import get_latest_finished_session from src.services.orchestrator import latest_session_analised_v2 +from src.api.schemas.common import ANALYSIS_ERROR_RESPONSES, COMMON_ERROR_RESPONSES, ErrorEnvelope +from src.api.schemas.analysis import ( + DashboardResponse, + TopSpeedTelemetryDataResponse, + TopSpeedSpeedTrapDataResponse, + ThrottleComparisonDataResponse, + SpeedDistributionDataResponse, + LaptimesDistributionDataResponse, + QualifyingResultsDataResponse, + ThrottleBrakeComparisonResponse, + TrackComparisonResponse, + LapTimeAnalysisResponse, + DriverPaceDataResponse, + TeamsPaceDataResponse, + TyreStintUsageDataResponse, + PositionChangesDataResponse, + RaceGapsDataResponse, + TyreDegradationDataResponse, + PitStrategyResponse, + SessionWeatherResponse, + RacePaceHeatmapResponse, + TrackEvolutionResponse, + TheoreticalBestDataResponse, + RaceStoryResponse, + TrackMapResponse, + LapAllDataResponse, + CornerDuelResponse, + DriverRadarResponse, +) # Importing Turn One Core files from src.services.analysis.v2.top_speed import TopSpeedPlot_Telemetry, TopSpeedData_Telemetry, TopSpeedPlot_SpeedTrap, TopSpeedData_SpeedTrap @@ -30,6 +60,7 @@ from src.services.analysis.v2.theoretical_best import TheoreticalBestPlot, TheoreticalBestData from src.services.analysis.v2.race_story import RaceStoryPlot, RaceStoryData from src.services.analysis.v2.telemetry_track_map import TrackMapPlot, TrackMapData +from src.services.analysis.v2.lap_all_data import LapAllData from src.services.analysis.v2.corner_duel import CornerDuelPlot, CornerDuelData from src.services.analysis.v2.driver_radar import DriverRadarPlot, DriverRadarData @@ -55,16 +86,40 @@ def _track(event_name, *args): except Exception: pass -router = APIRouter(prefix="/api/v2") - -@router.get('/dashboard', tags=["API v2", "Latest Session"]) +#: Documentation-only shape for every ``-plot`` endpoint: a PNG body, no JSON schema. +_PNG_RESPONSE = {"content": {"image/png": {}}, "description": "PNG plot."} + +router = APIRouter( + prefix="/api/v2", + # Validates `session` / `driver*` from the raw query string. Declares no + # parameters of its own, so the OpenAPI schema and the frozen public + # query-parameter contract are untouched. + dependencies=[Depends(guard_session_params)], +) + + +@router.get( + '/dashboard', + tags=["API v2", "Latest Session"], + summary="Latest session dashboard", + operation_id="v2_dashboard_latest_session", + responses={ + 200: {"model": DashboardResponse}, + 404: {"model": ErrorEnvelope, "description": "No finished sessions found in the schedule."}, + **COMMON_ERROR_RESPONSES, + }, +) @apply_tiered_limit("data") async def get_dashboard_data_v2(request: Request, api_key: str = Depends(verify_api_key)): """ Get main latest session data via the livetiming-only V2 path. Automatically detects the most recent completed session from the F1 static index (no FastF1). + + Unlike the rest of V2, this response is **not** immutable: it targets + the latest finished session and its content changes as a race weekend + progresses (each new completed session becomes the new "latest"). """ try: logger.info("Fetching V2 dashboard data for latest session") @@ -88,7 +143,17 @@ async def get_dashboard_data_v2(request: Request, api_key: str = Depends(verify_ # --- Simple Analysis Endpoints --- -@router.get('/top-speed-telemetry-plot', tags=["API v2", "Simple Analysis"]) +@router.get( + '/top-speed-telemetry-plot', + tags=["API v2", "Simple Analysis"], + summary="Top speed per team (telemetry) plot", + operation_id="v2_top_speed_telemetry_plot", + description=( + "PNG plot of each team's maximum speed for the session, computed from CarData " + "telemetry. Falls back to V1/FastF1 if livetiming data is unavailable." + ), + responses={200: _PNG_RESPONSE, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") async def top_speed_telemetry_plot( request: Request, @@ -116,7 +181,17 @@ async def top_speed_telemetry_plot( logger.error(f"Plot file not found: Y{year} GP{gp} {session}") raise HTTPException(status_code=404, detail="Plot not found") -@router.get('/top-speed-telemetry-data', tags=["API v2", "Simple Analysis"]) +@router.get( + '/top-speed-telemetry-data', + tags=["API v2", "Simple Analysis"], + summary="Top speed per team (telemetry) data", + operation_id="v2_top_speed_telemetry_data", + description=( + "JSON per-team top speed for the session, computed from CarData telemetry. " + "Falls back to V1/FastF1 if livetiming data is unavailable." + ), + responses={200: {"model": TopSpeedTelemetryDataResponse}, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("data") async def top_speed_telemetry_data( request: Request, @@ -140,7 +215,16 @@ async def top_speed_telemetry_data( except T1APIError: raise -@router.get('/top-speed-st-plot', tags=["API v2", "Simple Analysis"]) +@router.get( + '/top-speed-st-plot', + tags=["API v2", "Simple Analysis"], + summary="Top speed per team (speed trap) plot", + operation_id="v2_top_speed_speed_trap_plot", + description=( + "PNG plot of each team's official Speed Trap top speed for the session (no V1 fallback)." + ), + responses={200: _PNG_RESPONSE, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") async def top_speed_st_plot( request: Request, @@ -153,13 +237,7 @@ async def top_speed_st_plot( logger.info(f"Generating top speed plot: Y{year} GP{gp} {session}") output_path = await run_in_threadpool(TopSpeedPlot_SpeedTrap, year, gp, session) - # Track session if tracker is available - try: - from src.core.observability.analytics import SessionTracker - session_tracker = SessionTracker() - session_tracker.track_session('top-speed', year, gp, session) - except: - pass + _track('top-speed', year, gp, session) return FileResponse(output_path, media_type="image/png") except FileNotFoundError: @@ -171,7 +249,16 @@ async def top_speed_st_plot( logger.error(f"Error generating top speed plot: {e}", exc_info=True) raise HTTPException(status_code=500, detail="Failed to generate plot") -@router.get('/top-speed-st-data', tags=["API v2", "Simple Analysis"]) +@router.get( + '/top-speed-st-data', + tags=["API v2", "Simple Analysis"], + summary="Top speed per team (speed trap) data", + operation_id="v2_top_speed_speed_trap_data", + description=( + "JSON per-team official Speed Trap top speed for the session (no V1 fallback)." + ), + responses={200: {"model": TopSpeedSpeedTrapDataResponse}, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("data") async def top_speed_st_data( request: Request, @@ -183,15 +270,9 @@ async def top_speed_st_data( try: logger.info(f"Fetching top speed data: Y{year} GP{gp} {session}") result = await run_in_threadpool(TopSpeedData_SpeedTrap, year, gp, session) - - # Track session if tracker is available - try: - from src.core.observability.analytics import SessionTracker - session_tracker = SessionTracker() - session_tracker.track_session('top-speed', year, gp, session) - except: - pass - + + _track('top-speed', year, gp, session) + # Data functions now always return list directly (from MongoDB or processed) return result except T1APIError: @@ -202,7 +283,13 @@ async def top_speed_st_data( # Throttle comparison endpoints -@router.get('/throttle-comparison-plot', tags=["API v2", "Simple Analysis"]) +@router.get( + '/throttle-comparison-plot', + tags=["API v2", "Simple Analysis"], + summary="Throttle comparison plot", + operation_id="v2_throttle_comparison_plot", + responses={200: _PNG_RESPONSE, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") async def throttle_comparison_plot( request: Request, @@ -227,7 +314,13 @@ async def throttle_comparison_plot( except T1APIError: raise -@router.get('/throttle-comparison-data', tags=["API v2", "Simple Analysis"]) +@router.get( + '/throttle-comparison-data', + tags=["API v2", "Simple Analysis"], + summary="Throttle comparison data", + operation_id="v2_throttle_comparison_data", + responses={200: {"model": ThrottleComparisonDataResponse}, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("data") async def throttle_comparison_data( request: Request, @@ -254,7 +347,13 @@ async def throttle_comparison_data( except T1APIError: raise -@router.get('/speed-distribution-plot', tags=["API v2", "Simple Analysis"]) +@router.get( + '/speed-distribution-plot', + tags=["API v2", "Simple Analysis"], + summary="Speed distribution plot", + operation_id="v2_speed_distribution_plot", + responses={200: _PNG_RESPONSE, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") async def speed_distribution_plot( request: Request, @@ -268,15 +367,15 @@ async def speed_distribution_plot( try: logger.info(f"Generating speed distribution plot: Y{year} GP{gp} {session} Driver={driver}") output_path = await run_in_threadpool(SpeedDistributionPlot, year, gp, session, driver) - + # Track session if tracker is available try: from src.core.observability.analytics import SessionTracker session_tracker = SessionTracker() session_tracker.track_session('speed-distribution', year, gp, session) - except: - pass - + except Exception as track_err: + logger.debug(f"Session tracking failed: {track_err}") + return FileResponse(output_path, media_type='image/png') except T1APIError: raise @@ -284,7 +383,13 @@ async def speed_distribution_plot( logger.error(f"Error generating speed distribution plot: {e}", exc_info=True) raise HTTPException(status_code=500, detail="Failed to generate plot") -@router.get('/speed-distribution-data', tags=["API v2", "Simple Analysis"]) +@router.get( + '/speed-distribution-data', + tags=["API v2", "Simple Analysis"], + summary="Speed distribution data", + operation_id="v2_speed_distribution_data", + responses={200: {"model": SpeedDistributionDataResponse}, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("data") async def speed_distribution_data( request: Request, @@ -298,15 +403,15 @@ async def speed_distribution_data( try: logger.info(f"Fetching speed distribution data: Y{year} GP{gp} {session} Driver={driver}") result = await run_in_threadpool(SpeedDistributionData, year, gp, session, driver) - + # Track session if tracker is available try: from src.core.observability.analytics import SessionTracker session_tracker = SessionTracker() session_tracker.track_session('speed-distribution', year, gp, session) - except: - pass - + except Exception as track_err: + logger.debug(f"Session tracking failed: {track_err}") + if isinstance(result, (dict, list)): return result else: @@ -320,7 +425,13 @@ async def speed_distribution_data( # --- Lap Times Distribution --- -@router.get('/laptimes-distribution-data', tags=["API v2", "Simple Analysis"]) +@router.get( + '/laptimes-distribution-data', + tags=["API v2", "Simple Analysis"], + summary="Lap times distribution data", + operation_id="v2_laptimes_distribution_data", + responses={200: {"model": LaptimesDistributionDataResponse}, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("data") async def laptimes_distribution_data( request: Request, @@ -344,7 +455,13 @@ async def laptimes_distribution_data( # --- Qualifying Results --- -@router.get('/qualifying-results-plot', tags=["API v2", "Qualifying"]) +@router.get( + '/qualifying-results-plot', + tags=["API v2", "Qualifying"], + summary="Qualifying results plot", + operation_id="v2_qualifying_results_plot", + responses={200: _PNG_RESPONSE, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") async def qualifying_results_plot( request: Request, @@ -375,7 +492,13 @@ async def qualifying_results_plot( raise HTTPException(status_code=404, detail="Plot not found") -@router.get('/qualifying-results-data', tags=["API v2", "Qualifying"]) +@router.get( + '/qualifying-results-data', + tags=["API v2", "Qualifying"], + summary="Qualifying results data", + operation_id="v2_qualifying_results_data", + responses={200: {"model": QualifyingResultsDataResponse}, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("data") async def qualifying_results_data( request: Request, @@ -398,7 +521,13 @@ async def qualifying_results_data( # --- Throttle/Brake Comparison (2 drivers) --- -@router.get('/throttle-brake-comparison-plot', tags=["API v2", "Qualifying"]) +@router.get( + '/throttle-brake-comparison-plot', + tags=["API v2", "Qualifying"], + summary="Throttle/brake comparison plot", + operation_id="v2_throttle_brake_comparison_plot", + responses={200: _PNG_RESPONSE, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") async def throttle_brake_comparison_plot( request: Request, @@ -427,7 +556,13 @@ async def throttle_brake_comparison_plot( raise HTTPException(status_code=500, detail="Failed to generate plot") -@router.get('/throttle-brake-comparison-data', tags=["API v2", "Qualifying"]) +@router.get( + '/throttle-brake-comparison-data', + tags=["API v2", "Qualifying"], + summary="Throttle/brake comparison data", + operation_id="v2_throttle_brake_comparison_data", + responses={200: {"model": ThrottleBrakeComparisonResponse}, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("data") async def throttle_brake_comparison_data( request: Request, @@ -452,7 +587,13 @@ async def throttle_brake_comparison_data( # --- Track Comparison (2 drivers) --- -@router.get('/track-comparison-plot', tags=["API v2", "Qualifying"]) +@router.get( + '/track-comparison-plot', + tags=["API v2", "Qualifying"], + summary="Track minisector comparison plot", + operation_id="v2_track_comparison_plot", + responses={200: _PNG_RESPONSE, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") async def track_comparison_plot( request: Request, @@ -481,7 +622,13 @@ async def track_comparison_plot( raise HTTPException(status_code=500, detail="Failed to generate plot") -@router.get('/track-comparison-data', tags=["API v2", "Qualifying"]) +@router.get( + '/track-comparison-data', + tags=["API v2", "Qualifying"], + summary="Track minisector comparison data", + operation_id="v2_track_comparison_data", + responses={200: {"model": TrackComparisonResponse}, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("data") async def track_comparison_data( request: Request, @@ -506,7 +653,13 @@ async def track_comparison_data( # --- Lap Time Analysis (2 drivers) --- -@router.get('/lap-time-analysis-plot', tags=["API v2", "Qualifying"]) +@router.get( + '/lap-time-analysis-plot', + tags=["API v2", "Qualifying"], + summary="Lap time analysis plot", + operation_id="v2_lap_time_analysis_plot", + responses={200: _PNG_RESPONSE, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") async def lap_time_analysis_plot( request: Request, @@ -540,7 +693,13 @@ async def lap_time_analysis_plot( raise -@router.get('/lap-time-analysis-data', tags=["API v2", "Qualifying"]) +@router.get( + '/lap-time-analysis-data', + tags=["API v2", "Qualifying"], + summary="Lap time analysis data", + operation_id="v2_lap_time_analysis_data", + responses={200: {"model": LapTimeAnalysisResponse}, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("data") async def lap_time_analysis_data( request: Request, @@ -570,7 +729,13 @@ async def lap_time_analysis_data( # --- Pace Analysis --- -@router.get('/driver-pace-plot', tags=["API v2", "Pace Analysis"]) +@router.get( + '/driver-pace-plot', + tags=["API v2", "Pace Analysis"], + summary="Driver pace distribution plot", + operation_id="v2_driver_pace_plot", + responses={200: _PNG_RESPONSE, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") async def driver_pace_plot_v2( request: Request, @@ -598,7 +763,13 @@ async def driver_pace_plot_v2( raise HTTPException(status_code=404, detail="Plot not found") -@router.get('/driver-pace-data', tags=["API v2", "Pace Analysis"]) +@router.get( + '/driver-pace-data', + tags=["API v2", "Pace Analysis"], + summary="Driver pace distribution data", + operation_id="v2_driver_pace_data", + responses={200: {"model": DriverPaceDataResponse}, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("data") async def driver_pace_data_v2( request: Request, @@ -624,7 +795,13 @@ async def driver_pace_data_v2( raise -@router.get('/teams-pace-plot', tags=["API v2", "Pace Analysis"]) +@router.get( + '/teams-pace-plot', + tags=["API v2", "Pace Analysis"], + summary="Team pace distribution plot", + operation_id="v2_teams_pace_plot", + responses={200: _PNG_RESPONSE, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") async def teams_pace_plot_v2( request: Request, @@ -652,7 +829,13 @@ async def teams_pace_plot_v2( raise HTTPException(status_code=404, detail="Plot not found") -@router.get('/teams-pace-data', tags=["API v2", "Pace Analysis"]) +@router.get( + '/teams-pace-data', + tags=["API v2", "Pace Analysis"], + summary="Team pace distribution data", + operation_id="v2_teams_pace_data", + responses={200: {"model": TeamsPaceDataResponse}, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("data") async def teams_pace_data_v2( request: Request, @@ -678,7 +861,13 @@ async def teams_pace_data_v2( raise -@router.get('/tyre-stint-usage-plot', tags=["API v2", "Race Analysis"]) +@router.get( + '/tyre-stint-usage-plot', + tags=["API v2", "Race Analysis"], + summary="Tyre stint usage plot", + operation_id="v2_tyre_stint_usage_plot", + responses={200: _PNG_RESPONSE, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") async def tyre_stint_usage_plot_v2( request: Request, @@ -706,7 +895,13 @@ async def tyre_stint_usage_plot_v2( raise HTTPException(status_code=404, detail="Plot not found") -@router.get('/tyre-stint-usage-data', tags=["API v2", "Race Analysis"]) +@router.get( + '/tyre-stint-usage-data', + tags=["API v2", "Race Analysis"], + summary="Tyre stint usage data", + operation_id="v2_tyre_stint_usage_data", + responses={200: {"model": TyreStintUsageDataResponse}, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("data") async def tyre_stint_usage_data_v2( request: Request, @@ -732,7 +927,13 @@ async def tyre_stint_usage_data_v2( raise -@router.get('/position-changes-plot', tags=["API v2", "Race Analysis"]) +@router.get( + '/position-changes-plot', + tags=["API v2", "Race Analysis"], + summary="Race position changes plot", + operation_id="v2_position_changes_plot", + responses={200: _PNG_RESPONSE, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") async def position_changes_plot_v2( request: Request, @@ -753,7 +954,13 @@ async def position_changes_plot_v2( raise HTTPException(status_code=404, detail="Plot not found") -@router.get('/position-changes-data', tags=["API v2", "Race Analysis"]) +@router.get( + '/position-changes-data', + tags=["API v2", "Race Analysis"], + summary="Race position changes data", + operation_id="v2_position_changes_data", + responses={200: {"model": PositionChangesDataResponse}, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("data") async def position_changes_data_v2( request: Request, @@ -772,7 +979,13 @@ async def position_changes_data_v2( raise -@router.get('/race-gaps-plot', tags=["API v2", "Race Analysis"]) +@router.get( + '/race-gaps-plot', + tags=["API v2", "Race Analysis"], + summary="Race gaps / race trace plot", + operation_id="v2_race_gaps_plot", + responses={200: _PNG_RESPONSE, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") async def race_gaps_plot_v2( request: Request, @@ -797,7 +1010,13 @@ async def race_gaps_plot_v2( raise HTTPException(status_code=404, detail="Plot not found") -@router.get('/race-gaps-data', tags=["API v2", "Race Analysis"]) +@router.get( + '/race-gaps-data', + tags=["API v2", "Race Analysis"], + summary="Race gaps / race trace data", + operation_id="v2_race_gaps_data", + responses={200: {"model": RaceGapsDataResponse}, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("data") async def race_gaps_data_v2( request: Request, @@ -820,7 +1039,13 @@ async def race_gaps_data_v2( raise -@router.get('/tyre-degradation-plot', tags=["API v2", "Race Analysis"]) +@router.get( + '/tyre-degradation-plot', + tags=["API v2", "Race Analysis"], + summary="Tyre degradation plot", + operation_id="v2_tyre_degradation_plot", + responses={200: _PNG_RESPONSE, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") async def tyre_degradation_plot_v2( request: Request, @@ -848,7 +1073,13 @@ async def tyre_degradation_plot_v2( raise HTTPException(status_code=404, detail="Plot not found") -@router.get('/tyre-degradation-data', tags=["API v2", "Race Analysis"]) +@router.get( + '/tyre-degradation-data', + tags=["API v2", "Race Analysis"], + summary="Tyre degradation data", + operation_id="v2_tyre_degradation_data", + responses={200: {"model": TyreDegradationDataResponse}, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("data") async def tyre_degradation_data_v2( request: Request, @@ -874,7 +1105,13 @@ async def tyre_degradation_data_v2( raise -@router.get('/pit-strategy-plot', tags=["API v2", "Race Analysis"]) +@router.get( + '/pit-strategy-plot', + tags=["API v2", "Race Analysis"], + summary="Pit strategy & undercuts plot", + operation_id="v2_pit_strategy_plot", + responses={200: _PNG_RESPONSE, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") async def pit_strategy_plot_v2( request: Request, @@ -895,7 +1132,13 @@ async def pit_strategy_plot_v2( raise HTTPException(status_code=404, detail="Plot not found") -@router.get('/pit-strategy-data', tags=["API v2", "Race Analysis"]) +@router.get( + '/pit-strategy-data', + tags=["API v2", "Race Analysis"], + summary="Pit strategy & undercuts data", + operation_id="v2_pit_strategy_data", + responses={200: {"model": PitStrategyResponse}, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("data") async def pit_strategy_data_v2( request: Request, @@ -914,7 +1157,13 @@ async def pit_strategy_data_v2( raise -@router.get('/session-weather-plot', tags=["API v2", "Race Analysis"]) +@router.get( + '/session-weather-plot', + tags=["API v2", "Race Analysis"], + summary="Session weather timeline plot", + operation_id="v2_session_weather_plot", + responses={200: _PNG_RESPONSE, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") async def session_weather_plot_v2( request: Request, @@ -935,7 +1184,13 @@ async def session_weather_plot_v2( raise HTTPException(status_code=404, detail="Plot not found") -@router.get('/session-weather-data', tags=["API v2", "Race Analysis"]) +@router.get( + '/session-weather-data', + tags=["API v2", "Race Analysis"], + summary="Session weather timeline data", + operation_id="v2_session_weather_data", + responses={200: {"model": SessionWeatherResponse}, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("data") async def session_weather_data_v2( request: Request, @@ -954,7 +1209,13 @@ async def session_weather_data_v2( raise -@router.get('/race-pace-heatmap-plot', tags=["API v2", "Race Analysis"]) +@router.get( + '/race-pace-heatmap-plot', + tags=["API v2", "Race Analysis"], + summary="Race pace heatmap plot", + operation_id="v2_race_pace_heatmap_plot", + responses={200: _PNG_RESPONSE, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") async def race_pace_heatmap_plot_v2( request: Request, @@ -975,7 +1236,13 @@ async def race_pace_heatmap_plot_v2( raise HTTPException(status_code=404, detail="Plot not found") -@router.get('/race-pace-heatmap-data', tags=["API v2", "Race Analysis"]) +@router.get( + '/race-pace-heatmap-data', + tags=["API v2", "Race Analysis"], + summary="Race pace heatmap data", + operation_id="v2_race_pace_heatmap_data", + responses={200: {"model": RacePaceHeatmapResponse}, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("data") async def race_pace_heatmap_data_v2( request: Request, @@ -994,7 +1261,13 @@ async def race_pace_heatmap_data_v2( raise -@router.get('/track-evolution-plot', tags=["API v2", "Race Analysis"]) +@router.get( + '/track-evolution-plot', + tags=["API v2", "Race Analysis"], + summary="Track evolution plot", + operation_id="v2_track_evolution_plot", + responses={200: _PNG_RESPONSE, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") async def track_evolution_plot_v2( request: Request, @@ -1018,7 +1291,13 @@ async def track_evolution_plot_v2( raise HTTPException(status_code=404, detail="Plot not found") -@router.get('/track-evolution-data', tags=["API v2", "Race Analysis"]) +@router.get( + '/track-evolution-data', + tags=["API v2", "Race Analysis"], + summary="Track evolution data", + operation_id="v2_track_evolution_data", + responses={200: {"model": TrackEvolutionResponse}, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("data") async def track_evolution_data_v2( request: Request, @@ -1040,7 +1319,13 @@ async def track_evolution_data_v2( raise -@router.get('/theoretical-best-plot', tags=["API v2", "Qualifying Analysis"]) +@router.get( + '/theoretical-best-plot', + tags=["API v2", "Qualifying"], + summary="Theoretical best lap plot", + operation_id="v2_theoretical_best_plot", + responses={200: _PNG_RESPONSE, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") async def theoretical_best_plot_v2( request: Request, @@ -1061,7 +1346,13 @@ async def theoretical_best_plot_v2( raise HTTPException(status_code=404, detail="Plot not found") -@router.get('/theoretical-best-data', tags=["API v2", "Qualifying Analysis"]) +@router.get( + '/theoretical-best-data', + tags=["API v2", "Qualifying"], + summary="Theoretical best lap data", + operation_id="v2_theoretical_best_data", + responses={200: {"model": TheoreticalBestDataResponse}, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("data") async def theoretical_best_data_v2( request: Request, @@ -1080,7 +1371,13 @@ async def theoretical_best_data_v2( raise -@router.get('/race-story-plot', tags=["API v2", "Race Analysis"]) +@router.get( + '/race-story-plot', + tags=["API v2", "Race Analysis"], + summary="Race story timeline plot", + operation_id="v2_race_story_plot", + responses={200: _PNG_RESPONSE, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") async def race_story_plot_v2( request: Request, @@ -1101,7 +1398,13 @@ async def race_story_plot_v2( raise HTTPException(status_code=404, detail="Plot not found") -@router.get('/race-story-data', tags=["API v2", "Race Analysis"]) +@router.get( + '/race-story-data', + tags=["API v2", "Race Analysis"], + summary="Race story timeline data", + operation_id="v2_race_story_data", + responses={200: {"model": RaceStoryResponse}, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("data") async def race_story_data_v2( request: Request, @@ -1120,7 +1423,13 @@ async def race_story_data_v2( raise -@router.get('/track-map-plot', tags=["API v2", "Telemetry"]) +@router.get( + '/track-map-plot', + tags=["API v2", "Telemetry"], + summary="Telemetry track map plot", + operation_id="v2_track_map_plot", + responses={200: _PNG_RESPONSE, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") async def track_map_plot_v2( request: Request, @@ -1143,7 +1452,13 @@ async def track_map_plot_v2( raise HTTPException(status_code=404, detail="Plot not found") -@router.get('/track-map-data', tags=["API v2", "Telemetry"]) +@router.get( + '/track-map-data', + tags=["API v2", "Telemetry"], + summary="Telemetry track map data", + operation_id="v2_track_map_data", + responses={200: {"model": TrackMapResponse}, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("data") async def track_map_data_v2( request: Request, @@ -1164,7 +1479,42 @@ async def track_map_data_v2( raise -@router.get('/corner-duel-plot', tags=["API v2", "Telemetry"]) +@router.get( + '/lap-all-data', + tags=["API v2", "Telemetry"], + summary="Full single-lap telemetry & metadata", + operation_id="v2_lap_all_data", + responses={200: {"model": LapAllDataResponse}, **ANALYSIS_ERROR_RESPONSES}, +) +@apply_tiered_limit("data") +async def lap_all_data_v2( + request: Request, + year: int = Query(2025, ge=2018, le=2030), + gp: Union[int, str] = Query(1, description="Round number, Event Key, or Official Name"), + session: str = Query('Q'), + driver: str = Query(..., description="Driver TLA (e.g., VER)"), + lap: int = Query(..., ge=1, description="Lap number (required)"), + api_key: str = Depends(verify_api_key) +): + """Everything for one driver's single lap: full telemetry time-series (speed/rpm/throttle/ + brake/gear/drs + X/Y/Z + distance), lap/tyre/sector/pit metadata, nearest weather sample, + track status, and driver/session context. Any session.""" + logger.info(f"Fetching lap-all-data (V2): Y{year} GP{gp} {session} driver={driver} lap={lap}") + try: + result = await run_in_threadpool(LapAllData(), year, gp, session, driver, lap) + _track('lap-all-data', year, gp, session) + return result + except T1APIError: + raise + + +@router.get( + '/corner-duel-plot', + tags=["API v2", "Telemetry"], + summary="Corner-by-corner duel plot", + operation_id="v2_corner_duel_plot", + responses={200: _PNG_RESPONSE, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") async def corner_duel_plot_v2( request: Request, @@ -1187,7 +1537,13 @@ async def corner_duel_plot_v2( raise HTTPException(status_code=404, detail="Plot not found") -@router.get('/corner-duel-data', tags=["API v2", "Telemetry"]) +@router.get( + '/corner-duel-data', + tags=["API v2", "Telemetry"], + summary="Corner-by-corner duel data", + operation_id="v2_corner_duel_data", + responses={200: {"model": CornerDuelResponse}, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("data") async def corner_duel_data_v2( request: Request, @@ -1208,7 +1564,13 @@ async def corner_duel_data_v2( raise -@router.get('/driver-radar-plot', tags=["API v2", "Telemetry"]) +@router.get( + '/driver-radar-plot', + tags=["API v2", "Telemetry"], + summary="Driver performance radar plot", + operation_id="v2_driver_radar_plot", + responses={200: _PNG_RESPONSE, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") async def driver_radar_plot_v2( request: Request, @@ -1231,7 +1593,13 @@ async def driver_radar_plot_v2( raise HTTPException(status_code=404, detail="Plot not found") -@router.get('/driver-radar-data', tags=["API v2", "Telemetry"]) +@router.get( + '/driver-radar-data', + tags=["API v2", "Telemetry"], + summary="Driver performance radar data", + operation_id="v2_driver_radar_data", + responses={200: {"model": DriverRadarResponse}, **ANALYSIS_ERROR_RESPONSES}, +) @apply_tiered_limit("data") async def driver_radar_data_v2( request: Request, diff --git a/src/api/routers/auth.py b/src/api/routers/auth.py index 251033b..004de48 100644 --- a/src/api/routers/auth.py +++ b/src/api/routers/auth.py @@ -4,6 +4,8 @@ from fastapi.concurrency import run_in_threadpool from pydantic import BaseModel, Field, field_validator +from src.api.schemas.accounts import MeResponse +from src.api.schemas.common import COMMON_ERROR_RESPONSES, ErrorEnvelope from src.auth.dependencies import get_current_user from src.auth.jwt import create_access_token from src.auth.passwords import hash_password, verify_password @@ -50,7 +52,24 @@ class TokenResponse(BaseModel): user_id: str -@router.post("/signup", response_model=TokenResponse, status_code=status.HTTP_201_CREATED) +@router.post( + "/signup", + response_model=TokenResponse, + status_code=status.HTTP_201_CREATED, + summary="Create an account", + operation_id="auth_signup", + description=( + "Create a new user account and return a JWT bearer token. " + "Unlike the rest of this API, authenticated endpoints under `/api/auth` and `/api/keys` / " + "`/api/me` use an `Authorization: Bearer ` header, not the `X-API-Key` header — " + "send the returned `access_token` that way on subsequent requests." + ), + responses={ + 409: {"model": ErrorEnvelope, "description": "Email already registered."}, + 429: COMMON_ERROR_RESPONSES[429], + 500: COMMON_ERROR_RESPONSES[500], + }, +) @apply_tiered_limit("public") async def signup(request: Request, body: SignupRequest): pwd_hash = await run_in_threadpool(hash_password, body.password) @@ -61,7 +80,23 @@ async def signup(request: Request, body: SignupRequest): return TokenResponse(access_token=token, user_id=user["id"]) -@router.post("/login", response_model=TokenResponse) +@router.post( + "/login", + response_model=TokenResponse, + summary="Log in and obtain a bearer token", + operation_id="auth_login", + description=( + "Exchange email/password for a JWT bearer token. This and every other `/api/auth` " + "endpoint use `Authorization: Bearer ` — not the `X-API-Key` header used " + "elsewhere in this API." + ), + responses={ + 401: {"model": ErrorEnvelope, "description": "Invalid email or password."}, + 403: {"model": ErrorEnvelope, "description": "Account is disabled."}, + 429: COMMON_ERROR_RESPONSES[429], + 500: COMMON_ERROR_RESPONSES[500], + }, +) @apply_tiered_limit("public") async def login(request: Request, body: LoginRequest): user = await run_in_threadpool(find_user_by_email, body.email) @@ -74,7 +109,22 @@ async def login(request: Request, body: LoginRequest): return TokenResponse(access_token=token, user_id=user_id) -@router.get("/me") +@router.get( + "/me", + summary="Get the current user's profile", + operation_id="auth_get_me", + description=( + "Return the authenticated user's profile and API key counts. Requires " + "`Authorization: Bearer ` — not the `X-API-Key` header used elsewhere in this API." + ), + responses={ + 200: {"model": MeResponse, "description": "Current user profile."}, + 401: { + "model": ErrorEnvelope, + "description": "Bearer token missing, invalid, or expired; or the user is disabled.", + }, + }, +) async def me(user: dict = Depends(get_current_user)): keys = await run_in_threadpool(list_for_owner, user["id"]) active = sum(1 for k in keys if not k.get("revoked_at")) diff --git a/src/api/routers/backup_admin.py b/src/api/routers/backup_admin.py index 35d7a55..451476f 100644 --- a/src/api/routers/backup_admin.py +++ b/src/api/routers/backup_admin.py @@ -10,7 +10,15 @@ from pydantic import BaseModel from src.api.admin_security import enforce_ip_allowlist, enforce_ui_rate_limit -from src.api.routers.admin import require_admin_key +from src.api.routers.admin import ADMIN_ERROR_RESPONSES, _err, require_admin_key +from src.api.schemas.admin import ( + BackupListResponse, + BackupManifestResponse, + BackupRestoreResponse, + BackupRunResponse, + BackupStatusResponse, + BackupVerifyResponse, +) from src.core.config import settings from src.core.logging import get_logger from src.core.security.rate_limiting import apply_tiered_limit @@ -26,7 +34,7 @@ def _gate(request: Request) -> None: enforce_ui_rate_limit(request) -router = APIRouter(prefix="/api/admin/backup", tags=["General"], dependencies=[Depends(_gate)]) +router = APIRouter(prefix="/api/admin/backup", tags=["Admin"], dependencies=[Depends(_gate)]) def _require_enabled() -> None: @@ -42,9 +50,19 @@ class RestoreRequest(BaseModel): # ── status / discovery ──────────────────────────────────────────────────── -@router.get("/status") +@router.get( + "/status", + summary="Backup subsystem status", + operation_id="backup_status", + responses={200: {"model": BackupStatusResponse}, **ADMIN_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") async def backup_status(request: Request, api_key: str = Depends(require_admin_key)): + """Scheduler state, last/next run, last backup outcome, and current retention/S3 config. + + Available even when the subsystem is disabled (``s3_reachable`` is then ``null`` + since S3 is never pinged) — every other endpoint here requires it enabled. + """ sched = get_scheduler() s3_ok: Optional[bool] = None if settings.backup_enabled: @@ -77,26 +95,46 @@ async def backup_status(request: Request, api_key: str = Depends(require_admin_k } -@router.get("/list") +@router.get( + "/list", + summary="List backup ids for a retention tier", + operation_id="backup_list", + responses={ + 200: {"model": BackupListResponse}, + 503: _err("Backup subsystem is disabled (BACKUP_ENABLED=false)."), + **ADMIN_ERROR_RESPONSES, + }, +) @apply_tiered_limit("standard") async def backup_list( request: Request, tier: str = Query("daily", pattern="^(daily|weekly|monthly)$"), api_key: str = Depends(require_admin_key), ): + """Backup ids present in S3 for one retention tier.""" _require_enabled() storage = await run_in_threadpool(S3Storage) ids = await run_in_threadpool(storage.list_backups, tier) return {"tier": tier, "count": len(ids), "backup_ids": ids} -@router.get("/manifest/{backup_id}") +@router.get( + "/manifest/{backup_id}", + summary="Fetch a backup's manifest", + operation_id="backup_manifest", + responses={ + 200: {"model": BackupManifestResponse}, + 503: _err("Backup subsystem is disabled (BACKUP_ENABLED=false)."), + **ADMIN_ERROR_RESPONSES, + }, +) @apply_tiered_limit("standard") async def backup_manifest( request: Request, backup_id: str, api_key: str = Depends(require_admin_key), ): + """Checksums, sizes, and per-artifact metadata for one backup.""" _require_enabled() runner = await run_in_threadpool(RestoreRunner) manifest = await run_in_threadpool(runner.load_manifest, backup_id) @@ -106,12 +144,24 @@ async def backup_manifest( # ── actions ─────────────────────────────────────────────────────────────── -@router.post("/run") +@router.post( + "/run", + summary="Trigger an immediate backup", + operation_id="backup_run", + responses={ + 200: {"model": BackupRunResponse}, + 409: _err("A backup is already in progress."), + 503: _err("Backup subsystem is disabled (BACKUP_ENABLED=false)."), + **ADMIN_ERROR_RESPONSES, + }, +) @apply_tiered_limit("standard") async def backup_run( request: Request, api_key: str = Depends(require_admin_key), ): + """Queue a backup to start immediately, outside the normal schedule. Returns + before the backup finishes; poll ``GET /api/admin/backup/status`` for outcome.""" _require_enabled() sched = get_scheduler() if sched._manual_in_progress: @@ -120,13 +170,23 @@ async def backup_run( return {"status": "triggered", "message": "Backup scheduled to start immediately"} -@router.post("/verify/{backup_id}") +@router.post( + "/verify/{backup_id}", + summary="Verify a backup's artifact checksums", + operation_id="backup_verify", + responses={ + 200: {"model": BackupVerifyResponse}, + 503: _err("Backup subsystem is disabled (BACKUP_ENABLED=false)."), + **ADMIN_ERROR_RESPONSES, + }, +) @apply_tiered_limit("standard") async def backup_verify( request: Request, backup_id: str, api_key: str = Depends(require_admin_key), ): + """Download each manifest artifact and confirm its ciphertext sha256 still matches. Read-only.""" _require_enabled() runner = await run_in_threadpool(RestoreRunner) report = await run_in_threadpool(runner.verify, backup_id) @@ -137,7 +197,21 @@ async def backup_verify( } -@router.post("/restore/{backup_id}") +@router.post( + "/restore/{backup_id}", + summary="Restore a backup into MongoDB/SQLite (destructive)", + operation_id="backup_restore", + responses={ + 200: {"model": BackupRestoreResponse}, + 400: _err( + "Missing double-confirmation for a real (non-drill) restore: both `?confirm=true` " + "and body field `i_understand=true` are required. For a safe drill instead, pass " + "body field `mongo_target_db=`, which needs neither." + ), + 503: _err("Backup subsystem is disabled (BACKUP_ENABLED=false)."), + **ADMIN_ERROR_RESPONSES, + }, +) @apply_tiered_limit("standard") async def backup_restore( request: Request, @@ -146,6 +220,16 @@ async def backup_restore( confirm: bool = Query(False), api_key: str = Depends(require_admin_key), ): + """Restore backup components into MongoDB (and SQLite) from the manifest. + + **Destructive against the live database** — restored collections are + overwritten (and, with ``mongo_drop=true``, dropped first) by the backup's + contents. Requires **both** ``?confirm=true`` on the query string **and** + body field ``i_understand=true``; without both, the handler refuses with + 400 before touching anything. The one exception is a drill: passing body + field ``mongo_target_db=`` restores into that database + instead of production and needs neither confirmation flag. + """ _require_enabled() is_drill = bool(payload.mongo_target_db) if not is_drill and not (confirm and payload.i_understand): diff --git a/src/api/routers/batch_v2.py b/src/api/routers/batch_v2.py new file mode 100644 index 0000000..48327a8 --- /dev/null +++ b/src/api/routers/batch_v2.py @@ -0,0 +1,232 @@ +"""Batch endpoint: many V2 features for one session in a single request. + +Why this exists: a ``SessionDataStore`` caches parsed livetiming streams *per +instance*, and every V2 analysis module builds its own via +``build_session_store()``. So a frontend asking for N features of one session +previously meant the same multi-megabyte streams were downloaded and parsed N +times, across N HTTP round-trips. ``shared_session_stores()`` +(``src/services/analysis/v2/_helpers.py``) memoizes those instances for the +duration of a scope; this endpoint is the one caller that opens it, running +every requested feature's generator inside a single scope so repeated +``build_session_store()`` calls for the same session return one instance. + +The scope is opened *inside* the threadpool worker (see ``_run_batch``) rather +than around the ``run_in_threadpool`` call itself. A ``ContextVar`` set on the +event loop thread is copied into an ``anyio`` worker thread's context, so it +would likely propagate either way -- but this endpoint does not lean on that: +opening the scope inside the worker function is unambiguous and is what +``tests/unit/api/test_batch.py`` verifies actually happens. +""" +from typing import Any, Dict, List, Optional + +from fastapi import APIRouter, Depends, HTTPException, Request +from fastapi.concurrency import run_in_threadpool + +from src.api.deps import validate_driver, validate_gp, validate_session +from src.api.schemas.batch import ( + BatchFeatureRequest, + BatchRequestBody, + BatchResponse, +) +from src.api.schemas.common import COMMON_ERROR_RESPONSES, ErrorEnvelope +from src.core.logging import get_logger +from src.core.security.api_keys import verify_api_key +from src.core.security.rate_limiting import apply_tiered_limit +from src.repositories.plots import get_plot_data_from_mongo +from src.services.analysis.v2._helpers import shared_session_stores +from src.services.analysis.v2.registry import ( + KIND_PER_DRIVER, + KIND_PER_DRIVER_LAP, + KIND_PER_PAIR, + KIND_SINGLETON, + feature_by_key, +) +from src.services.orchestrator_helpers import simplify_session_name + +logger = get_logger(__name__) + +router = APIRouter(prefix="/api/v2") + +#: A full-catalog request would re-run the exact "generate everything" job the +#: admin backfill already exists for, one request at a time and without its +#: job tracking / concurrency controls. 25 comfortably covers "give me every +#: singleton plus a couple of per-driver views for a dashboard" while keeping +#: one request's worst case bounded. +MAX_BATCH_ITEMS = 25 + + +def _cached_or_run( + year: int, + gp: Any, + session_type: str, + data_type: Optional[str], + generator, +) -> Any: + """Mongo-then-generate, mirroring what the single-feature endpoints do. + + Most registry generators already perform this check internally (directly, + or via ``cached_or_generate``), so this is frequently a redundant-but-cheap + point read. It is not redundant for any generator that does not, and it + keeps the guarantee local to this endpoint rather than depending on every + current and future catalog entry doing it themselves. + """ + if data_type: + cached = get_plot_data_from_mongo(year, gp, session_type, data_type, version="v2") + if cached: + return cached["data"] + return generator() + + +def _run_one_feature( + year: int, gp: Any, session_type: str, item: BatchFeatureRequest +) -> Dict[str, Any]: + """Resolve and run a single requested feature, never raising. + + Every failure mode -- unknown handling aside, since unknown keys are + rejected before this runs -- becomes a per-item error so one bad feature + cannot fail the whole batch. + """ + entry = feature_by_key(item.key) + if entry is None: # pragma: no cover - filtered out before _run_batch + return {"key": item.key, "status": "error", "error": f"Unknown feature key: {item.key!r}"} + + if not entry.session_scoped: + return { + "key": item.key, + "status": "error", + "error": "Season/career-scope features are not addressed by (year, gp, session) " + "and are not supported in a session batch.", + } + + if not entry.applies(session_type): + return { + "key": item.key, + "status": "error", + "error": f"Feature '{item.key}' does not apply to session type '{session_type}'.", + } + + try: + if entry.kind == KIND_SINGLETON: + data_type = entry.spec.data_type + data = _cached_or_run( + year, gp, session_type, data_type, + lambda: entry.spec.generate(year, gp, session_type), + ) + elif entry.kind == KIND_PER_DRIVER: + driver = validate_driver(item.driver) + if not driver: + return {"key": item.key, "status": "error", "error": "'driver' is required for this feature."} + data_type = entry.spec.key_for(driver) + data = _cached_or_run( + year, gp, session_type, data_type, + lambda: entry.spec.generate(year, gp, session_type, driver), + ) + elif entry.kind == KIND_PER_PAIR: + d1 = validate_driver(item.driver1) + d2 = validate_driver(item.driver2) + if not d1 or not d2: + return { + "key": item.key, "status": "error", + "error": "'driver1' and 'driver2' are both required for this feature.", + } + data_type = entry.spec.key_for(d1, d2) + data = _cached_or_run( + year, gp, session_type, data_type, + lambda: entry.spec.generate(year, gp, session_type, d1, d2), + ) + elif entry.kind == KIND_PER_DRIVER_LAP: + driver = validate_driver(item.driver) + if not driver or item.lap is None: + return { + "key": item.key, "status": "error", + "error": "'driver' and 'lap' are both required for this feature " + "(per-lap features are never generated implicitly).", + } + data_type = entry.spec.key_for(driver, item.lap) + data = _cached_or_run( + year, gp, session_type, data_type, + lambda: entry.spec.generate(year, gp, session_type, driver, item.lap), + ) + else: # pragma: no cover - catalog only defines the kinds above + return {"key": item.key, "status": "error", "error": f"Unsupported feature kind: {entry.kind}"} + except Exception as exc: + logger.warning( + "Batch feature %r failed for %s gp=%s session=%s: %s", + item.key, year, gp, session_type, exc, + ) + return {"key": item.key, "status": "error", "error": str(exc)} + + if not data: + return {"key": item.key, "status": "error", "error": "No data available for this session."} + + return {"key": item.key, "status": "ok", "data": data} + + +@router.post( + "/batch", + tags=["API v2"], + summary="Batch: multiple V2 features for one session", + operation_id="v2_batch_features", + description=( + "Fetch JSON data for several V2 features of one session in a single request. " + "Every uncached feature in the batch is generated inside one shared session-store " + "scope, so N features share one set of parsed livetiming streams instead of each " + "re-downloading and re-parsing them. Only JSON data features are supported (no PNG " + "plots). A failing feature is reported with its own error rather than failing the " + "whole batch -- check each result's `status`." + ), + responses={ + 200: {"model": BatchResponse}, + 400: { + "model": ErrorEnvelope, + "description": ( + "Malformed request: bad session/gp, empty or oversized feature list, " + "or an unknown feature key." + ), + }, + **COMMON_ERROR_RESPONSES, + }, +) +@apply_tiered_limit("data") +async def batch_v2( + request: Request, + body: BatchRequestBody, + api_key: str = Depends(verify_api_key), +): + if not body.features: + raise HTTPException(status_code=400, detail="'features' must be a non-empty list.") + if len(body.features) > MAX_BATCH_ITEMS: + raise HTTPException( + status_code=400, + detail=f"Too many features requested ({len(body.features)}); the limit is {MAX_BATCH_ITEMS}.", + ) + + gp = validate_gp(body.gp) + session_canonical = validate_session(body.session) + session_type = simplify_session_name(session_canonical).strip().upper() + + # Reject the whole request for a structurally bad key rather than burying + # a typo'd feature name inside a per-item error the caller has to notice. + for item in body.features: + if feature_by_key(item.key) is None: + raise HTTPException(status_code=400, detail=f"Unknown feature key: {item.key!r}") + + def _run_batch() -> List[Dict[str, Any]]: + # Opened here, inside the threadpool worker: shared_session_stores() + # sets a ContextVar, and every build_session_store() call this batch + # makes -- from whichever module each feature's generate() delegates + # to -- happens on this same thread for the duration of the scope. + results: List[Dict[str, Any]] = [] + with shared_session_stores(): + for item in body.features: + results.append(_run_one_feature(body.year, gp, session_type, item)) + return results + + results = await run_in_threadpool(_run_batch) + + return { + "year": body.year, + "gp": body.gp, + "session": session_type, + "results": results, + } diff --git a/src/api/routers/circuits_api.py b/src/api/routers/circuits_api.py index 61fbf59..9b5b3b0 100644 --- a/src/api/routers/circuits_api.py +++ b/src/api/routers/circuits_api.py @@ -1,36 +1,71 @@ from fastapi import APIRouter +from src.api.schemas.common import COMMON_ERROR_RESPONSES, ErrorEnvelope +from src.api.schemas.seasonal import CircuitDataResponse, CircuitInfoResponse, YearlyCircuitsResponse from src.core.logging import get_logger from src.core.security.rate_limiting import apply_tiered_limit from fastapi import Request, Query, HTTPException, Path -from src.ingestion.circuits_loader import get_yearly_circuits, get_circuit_data_by_id, get_circuit_data_by_name, get_circuit_data_file +from src.ingestion.circuits_loader import get_yearly_circuits, get_circuit_data_by_id, get_circuit_data_file logger = get_logger(__name__) router = APIRouter(prefix='/api/static') -@router.get('/circuits', tags=["Static"]) +#: This router has no `verify_api_key` dependency (see module-level endpoint docs), so +#: 401/403 can never occur here; only the rate-limit and server-error cases apply. +_UNAUTH_COMMON_RESPONSES = {429: COMMON_ERROR_RESPONSES[429], 500: COMMON_ERROR_RESPONSES[500]} + + +@router.get( + '/circuits', + tags=["Static"], + summary="List circuits for a season", + operation_id="static_season_circuits", + responses={ + **_UNAUTH_COMMON_RESPONSES, + 200: {"model": YearlyCircuitsResponse, "description": "All circuit summaries for the season."}, + }, +) @apply_tiered_limit("data") async def get_circuits_from_year( request: Request, - year: int = Query(2026, ge=2025, le=2026, description="Season year (2025-2026)") + year: int = Query(2026, ge=2024, le=2026, description="Season year (2024-2026)") ): - """Get circuits for a specific season year""" + """Get circuits for a specific season year. + + Unauthenticated: this endpoint has no API-key requirement and serves static reference + data curated in the repo (``src/domain/data/circuits/``), not live session data. + """ try: circuits = get_yearly_circuits(year) return {"circuits": circuits} except Exception as e: logger.error(f"Error fetching circuits for year {year}: {e}") raise HTTPException(status_code=500, detail="Internal Server Error") - -@router.get('/circuits/{circuit_id}/info', tags=["Static"]) + + +@router.get( + '/circuits/{circuit_id}/info', + tags=["Static"], + summary="Get circuit summary by ID", + operation_id="static_circuit_info", + responses={ + **_UNAUTH_COMMON_RESPONSES, + 200: {"model": CircuitInfoResponse, "description": "The matched circuit summary."}, + 404: {"model": ErrorEnvelope, "description": "No circuit matched `circuit_id` for that season."}, + }, +) @apply_tiered_limit("data") async def get_circuit_info_by_id( request: Request, circuit_id: int = Path(..., description="Circuit ID"), - year: int = Query(2026, ge=2025, le=2026, description="Season year (2025-2026)") + year: int = Query(2026, ge=2024, le=2026, description="Season year (2024-2026)") ): - """Get basic info for a specific circuit by ID""" + """Get basic info for a specific circuit by ID. + + Unauthenticated: this endpoint has no API-key requirement and serves static reference + data curated in the repo (``src/domain/data/circuits/``), not live session data. + """ try: circuit_details = get_circuit_data_by_id(circuit_id, year) if not circuit_details: @@ -40,18 +75,33 @@ async def get_circuit_info_by_id( logger.error(f"Error fetching circuit info for ID {circuit_id}: {e}") raise HTTPException(status_code=404, detail=str(e)) -@router.get('/circuits/{circuit_id}/data', tags=["Static"]) + +@router.get( + '/circuits/{circuit_id}/data', + tags=["Static"], + summary="Get full circuit layout by ID", + operation_id="static_circuit_data", + responses={ + **_UNAUTH_COMMON_RESPONSES, + 200: {"model": CircuitDataResponse, "description": "Full circuit layout in our own schema."}, + 404: {"model": ErrorEnvelope, "description": "No circuit layout file found for `circuit_id`/`year`."}, + }, +) @apply_tiered_limit("data") async def get_circuit_data_by_id_endpoint( request: Request, circuit_id: int = Path(..., description="Circuit ID"), - year: int = Query(2026, ge=2025, le=2026, description="Season year (2025-2026)") + year: int = Query(2026, ge=2024, le=2026, description="Season year (2024-2026)") ): - """Get full circuit data including files for a specific circuit by ID""" + """Get the full circuit layout (corners, rotation, marshal lights/sectors, track + outline) for a specific circuit by ID, in our own schema. + + Unauthenticated: this endpoint has no API-key requirement and serves static reference + data curated in the repo (``src/domain/data/circuits/``), not live session data. + """ try: circuit_data = get_circuit_data_file(circuit_id, year) return {"data": circuit_data} except ValueError as e: logger.error(f"Error fetching circuit data for ID {circuit_id}: {e}") raise HTTPException(status_code=404, detail=str(e)) - \ No newline at end of file diff --git a/src/api/routers/discovery_v2.py b/src/api/routers/discovery_v2.py new file mode 100644 index 0000000..1329f04 --- /dev/null +++ b/src/api/routers/discovery_v2.py @@ -0,0 +1,202 @@ +"""Feature discovery for the V2 analysis API. + +Clients previously had to hardcode endpoint URLs, with no way to ask what +analysis exists at all, or whether a given session actually has data yet. +``src/services/analysis/v2/registry.py`` already holds the canonical feature +catalog and ``src/workers/plot_inventory.py`` already knows what is stored, +but both were admin-only. These two endpoints expose them publicly: + +* ``GET /api/v2/features`` -- the static catalog of every generatable feature. +* ``GET /api/v2/sessions/{year}/{gp}/{session}/availability`` -- what is + actually stored for one specific session right now. +""" +from __future__ import annotations + +from collections import OrderedDict +from typing import List, Optional, Union + +from fastapi import APIRouter, Depends, HTTPException, Path, Query, Request +from fastapi.concurrency import run_in_threadpool + +from src.api.deps import validate_gp, validate_session +from src.api.schemas.common import ANALYSIS_ERROR_RESPONSES, COMMON_ERROR_RESPONSES +from src.api.schemas.discovery import FeatureCatalogResponse, SessionAvailabilityResponse +from src.core.config import settings +from src.core.logging import get_logger +from src.core.security.api_keys import verify_api_key +from src.core.security.rate_limiting import apply_tiered_limit +from src.services.analysis.v2.registry import ( + FEATURE_CATALOG, + KIND_CAREER, + KIND_PER_DRIVER, + KIND_PER_DRIVER_LAP, + KIND_PER_PAIR, + KIND_SEASON, + KIND_SINGLETON, + session_drivers, +) +from src.services.orchestrator_helpers import simplify_session_name +from src.workers.plot_inventory import compute_inventory + +logger = get_logger(__name__) + +router = APIRouter(prefix="/api/v2") + +#: Every ``kind`` a caller may filter ``/features`` by. Kept as a set literal +#: (rather than reading ``FeatureEntry.kind`` values off the catalog) so an +#: invalid filter is rejected even if the catalog is momentarily empty. +_VALID_KINDS = frozenset( + {KIND_SINGLETON, KIND_PER_DRIVER, KIND_PER_PAIR, KIND_PER_DRIVER_LAP, KIND_SEASON, KIND_CAREER} +) + + +def _normalize_session_filter(session: str) -> str: + """Map ``Q``/``FP1``/``Qualifying`` etc. onto the registry's abbreviations.""" + return simplify_session_name(session).strip().upper() + + +@router.get( + "/features", + tags=["API v2", "Seasonal Data"], + summary="Catalog of every generatable V2 feature", + operation_id="v2_feature_catalog", + description=( + "Static catalog of every V2 analysis feature the backend can generate -- " + "singletons through season/career scope -- read from the same registry the " + "admin backfill uses, so it can never drift from what actually exists. " + "Optionally filter by `session` (e.g. `Q`, `FP1`, or a long form like " + "`Qualifying`) to only see features applicable to that session type, and/or " + "by `kind` (singleton, per_driver, per_pair, per_driver_lap, season, career). " + "The catalog is static for a given build, so the response is cacheable." + ), + responses={200: {"model": FeatureCatalogResponse}, **COMMON_ERROR_RESPONSES}, +) +@apply_tiered_limit("standard") +async def v2_feature_catalog( + request: Request, + session: Optional[str] = Query( + None, description="Optional session filter, e.g. Q, FP1, or a long form like Qualifying." + ), + kind: Optional[str] = Query( + None, + description=( + "Optional kind filter: singleton, per_driver, per_pair, per_driver_lap, " + "season, career." + ), + ), + api_key: str = Depends(verify_api_key), +): + entries = FEATURE_CATALOG + + if kind is not None: + if kind not in _VALID_KINDS: + raise HTTPException( + status_code=400, + detail=f"Invalid kind '{kind}'. Valid values: {', '.join(sorted(_VALID_KINDS))}", + ) + entries = [e for e in entries if e.kind == kind] + + if session: + normalized = _normalize_session_filter(session) + entries = [e for e in entries if e.session_scoped and e.applies(normalized)] + + by_group: "OrderedDict[str, int]" = OrderedDict() + for entry in entries: + by_group[entry.group] = by_group.get(entry.group, 0) + 1 + + return { + "features": [entry.as_dict() for entry in entries], + "count": len(entries), + "groups": [{"group": g, "count": c} for g, c in sorted(by_group.items())], + } + + +@router.get( + "/sessions/{year}/{gp}/{session}/availability", + tags=["API v2", "Seasonal Data"], + summary="Which V2 features are already generated for a session", + operation_id="v2_session_feature_availability", + description=( + "Reports which singleton V2 features are already stored for this session " + "versus still missing, so a frontend can render only populated tiles instead " + "of firing every analysis endpoint and handling the failures. `gp` accepts a " + "round number, event key, or official event name, same as the rest of v2. " + "Set `include_drivers=true` to also resolve the participating driver TLAs -- " + "this costs a livetiming fetch, so it defaults to false and is skipped unless " + "asked for." + ), + responses={ + 200: {"model": SessionAvailabilityResponse}, + 404: {"description": "The event or session is not in the season schedule."}, + **ANALYSIS_ERROR_RESPONSES, + }, +) +@apply_tiered_limit("data") +async def v2_session_feature_availability( + request: Request, + year: int = Path(..., ge=settings.min_year, le=settings.max_year, description="Season year."), + gp: Union[int, str] = Path(..., description="Round number, event key, or official event name."), + session: str = Path(..., description="Session identifier, e.g. FP1, Q, SQ, S, R."), + include_drivers: bool = Query( + False, + description="Also resolve participating driver TLAs. Costs a livetiming fetch; off by default.", + ), + api_key: str = Depends(verify_api_key), +): + validated_gp = validate_gp(gp) + validated_session = validate_session(session) + + logger.info( + "Fetching V2 feature availability: Y%s GP%s %s", year, validated_gp, validated_session + ) + inventory = await run_in_threadpool( + compute_inventory, year=year, identifier=validated_gp, session=validated_session + ) + + grand_prix = inventory.get("grand_prix") or [] + if not grand_prix: + raise HTTPException(status_code=404, detail="No such event in the season schedule.") + + gp_entry = grand_prix[0] + sessions = gp_entry.get("sessions") or [] + if not sessions: + raise HTTPException( + status_code=404, + detail=f"Session '{validated_session}' is not scheduled for this event.", + ) + session_row = sessions[0] + + labels = session_row.get("labels") or {} + present = set(session_row.get("present") or []) + expected: List[str] = session_row.get("expected") or [] + features = [ + {"data_type": dt, "label": labels.get(dt, dt), "available": dt in present} + for dt in expected + ] + + drivers: Optional[List[str]] = None + if include_drivers: + try: + drivers = await run_in_threadpool( + session_drivers, + year, + gp_entry.get("event_name") or validated_gp, + validated_session, + ) + except Exception as exc: + logger.warning( + "Could not resolve drivers for Y%s GP%s %s: %s", + year, validated_gp, validated_session, exc, + ) + drivers = [] + + return { + "year": year, + "gp": gp_entry.get("event_name"), + "round_nr": gp_entry.get("round_nr"), + "session": validated_session, + "available": sorted(present), + "missing": sorted(session_row.get("missing") or []), + "features": features, + "drivers": drivers, + } diff --git a/src/api/routers/drivers_api.py b/src/api/routers/drivers_api.py index 2e6772c..a72f286 100644 --- a/src/api/routers/drivers_api.py +++ b/src/api/routers/drivers_api.py @@ -1,38 +1,71 @@ from fastapi import APIRouter +from src.api.schemas.common import COMMON_ERROR_RESPONSES, ErrorEnvelope +from src.api.schemas.seasonal import DriverDetailResponse, SeasonDriversResponse from src.core.logging import get_logger from src.core.security.rate_limiting import apply_tiered_limit from fastapi import Request, Query, HTTPException, Path from src.ingestion.reference import get_season_drivers, get_driver_details_by_name - - logger = get_logger(__name__) router = APIRouter(prefix='/api/static') +#: This router has no `verify_api_key` dependency (see module-level endpoint docs), so +#: 401/403 can never occur here; only the rate-limit and server-error cases apply. +_UNAUTH_COMMON_RESPONSES = {429: COMMON_ERROR_RESPONSES[429], 500: COMMON_ERROR_RESPONSES[500]} -@router.get('/drivers', tags=["Static"]) + +@router.get( + '/drivers', + tags=["Static"], + summary="List drivers for a season", + operation_id="static_season_drivers", + responses={ + **_UNAUTH_COMMON_RESPONSES, + 200: {"model": SeasonDriversResponse, "description": "All drivers for the season."}, + 400: {"model": ErrorEnvelope, "description": "Season year not covered by the static reference data."}, + }, +) @apply_tiered_limit("data") async def get_drivers_from_year( request: Request, year: int = Query(2026, ge=2025, le=2026, description="Season year (2025-2026)") ): - """Get drivers for a specific season year""" + """Get drivers for a specific season year. + + Unauthenticated: this endpoint has no API-key requirement and serves static reference + data curated in the repo (``src/domain/data/drivers.json``), not live session data. + """ try: drivers = get_season_drivers(year) return {"drivers": drivers} except ValueError as e: logger.error(f"Error fetching drivers for year {year}: {e}") raise HTTPException(status_code=400, detail=str(e)) - -@router.get('/drivers/{driver_name}', tags=["Static"]) + + +@router.get( + '/drivers/{driver_name}', + tags=["Static"], + summary="Get driver details by name", + operation_id="static_driver_details", + responses={ + **_UNAUTH_COMMON_RESPONSES, + 200: {"model": DriverDetailResponse, "description": "The matched driver."}, + 404: {"model": ErrorEnvelope, "description": "No driver matched `driver_name` for that season."}, + }, +) @apply_tiered_limit("data") async def get_driver_details( request: Request, year: int = Query(2026, ge=2025, le=2026, description="Season year (2025-2026)"), driver_name: str = Path(..., description="Driver Name") ): - """Get details for a specific driver by Name""" + """Get details for a specific driver by Name. + + Unauthenticated: this endpoint has no API-key requirement and serves static reference + data curated in the repo (``src/domain/data/drivers.json``), not live session data. + """ try: team_details = get_driver_details_by_name(year, driver_name) if not team_details: @@ -40,4 +73,4 @@ async def get_driver_details( return {"team": team_details} except ValueError as e: logger.error(f"Error fetching driver details for {driver_name}: {e}") - raise HTTPException(status_code=404, detail=str(e)) \ No newline at end of file + raise HTTPException(status_code=404, detail=str(e)) diff --git a/src/api/routers/keys.py b/src/api/routers/keys.py index 66c25f0..9c94c8a 100644 --- a/src/api/routers/keys.py +++ b/src/api/routers/keys.py @@ -4,6 +4,16 @@ from fastapi.concurrency import run_in_threadpool from pydantic import BaseModel, Field +from src.api.schemas.accounts import ( + CreateKeyResponse, + KeyDashboardResponse, + KeyPeakHoursResponse, + KeyUsageResponse, + ListMyKeysResponse, + MyUsageResponse, + RevokeKeyResponse, +) +from src.api.schemas.common import ErrorEnvelope from src.auth.dependencies import get_current_user from src.core.security.api_keys import invalidate_key_cache from src.core.security.rate_limiting import apply_tiered_limit, limits_for_tier @@ -19,6 +29,11 @@ revoke, ) +#: Shared 401 for every endpoint here — all are gated by `get_current_user` (JWT bearer). +_UNAUTHORIZED = {401: {"model": ErrorEnvelope, "description": "Bearer token missing, invalid, or expired."}} +#: A key_id that doesn't exist, or belongs to a different user (never leaked as 403). +_KEY_NOT_FOUND = {404: {"model": ErrorEnvelope, "description": "No such key owned by the caller."}} + router = APIRouter(prefix="/api/keys", tags=["Auth"]) me_router = APIRouter(prefix="/api/me", tags=["Auth"]) @@ -27,13 +42,31 @@ class CreateKeyRequest(BaseModel): label: str = Field(min_length=1, max_length=80) -@router.get("") +@router.get( + "", + summary="List my API keys", + operation_id="keys_list_mine", + description="List every API key (active and revoked) owned by the caller. Requires a bearer token.", + responses={200: {"model": ListMyKeysResponse, "description": "Keys owned by the caller."}, **_UNAUTHORIZED}, +) async def list_my_keys(user: dict = Depends(get_current_user)): keys = await run_in_threadpool(list_for_owner, user["id"]) return {"keys": keys} -@router.post("", status_code=status.HTTP_201_CREATED) +@router.post( + "", + status_code=status.HTTP_201_CREATED, + summary="Create an API key", + operation_id="keys_create", + responses={ + 201: { + "model": CreateKeyResponse, + "description": "Key created. `raw_key` is shown exactly once — capture it now.", + }, + **_UNAUTHORIZED, + }, +) @apply_tiered_limit("public") async def create_my_key( request: Request, @@ -43,7 +76,10 @@ async def create_my_key( """Mint a new API key for the current user. The ``raw_key`` is returned **once**; persist it client-side immediately - because we only store its hash. + because we only store its hash (see ``src/repositories/api_keys.py``). + This endpoint always mints a **standard**-tier key — non-admin users + cannot self-serve a premium-tier key; premium tier is only granted + through the admin endpoints. """ # Non-admin users always get standard tier — admins promote keys via # the admin endpoints. @@ -59,7 +95,16 @@ async def create_my_key( } -@router.get("/{key_id}/usage") +@router.get( + "/{key_id}/usage", + summary="Get hourly usage stats for a key", + operation_id="keys_get_usage", + responses={ + 200: {"model": KeyUsageResponse, "description": "Hourly usage buckets over the window."}, + **_UNAUTHORIZED, + **_KEY_NOT_FOUND, + }, +) async def get_my_key_usage( key_id: str, hours: int = Query(24, ge=1, le=720), @@ -95,7 +140,16 @@ def _build_quota(tier: str, used_this_month: int, month_resets_at: str) -> dict: } -@router.get("/{key_id}/dashboard") +@router.get( + "/{key_id}/dashboard", + summary="Get the usage dashboard for a key", + operation_id="keys_get_dashboard", + responses={ + 200: {"model": KeyDashboardResponse, "description": "Quota, rate limit, and usage dashboard."}, + **_UNAUTHORIZED, + **_KEY_NOT_FOUND, + }, +) async def get_my_key_dashboard( key_id: str, user: dict = Depends(get_current_user), @@ -143,7 +197,16 @@ async def get_my_key_dashboard( } -@router.get("/{key_id}/peak-hours") +@router.get( + "/{key_id}/peak-hours", + summary="Get hour-of-day usage distribution for a key", + operation_id="keys_get_peak_hours", + responses={ + 200: {"model": KeyPeakHoursResponse, "description": "24-entry hour-of-day (UTC) request distribution."}, + **_UNAUTHORIZED, + **_KEY_NOT_FOUND, + }, +) async def get_my_key_peak_hours( key_id: str, days: int = Query(30, ge=1, le=90), @@ -161,7 +224,12 @@ async def get_my_key_peak_hours( return {"key_id": key_id, "days": days, "peak_hour_utc": peak, "by_hour": series} -@me_router.get("/usage") +@me_router.get( + "/usage", + summary="Get my aggregate usage across all keys", + operation_id="me_get_usage", + responses={200: {"model": MyUsageResponse, "description": "Aggregate usage dashboard."}, **_UNAUTHORIZED}, +) async def get_my_usage(user: dict = Depends(get_current_user)): """Aggregate dashboard across **all** active keys owned by the user. @@ -217,7 +285,17 @@ async def get_my_usage(user: dict = Depends(get_current_user)): } -@router.delete("/{key_id}", status_code=status.HTTP_200_OK) +@router.delete( + "/{key_id}", + status_code=status.HTTP_200_OK, + summary="Revoke an API key", + operation_id="keys_revoke", + responses={ + 200: {"model": RevokeKeyResponse, "description": "Key revoked."}, + **_UNAUTHORIZED, + **_KEY_NOT_FOUND, + }, +) async def revoke_my_key(key_id: str, user: dict = Depends(get_current_user)): existing = await run_in_threadpool(find_by_id, key_id) if not existing or str(existing.get("owner_id")) != user["id"]: diff --git a/src/api/routers/media_api.py b/src/api/routers/media_api.py new file mode 100644 index 0000000..97f9067 --- /dev/null +++ b/src/api/routers/media_api.py @@ -0,0 +1,175 @@ +"""Static media endpoints: driver images and team logos. + +Like ``drivers_api``/``teams_api`` this router is **unauthenticated** — it serves +curated repo assets, not live session data. The single-item endpoints 302-redirect +to the file under the ``/assets`` mount (see ``src/api/app.py``) so a CDN can cache +the bytes; the list endpoints return JSON metadata with the same URLs plus an +``available`` flag telling clients which files have actually been uploaded. + +Asset layout (files to add live here): + * driver images -> ``assets/drivers/{CODE}.png`` (e.g. assets/drivers/VER.png) + * team logos -> ``assets/logos/{SHORT_NAME}.png`` (e.g. assets/logos/RBR.png) +""" +from __future__ import annotations + +from pathlib import Path + +from fastapi import APIRouter, HTTPException, Path as PathParam, Query, Request +from fastapi.responses import RedirectResponse + +from src.api.schemas.common import COMMON_ERROR_RESPONSES, ErrorEnvelope +from src.api.schemas.media import ( + DriverImageItem, + DriverImagesResponse, + TeamLogoItem, + TeamLogosResponse, +) +from src.core.logging import get_logger +from src.core.security.rate_limiting import apply_tiered_limit +from src.ingestion.reference import get_season_drivers, get_season_teams + +logger = get_logger(__name__) + +router = APIRouter(prefix="/api/static/media") + +#: No ``verify_api_key`` dependency here, so 401/403 cannot occur. +_UNAUTH_COMMON_RESPONSES = {429: COMMON_ERROR_RESPONSES[429], 500: COMMON_ERROR_RESPONSES[500]} + +#: Repo-root ``assets/`` directory (this file is src/api/routers/media_api.py). +_ASSETS_DIR = Path(__file__).resolve().parents[3] / "assets" +_DRIVERS_DIR = _ASSETS_DIR / "drivers" +_LOGOS_DIR = _ASSETS_DIR / "logos" + +DRIVER_IMAGE_URL = "/assets/drivers/{code}.png" +TEAM_LOGO_URL = "/assets/logos/{short_name}.png" + + +def _driver_image_available(code: str) -> bool: + return (_DRIVERS_DIR / f"{code}.png").is_file() + + +def _team_logo_available(short_name: str) -> bool: + return (_LOGOS_DIR / f"{short_name}.png").is_file() + + +@router.get( + "/drivers", + tags=["Static"], + summary="List driver image URLs for a season", + operation_id="static_media_driver_images", + responses={ + **_UNAUTH_COMMON_RESPONSES, + 200: {"model": DriverImagesResponse, "description": "One entry per driver on the grid."}, + 400: {"model": ErrorEnvelope, "description": "Season year not covered by the static reference data."}, + }, +) +@apply_tiered_limit("data") +async def list_driver_images( + request: Request, + year: int = Query(2026, ge=2025, le=2026, description="Season year (2025-2026)"), +): + """List every driver for ``year`` with the URL of their portrait. + + Unauthenticated. ``available`` is ``false`` when no PNG has been uploaded for that + driver yet; the ``image_url`` is still returned so clients can retry later. + """ + try: + drivers = get_season_drivers(year) + except ValueError as e: + logger.error("Error listing driver images for %s: %s", year, e) + raise HTTPException(status_code=400, detail=str(e)) + + items = [] + for d in drivers: + code = (d.get("code") or "").upper() + items.append(DriverImageItem( + code=code, + name=d.get("full_name") or d.get("name"), + team=d.get("team"), + number=d.get("number"), + image_url=DRIVER_IMAGE_URL.format(code=code), + available=_driver_image_available(code), + )) + return {"year": year, "images": items} + + +@router.get( + "/drivers/{code}", + tags=["Static"], + summary="Redirect to a driver image", + operation_id="static_media_driver_image", + responses={ + **_UNAUTH_COMMON_RESPONSES, + 307: {"description": "Redirect to the PNG under /assets/drivers/."}, + 404: {"model": ErrorEnvelope, "description": "No image uploaded for that driver code."}, + }, +) +@apply_tiered_limit("data") +async def get_driver_image( + request: Request, + code: str = PathParam(..., description="Three-letter driver code, e.g. VER"), +): + """302-redirect to ``/assets/drivers/{CODE}.png``. Unauthenticated.""" + code = code.upper() + if not _driver_image_available(code): + raise HTTPException(status_code=404, detail=f"No image for driver code {code!r}") + return RedirectResponse(url=DRIVER_IMAGE_URL.format(code=code), status_code=302) + + +@router.get( + "/teams", + tags=["Static"], + summary="List team logo URLs for a season", + operation_id="static_media_team_logos", + responses={ + **_UNAUTH_COMMON_RESPONSES, + 200: {"model": TeamLogosResponse, "description": "One entry per constructor."}, + 400: {"model": ErrorEnvelope, "description": "Season year not covered by the static reference data."}, + }, +) +@apply_tiered_limit("data") +async def list_team_logos( + request: Request, + year: int = Query(2026, ge=2025, le=2026, description="Season year (2025-2026)"), +): + """List every constructor for ``year`` with the URL of its logo. Unauthenticated.""" + try: + teams = get_season_teams(year) + except ValueError as e: + logger.error("Error listing team logos for %s: %s", year, e) + raise HTTPException(status_code=400, detail=str(e)) + + items = [] + for t in teams: + short_name = (t.get("short_name") or "").upper() + items.append(TeamLogoItem( + name=t.get("name") or "", + short_name=short_name, + color=t.get("color"), + logo_url=TEAM_LOGO_URL.format(short_name=short_name), + available=_team_logo_available(short_name), + )) + return {"year": year, "logos": items} + + +@router.get( + "/teams/{short_name}", + tags=["Static"], + summary="Redirect to a team logo", + operation_id="static_media_team_logo", + responses={ + **_UNAUTH_COMMON_RESPONSES, + 307: {"description": "Redirect to the PNG under /assets/logos/."}, + 404: {"model": ErrorEnvelope, "description": "No logo uploaded for that team code."}, + }, +) +@apply_tiered_limit("data") +async def get_team_logo( + request: Request, + short_name: str = PathParam(..., description="Short team code, e.g. RBR"), +): + """302-redirect to ``/assets/logos/{SHORT_NAME}.png``. Unauthenticated.""" + short_name = short_name.upper() + if not _team_logo_available(short_name): + raise HTTPException(status_code=404, detail=f"No logo for team code {short_name!r}") + return RedirectResponse(url=TEAM_LOGO_URL.format(short_name=short_name), status_code=302) diff --git a/src/api/routers/monitoring.py b/src/api/routers/monitoring.py index 442ffc4..e9eeafa 100644 --- a/src/api/routers/monitoring.py +++ b/src/api/routers/monitoring.py @@ -13,6 +13,23 @@ ACTIVE_REQUESTS ) from src.core.config import settings +from src.api.routers.admin import require_admin_key +from src.api.schemas.common import COMMON_ERROR_RESPONSES, ErrorEnvelope +from src.api.schemas.monitoring import ( + CurrentLoadResponse, + DetailedHealthResponse, + DiagnosticsResponse, + EndpointStatsResponse, + RecentErrorsResponse, + RecentRequestsResponse, + SystemMetricsResponse, + TestPingResponse, +) + +#: Operator-only endpoints in this router are gated by `require_admin_key`, which itself +#: depends on `verify_api_key` — so both "no/invalid key" (401/403) and "valid key but not +#: admin" (403) fall out of `COMMON_ERROR_RESPONSES` already. +_ADMIN_NOTE = "**Operator only** — requires an admin API key (`require_admin_key`)." logger = get_logger(__name__) @@ -22,8 +39,20 @@ # MONITORING & OBSERVABILITY ENDPOINTS # ============================================================================ -@router.get('/metrics', tags=["Monitoring"], include_in_schema=True) -async def metrics(): +@router.get( + '/metrics', + tags=["Monitoring"], + include_in_schema=False, + summary="Prometheus metrics", + operation_id="monitoring_prometheus_metrics", + description=f"Prometheus text-format metrics for scraping. {_ADMIN_NOTE}", + responses={ + 200: {"content": {"text/plain": {}}, "description": "Prometheus exposition-format text."}, + **COMMON_ERROR_RESPONSES, + }, +) +@apply_tiered_limit("standard") +async def metrics(request: Request, api_key: str = Depends(require_admin_key)): """ Prometheus metrics endpoint Returns metrics in Prometheus text format for scraping @@ -33,9 +62,19 @@ async def metrics(): media_type=get_prometheus_content_type() ) -@router.get('/api/monitoring/system', tags=["Monitoring"]) +@router.get( + '/api/monitoring/system', + tags=["Monitoring"], + summary="Get real-time system metrics", + operation_id="monitoring_system_metrics", + description=f"CPU, memory, disk, network usage and uptime. {_ADMIN_NOTE}", + responses={ + 200: {"model": SystemMetricsResponse, "description": "Current system metrics."}, + **COMMON_ERROR_RESPONSES, + }, +) @apply_tiered_limit("standard") -async def get_system_metrics(request: Request, api_key: str = Depends(verify_api_key)): +async def get_system_metrics(request: Request, api_key: str = Depends(require_admin_key)): """ Get real-time system metrics Shows CPU, memory, disk, network usage and uptime @@ -48,12 +87,23 @@ async def get_system_metrics(request: Request, api_key: str = Depends(verify_api logger.error(f"Error getting system metrics: {e}", exc_info=True) raise HTTPException(status_code=500, detail="Failed to get system metrics") -@router.get('/api/monitoring/requests', tags=["Monitoring"]) +@router.get( + '/api/monitoring/requests', + tags=["Monitoring"], + summary="List recent requests", + operation_id="monitoring_recent_requests", + description=f"Recent requests with full traceability (ID, timestamp, endpoint, status, duration, client). " + f"{_ADMIN_NOTE}", + responses={ + 200: {"model": RecentRequestsResponse, "description": "Recent request records."}, + **COMMON_ERROR_RESPONSES, + }, +) @apply_tiered_limit("standard") async def get_recent_requests( request: Request, limit: int = Query(100, ge=1, le=1000, description="Number of recent requests to return"), - api_key: str = Depends(verify_api_key) + api_key: str = Depends(require_admin_key) ): """ Get recent requests with full traceability @@ -71,12 +121,19 @@ async def get_recent_requests( logger.error(f"Error getting recent requests: {e}", exc_info=True) raise HTTPException(status_code=500, detail="Failed to get recent requests") -@router.get('/api/monitoring/errors', tags=["Monitoring"]) +@router.get( + '/api/monitoring/errors', + tags=["Monitoring"], + summary="List recent errors", + operation_id="monitoring_recent_errors", + description=f"Recent errors with stack traces, request context, and error types. {_ADMIN_NOTE}", + responses={200: {"model": RecentErrorsResponse, "description": "Recent error records."}, **COMMON_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") async def get_recent_errors( request: Request, limit: int = Query(50, ge=1, le=500, description="Number of recent errors to return"), - api_key: str = Depends(verify_api_key) + api_key: str = Depends(require_admin_key) ): """ Get recent errors with full details @@ -94,7 +151,18 @@ async def get_recent_errors( logger.error(f"Error getting recent errors: {e}", exc_info=True) raise HTTPException(status_code=500, detail="Failed to get recent errors") -@router.get('/api/monitoring/stats', tags=["Monitoring"]) +@router.get( + '/api/monitoring/stats', + tags=["Monitoring"], + summary="Get per-endpoint request statistics", + operation_id="monitoring_endpoint_stats", + description="Request counts, error rates, and duration stats per endpoint. Requires any valid API key " + "(not operator-only).", + responses={ + 200: {"model": EndpointStatsResponse, "description": "Per-endpoint statistics."}, + **COMMON_ERROR_RESPONSES, + }, +) @apply_tiered_limit("standard") async def get_endpoint_stats(request: Request, api_key: str = Depends(verify_api_key)): """ @@ -114,9 +182,16 @@ async def get_endpoint_stats(request: Request, api_key: str = Depends(verify_api logger.error(f"Error getting endpoint stats: {e}", exc_info=True) raise HTTPException(status_code=500, detail="Failed to get endpoint stats") -@router.get('/api/monitoring/load', tags=["Monitoring"]) +@router.get( + '/api/monitoring/load', + tags=["Monitoring"], + summary="Get current load and active requests", + operation_id="monitoring_current_load", + description=f"Real-time system load and active API request count. {_ADMIN_NOTE}", + responses={200: {"model": CurrentLoadResponse, "description": "Current load snapshot."}, **COMMON_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") -async def get_current_load(request: Request, api_key: str = Depends(verify_api_key)): +async def get_current_load(request: Request, api_key: str = Depends(require_admin_key)): """ Get current load and active requests Real-time view of system load and active API requests @@ -153,9 +228,20 @@ async def get_current_load(request: Request, api_key: str = Depends(verify_api_k logger.error(f"Error getting current load: {e}", exc_info=True) raise HTTPException(status_code=500, detail="Failed to get current load") -@router.get('/api/monitoring/health-detailed', tags=["Monitoring"]) +@router.get( + '/api/monitoring/health-detailed', + tags=["Monitoring"], + summary="Get comprehensive health with observability", + operation_id="monitoring_health_detailed", + description=f"System metrics, request stats, and service health combined. {_ADMIN_NOTE}", + responses={ + 200: {"model": DetailedHealthResponse, "description": "Combined health/observability snapshot."}, + **COMMON_ERROR_RESPONSES, + 503: {"model": ErrorEnvelope, "description": "Health check itself failed while introspecting services."}, + }, +) @apply_tiered_limit("standard") -async def get_detailed_health(request: Request, api_key: str = Depends(verify_api_key)): +async def get_detailed_health(request: Request, api_key: str = Depends(require_admin_key)): """ Comprehensive health check with full observability Combines system metrics, request stats, and service health in one endpoint @@ -182,7 +268,8 @@ async def get_detailed_health(request: Request, api_key: str = Depends(verify_ap try: session_tracker = SessionTracker() session_tracker_status = "healthy" - except: + except Exception as e: + logger.debug(f"Session tracker unavailable: {e}") session_tracker_status = "unavailable" return { @@ -219,9 +306,16 @@ async def get_detailed_health(request: Request, api_key: str = Depends(verify_ap # TEST & DIAGNOSTICS ENDPOINTS # ============================================================================ -@router.get('/api/test/ping', tags=["Monitoring"]) +@router.get( + '/api/test/ping', + tags=["Monitoring"], + summary="Ping the API", + operation_id="monitoring_test_ping", + description="Simple liveness ping. Returns request ID and timing info — useful for load testing.", + responses={200: {"model": TestPingResponse, "description": "Pong."}, **COMMON_ERROR_RESPONSES}, +) @apply_tiered_limit("public") -async def test_ping(request: Request): +async def test_ping(request: Request, api_key: str = Depends(verify_api_key)): """ Simple ping endpoint for testing Returns request ID and timing info - useful for load testing @@ -234,7 +328,28 @@ async def test_ping(request: Request): "message": "API is responding" } -@router.get('/api/test/error', tags=["Monitoring"]) +@router.get( + '/api/test/error', + tags=["Monitoring"], + summary="Trigger a test error", + operation_id="monitoring_test_error", + description=( + "Deliberately raises an error for testing error logging/tracing. In production " + "(`settings.is_production`) this always returns 404 regardless of `error_type`." + ), + responses={ + 400: {"model": ErrorEnvelope, "description": "`error_type=400` (non-production only)."}, + 404: { + "model": ErrorEnvelope, + "description": "`error_type=404`, an unrecognised `error_type`, or any call in production.", + }, + 500: { + "model": ErrorEnvelope, + "description": "`error_type=500`, or `error_type=exception` (raises an uncaught `ValueError`).", + }, + **{k: v for k, v in COMMON_ERROR_RESPONSES.items() if k != 500}, + }, +) @apply_tiered_limit("standard") async def test_error( request: Request, @@ -245,8 +360,11 @@ async def test_error( Test error handling and tracing Useful for testing error logging and monitoring systems """ + if settings.is_production: + raise HTTPException(status_code=404, detail="Not found") + request_id = getattr(request.state, 'request_id', 'unknown') - + if error_type == "400": raise HTTPException(status_code=400, detail=f"[{request_id}] Test bad request error") elif error_type == "404": @@ -258,9 +376,20 @@ async def test_error( else: raise HTTPException(status_code=400, detail="Invalid error_type. Use: 400, 404, 500, or exception") -@router.get('/api/diagnostics', tags=["Monitoring"]) +@router.get( + '/api/diagnostics', + tags=["Monitoring"], + summary="Get complete diagnostics overview", + operation_id="monitoring_diagnostics", + description=f"Everything about API status in one call: system, requests, top/error-prone endpoints, " + f"recent error samples, background processor, and service health. {_ADMIN_NOTE}", + responses={ + 200: {"model": DiagnosticsResponse, "description": "Full diagnostics snapshot."}, + **COMMON_ERROR_RESPONSES, + }, +) @apply_tiered_limit("standard") -async def get_diagnostics(request: Request, api_key: str = Depends(verify_api_key)): +async def get_diagnostics(request: Request, api_key: str = Depends(require_admin_key)): """ Complete diagnostics overview Everything you need to know about the API status in one endpoint @@ -300,7 +429,8 @@ async def get_diagnostics(request: Request, api_key: str = Depends(verify_api_ke try: session_tracker = SessionTracker() session_tracker_status = "healthy" - except: + except Exception as e: + logger.debug(f"Session tracker unavailable: {e}") session_tracker_status = "unavailable" return { diff --git a/src/api/routers/seasonal_v1.py b/src/api/routers/seasonal_v1.py index 465e144..0b6a4a3 100644 --- a/src/api/routers/seasonal_v1.py +++ b/src/api/routers/seasonal_v1.py @@ -1,25 +1,59 @@ -from fastapi import APIRouter, Request, HTTPException, Depends +from fastapi import APIRouter, Request, HTTPException, Depends, Response from fastapi.concurrency import run_in_threadpool from src.core.logging import get_logger from src.core.security.api_keys import verify_api_key from src.core.security.rate_limiting import apply_tiered_limit +from src.api.schemas.common import COMMON_ERROR_RESPONSES, ErrorEnvelope +from src.api.schemas.legacy_v1 import ( + LegacySeasonsListResponse, + LegacySeasonSummaryResponse, + LegacySeasonDriversResponse, + LegacySeasonTeamsResponse, + LegacyDriverInfoResponse, + LegacyTeamInfoResponse, +) logger = get_logger(__name__) -router = APIRouter(prefix="/api/v1") + +def _sunset_headers(response: Response) -> None: + """RFC 8594 retirement notice, applied to every ``/api/v1`` response. + + Mirrors ``src/api/routers/analysis_v1.py::_sunset_headers`` — duplicated rather than + shared because the two routers are independently owned and this file must not import + from that one. + """ + response.headers["Deprecation"] = "true" + response.headers["Sunset"] = "Sun, 01 Sep 2027 00:00:00 GMT" + + +router = APIRouter(prefix="/api/v1", dependencies=[Depends(_sunset_headers)]) # ============================================================================ # SEASONAL DATA ENDPOINTS # ============================================================================ -@router.get('/seasons', tags=["API v1", "Seasonal Data"]) + +@router.get( + '/seasons', + tags=["API v1"], + deprecated=True, + summary="List seasons with stored data", + operation_id="v1_seasons", + description=( + "Get list of all available seasons (years with a MongoDB season document). " + "**Deprecated, no V2 equivalent** — V2 has no endpoint enumerating covered years; " + "the closest modern reference data (`GET /api/static/drivers`, " + "`GET /api/static/teams`) currently covers seasons 2025-2026 only." + ), + responses={200: {"model": LegacySeasonsListResponse}, **COMMON_ERROR_RESPONSES}, +) @apply_tiered_limit("standard") async def get_available_seasons( request: Request, api_key: str = Depends(verify_api_key) ): - """Get list of all available seasons""" try: logger.info("Fetching available seasons") from src.repositories.seasonal_data import get_available_seasons @@ -29,22 +63,40 @@ async def get_available_seasons( logger.error(f"Error fetching available seasons: {e}", exc_info=True) raise HTTPException(status_code=500, detail="Failed to fetch available seasons") -@router.get('/season/{year}', tags=["API v1", "Seasonal Data"]) + +@router.get( + '/season/{year}', + tags=["API v1"], + deprecated=True, + summary="Complete season summary", + operation_id="v1_season_summary", + description=( + "Get complete season data including drivers, teams, and races. **Deprecated, no " + "single V2 equivalent** — the closest coverage is composing " + "`GET /api/v2/seasons/{year}/events` (schedule) with " + "`GET /api/static/drivers?year=` and `GET /api/static/teams?year=` (roster); " + "no V2 endpoint returns this aggregate in one call." + ), + responses={ + **COMMON_ERROR_RESPONSES, + 200: {"model": LegacySeasonSummaryResponse}, + 404: {"model": ErrorEnvelope, "description": "No stored season document for this year."}, + }, +) @apply_tiered_limit("standard") async def get_season_summary( request: Request, year: int, api_key: str = Depends(verify_api_key) ): - """Get complete season data including drivers, teams, and races""" try: logger.info(f"Fetching complete season data for {year}") from src.repositories.seasonal_data import get_season_summary season_data = await run_in_threadpool(lambda: get_season_summary(year)) - + if not season_data: raise HTTPException(status_code=404, detail=f"Season {year} not found") - + return season_data except HTTPException: raise @@ -52,22 +104,39 @@ async def get_season_summary( logger.error(f"Error fetching season summary: {e}", exc_info=True) raise HTTPException(status_code=500, detail="Failed to fetch season summary") -@router.get('/season/{year}/drivers', tags=["API v1", "Seasonal Data"]) + +@router.get( + '/season/{year}/drivers', + tags=["API v1"], + deprecated=True, + summary="List drivers for a season", + operation_id="v1_season_drivers", + description=( + "Get list of drivers for a specific season (from the MongoDB season document). " + "**Deprecated** — closest replacement is `GET /api/static/drivers?year=` (curated " + "reference data, covers seasons 2025-2026; different source, not a drop-in " + "replacement for older years)." + ), + responses={ + **COMMON_ERROR_RESPONSES, + 200: {"model": LegacySeasonDriversResponse}, + 404: {"model": ErrorEnvelope, "description": "No drivers found for this season."}, + }, +) @apply_tiered_limit("standard") async def get_season_drivers( request: Request, year: int, api_key: str = Depends(verify_api_key) ): - """Get list of drivers for a specific season""" try: logger.info(f"Fetching drivers for season {year}") from src.repositories.seasonal_data import get_drivers_for_season drivers = await run_in_threadpool(lambda: get_drivers_for_season(year)) - + if not drivers: raise HTTPException(status_code=404, detail=f"No drivers found for season {year}") - + return {"year": year, "drivers": drivers} except HTTPException: raise @@ -75,22 +144,39 @@ async def get_season_drivers( logger.error(f"Error fetching season drivers: {e}", exc_info=True) raise HTTPException(status_code=500, detail="Failed to fetch season drivers") -@router.get('/season/{year}/teams', tags=["API v1", "Seasonal Data"]) + +@router.get( + '/season/{year}/teams', + tags=["API v1"], + deprecated=True, + summary="List teams for a season", + operation_id="v1_season_teams", + description=( + "Get list of teams for a specific season (from the MongoDB season document). " + "**Deprecated** — closest replacement is `GET /api/static/teams?year=` (curated " + "reference data, covers seasons 2025-2026; different source, not a drop-in " + "replacement for older years)." + ), + responses={ + **COMMON_ERROR_RESPONSES, + 200: {"model": LegacySeasonTeamsResponse}, + 404: {"model": ErrorEnvelope, "description": "No teams found for this season."}, + }, +) @apply_tiered_limit("standard") async def get_season_teams( request: Request, year: int, api_key: str = Depends(verify_api_key) ): - """Get list of teams for a specific season""" try: logger.info(f"Fetching teams for season {year}") from src.repositories.seasonal_data import get_teams_for_season teams = await run_in_threadpool(lambda: get_teams_for_season(year)) - + if not teams: raise HTTPException(status_code=404, detail=f"No teams found for season {year}") - + return {"year": year, "teams": teams} except HTTPException: raise @@ -98,7 +184,25 @@ async def get_season_teams( logger.error(f"Error fetching season teams: {e}", exc_info=True) raise HTTPException(status_code=500, detail="Failed to fetch season teams") -@router.get('/season/{year}/driver/{driver_code}', tags=["API v1", "Seasonal Data"]) + +@router.get( + '/season/{year}/driver/{driver_code}', + tags=["API v1"], + deprecated=True, + summary="Get one driver for a season", + operation_id="v1_season_driver", + description=( + "Get specific driver information for a season (from the MongoDB season " + "document). **Deprecated** — closest replacement is " + "`GET /api/static/drivers/{driver_name}?year=` (curated reference data, covers " + "seasons 2025-2026; different source, not a drop-in replacement for older years)." + ), + responses={ + **COMMON_ERROR_RESPONSES, + 200: {"model": LegacyDriverInfoResponse}, + 404: {"model": ErrorEnvelope, "description": "No such driver for this season."}, + }, +) @apply_tiered_limit("standard") async def get_driver_info( request: Request, @@ -106,15 +210,14 @@ async def get_driver_info( driver_code: str, api_key: str = Depends(verify_api_key) ): - """Get specific driver information for a season""" try: logger.info(f"Fetching driver {driver_code} for season {year}") from src.repositories.seasonal_data import get_driver_by_code driver = await run_in_threadpool(lambda: get_driver_by_code(year, driver_code.upper())) - + if not driver: raise HTTPException(status_code=404, detail=f"Driver {driver_code} not found for season {year}") - + return driver except HTTPException: raise @@ -122,7 +225,25 @@ async def get_driver_info( logger.error(f"Error fetching driver info: {e}", exc_info=True) raise HTTPException(status_code=500, detail="Failed to fetch driver info") -@router.get('/season/{year}/team/{team_name}', tags=["API v1", "Seasonal Data"]) + +@router.get( + '/season/{year}/team/{team_name}', + tags=["API v1"], + deprecated=True, + summary="Get one team for a season", + operation_id="v1_season_team", + description=( + "Get specific team information for a season (from the MongoDB season document). " + "**Deprecated** — closest replacement is `GET /api/static/teams/{team_name}?year=` " + "(curated reference data, covers seasons 2025-2026; different source, not a " + "drop-in replacement for older years)." + ), + responses={ + **COMMON_ERROR_RESPONSES, + 200: {"model": LegacyTeamInfoResponse}, + 404: {"model": ErrorEnvelope, "description": "No such team for this season."}, + }, +) @apply_tiered_limit("standard") async def get_team_info( request: Request, @@ -130,15 +251,14 @@ async def get_team_info( team_name: str, api_key: str = Depends(verify_api_key) ): - """Get specific team information for a season""" try: logger.info(f"Fetching team {team_name} for season {year}") from src.repositories.seasonal_data import get_team_by_name team = await run_in_threadpool(lambda: get_team_by_name(year, team_name)) - + if not team: raise HTTPException(status_code=404, detail=f"Team {team_name} not found for season {year}") - + return team except HTTPException: raise diff --git a/src/api/routers/seasonal_v2.py b/src/api/routers/seasonal_v2.py index f16f1e6..67a3c0c 100644 --- a/src/api/routers/seasonal_v2.py +++ b/src/api/routers/seasonal_v2.py @@ -1,10 +1,18 @@ from typing import Optional from fastapi import APIRouter, Request, HTTPException, Depends, Query -from fastapi.responses import FileResponse, JSONResponse +from fastapi.responses import FileResponse from fastapi.concurrency import run_in_threadpool import requests +from src.api.schemas.common import ANALYSIS_ERROR_RESPONSES, COMMON_ERROR_RESPONSES, ErrorEnvelope +from src.api.schemas.seasonal import ( + EventSessionsResponse, + SeasonDriverRadarResponse, + SeasonEventsResponse, + SeasonFormResponse, + TeammateBattleResponse, +) from src.core.exceptions import T1APIError from src.core.logging import get_logger from src.core.security.api_keys import verify_api_key @@ -21,6 +29,14 @@ SeasonRadarPlot, SeasonRadarData, CareerRadarPlot, CareerRadarData, ) +#: PNG plot endpoints have no JSON body. +_PNG_RESPONSE = {"content": {"image/png": {}}, "description": "PNG plot."} + +#: A plot's 404 can be either a schedule miss (SessionNotFoundEnvelope, from +#: ANALYSIS_ERROR_RESPONSES) or a generic "Plot not found" (ErrorEnvelope) when the file +#: itself is missing after a successful generation. Both are documented via description. +_PLOT_NOT_FOUND_NOTE = " A missing rendered file (rare) 404s as a plain error envelope instead." + def _track(event_name, *args): try: @@ -34,7 +50,18 @@ def _track(event_name, *args): # SEASONAL DATA ENDPOINTS (V2) # ============================================================================ -@router.get('/seasons/{year}/events', tags=["API v2", "Seasonal Data"]) +@router.get( + '/seasons/{year}/events', + tags=["API v2", "Seasonal Data"], + summary="List season events (meetings)", + operation_id="v2_season_events", + responses={ + **COMMON_ERROR_RESPONSES, + 200: {"model": SeasonEventsResponse, "description": "All meetings for the season."}, + 404: {"model": ErrorEnvelope, "description": "Season data not found on official F1 servers."}, + 502: {"model": ErrorEnvelope, "description": "Error communicating with F1 servers."}, + }, +) @apply_tiered_limit("standard") async def get_season_events( request: Request, @@ -48,12 +75,12 @@ async def get_season_events( try: logger.info(f"Fetching events for season {year} via F1StaticClient") client = F1StaticClient() - + # Run synchronous network request in a threadpool to prevent blocking the async event loop season_index = await run_in_threadpool(client.fetch_season_index, year) - + meetings = season_index.get('Meetings', []) - + # Format the response nicely events = [] for meeting in meetings: @@ -65,9 +92,9 @@ async def get_season_events( "key": meeting.get('Key'), "code": meeting.get('Code') }) - + return {"year": year, "events": events} - + except requests.exceptions.HTTPError as e: if e.response.status_code == 404: logger.error(f"Season index not found for year {year}") @@ -79,7 +106,21 @@ async def get_season_events( raise HTTPException(status_code=500, detail="Failed to fetch available events for the season.") -@router.get('/seasons/{year}/events/{event_name}/sessions', tags=["API v2", "Seasonal Data"]) +@router.get( + '/seasons/{year}/events/{event_name}/sessions', + tags=["API v2", "Seasonal Data"], + summary="List sessions for a season event", + operation_id="v2_season_event_sessions", + responses={ + **COMMON_ERROR_RESPONSES, + 200: {"model": EventSessionsResponse, "description": "All sessions for the matched meeting."}, + 404: { + "model": ErrorEnvelope, + "description": "Season data not found on official F1 servers, or no event matched `event_name`.", + }, + 502: {"model": ErrorEnvelope, "description": "Error communicating with F1 servers."}, + }, +) @apply_tiered_limit("standard") async def get_event_sessions( request: Request, @@ -94,10 +135,10 @@ async def get_event_sessions( try: logger.info(f"Fetching sessions for {event_name} ({year}) via F1StaticClient") client = F1StaticClient() - + # We need the full season index to find the event and its sessions season_index = await run_in_threadpool(client.fetch_season_index, year) - + # Find the meeting meetings = season_index.get('Meetings', []) event_data = None @@ -105,12 +146,15 @@ async def get_event_sessions( if event_name.lower() in meeting.get('Name', '').lower() or event_name.lower() == str(meeting.get('Key')): event_data = meeting break - + if not event_data: - raise HTTPException(status_code=404, detail=f"Event matching '{event_name}' not found in the {year} season.") - + raise HTTPException( + status_code=404, + detail=f"Event matching '{event_name}' not found in the {year} season.", + ) + sessions_data = event_data.get('Sessions', []) - + sessions = [] for session in sessions_data: sessions.append({ @@ -122,14 +166,14 @@ async def get_event_sessions( "path": session.get('Path'), "key": session.get('Key') }) - + return { "year": year, "event_name": event_data.get('Name'), "event_key": event_data.get('Key'), "sessions": sessions } - + except HTTPException: raise except requests.exceptions.HTTPError as e: @@ -147,14 +191,31 @@ async def get_event_sessions( # TEAMMATE BATTLE TRACKER (V2, seasonal) # ============================================================================ -@router.get('/seasons/{year}/teammate-battle-plot', tags=["API v2", "Seasonal Data"]) +@router.get( + '/seasons/{year}/teammate-battle-plot', + tags=["API v2", "Seasonal Data"], + summary="Teammate battle scorecard plot (PNG)", + operation_id="v2_teammate_battle_plot", + responses={ + **ANALYSIS_ERROR_RESPONSES, + 200: _PNG_RESPONSE, + 404: { + **ANALYSIS_ERROR_RESPONSES[404], + "description": ANALYSIS_ERROR_RESPONSES[404]["description"] + _PLOT_NOT_FOUND_NOTE, + }, + }, +) @apply_tiered_limit("standard") async def teammate_battle_plot_v2( request: Request, year: int, api_key: str = Depends(verify_api_key) ): - """Season-long teammate H2H scorecard: quali/race wins and average quali gap per team.""" + """Season-long teammate H2H scorecard: quali/race wins and average quali gap per team. + + For the current (in-progress) season this is regenerated on request rather than served + from a durable stored row, since the live season's payloads are cached in Redis only. + """ logger.info(f"Generating teammate battle plot (V2): {year}") try: output_path = await run_in_threadpool(TeammateBattlePlot(), year) @@ -166,14 +227,27 @@ async def teammate_battle_plot_v2( raise HTTPException(status_code=404, detail="Plot not found") -@router.get('/seasons/{year}/teammate-battle-data', tags=["API v2", "Seasonal Data"]) +@router.get( + '/seasons/{year}/teammate-battle-data', + tags=["API v2", "Seasonal Data"], + summary="Teammate battle scorecard data", + operation_id="v2_teammate_battle_data", + responses={ + **ANALYSIS_ERROR_RESPONSES, + 200: {"model": TeammateBattleResponse, "description": "Per-team quali/race H2H scorecard."}, + }, +) @apply_tiered_limit("data") async def teammate_battle_data_v2( request: Request, year: int, api_key: str = Depends(verify_api_key) ): - """JSON teammate H2H payload: per-team quali/race head-to-head + average quali gap.""" + """JSON teammate H2H payload: per-team quali/race head-to-head + average quali gap. + + For the current (in-progress) season this is regenerated on request rather than served + from a durable stored row, since the live season's payloads are cached in Redis only. + """ logger.info(f"Fetching teammate battle data (V2): {year}") try: result = await run_in_threadpool(TeammateBattleData(), year) @@ -187,7 +261,20 @@ async def teammate_battle_data_v2( # SEASON FORM GUIDE (V2, seasonal) # ============================================================================ -@router.get('/seasons/{year}/form-guide-plot', tags=["API v2", "Seasonal Data"]) +@router.get( + '/seasons/{year}/form-guide-plot', + tags=["API v2", "Seasonal Data"], + summary="Season form guide plot (PNG)", + operation_id="v2_season_form_guide_plot", + responses={ + **ANALYSIS_ERROR_RESPONSES, + 200: _PNG_RESPONSE, + 404: { + **ANALYSIS_ERROR_RESPONSES[404], + "description": ANALYSIS_ERROR_RESPONSES[404]["description"] + _PLOT_NOT_FOUND_NOTE, + }, + }, +) @apply_tiered_limit("standard") async def form_guide_plot_v2( request: Request, @@ -196,7 +283,11 @@ async def form_guide_plot_v2( drivers: Optional[str] = Query(None, description="Comma-separated TLAs; default top 10 by mean finish"), api_key: str = Depends(verify_api_key) ): - """Rolling-average race/quali form guide across the season, per driver.""" + """Rolling-average race/quali form guide across the season, per driver. + + For the current (in-progress) season this is regenerated on request rather than served + from a durable stored row, since the live season's payloads are cached in Redis only. + """ logger.info(f"Generating season form guide plot (V2): {year} window={window} drivers={drivers}") try: driver_list = [d.strip().upper() for d in drivers.split(",") if d.strip()] if drivers else None @@ -209,7 +300,16 @@ async def form_guide_plot_v2( raise HTTPException(status_code=404, detail="Plot not found") -@router.get('/seasons/{year}/form-guide-data', tags=["API v2", "Seasonal Data"]) +@router.get( + '/seasons/{year}/form-guide-data', + tags=["API v2", "Seasonal Data"], + summary="Season form guide data", + operation_id="v2_season_form_guide_data", + responses={ + **ANALYSIS_ERROR_RESPONSES, + 200: {"model": SeasonFormResponse, "description": "Rolling-average race/quali position series."}, + }, +) @apply_tiered_limit("data") async def form_guide_data_v2( request: Request, @@ -218,7 +318,11 @@ async def form_guide_data_v2( drivers: Optional[str] = Query(None, description="Comma-separated TLAs; default top 10 by mean finish"), api_key: str = Depends(verify_api_key) ): - """JSON rolling-average race/quali position series per driver.""" + """JSON rolling-average race/quali position series per driver. + + For the current (in-progress) season this is regenerated on request rather than served + from a durable stored row, since the live season's payloads are cached in Redis only. + """ logger.info(f"Fetching season form guide data (V2): {year} window={window} drivers={drivers}") try: driver_list = [d.strip().upper() for d in drivers.split(",") if d.strip()] if drivers else None @@ -229,7 +333,20 @@ async def form_guide_data_v2( raise -@router.get('/seasons/{year}/driver-radar-plot', tags=["API v2", "Seasonal Data"]) +@router.get( + '/seasons/{year}/driver-radar-plot', + tags=["API v2", "Seasonal Data"], + summary="Season driver radar plot (PNG)", + operation_id="v2_season_driver_radar_plot", + responses={ + **ANALYSIS_ERROR_RESPONSES, + 200: _PNG_RESPONSE, + 404: { + **ANALYSIS_ERROR_RESPONSES[404], + "description": ANALYSIS_ERROR_RESPONSES[404]["description"] + _PLOT_NOT_FOUND_NOTE, + }, + }, +) @apply_tiered_limit("standard") async def season_radar_plot_v2( request: Request, @@ -238,7 +355,11 @@ async def season_radar_plot_v2( portrait: bool = Query(False, description="Portrait 4:5 crop for social media"), api_key: str = Depends(verify_api_key) ): - """Season driver performance radar (race pace, qualifying, consistency, racecraft, reliability, peak).""" + """Season driver performance radar (race pace, qualifying, consistency, racecraft, reliability, peak). + + For the current (in-progress) season this is regenerated on request rather than served + from a durable stored row, since the live season's payloads are cached in Redis only. + """ logger.info(f"Generating season radar plot (V2): {year} drivers={drivers}") try: output_path = await run_in_threadpool(SeasonRadarPlot(), year, drivers, portrait) @@ -250,7 +371,16 @@ async def season_radar_plot_v2( raise HTTPException(status_code=404, detail="Plot not found") -@router.get('/seasons/{year}/driver-radar-data', tags=["API v2", "Seasonal Data"]) +@router.get( + '/seasons/{year}/driver-radar-data', + tags=["API v2", "Seasonal Data"], + summary="Season driver radar data", + operation_id="v2_season_driver_radar_data", + responses={ + **ANALYSIS_ERROR_RESPONSES, + 200: {"model": SeasonDriverRadarResponse, "description": "Season driver radar (scope='season')."}, + }, +) @apply_tiered_limit("data") async def season_radar_data_v2( request: Request, @@ -258,7 +388,11 @@ async def season_radar_data_v2( drivers: Optional[str] = Query(None, description="Comma-separated TLAs (max 3); default best 3 by race pace"), api_key: str = Depends(verify_api_key) ): - """JSON season driver radar: 0-100 axis values + raw metrics per driver.""" + """JSON season driver radar: 0-100 axis values + raw metrics per driver. + + For the current (in-progress) season this is regenerated on request rather than served + from a durable stored row, since the live season's payloads are cached in Redis only. + """ logger.info(f"Fetching season radar data (V2): {year} drivers={drivers}") try: result = await run_in_threadpool(SeasonRadarData(), year, drivers) @@ -268,7 +402,20 @@ async def season_radar_data_v2( raise -@router.get('/career/driver-radar-plot', tags=["API v2", "Seasonal Data"]) +@router.get( + '/career/driver-radar-plot', + tags=["API v2", "Seasonal Data"], + summary="Career driver radar plot (PNG)", + operation_id="v2_career_driver_radar_plot", + responses={ + **ANALYSIS_ERROR_RESPONSES, + 200: _PNG_RESPONSE, + 404: { + **ANALYSIS_ERROR_RESPONSES[404], + "description": ANALYSIS_ERROR_RESPONSES[404]["description"] + _PLOT_NOT_FOUND_NOTE, + }, + }, +) @apply_tiered_limit("standard") async def career_radar_plot_v2( request: Request, @@ -277,7 +424,12 @@ async def career_radar_plot_v2( portrait: bool = Query(False, description="Portrait 4:5 crop for social media"), api_key: str = Depends(verify_api_key) ): - """Career driver performance radar aggregated over multiple seasons of results.""" + """Career driver performance radar aggregated over multiple seasons of results. + + If the span includes the current (in-progress) season, that season's contribution is + regenerated on request rather than read from a durable row, since the live season's + payloads are cached in Redis only. + """ logger.info(f"Generating career radar plot (V2): years={years} drivers={drivers}") try: output_path = await run_in_threadpool(CareerRadarPlot(), years, drivers, portrait) @@ -289,7 +441,16 @@ async def career_radar_plot_v2( raise HTTPException(status_code=404, detail="Plot not found") -@router.get('/career/driver-radar-data', tags=["API v2", "Seasonal Data"]) +@router.get( + '/career/driver-radar-data', + tags=["API v2", "Seasonal Data"], + summary="Career driver radar data", + operation_id="v2_career_driver_radar_data", + responses={ + **ANALYSIS_ERROR_RESPONSES, + 200: {"model": SeasonDriverRadarResponse, "description": "Career driver radar (scope='career')."}, + }, +) @apply_tiered_limit("data") async def career_radar_data_v2( request: Request, @@ -297,7 +458,12 @@ async def career_radar_data_v2( drivers: Optional[str] = Query(None, description="Comma-separated TLAs (max 3); default best 3 by race pace"), api_key: str = Depends(verify_api_key) ): - """JSON career driver radar: 0-100 axis values + raw metrics per driver across seasons.""" + """JSON career driver radar: 0-100 axis values + raw metrics per driver across seasons. + + If the span includes the current (in-progress) season, that season's contribution is + regenerated on request rather than read from a durable row, since the live season's + payloads are cached in Redis only. + """ logger.info(f"Fetching career radar data (V2): years={years} drivers={drivers}") try: result = await run_in_threadpool(CareerRadarData(), years, drivers) diff --git a/src/api/routers/standings_v2.py b/src/api/routers/standings_v2.py index e084d27..ca6098e 100644 --- a/src/api/routers/standings_v2.py +++ b/src/api/routers/standings_v2.py @@ -6,6 +6,7 @@ from fastapi import APIRouter, Depends, Request from fastapi.concurrency import run_in_threadpool +from src.api.schemas.common import ANALYSIS_ERROR_RESPONSES from src.api.schemas.standings import ( ConstructorsStandingsResponse, DriversStandingsResponse, @@ -16,7 +17,9 @@ from src.core.security.rate_limiting import apply_tiered_limit from src.services.standings.v2.standings import ( get_constructors_standings, + get_constructors_standings_live, get_drivers_standings, + get_drivers_standings_live, ) logger = get_logger(__name__) @@ -46,10 +49,39 @@ def _resolve_current_year_constructors() -> dict: return get_constructors_standings(year - 1) +def _resolve_live_drivers() -> dict: + year = datetime.utcnow().year + try: + payload = get_drivers_standings_live(year) + if payload.get("standings"): + return payload + except SessionNotFoundError: + pass + return get_drivers_standings_live(year - 1) + + +def _resolve_live_constructors() -> dict: + year = datetime.utcnow().year + try: + payload = get_constructors_standings_live(year) + if payload.get("standings"): + return payload + except SessionNotFoundError: + pass + return get_constructors_standings_live(year - 1) + + @router.get( "/seasons/{year}/drivers-standings", tags=["API v2", "Seasonal Data"], response_model=DriversStandingsResponse, + summary="Drivers' standings for a season", + operation_id="v2_season_drivers_standings", + description=( + "Full-season drivers' championship standings. This is the **canonical** form of this " + "data; `/api/v2/standings/drivers` returns the same shape for the current season only." + ), + responses={**ANALYSIS_ERROR_RESPONSES}, ) @apply_tiered_limit("standard") async def drivers_standings_for_season( @@ -64,6 +96,14 @@ async def drivers_standings_for_season( "/seasons/{year}/constructors-standings", tags=["API v2", "Seasonal Data"], response_model=ConstructorsStandingsResponse, + summary="Constructors' standings for a season", + operation_id="v2_season_constructors_standings", + description=( + "Full-season constructors' championship standings. This is the **canonical** form of " + "this data; `/api/v2/standings/constructors` returns the same shape for the current " + "season only." + ), + responses={**ANALYSIS_ERROR_RESPONSES}, ) @apply_tiered_limit("standard") async def constructors_standings_for_season( @@ -78,6 +118,10 @@ async def constructors_standings_for_season( "/seasons/{year}/round/{round_nr}/drivers-standings", tags=["API v2", "Seasonal Data"], response_model=DriversStandingsResponse, + summary="Drivers' standings after a round", + operation_id="v2_round_drivers_standings", + description="Drivers' championship standings as they stood immediately after `round_nr`.", + responses={**ANALYSIS_ERROR_RESPONSES}, ) @apply_tiered_limit("standard") async def drivers_standings_after_round( @@ -93,6 +137,10 @@ async def drivers_standings_after_round( "/seasons/{year}/round/{round_nr}/constructors-standings", tags=["API v2", "Seasonal Data"], response_model=ConstructorsStandingsResponse, + summary="Constructors' standings after a round", + operation_id="v2_round_constructors_standings", + description="Constructors' championship standings as they stood immediately after `round_nr`.", + responses={**ANALYSIS_ERROR_RESPONSES}, ) @apply_tiered_limit("standard") async def constructors_standings_after_round( @@ -108,6 +156,14 @@ async def constructors_standings_after_round( "/standings/drivers", tags=["API v2", "Seasonal Data"], response_model=DriversStandingsResponse, + summary="Current drivers' standings", + operation_id="v2_current_drivers_standings", + description=( + "Drivers' championship standings for the current season, falling back to the prior " + "season if the current one has no results yet. Short form of the canonical " + "`/api/v2/seasons/{year}/drivers-standings`; defaults to the current season." + ), + responses={**ANALYSIS_ERROR_RESPONSES}, ) @apply_tiered_limit("standard") async def current_drivers_standings( @@ -121,6 +177,14 @@ async def current_drivers_standings( "/standings/constructors", tags=["API v2", "Seasonal Data"], response_model=ConstructorsStandingsResponse, + summary="Current constructors' standings", + operation_id="v2_current_constructors_standings", + description=( + "Constructors' championship standings for the current season, falling back to the " + "prior season if the current one has no results yet. Short form of the canonical " + "`/api/v2/seasons/{year}/constructors-standings`; defaults to the current season." + ), + responses={**ANALYSIS_ERROR_RESPONSES}, ) @apply_tiered_limit("standard") async def current_constructors_standings( @@ -128,3 +192,46 @@ async def current_constructors_standings( api_key: str = Depends(verify_api_key), ): return await run_in_threadpool(_resolve_current_year_constructors) + + +@router.get( + "/standings/drivers/live", + tags=["API v2", "Seasonal Data"], + response_model=DriversStandingsResponse, + summary="Live drivers' standings", + operation_id="v2_live_drivers_standings", + description=( + "Drivers' championship standings for the current season, fetched straight from the " + "upstream feed on every call — **no cache layer**. Use this while a race weekend is " + "in progress; use `/api/v2/standings/drivers` when a cached snapshot is acceptable." + ), + responses={**ANALYSIS_ERROR_RESPONSES}, +) +@apply_tiered_limit("standard") +async def live_drivers_standings( + request: Request, + api_key: str = Depends(verify_api_key), +): + return await run_in_threadpool(_resolve_live_drivers) + + +@router.get( + "/standings/constructors/live", + tags=["API v2", "Seasonal Data"], + response_model=ConstructorsStandingsResponse, + summary="Live constructors' standings", + operation_id="v2_live_constructors_standings", + description=( + "Constructors' championship standings for the current season, fetched straight from " + "the upstream feed on every call — **no cache layer**. Use this while a race weekend " + "is in progress; use `/api/v2/standings/constructors` when a cached snapshot is " + "acceptable." + ), + responses={**ANALYSIS_ERROR_RESPONSES}, +) +@apply_tiered_limit("standard") +async def live_constructors_standings( + request: Request, + api_key: str = Depends(verify_api_key), +): + return await run_in_threadpool(_resolve_live_constructors) diff --git a/src/api/routers/teams_api.py b/src/api/routers/teams_api.py index 28e4445..268b82e 100644 --- a/src/api/routers/teams_api.py +++ b/src/api/routers/teams_api.py @@ -1,38 +1,71 @@ from fastapi import APIRouter +from src.api.schemas.common import COMMON_ERROR_RESPONSES, ErrorEnvelope +from src.api.schemas.seasonal import SeasonTeamsResponse, TeamDetailResponse from src.core.logging import get_logger from src.core.security.rate_limiting import apply_tiered_limit from fastapi import Request, Query, HTTPException, Path from src.ingestion.reference import get_season_teams, get_team_details_by_name - - logger = get_logger(__name__) router = APIRouter(prefix='/api/static') +#: This router has no `verify_api_key` dependency (see module-level endpoint docs), so +#: 401/403 can never occur here; only the rate-limit and server-error cases apply. +_UNAUTH_COMMON_RESPONSES = {429: COMMON_ERROR_RESPONSES[429], 500: COMMON_ERROR_RESPONSES[500]} -@router.get('/teams', tags=["Static"]) + +@router.get( + '/teams', + tags=["Static"], + summary="List teams for a season", + operation_id="static_season_teams", + responses={ + **_UNAUTH_COMMON_RESPONSES, + 200: {"model": SeasonTeamsResponse, "description": "All constructors for the season."}, + 400: {"model": ErrorEnvelope, "description": "Season year not covered by the static reference data."}, + }, +) @apply_tiered_limit("data") async def get_teams_from_year( request: Request, year: int = Query(2026, ge=2025, le=2026, description="Season year (2025-2026)") ): - """Get teams for a specific season year""" + """Get teams for a specific season year. + + Unauthenticated: this endpoint has no API-key requirement and serves static reference + data curated in the repo (``src/domain/data/teams.json``), not live session data. + """ try: teams = get_season_teams(year) return {"teams": teams} except ValueError as e: logger.error(f"Error fetching teams for year {year}: {e}") raise HTTPException(status_code=400, detail=str(e)) - -@router.get('/teams/{team_name}', tags=["Static"]) + + +@router.get( + '/teams/{team_name}', + tags=["Static"], + summary="Get team details by name", + operation_id="static_team_details", + responses={ + **_UNAUTH_COMMON_RESPONSES, + 200: {"model": TeamDetailResponse, "description": "The matched constructor."}, + 404: {"model": ErrorEnvelope, "description": "No team matched `team_name` for that season."}, + }, +) @apply_tiered_limit("data") async def get_team_details( request: Request, year: int = Query(2026, ge=2025, le=2026, description="Season year (2025-2026)"), team_name: str = Path(..., description="Team Name") ): - """Get details for a specific team by Name""" + """Get details for a specific team by Name. + + Unauthenticated: this endpoint has no API-key requirement and serves static reference + data curated in the repo (``src/domain/data/teams.json``), not live session data. + """ try: team_details = get_team_details_by_name(year, team_name) if not team_details: @@ -41,4 +74,3 @@ async def get_team_details( except ValueError as e: logger.error(f"Error fetching team details for {team_name}: {e}") raise HTTPException(status_code=404, detail=str(e)) - diff --git a/src/api/routers/telemetry_v2.py b/src/api/routers/telemetry_v2.py new file mode 100644 index 0000000..9286c3f --- /dev/null +++ b/src/api/routers/telemetry_v2.py @@ -0,0 +1,125 @@ +"""Animation-ready telemetry endpoints (V2, livetiming-backed). + +Thin HTTP wrapper around ``src/services/analysis/v2/lap_frames.py``. See that +module's docstring for why a *resampled* multi-driver, multi-lap frame stream +is a different shape from ``/api/v2/lap-all-data`` (one driver, one lap, raw +samples) and worth its own endpoint. +""" +from fastapi import APIRouter, Request, HTTPException, Depends, Query +from fastapi.concurrency import run_in_threadpool +from typing import Optional, Union + +from src.api.deps import guard_session_params +from src.core.logging import get_logger +from src.core.security.api_keys import verify_api_key +from src.core.security.rate_limiting import apply_tiered_limit +from src.api.schemas.common import ANALYSIS_ERROR_RESPONSES +from src.api.schemas.telemetry import LapsDataResponse, TrackMapResponse +from src.services.analysis.v2.lap_frames import LapsData, TrackMapData +from src.core.exceptions import T1APIError + +logger = get_logger(__name__) + + +def _track(event_name, *args): + try: + from src.core.observability.analytics import SessionTracker + SessionTracker().track_session(event_name, *args) + except Exception: + pass + + +router = APIRouter( + prefix="/api/v2/telemetry", + dependencies=[Depends(guard_session_params)], +) + + +@router.get( + '/laps-data', + tags=["API v2", "Telemetry"], + summary="Resampled telemetry frames over a lap range", + operation_id="v2_telemetry_laps_data", + responses={200: {"model": LapsDataResponse}, **ANALYSIS_ERROR_RESPONSES}, +) +@apply_tiered_limit("data") +async def telemetry_laps_data_v2( + request: Request, + year: int = Query(2025, ge=2018, le=2030), + gp: Union[int, str] = Query(1, description="Round number, Event Key, or Official Name"), + session: str = Query('R'), + drivers: str = Query(..., description="Comma-separated driver TLAs, e.g. VER,HAM"), + lap_from: int = Query(..., ge=1), + lap_to: Optional[int] = Query(None, ge=1, description="Defaults to lap_from"), + hz: int = Query(10, ge=1, le=20, description="Output frame rate"), + format: str = Query('frames', description="frames | columnar"), + precision: int = Query(2, ge=0, le=6), + include_track: bool = Query(False), + api_key: str = Depends(verify_api_key) +): + """A single uniform time grid across a lap range and a set of drivers, ready + for animation playback: one row per tick with position, throttle, brake and + the rest resampled onto it, instead of each driver's raw samples landing on + different instants. + + ``hz`` picks the output frame rate (1-20), ``format`` picks ``frames`` + (array of samples) or ``columnar`` (one array per field), and + ``precision`` rounds every float in the response. The response's + ``range.driver_laps`` and ``range.frame_count`` reflect the actual cost of + the request against the service's driver-lap and frame budget — a request + over budget is rejected with 400 before any stream is touched, and the + error message suggests an ``hz`` that would fit. Any session. + """ + lap_to = lap_to if lap_to is not None else lap_from + if lap_to < lap_from: + raise HTTPException(status_code=400, detail=f"lap_to ({lap_to}) must be >= lap_from ({lap_from}).") + if format not in ("frames", "columnar"): + raise HTTPException(status_code=400, detail="format must be one of 'frames', 'columnar'.") + driver_list = [d.strip().upper() for d in drivers.split(',') if d.strip()] + if not driver_list: + raise HTTPException(status_code=400, detail="At least one driver is required.") + + logger.info( + f"Fetching telemetry laps-data (V2): Y{year} GP{gp} {session} drivers={driver_list} " + f"laps={lap_from}-{lap_to} hz={hz} format={format}" + ) + try: + result = await run_in_threadpool( + LapsData(), year, gp, session, driver_list, lap_from, lap_to, + hz, format, precision, include_track, + ) + _track('telemetry-laps-data', year, gp, session) + return result + except T1APIError: + raise + + +@router.get( + '/track-map', + tags=["API v2", "Telemetry"], + summary="Circuit geometry for a session", + operation_id="v2_telemetry_track_map", + responses={200: {"model": TrackMapResponse}, **ANALYSIS_ERROR_RESPONSES}, +) +@apply_tiered_limit("data") +async def telemetry_track_map_v2( + request: Request, + year: int = Query(2025, ge=2018, le=2030), + gp: Union[int, str] = Query(1, description="Round number, Event Key, or Official Name"), + session: str = Query('R'), + api_key: str = Depends(verify_api_key) +): + """Session-level circuit geometry — rotation, corners, and track outline — + with no driver attached. Deliberately distinct from the existing per-driver + ``/api/v2/track-map-data``, which colours one driver's fastest lap by speed + or gear; this endpoint returns only the circuit itself, for drawing the + track once and animating cars over it (e.g. with ``/laps-data``). Any + session. + """ + logger.info(f"Fetching telemetry track-map (V2): Y{year} GP{gp} {session}") + try: + result = await run_in_threadpool(TrackMapData(), year, gp, session) + _track('telemetry-track-map', year, gp, session) + return result + except T1APIError: + raise diff --git a/src/api/schemas/accounts.py b/src/api/schemas/accounts.py new file mode 100644 index 0000000..fce868b --- /dev/null +++ b/src/api/schemas/accounts.py @@ -0,0 +1,189 @@ +"""Documentation-only response models for the account/auth surface. + +These models back ``responses=`` entries for Swagger only — they are never +passed as a bare ``response_model=`` (see ``src/api/schemas/common.py`` for +why). The one exception is ``TokenResponse`` in ``auth.py`` itself, which +already existed as a real ``response_model=`` before this pass and is left +untouched. + +Shapes here are traced from what the handlers actually build: +``src/repositories/api_keys.py`` (``_serialize``, ``create_api_key``), +``src/repositories/api_key_usage.py`` (``summary_for_key``, +``dashboard_for_key``, ``peak_hours_for_key``), and the inline dicts in +``src/api/routers/auth.py`` / ``src/api/routers/keys.py``. +""" +from __future__ import annotations + +from typing import Any, Dict, List, Optional + +from pydantic import BaseModel, Field + + +class MeResponse(BaseModel): + """Current-user profile, built inline in ``GET /api/auth/me``.""" + + id: str + email: Optional[str] = None + is_admin: bool + created_at: Optional[Any] = Field(default=None, description="Stored as a BSON datetime; serialized by FastAPI.") + key_count: int = Field(description="Total API keys ever created by this user, including revoked ones.") + active_key_count: int = Field(description="API keys that are not revoked.") + + +class ApiKeySummary(BaseModel): + """One key as returned by ``src.repositories.api_keys._serialize`` — never includes the raw key or hash.""" + + id: str + owner_id: Optional[str] = None + key_prefix: str = Field(description="First 11 characters of the raw key, e.g. `t1_abcdEFGh`.") + tier: str = Field(description="`standard` or `premium`.") + label: str + created_at: Optional[Any] = None + last_used_at: Optional[Any] = None + revoked_at: Optional[Any] = Field(default=None, description="Null while the key is active.") + + +class ListMyKeysResponse(BaseModel): + """``GET /api/keys`` — every key (active and revoked) owned by the caller.""" + + keys: List[ApiKeySummary] + + +class CreateKeyResponse(BaseModel): + """``POST /api/keys``. + + ``raw_key`` is returned exactly once, at creation time — only its SHA-256 + hash (``key_hash``) is persisted (see ``src/repositories/api_keys.py``), + so a key that isn't captured from this response cannot be recovered and + must be revoked and re-issued. This endpoint always mints a + **standard**-tier key; premium tier can only be granted through the + admin endpoints, never by a user (admin or not) through self-service. + """ + + id: str + raw_key: str = Field(description="The plaintext API key. Shown only in this response — store it now.") + key_prefix: str + tier: str + label: str + created_at: Optional[Any] = None + warning: str + + +class UsageBucket(BaseModel): + """One hourly bucket from ``api_key_usage`` (bucket key is `yyyymmddhh`).""" + + bucket: Optional[str] = None + count: int = 0 + errors: int = 0 + avg_duration_ms: float = 0.0 + + +class KeyUsageResponse(BaseModel): + """``GET /api/keys/{key_id}/usage`` — hourly stats over a rolling window.""" + + key_id: str + key_prefix: Optional[str] = None + label: Optional[str] = None + window_hours: int + total_requests: int + total_errors: int + error_rate_percent: float + avg_duration_ms: float + buckets: List[UsageBucket] + + +class WindowStats(BaseModel): + """Aggregate request/error counts for a fixed calendar window.""" + + requests: int = 0 + errors: int = 0 + avg_ms: float = 0.0 + error_rate_percent: float = 0.0 + + +class KeyInfo(BaseModel): + id: str + prefix: Optional[str] = None + label: Optional[str] = None + tier: str + + +class QuotaInfo(BaseModel): + """Built by ``keys.py:_build_quota`` from ``limits_for_tier``.""" + + monthly_limit: int + used_this_month: int + remaining: int + percent_used: float + resets_at: str + + +class RateLimitInfo(BaseModel): + per_minute: int + per_hour: int + + +class HourCount(BaseModel): + hour: int = Field(ge=0, le=23) + count: int = 0 + errors: int = 0 + + +class KeyDashboardUsage(BaseModel): + today: WindowStats + last_7_days: WindowStats + current_month: WindowStats + + +class KeyDashboardResponse(BaseModel): + """``GET /api/keys/{key_id}/dashboard`` — full per-key usage dashboard.""" + + key: KeyInfo + quota: QuotaInfo + rate_limit: RateLimitInfo + usage: KeyDashboardUsage + peak_hour_utc: HourCount + last_24h: List[UsageBucket] + + +class KeyPeakHoursResponse(BaseModel): + """``GET /api/keys/{key_id}/peak-hours`` — 24-entry hour-of-day (UTC) distribution.""" + + key_id: str + days: int + peak_hour_utc: HourCount + by_hour: List[HourCount] + + +class PerKeyUsageSummary(BaseModel): + """One row of the ``keys`` list in ``GET /api/me/usage``.""" + + id: str + prefix: Optional[str] = None + label: Optional[str] = None + tier: Optional[str] = None + today: int + current_month: int + + +class MyUsageTotals(BaseModel): + today: Dict[str, int] + last_7_days: Dict[str, int] + current_month: Dict[str, int] + + +class MyUsageResponse(BaseModel): + """``GET /api/me/usage`` — aggregate dashboard across all of the caller's active keys.""" + + user_id: str + key_count: int + totals: MyUsageTotals + quota: QuotaInfo + keys: List[PerKeyUsageSummary] + + +class RevokeKeyResponse(BaseModel): + """``DELETE /api/keys/{key_id}``.""" + + id: str + revoked: bool diff --git a/src/api/schemas/admin.py b/src/api/schemas/admin.py new file mode 100644 index 0000000..0646c1e --- /dev/null +++ b/src/api/schemas/admin.py @@ -0,0 +1,1145 @@ +"""Documentation-only response schemas for the ``/api/admin/*`` routers. + +These models exist purely so Swagger can show a real shape for every admin +endpoint. Per the house rule (see ``src/api/schemas/analysis.py``) they are +attached via ``responses={200: {"model": ...}}`` — **never** via +``response_model=`` — so they cannot filter or otherwise alter the live +payload. Each model is derived from the actual ``return`` statements of the +handler or the service/repository function it calls; nothing here is guessed. + +A few payloads are genuinely dynamic — a job record that is the union of two +independent serializations (``PlotGenJob.as_dict()`` and +``admin_jobs._serialize()``), a stored user/key document that mirrors whatever +is in Mongo, or a background-processor result whose ``results`` key is a +free-form ``{feature: count}`` map. Those use ``model_config = {"extra": +"allow"}`` and/or ``Dict[str, Any]`` rather than a guessed fixed schema — see +the docstring on each for why. +""" +from __future__ import annotations + +from typing import Any, Dict, List, Optional + +from pydantic import BaseModel, Field + + +# --------------------------------------------------------------------------- +# Shared building blocks +# --------------------------------------------------------------------------- + +class ExtraGroup(BaseModel): + """One bucket of stored keys the singleton expectation set says nothing + about (e.g. ``lap_all_data x1100``) — see ``plot_inventory._group_extras``. + """ + + prefix: str + count: int + sample: List[str] = Field(description="Up to 6 example keys from this bucket.") + + +class UsageWindowStats(BaseModel): + """One aggregated window from ``api_key_usage._aggregate_window``.""" + + requests: int + errors: int + avg_ms: float + error_rate_percent: float + + +class UsageBucket(BaseModel): + """One hourly bucket from ``api_key_usage.summary_for_key``/``summary_for_keys``.""" + + bucket: Optional[str] = Field(default=None, description="``yyyymmddhh`` bucket key.") + count: int + errors: int + avg_duration_ms: float + + +class KeyUsageSummary(BaseModel): + """Windowed usage summary — ``api_key_usage.summary_for_key``/``summary_for_keys``.""" + + window_hours: int + total_requests: int + total_errors: int + error_rate_percent: float + avg_duration_ms: float + buckets: List[UsageBucket] + + +class PeakHourEntry(BaseModel): + """One hour-of-day (UTC) bucket from ``api_key_usage.peak_hours_for_key*``.""" + + hour: int + count: int + errors: Optional[int] = Field( + default=None, + description="Absent only in the no-data fallback of /peak-hours' peak_hour_utc.", + ) + + +class RequestTrackerSummary(BaseModel): + """``RequestTracker.get_summary()`` — in-process request counters.""" + + total_requests: int + total_errors: int + error_rate_percent: float + tracked_requests_in_memory: int + tracked_errors_in_memory: int + unique_endpoints: int + + +# --------------------------------------------------------------------------- +# Processor / populate-sessions +# --------------------------------------------------------------------------- + +class ProcessorStatusResponse(BaseModel): + """``GET /api/admin/processor-status`` — ``BackgroundProcessor`` state.""" + + running: bool + check_interval: float + processed_sessions_count: int + processed_sessions: List[str] = Field(description="Last 20 processed session ids.") + status: str + + +class ProcessLatestResponse(BaseModel): + """``POST /api/admin/process-latest`` — ``BackgroundProcessor.force_process_latest()``. + + ``results`` is the free-form ``{feature_name: count}`` map returned by + ``PlotDataGenerator.generate_all_session_data`` and is only present on a + successful run; permissive because its keys track whatever plot features + the generator currently supports. + """ + + status: str + session: Optional[str] = None + results: Optional[Dict[str, int]] = None + error: Optional[str] = None + reason: Optional[str] = None + + model_config = {"extra": "allow"} + + +# --------------------------------------------------------------------------- +# MongoDB overview / coverage +# --------------------------------------------------------------------------- + +class MongoOverviewYearStat(BaseModel): + year: int + collection: str + gp_documents: int + gp_with_session_data: int + + +class MongoOverviewResponse(BaseModel): + """``GET /api/admin/mongodb/overview`` — ``_query_mongodb_overview``.""" + + version: str + database: str + collections_matched: int + total_gp_documents: int + years: List[MongoOverviewYearStat] + + +class MongoPlotDetail(BaseModel): + plot_type: str + record_estimate: int = Field(description="List length / dict key count; a rough size proxy only.") + + +class MongoSessionSummary(BaseModel): + session_type: str + has_data: bool + plot_count: int + plot_types: List[str] + plot_details: List[MongoPlotDetail] + + +class MongoGpResult(BaseModel): + year: int + round_nr: Optional[int] = None + gp_id: Optional[str] = None + event_name: Optional[str] = None + session_count: int + sessions: List[MongoSessionSummary] + + +class MongoSessionsCoverageResponse(BaseModel): + """``GET /api/admin/mongodb/sessions-with-data`` — ``_query_mongodb_coverage``.""" + + version: str + database: str + years_scanned: List[int] + total_gp_documents_scanned: int + total_gp_results: int + available_session_types: List[str] + available_plot_types: List[str] + grand_prix: List[MongoGpResult] + + +# --------------------------------------------------------------------------- +# Plot inventory & backfill (V2) +# --------------------------------------------------------------------------- + +class PlotInventorySessionEntry(BaseModel): + session_type: str + expected: List[str] = Field(description="Every singleton data_type expected for this session.") + present: List[str] + missing: List[str] + extra_groups: List[ExtraGroup] = Field( + description="Stored per-driver/pair/lap and legacy keys the expectation set says nothing about." + ) + extra_count: int + labels: Dict[str, str] = Field(description="data_type -> human label.") + + +class PlotInventoryGp(BaseModel): + year: int + round_nr: int + event_name: str + sessions: List[PlotInventorySessionEntry] + + +class PlotInventoryScope(BaseModel): + year: Optional[int] = None + gp: Optional[Any] = None + session: Optional[str] = None + + +class PlotInventoryResponse(BaseModel): + """``GET /api/admin/plots/missing`` — ``plot_inventory.compute_inventory`` + (aliased as ``compute_missing``). Schedule-driven, so entirely-absent + sessions/GPs are reported too, not just Mongo gaps. + """ + + version: str + scope: PlotInventoryScope + years_scanned: List[int] + total_sessions: int + total_expected_plots: int + total_missing_plots: int + total_extra_plots: int + grand_prix: List[PlotInventoryGp] + + +class FeatureCatalogEntry(BaseModel): + """One selectable feature — ``registry.FeatureEntry.as_dict()``.""" + + key: str + label: str + kind: str = Field(description="singleton | per_driver | per_pair | per_driver_lap | season | career") + group: str + applies_to: List[str] = Field(description="Session types this applies to; empty means every type.") + cost: str = Field(description="light | heavy | extreme") + session_scoped: bool + + +class PlotCatalogResponse(BaseModel): + """``GET /api/admin/plots/catalog``.""" + + count: int + features: List[FeatureCatalogEntry] + session: Optional[str] = None + + +class SeasonFeatureRow(BaseModel): + feature: str + label: str + data_type: str + present: bool + + +class SeasonInventoryResponse(BaseModel): + """``GET /api/admin/plots/season`` — ``plot_inventory.season_inventory``.""" + + year: int + features: List[SeasonFeatureRow] + extra_groups: List[ExtraGroup] + is_current_season: bool + + +class LapRange(BaseModel): + min: int + max: int + + +class SessionDriversResponse(BaseModel): + """``GET /api/admin/sessions/{year}/{gp}/{session}/drivers``.""" + + year: int + gp: str + session: str + drivers: List[str] + laps: Optional[Dict[str, List[int]]] = Field( + default=None, description="Only present when include_laps=true. Driver TLA -> lap numbers." + ) + lap_range: Optional[LapRange] = Field(default=None, description="Only present when include_laps=true.") + + +class PlanFeatureCost(BaseModel): + feature: str + label: str + units: int + + +class PlanEstimateResponse(BaseModel): + """``POST /api/admin/plots/estimate`` — ``plot_inventory.estimate_plan``.""" + + units: int + by_feature: List[PlanFeatureCost] + warnings: List[str] + drivers_by_session: Dict[str, List[str]] + truncated: bool = Field(description="True if the plan hit MAX_PLAN_UNITS and was cut short.") + sessions: int = Field(description="Distinct (year, gp, session) touched, excluding season/career units.") + + +class PlotGenJobResponse(BaseModel): + """``POST /api/admin/plots/generate`` — ``PlotGenJob.as_dict()`` at creation + time (freshly queued, so counters are still zero). + """ + + job_id: str + scope: Dict[str, Any] + selection: Dict[str, Any] + status: str = Field(description="queued | running | completed | failed | cancelled") + total: int + done: int + success: int + failed: int + skipped: int + current: Optional[str] = None + per_feature: Dict[str, Dict[str, int]] + errors: List[str] = Field(description="Most recent 25 errors.") + warnings: List[str] + started_at: Optional[str] = None + finished_at: Optional[str] = None + + +class JobRecord(BaseModel): + """One entry from ``GET /api/admin/plots/jobs`` or ``/jobs/{job_id}``. + + Genuinely a union of two independent serializations: + ``admin_jobs._serialize()`` (the durable Mongo doc — contributes ``kind``, + ``cancel_requested``, ``worker``, ``created_at``, ``heartbeat_at``) merged + with ``PlotGenJob.as_dict()`` (the live in-process job, when this process + owns it — contributes ``warnings``) via ``{**doc, **live}``. A job served + from a process that never ran it has only the Mongo fields. Permissive + because the merge means neither side's field set is guaranteed alone. + """ + + job_id: str + kind: Optional[str] = None + scope: Dict[str, Any] + selection: Dict[str, Any] + status: str + total: int + done: int + success: int + failed: int + skipped: int + current: Optional[str] = None + per_feature: Dict[str, Any] + errors: List[str] + warnings: Optional[List[str]] = None + cancel_requested: Optional[bool] = None + worker: Optional[str] = None + created_at: Optional[str] = None + started_at: Optional[str] = None + finished_at: Optional[str] = None + heartbeat_at: Optional[str] = None + + model_config = {"extra": "allow"} + + +class JobsListResponse(BaseModel): + """``GET /api/admin/plots/jobs``.""" + + count: int + jobs: List[JobRecord] + + +class JobCancelResponse(BaseModel): + """``POST /api/admin/plots/jobs/{job_id}/cancel``. + + ``cancel_requested=true`` only means the flag was set — the worker stops at + its next progress flush (~2s / 25 units), not synchronously with this call. + """ + + job_id: str + cancel_requested: bool + + +# --------------------------------------------------------------------------- +# User / API-key management +# --------------------------------------------------------------------------- + +class UserRecord(BaseModel): + """One ``users`` document — ``users.list_users`` (password_hash excluded). + + Permissive: this mirrors whatever is actually stored, and the collection + predates a fixed schema. + """ + + id: str + email: Optional[str] = None + is_admin: Optional[bool] = None + disabled: Optional[bool] = None + created_at: Optional[Any] = None + + model_config = {"extra": "allow"} + + +class UsersListResponse(BaseModel): + """``GET /api/admin/users``.""" + + count: int + users: List[UserRecord] + + +class ApiKeyRecord(BaseModel): + """One ``api_keys`` document — ``api_keys.list_all`` (key_hash excluded, + raw_key never stored/returned outside creation). + """ + + id: str + owner_id: Optional[str] = None + key_prefix: str + tier: str + label: str + created_at: Optional[Any] = None + last_used_at: Optional[Any] = None + revoked_at: Optional[Any] = None + + +class KeysListResponse(BaseModel): + """``GET /api/admin/keys``.""" + + count: int + keys: List[ApiKeyRecord] + + +class KeyVerifyResponse(BaseModel): + """``GET /api/admin/keys/verify``. + + Three distinct shapes depending on what happened (lookup error / not + found / found), so every field beyond ``found`` is optional. + """ + + found: bool + error: Optional[str] = Field(default=None, description="Set only when the Mongo lookup itself raised.") + key_prefix: Optional[str] = None + tier: Optional[str] = None + revoked: Optional[bool] = None + owner_id: Optional[str] = None + created_at: Optional[str] = None + cached: Optional[Dict[str, Any]] = Field( + default=None, description="Raw Redis auth-cache entry for this key hash, if any." + ) + hint: Optional[str] = None + + +class KeyRevokeResponse(BaseModel): + """``POST /api/admin/keys/{key_id}/revoke``.""" + + id: str + revoked: bool + + +# --------------------------------------------------------------------------- +# Usage / dashboard / analytics +# --------------------------------------------------------------------------- + +class UsageTopRow(BaseModel): + key_hash: str = Field(description="SHA-256 of the raw key — never the key itself.") + count: int + errors: int + avg_duration_ms: float + key_prefix: Optional[str] = None + label: Optional[str] = None + tier: Optional[str] = None + owner_id: Optional[str] = None + + +class UsageTopResponse(BaseModel): + """``GET /api/admin/usage/top``.""" + + window_hours: int + count: int + rows: List[UsageTopRow] + + +class UsageForKeyResponse(BaseModel): + """``GET /api/admin/usage/keys/{key_id}``.""" + + key_id: str + key_prefix: Optional[str] = None + owner_id: Optional[str] = None + tier: Optional[str] = None + label: Optional[str] = None + usage: KeyUsageSummary + + +class DashboardTotals(BaseModel): + today: UsageWindowStats + last_7_days: UsageWindowStats + current_month: UsageWindowStats + + +class DashboardTopKeyRow(BaseModel): + key_hash: str + count: int + errors: int + avg_duration_ms: float + key_prefix: Optional[str] = None + label: Optional[str] = None + tier: Optional[str] = None + + +class AdminDashboardResponse(BaseModel): + """``GET /api/admin/dashboard`` — platform-wide usage summary.""" + + totals: DashboardTotals + month_resets_at: str + top_keys_24h: List[DashboardTopKeyRow] + request_tracker_summary: RequestTrackerSummary + + +class PeakHoursResponse(BaseModel): + """``GET /api/admin/peak-hours``.""" + + days: int + peak_hour_utc: PeakHourEntry + by_hour: List[PeakHourEntry] = Field(description="Always 24 entries, hour 0..23 UTC.") + + +class QuotaRow(BaseModel): + key_id: str + key_prefix: Optional[str] = None + label: Optional[str] = None + tier: str + monthly_limit: int + used_this_month: int + remaining: int + percent_used: float + + +class QuotaUsageResponse(BaseModel): + """``GET /api/admin/quota-usage``.""" + + count: int + rows: List[QuotaRow] = Field(description="Sorted by percent_used, descending.") + + +class DashboardForKeysResult(BaseModel): + """``api_key_usage.dashboard_for_keys`` — aggregated across a set of keys.""" + + today: UsageWindowStats + last_7_days: UsageWindowStats + current_month: UsageWindowStats + window: Optional[UsageWindowStats] = Field(default=None, description="Present only when hours was passed.") + window_hours: Optional[int] = None + buckets: List[UsageBucket] + month_resets_at: str + + +class UserUsageKeyRow(BaseModel): + id: str + key_prefix: Optional[str] = None + label: Optional[str] = None + tier: Optional[str] = None + revoked_at: Optional[Any] = None + today: UsageWindowStats + last_7_days: UsageWindowStats + current_month: UsageWindowStats + + +class UserUsageResponse(BaseModel): + """``GET /api/admin/users/{user_id}/usage``.""" + + user: UserRecord + window_hours: int + aggregate: DashboardForKeysResult + peak_hours: List[PeakHourEntry] + keys: List[UserUsageKeyRow] + + +class DashboardForKeyResult(BaseModel): + """``api_key_usage.dashboard_for_key`` — single-key today/7d/month + hourly series.""" + + today: UsageWindowStats + last_7_days: UsageWindowStats + current_month: UsageWindowStats + last_24h: List[UsageBucket] + month_resets_at: str + + +class KeyAnalyticsKeyInfo(BaseModel): + id: str + key_prefix: Optional[str] = None + label: Optional[str] = None + tier: str + created_at: Optional[str] = None + last_used_at: Optional[str] = None + revoked_at: Optional[str] = None + owner_id: Optional[str] = None + + +class KeyAnalyticsQuota(BaseModel): + monthly_limit: int + used_this_month: int + remaining: int + percent_used: float + + +class KeyAnalyticsResponse(BaseModel): + """``GET /api/admin/keys/{key_id}/analytics``.""" + + key: KeyAnalyticsKeyInfo + owner: Optional[UserRecord] = None + window_hours: int + dashboard: DashboardForKeyResult + window_summary: KeyUsageSummary + peak_hours: List[PeakHourEntry] + quota: KeyAnalyticsQuota + + +class EndpointStatsEntry(BaseModel): + """Per-endpoint slice of ``RequestTracker.get_endpoint_stats()``.""" + + total_requests: int + total_errors: int + error_rate: float + avg_duration_ms: float + min_duration_ms: float + max_duration_ms: float + + +class PerformanceResponse(BaseModel): + """``GET /api/admin/performance``. + + ``endpoints`` is keyed by endpoint identifier (dynamic — one entry per + endpoint actually hit since process start), so it is a plain mapping + rather than a fixed set of fields. + """ + + summary: RequestTrackerSummary + endpoints: Dict[str, EndpointStatsEntry] + + +# --------------------------------------------------------------------------- +# V2 cache admin (admin_cache.py) +# --------------------------------------------------------------------------- + +class RawCacheSessionEntry(BaseModel): + """One session's raw-stream summary — ``raw_stream_cache.list_raw_stream_sessions``.""" + + session_key: str + year: Optional[int] = None + round_nr: Optional[int] = None + session: Optional[str] = None + streams: List[str] = Field(description="Distinct stream names cached for this session (e.g. CarData.z).") + bytes: int + schema_drift: int = Field(description="Count of blobs written under an older SCHEMA_VERSION.") + newest: Optional[str] = None + stream_count: int + + +class RawCacheInfo(BaseModel): + sessions: List[RawCacheSessionEntry] + session_count: int + files: int + bytes: int + schema_version: int + schema_drift: int + + +class BundleCacheEntry(BaseModel): + """One derived-bundle summary — ``session_cache.list_bundles``.""" + + doc_id: str + year: Optional[int] = None + round_nr: Optional[int] = None + session: Optional[str] = None + event_name: Optional[str] = None + keys: List[str] = Field(description="Top-level keys stored in this session's derived bundle.") + schema_version: Optional[int] = None + schema_drift: bool + created_at: Optional[str] = None + + +class BundleCacheInfo(BaseModel): + sessions: List[BundleCacheEntry] + session_count: int + total: int + schema_version: int + schema_drift: int + + +class CacheInventoryResponse(BaseModel): + """``GET /api/admin/cache/inventory`` — ``admin_views.cache_inventory``.""" + + year: Optional[int] = None + raw: RawCacheInfo + bundles: BundleCacheInfo + + +class CachePurgeRawResponse(BaseModel): + """``POST /api/admin/cache/purge/raw/{session_key}`` (destructive).""" + + session_key: str + removed: int = Field(description="Number of stream blobs deleted.") + + +class CachePurgeBundleResponse(BaseModel): + """``POST /api/admin/cache/purge/bundle/{doc_id}`` (destructive).""" + + doc_id: str + removed: bool + + +class CachePrewarmResponse(BaseModel): + """``POST /api/admin/cache/prewarm``.""" + + year: int + gp: str + session: str + prewarmed: bool + + +# --------------------------------------------------------------------------- +# Stored-data browse/delete (admin_data.py) +# --------------------------------------------------------------------------- + +class DataBrowseRow(BaseModel): + """One session's stored keys — ``MongoDBManager.summarize_stored_data``.""" + + year: int + gp_id: Optional[str] = None + event_name: Optional[str] = None + round_nr: Optional[int] = None + session_type: Optional[str] = None + data_types: List[str] = Field(description="Every stored data_type for this session, legacy keys included.") + count: int + + +class DataBrowseResponse(BaseModel): + """``GET /api/admin/data/browse`` — ``admin_views.browse_stored_data``.""" + + year: int + rows: List[DataBrowseRow] + total_sessions: int + total_data_types: int + + +class DataDeleteResponse(BaseModel): + """``DELETE /api/admin/data/{year}/{gp_id}/{session_type}/{data_type}`` (destructive). + + Removes exactly one stored ``data_type`` entry; the rest of the session + document is left untouched. Not recoverable — the payload must be + regenerated (e.g. via ``/api/admin/plots/generate?force=true``). + """ + + year: int + gp_id: str + session_type: str + data_type: str + deleted: bool + + +# --------------------------------------------------------------------------- +# Backup subsystem (backup_admin.py) +# --------------------------------------------------------------------------- + +class BackupStatusConfig(BaseModel): + schedule_utc: str + retention_daily: int + retention_weekly: int + retention_monthly: int + include_volumes: bool + bucket: Optional[str] = None + prefix: Optional[str] = None + + +class BackupStatusResponse(BaseModel): + """``GET /api/admin/backup/status``.""" + + enabled: bool + scheduler_running: bool + manual_in_progress: bool + last_run_at: Optional[str] = None + next_run_at: Optional[str] = None + last_error: Optional[str] = None + last_backup_id: Optional[str] = None + last_backup_tier: Optional[str] = None + last_backup_success: Optional[bool] = None + s3_reachable: Optional[bool] = Field( + default=None, description="null when the backup subsystem is disabled (S3 was never pinged)." + ) + config: BackupStatusConfig + + +class BackupListResponse(BaseModel): + """``GET /api/admin/backup/list``.""" + + tier: str + count: int + backup_ids: List[str] + + +class BackupArtifact(BaseModel): + """One artifact in a backup manifest — ``services.backup.manifest.Artifact``.""" + + name: str = Field(description='Logical component name, e.g. "mongo".') + s3_key: str + sha256_plaintext: str + sha256_ciphertext: str + plaintext_bytes: int + ciphertext_bytes: int + encrypted: bool + + +class BackupManifestResponse(BaseModel): + """``GET /api/admin/backup/manifest/{backup_id}`` — ``services.backup.manifest.Manifest``.""" + + backup_id: str + tier: str + started_at: str + finished_at: str + app_version: str + mongo_database: str + sqlite_path: str + artifacts: List[BackupArtifact] + success: bool + error: Optional[str] = None + encryption: str + + +class BackupRunResponse(BaseModel): + """``POST /api/admin/backup/run``.""" + + status: str + message: str + + +class BackupVerifyResponse(BaseModel): + """``POST /api/admin/backup/verify/{backup_id}``.""" + + backup_id: str + tier: str + verified: List[str] = Field(description="Component names whose ciphertext checksum matched the manifest.") + + +class BackupRestoreResponse(BaseModel): + """``POST /api/admin/backup/restore/{backup_id}`` (destructive). + + Restores components from the manifest into MongoDB/SQLite. Without both + ``?confirm=true`` and body field ``i_understand=true`` (or a throwaway + ``mongo_target_db`` drill), the handler refuses with 400 before touching + anything. + """ + + backup_id: str + tier: str + restored: List[str] = Field(description="Component names actually restored.") + skipped: List[str] = Field(description="Component names present in the manifest but not restored.") + mongo_target_db: Optional[str] = Field( + default=None, description="Set only for a drill restore into a throwaway database." + ) + + +# --------------------------------------------------------------------------- +# Storage cleanup (/api/admin/storage/*) +# --------------------------------------------------------------------------- + +class StorageScope(BaseModel): + """The filter that selects what a cleanup touches. + + Every field is optional and narrows the scope; omitting all of them means + "everything", which the purge endpoint refuses without an explicit + ``allow_full_purge``. + """ + + year: Optional[int] = Field(None, description="Season year, e.g. 2025.", examples=[2025]) + gp: Optional[str] = Field( + None, + description=( + "Grand Prix, matched loosely against every identifier a layer knows it by: " + "the Mongo `gp_id` (`2025_ITA`), the round number, and the event directory " + "name (`Italian Grand Prix`). Case, spaces and punctuation are ignored." + ), + examples=["Italian Grand Prix", "2025_ITA", "16"], + ) + session: Optional[str] = Field( + None, + description=( + "Session type. Long and short spellings are equivalent, so `R` also matches " + "the legacy `Race` directories." + ), + examples=["R", "Q", "FP1"], + ) + data_type: Optional[str] = Field( + None, + description=( + "A single stored feature key, e.g. `speed_distribution`. Scoping by " + "data_type deliberately excludes the raw-stream and bundle layers: those " + "are per-session, so deleting them would pull data out from under every " + "other feature of that session." + ), + examples=["speed_distribution"], + ) + layers: Optional[List[str]] = Field( + None, + description=( + "Which storage layers to act on. Defaults to all of: " + "`mongo`, `raw_streams`, `bundles`, `plots`, `redis`." + ), + examples=[["plots", "redis"]], + ) + + +class StorageCleanupItem(BaseModel): + """One concrete deletable thing, as it exists in storage right now.""" + + layer: str = Field(..., description="Which storage layer holds it.") + key: str = Field(..., description="Layer-native identifier used to delete it.") + label: str = Field(..., description="Human-readable description for the preview.") + bytes: int = Field(0, description="Size on disk where the layer reports one; 0 otherwise.") + detail: Dict[str, Any] = Field(default_factory=dict, description="Layer-specific fields.") + + +class StorageLayerPlan(BaseModel): + """Per-layer slice of a cleanup preview.""" + + count: int + bytes: int + items: List[StorageCleanupItem] = Field(default_factory=list) + patterns: Optional[List[str]] = Field( + None, + description="Redis only: the glob patterns that would be purged. Always under `t1api:v2:`.", + ) + + +class StoragePreviewResponse(BaseModel): + """Dry run. Enumerates exactly what a purge would delete, and deletes nothing.""" + + scope: Dict[str, Any] + unscoped: bool = Field( + ..., description="True when no filter is set, i.e. this would delete everything." + ) + layers: Dict[str, StorageLayerPlan] + total_items: int + total_bytes: int + confirm_token: str = Field( + ..., + description=( + "Fingerprint of this exact item set. Pass it back to `/purge`; the purge " + "recomputes it and refuses on a mismatch, so nothing can be deleted that " + "was not visible in this preview." + ), + ) + + +class StoragePurgeRequest(BaseModel): + """Body for a destructive purge.""" + + scope: StorageScope = Field(default_factory=StorageScope) + confirm_token: str = Field( + ..., description="The `confirm_token` from a matching `/preview` call." + ) + allow_full_purge: bool = Field( + False, + description=( + "Required to run a purge whose scope is empty (every year, GP, session and " + "data type). Without it such a request is rejected with 400." + ), + ) + + +class StorageLayerResult(BaseModel): + """What actually happened to one layer.""" + + requested: int + deleted: int + bytes: int = 0 + patterns: Optional[List[str]] = None + errors: List[str] = Field(default_factory=list) + + +class StoragePurgeResponse(BaseModel): + """Outcome of a purge. Partial failure is reported, never raised.""" + + scope: Dict[str, Any] + layers: Dict[str, StorageLayerResult] + total_deleted: int + bytes_reclaimed: int + errors: List[str] = Field(default_factory=list) + ok: bool = Field(..., description="True when every layer completed without an error.") + + +class StorageOrphanVariant(BaseModel): + path: str + name: str + files: int + bytes: int + + +class StorageOrphanGroup(BaseModel): + """Two or more directories holding the same GP under different spellings.""" + + year: int + variants: List[StorageOrphanVariant] + suggested_keep: str = Field( + ..., + description=( + "The variant holding the most files (ties broken by size). A suggestion " + "only — this endpoint never deletes, because only an operator can say " + "which spelling is canonical." + ), + ) + reclaimable_bytes: int + + +class StorageTotalsPlots(BaseModel): + files: int + bytes: int + root: str + + +class StorageTotalsRaw(BaseModel): + files: int + bytes: int + + +class StorageTotalsBundles(BaseModel): + count: int + schema_drift: int + + +class StorageTotalsResponse(BaseModel): + """Headline storage figures for the cleanup dashboard.""" + + plots: StorageTotalsPlots + raw_streams: StorageTotalsRaw + bundles: StorageTotalsBundles + orphan_plot_groups: int + orphan_reclaimable_bytes: int + + +class StorageOrphansResponse(BaseModel): + groups: List[StorageOrphanGroup] + total_groups: int + total_reclaimable_bytes: int + + +# --------------------------------------------------------------------------- +# Circuit layouts (/api/admin/circuits/*) +# --------------------------------------------------------------------------- + +class CircuitStatusRow(BaseModel): + """One scheduled event's layout coverage — ``admin_views.circuit_layout_status``.""" + + round: Optional[int] = None + grand_prix: str + circuit: str + location: str + country: str + circuit_key: Optional[int] = Field( + None, description="Livetiming's Circuit.Key. Absent when the event hasn't been listed yet." + ) + layout_present: bool + source: Optional[str] = Field( + None, description='"multiviewer" (seeded/synced), "telemetry" (derived) or "invalid".' + ) + file: Optional[str] = Field(None, description="Stored layout filename, if any.") + in_mongo: bool + + +class CircuitLayoutStatusResponse(BaseModel): + """``GET /api/admin/circuits/status`` — which circuits in a season have a + stored layout. Schedule-driven, so a brand-new circuit multiviewer hasn't + published yet shows as missing rather than silently absent. + """ + + year: int + rows: List[CircuitStatusRow] + total: int + missing: int + unknown_key: int + stored_files: int + error: Optional[str] = Field( + None, description="Set when the season schedule itself could not be loaded; rows are then empty." + ) + + +class CircuitDeriveRequest(BaseModel): + """Body for ``POST /api/admin/circuits/derive``.""" + + year: int = Field(..., ge=2018, le=2030, examples=[2026]) + gp: str = Field( + ..., + description="Grand Prix: name, round number, livetiming key, circuit or host city, e.g. 'Madrid'.", + examples=["Madrid"], + ) + session: str = Field("Q", description="Session identifier, e.g. FP1, Q, SQ, S, R.", examples=["Q"]) + driver: Optional[str] = Field( + None, description="TLA; default = the session's fastest lap.", examples=["VER"] + ) + rotation: Optional[float] = Field( + None, ge=0, lt=360, description="Override auto-detected rotation, in degrees." + ) + min_turn_deg: float = Field( + 25.0, ge=5, le=90, description="Minimum total heading change for a corner to be kept." + ) + dry_run: bool = Field(True, description="Preview only; nothing is written.") + overwrite: bool = Field(False, description="Replace an existing stored layout for this circuit/year.") + + +class CircuitDeriveCorner(BaseModel): + """One detected corner — the ``corners`` entries of ``derive_and_store``'s stats.""" + + number: int + length_m: float = Field(description="Arc-length position of the apex along the lap, in metres.") + turn_deg: float = Field(description="Total heading change through the corner, in degrees.") + direction: str = Field(description='"left" or "right".') + min_speed_kmh: Optional[float] = Field( + None, description="Set only when CarData speed was available and the apex was snapped to it." + ) + + +class CircuitDeriveStats(BaseModel): + """Diagnostics from one ``derive_and_store`` call, minus the ``corners`` list + (returned separately at the top level of :class:`CircuitDeriveResponse`).""" + + lap_length_m: float + n_points: int + n_corners: int + closure_gap_m: float = Field(description="Start/end gap of the traced lap, in metres.") + samples: int = Field(description="Deduplicated position samples used to build the outline.") + speed_available: bool + snapped: int = Field(description="Corners whose apex was moved onto a local speed minimum.") + rotation: float + auto_rotation: bool = Field(description="True unless the caller passed an explicit rotation.") + source_driver: str = Field(description="TLA of the lap the outline was traced from.") + source_lap_time_s: float + candidates_tried: int = Field(description="Laps attempted before one produced a closed outline.") + rejected: List[str] = Field(description="One diagnostic string per rejected candidate lap.") + + +class CircuitDeriveResponse(BaseModel): + """``POST /api/admin/circuits/derive``. + + ``layout`` (the full ``CircuitLayout``) is deliberately not modelled here — + the router strips it from the response to keep this payload reviewable. + """ + + year: int + circuit_id: str + circuit_name: str + session: str = Field(description='e.g. "2026/Spanish Grand Prix/Q".') + dry_run: bool + written: bool + path: Optional[str] = Field(None, description="Set only when written=true.") + existing_source: Optional[str] = Field( + None, description="Source of a previously stored layout for this circuit/year, if any." + ) + rotation: float + stats: CircuitDeriveStats + corners: List[CircuitDeriveCorner] diff --git a/src/api/schemas/analysis.py b/src/api/schemas/analysis.py new file mode 100644 index 0000000..bf98827 --- /dev/null +++ b/src/api/schemas/analysis.py @@ -0,0 +1,726 @@ +"""Documentation-only response schemas for the V2 analysis router. + +These models exist purely so Swagger can show a real shape for every +``/api/v2/...`` JSON endpoint. Per ``src/api/routers/analysis_v2.py`` they are +attached via ``responses={200: {"model": ...}}`` — **never** via +``response_model=`` — so they cannot filter or otherwise alter the live +payload. Each model is derived from the actual ``return`` statements of the +service function it documents (see the module docstring on each field's +origin below); nothing here is guessed. + +A few payloads are genuinely dynamic (the ``/dashboard`` aggregate, the raw +weather sample embedded in ``lap-all-data``, and the ``circuit`` block shared +by ``track-map`` / ``corner-duel``). Those use a permissive shape +(``model_config = {"extra": "allow"}`` or ``Dict[str, Any]``) rather than a +guessed fixed schema — see the docstring on each for why. +""" +from __future__ import annotations + +from typing import Any, Dict, List, Optional + +from pydantic import BaseModel, Field, RootModel + + +# --------------------------------------------------------------------------- +# Shared building blocks +# --------------------------------------------------------------------------- + +class SessionInfo(BaseModel): + """Session identity echoed back inside several payloads.""" + + year: int + event_name: str + session_name: str + + +class TrackStatusPeriod(BaseModel): + """One contiguous track-status window (GREEN/YELLOW/SC/VSC/RED). + + ``end_lap``/``end_time_s`` are ``None`` when the status was still active + when the session ended. + """ + + status: str + start_lap: Optional[int] = None + end_lap: Optional[int] = None + start_time_s: Optional[float] = None + end_time_s: Optional[float] = None + + +class LapGapPoint(BaseModel): + """One lap's gap-to-leader sample. ``gap_s`` is ``None`` on a red-flag lap + (the plotted line breaks there rather than drawing a false segment).""" + + lap: int + gap_s: Optional[float] = None + + +# --------------------------------------------------------------------------- +# Dashboard (latest session, all session types) +# --------------------------------------------------------------------------- + +class DashboardResponse(BaseModel): + """Latest finished session, routed by session category. + + Genuinely dynamic: the extra keys present depend on ``session_type`` + (``practice``/``qualifying``/``sprint_qualifying``/``sprint``/``race`` — + see ``src/services/orchestrator.py``), and each data block + (``top_speed``, ``throttle_comparison``, and ``qualifying_results`` for + qualifying sessions) is *either* that feature's normal payload *or* + ``{"error": ""}`` if that block failed to generate. A fixed + schema would misrepresent this, so only the four keys common to every + session type are declared and the rest is left permissive. + """ + + session_type: str + year: int + round: int + session_name: str + + model_config = {"extra": "allow"} + + +# --------------------------------------------------------------------------- +# Simple Analysis +# --------------------------------------------------------------------------- + +class TopSpeedEntry(BaseModel): + """One team's top speed for a session — from ``top_speed.py``. + + Shared shape for both the CarData-telemetry source and the official + Speed Trap source; only the underlying data source differs. + """ + + Team: str + top_speed_kmh: float = Field(alias="Top Speed (km/h)") + Color: str = Field(description="Team hex color") + + model_config = {"populate_by_name": True} + + +TopSpeedTelemetryDataResponse = RootModel[List[TopSpeedEntry]] +TopSpeedSpeedTrapDataResponse = RootModel[List[TopSpeedEntry]] + + +class ThrottleComparisonEntry(BaseModel): + """One driver's average throttle over their fastest lap — from ``throttle_comparison.py``.""" + + Driver: str + avg_throttle_pct: float = Field(alias="Average Throttle (%)") + Color: str = Field(description="Driver hex color") + + model_config = {"populate_by_name": True} + + +ThrottleComparisonDataResponse = RootModel[List[ThrottleComparisonEntry]] + + +class SpeedDistributionPoint(BaseModel): + """One telemetry sample along a driver's fastest lap — from ``speed_distribution.py``.""" + + time_s: float = Field(alias="Time (s)") + speed_kmh: float = Field(alias="Speed (km/h)") + Driver: str + Color: str + + model_config = {"populate_by_name": True} + + +SpeedDistributionDataResponse = RootModel[List[SpeedDistributionPoint]] + + +class LapTimesDistributionEntry(BaseModel): + """One completed lap for a driver — from ``laptimes_distribution.py``.""" + + driver: str + lap_number: int + lap_times_formatted: str + lap_times_seconds: float + compound: str = Field(description="Tyre compound active on this lap, or UNKNOWN") + + +LaptimesDistributionDataResponse = RootModel[List[LapTimesDistributionEntry]] + + +# --------------------------------------------------------------------------- +# Qualifying +# --------------------------------------------------------------------------- + +class QualifyingResultEntry(BaseModel): + """One driver's qualifying classification row — from ``qualifying_results.py``.""" + + Driver: str + Team: str + LapTime: str = Field(description="Formatted lap time, e.g. '1:32.456'") + LapTimeDelta: float = Field(description="Gap to pole in seconds; 0.0 for the pole-sitter") + Color: str + + +QualifyingResultsDataResponse = RootModel[List[QualifyingResultEntry]] + + +class ThrottleBrakeTelemetryPoint(BaseModel): + """One telemetry sample from ``throttle_brake_comparison.py``.""" + + distance: float + speed: float + throttle: float + brake: float + lap_time: float = Field(description="Elapsed time since the start of the lap, in seconds") + driver: str + + +class ThrottleBrakeComparisonResponse(BaseModel): + """Speed/Throttle/Brake vs distance for two drivers' fastest laps.""" + + driver1: str + driver2: str + driver1_color: str + driver2_color: str + telemetry: List[ThrottleBrakeTelemetryPoint] = Field( + description="Interleaved samples for both drivers; filter by `driver` to split" + ) + + +class TrackComparisonTelemetryPoint(BaseModel): + """One telemetry sample from ``track_comparison.py``, tagged with its minisector winner.""" + + x: float + y: float + distance: float + speed: float + driver: str + minisector: int + fastest_driver: str = Field(description="TLA of whichever driver was fastest through this minisector") + fastest_driver_int: int = Field(description="1 or 2 (driver1/driver2 index), 0 if undetermined") + + +class TrackComparisonResponse(BaseModel): + """Track map data with per-minisector fastest-driver assignment for two drivers.""" + + driver1: str + driver2: str + driver1_color: str + driver2_color: str + telemetry: List[TrackComparisonTelemetryPoint] + session_info: SessionInfo + + +class LapTimeAnalysisTelemetryPoint(BaseModel): + """One telemetry sample from ``lap_time_analysis.py``.""" + + distance: float + speed: float + throttle: float + lap_time: float = Field(description="Elapsed time since the start of the lap, in seconds") + driver: str + + +class LapTimeAnalysisDeltaPoint(BaseModel): + distance: float + delta: float = Field(description="Gap of driver2 vs driver1 at this distance; positive = driver2 behind") + + +class LapTimeAnalysisResponse(BaseModel): + """Speed/Throttle telemetry plus a delta-time series for two drivers' fastest laps.""" + + driver1: str + driver2: str + driver1_color: str + driver2_color: str + driver1_laptime: float = Field(description="driver1's fastest lap time in seconds") + driver2_laptime: float = Field(description="driver2's fastest lap time in seconds") + reference_driver: str = Field(description="Always driver1 — the distance/delta reference lap") + telemetry: List[LapTimeAnalysisTelemetryPoint] + delta: List[LapTimeAnalysisDeltaPoint] + session_info: SessionInfo + + +class TheoreticalBestEntry(BaseModel): + """Theoretical vs actual best lap for one driver — from ``theoretical_best.py``. + + ``theoretical_s`` is the sum of the driver's best individual sector times; + ``delta_s`` is clamped at 0.0 (sector-time rounding noise can otherwise put + the sum a few ms above the actual lap). + """ + + driver: str + team: str + color: str + theoretical_s: float + actual_s: float + delta_s: float = Field(description="Time left on the table: actual_s - theoretical_s, clamped >= 0") + + +TheoreticalBestDataResponse = RootModel[List[TheoreticalBestEntry]] + + +# --------------------------------------------------------------------------- +# Pace Analysis +# --------------------------------------------------------------------------- + +class DriverPaceEntry(BaseModel): + """One driver's lap-time distribution (107%-quicklap filtered) — from ``driver_pace.py``.""" + + driver: str + team: str + color: str + lap_times_seconds: List[float] = Field(description="Every filtered clean lap time, in seconds") + lap_count: int + min: float + q1: float + median: float + q3: float + max: float + + +DriverPaceDataResponse = RootModel[List[DriverPaceEntry]] + + +class TeamsPaceEntry(BaseModel): + """One team's lap-time distribution (both cars, 107%-quicklap filtered) — from ``teams_pace.py``.""" + + team: str + color: str + lap_times_seconds: List[float] + lap_count: int + min: float + q1: float + median: float + q3: float + max: float + + +TeamsPaceDataResponse = RootModel[List[TeamsPaceEntry]] + + +# --------------------------------------------------------------------------- +# Race Analysis +# --------------------------------------------------------------------------- + +class TyreStintUsageEntry(BaseModel): + """One stint for one driver — from ``tyre_stint_usage.py``.""" + + driver: str + team: str + position: int = Field(description="Finishing position; 99 when unknown") + stint_number: int + compound: str + start_lap: int + end_lap: int + lap_count: int + tyre_life_end: Optional[int] = Field(default=None, description="Tyre age (laps) at the end of the stint") + color: str + + +TyreStintUsageDataResponse = RootModel[List[TyreStintUsageEntry]] + + +class LapPositionPoint(BaseModel): + """One lap's race position. ``lap`` 0 = starting grid.""" + + lap: int + position: int + + +class PositionChangesEntry(BaseModel): + """One driver's position trace across the race — from ``position_changes.py``. Race/Sprint only.""" + + driver: str + team: str + color: str + start_pos: int + end_pos: int + positions: List[LapPositionPoint] + + +PositionChangesDataResponse = RootModel[List[PositionChangesEntry]] + + +class RaceGapsEntry(BaseModel): + """One driver's per-lap gap series — from ``race_gaps.py``. Race/Sprint only. + + ``reference=leader``: gap to the per-lap leader (>= 0, leader = 0). + ``reference=average``: signed gap to a constant-pace reference (positive = + ahead of reference pace). + """ + + driver: str + team: str + color: str + laps: List[LapGapPoint] + + +RaceGapsDataResponse = RootModel[List[RaceGapsEntry]] + + +class TyreDegradationPoint(BaseModel): + driver: str + tyre_age: int = Field(description="Laps on this set of tyres") + lap_time_s: float + fuel_corrected_s: Optional[float] = Field( + default=None, description="Only present when fuel_corrected=true was requested" + ) + + +class TyreDegradationCompound(BaseModel): + """One compound's degradation points and linear fit — from ``tyre_degradation.py``. Race/Sprint only.""" + + compound: str + color: str + points: List[TyreDegradationPoint] + deg_rate_s_per_lap: Optional[float] = Field( + default=None, description="Linear-fit slope (s/lap); None if too few clean laps to fit" + ) + r_squared: Optional[float] = None + n_points: int + + +TyreDegradationDataResponse = RootModel[List[TyreDegradationCompound]] + + +class PitStopEntry(BaseModel): + """One pit stop — from ``pit_strategy.py``.""" + + driver: str + team: str + lap: int + stop_n: int + pit_lane_time_s: Optional[float] = None + compound_in: Optional[str] = Field(default=None, description="Tyre removed") + compound_out: Optional[str] = Field(default=None, description="Tyre fitted") + under_sc: bool = Field(description="Whether the stop happened under Safety Car / VSC") + drive_through: bool = Field(description="Pit-lane increment with no compound change (drive-through/red-flag)") + + +class UndercutEntry(BaseModel): + """One detected undercut attempt — from ``pit_strategy.py``. + + ``gain_s`` is signed so positive means the attacker gained (closed the gap + or jumped ahead); ``worked`` means the attacker ends up ahead after both + pit cycles complete. + """ + + attacker: str + defender: str + lap: int = Field(description="Lap the attacker pitted on") + gap_before_s: float + gap_after_s: float + gain_s: float + worked: bool + + +class FastestStop(BaseModel): + driver: str + lap: int + pit_lane_time_s: float + + +class TeamAvgStop(BaseModel): + team: str + avg_pit_lane_time_s: float + n_stops: int + + +class PitStrategySummary(BaseModel): + fastest_stop: Optional[FastestStop] = None + avg_stop_by_team: List[TeamAvgStop] + + +class FreeChangeEntry(BaseModel): + """A compound change not backed by a measured pit stop (e.g. a red-flag tyre change).""" + + driver: str + lap: int + compound_in: str + compound_out: str + + +class PitStrategyResponse(BaseModel): + """Full pit strategy payload — stops, undercuts, summary, free changes. Race/Sprint only.""" + + stops: List[PitStopEntry] + undercuts: List[UndercutEntry] + summary: PitStrategySummary + free_changes: List[FreeChangeEntry] + + +class WeatherSample(BaseModel): + """One WeatherData sample — from ``session_weather.py``. + + ``lap`` is only populated for Race/Sprint sessions (a single well-ordered + lap counter); it is ``null`` for Q/SQ/FP sessions where each car runs its + own lap count. + """ + + time_s: float + lap: Optional[int] = None + air_temp: Optional[float] = None + track_temp: Optional[float] = None + humidity: Optional[float] = None + rainfall: int = Field(description="1 if raining, else 0") + wind_speed: Optional[float] = None + wind_dir: Optional[float] = None + + +class RaceControlMessageEntry(BaseModel): + time_s: Optional[float] = None + lap: Optional[int] = None + category: Optional[str] = None + flag: Optional[str] = None + message: str + + +class SessionWeatherResponse(BaseModel): + """Weather series + track-status periods + race-control messages. Any session type.""" + + weather: List[WeatherSample] + track_status_periods: List[TrackStatusPeriod] + race_control: List[RaceControlMessageEntry] + + +class RacePaceHeatmapResponse(BaseModel): + """Driver x lap grid of delta to field median lap time — from ``race_pace_heatmap.py``. Race/Sprint only.""" + + drivers: List[str] = Field(description="TLAs in finish order (row order, winner first)") + laps: List[int] = Field(description="Sorted lap numbers forming the grid columns") + grid: Dict[str, List[Optional[float]]] = Field( + description="{tla: [delta_s_or_null, ...]} aligned to `laps`; null marks a masked/missing cell" + ) + pit_laps: Dict[str, List[int]] = Field(description="{tla: [lap, ...]} laps where the driver pitted") + sc_laps: List[int] = Field(description="Laps masked out for SC/VSC/RED track status") + + +class RunningBestPoint(BaseModel): + minute: float = Field(description="Minutes since the first recorded lap timestamp") + best_s: float = Field(description="Running-minimum lap time so far, in seconds") + + +class TrackTempPoint(BaseModel): + minute: float + track_temp: float + + +class TrackEvolutionResponse(BaseModel): + """Session-best lap time evolution vs track temperature. Practice/Qualifying only.""" + + overall: List[RunningBestPoint] = Field(description="Whole-session running-best step series") + drivers: Dict[str, List[RunningBestPoint]] = Field( + description="Per-driver running-best series for the plotted drivers (TLA keys)" + ) + weather: List[TrackTempPoint] = Field(description="Empty if the WeatherData stream is unavailable") + + +class RaceStoryPitStop(BaseModel): + lap: int + compound: Optional[str] = Field(default=None, description="Compound fitted at this stop") + + +class RaceStoryDriverEntry(BaseModel): + driver: str + team: str + color: str + finish_rank: int + laps: List[LapGapPoint] = Field(description="Gap-to-leader series, same convention as race-gaps (leader mode)") + pit_stops: List[RaceStoryPitStop] + last_lap: Optional[int] = None + + +class KeyMoment(BaseModel): + """One numbered, captioned event on the race-story timeline.""" + + lap: Optional[int] = None + kind: str = Field(description="'lead_change', 'retirement', or 'penalty'") + caption: str + n: int = Field(description="1-based display number matching the plot's annotation chip") + + +class RaceStoryResponse(BaseModel): + """Gap-to-leader traces, pit stops, and key moments for the top finishers. Race/Sprint only.""" + + drivers: List[RaceStoryDriverEntry] = Field(description="Top ~10 finishers") + key_moments: List[KeyMoment] + track_status_periods: List[TrackStatusPeriod] + + +# --------------------------------------------------------------------------- +# Telemetry +# --------------------------------------------------------------------------- + +class TrackMapPoint(BaseModel): + distance: float + x: float + y: float + speed: Optional[float] = None + gear: Optional[int] = None + brake: Optional[float] = None + + +class BrakingSegment(BaseModel): + """One contiguous braking zone (positional indices into `points`).""" + + start_idx: int + end_idx: int + start_distance: float + end_distance: float + + +class TrackMapCallout(BaseModel): + distance: float + speed: float + x: Optional[float] = None + y: Optional[float] = None + + +class TrackMapCallouts(BaseModel): + top_speed: Optional[TrackMapCallout] = None + slowest_corner: Optional[TrackMapCallout] = None + + +class TrackMapResponse(BaseModel): + """Fastest-lap telemetry track map for one driver — from ``telemetry_track_map.py``. Any session. + + ``circuit`` is the full ``CircuitLayout`` lookup (rotation, corners, track + outline) when a matching circuit JSON was found, else ``null``; its shape + comes from a separately-owned circuit-data file and is intentionally left + permissive here rather than modeled field-by-field. + """ + + driver: str + color_by: str = Field(description="'speed' or 'gear'") + lap_time_s: float + points: List[TrackMapPoint] + braking_segments: List[BrakingSegment] + callouts: TrackMapCallouts + circuit: Optional[Dict[str, Any]] = None + session_info: SessionInfo + + +class LapAllDataDriver(BaseModel): + tla: str + car_number: str + name: str + team: str + color: str + racing_number: str + + +class LapAllDataLap(BaseModel): + number: int + lap_time_s: float + timestamp_s: float + pit_in: bool + pit_out: bool + position: Optional[int] = None + + +class LapAllDataTyre(BaseModel): + compound: Optional[str] = None + stint_number: Optional[int] = None + tyre_life_end: Optional[int] = None + start_lap: Optional[int] = None + end_lap: Optional[int] = None + + +class LapAllDataSectors(BaseModel): + s1: Optional[float] = None + s2: Optional[float] = None + s3: Optional[float] = None + + +class LapAllDataTelemetryPoint(BaseModel): + time: float + distance: float + speed: Optional[float] = None + rpm: Optional[float] = None + throttle: Optional[float] = None + brake: Optional[float] = None + gear: Optional[int] = None + drs: Optional[int] = None + x: Optional[float] = None + y: Optional[float] = None + z: Optional[float] = None + + +class LapAllDataTrackStatus(BaseModel): + status: Optional[str] = None + start_lap: Optional[int] = None + end_lap: Optional[int] = None + + +class LapAllDataResponse(BaseModel): + """Everything for one driver's single lap — from ``lap_all_data.py``. Any session. + + ``weather`` is the raw nearest ``WeatherData`` stream entry (untouched + upstream keys such as ``AirTemp``/``TrackTemp``/``Humidity`` as strings), + unlike the normalized ``WeatherSample`` used by ``session-weather-data``; + it is left as a permissive object rather than modeled field-by-field, and + is ``null`` if no weather sample was available. + """ + + driver: LapAllDataDriver + lap: LapAllDataLap + tyre: LapAllDataTyre + sectors: LapAllDataSectors + weather: Optional[Dict[str, Any]] = None + track_status: List[LapAllDataTrackStatus] + telemetry: List[LapAllDataTelemetryPoint] + session_info: SessionInfo + + +class CornerDuelDeltaPoint(BaseModel): + distance: float + delta_s: float = Field(description="t2(d) - t1(d); positive = driver2 behind driver1 at this point") + + +class CornerDuelSpeedPoint(BaseModel): + dist_m: float + speed_kmh: float + + +class CornerDuelCorner(BaseModel): + """One corner's comparative data — from ``corner_duel.py``.""" + + number: int = Field(description="Circuit corner number when matched, else sequential track order") + apex_distance_m: float + min_speed_kmh: Dict[str, Optional[float]] = Field(description="{driver_tla: min_speed_kmh}") + braking_point_m: Dict[str, Optional[float]] = Field( + description="{driver_tla: braking_point_m}; currently only driver1 is populated" + ) + delta_gain_s: Optional[float] = Field( + default=None, description="Positive = driver2 gained through this corner relative to driver1" + ) + beneficiary: Optional[str] = Field(default=None, description="TLA of whoever gained, or null if undetermined") + + +class CornerDuelResponse(BaseModel): + """Corner-by-corner duel: delta series, apex speeds, braking points, delta gain. Any session.""" + + driver1: str + driver2: str + driver1_color: str + driver2_color: str + same_team: bool + delta_series: List[CornerDuelDeltaPoint] + speed_series: Dict[str, List[CornerDuelSpeedPoint]] = Field(description="{driver_tla: [speed samples]}") + corners: List[CornerDuelCorner] + session_info: SessionInfo + + +class DriverRadarEntry(BaseModel): + tla: str + team: str + color: str + values: List[Optional[float]] = Field( + description="0-100 scaled score per axis, aligned to the response's `axes` list; null = missing spoke" + ) + raw: Dict[str, Optional[float]] = Field(description="Unscaled metric value per axis key") + + +class DriverRadarResponse(BaseModel): + """Single-session driver performance radar — from ``driver_radar.py``. Any session.""" + + scope: str = Field(description="'session' for this endpoint") + axes: List[str] = Field(description="Axis display names, in the order `values`/`raw` are aligned to") + drivers: List[DriverRadarEntry] + hero: bool = Field(description="True when exactly one driver is charted") diff --git a/src/api/schemas/batch.py b/src/api/schemas/batch.py new file mode 100644 index 0000000..8edb0c0 --- /dev/null +++ b/src/api/schemas/batch.py @@ -0,0 +1,72 @@ +"""Request/response schemas for the V2 batch endpoint (documentation only). + +Per the project's OpenAPI conventions (see CLAUDE.md), these are attached via +``responses={200: {"model": ...}}`` for Swagger only -- never via +``response_model=``, which would filter the hand-built dict actually returned +by the endpoint and silently drop fields from production traffic. +""" +from __future__ import annotations + +from typing import Any, List, Optional, Union + +from pydantic import BaseModel, Field + + +class BatchFeatureRequest(BaseModel): + """One requested feature within a batch. + + Only the fields the feature's ``kind`` needs are read (see + ``registry.KIND_*``): a singleton feature needs none of these, a + per-driver feature needs ``driver``, a per-pair feature needs ``driver1`` + / ``driver2``, and a per-driver-lap feature needs ``driver`` + ``lap``. + """ + + key: str = Field( + ..., + description="Feature key from the V2 registry catalog (registry.FEATURE_CATALOG / " + "GET /api/admin/plots/catalog).", + ) + driver: Optional[str] = Field( + None, description="Driver TLA, for per-driver features (e.g. VER)." + ) + driver1: Optional[str] = Field( + None, description="First driver TLA, for per-pair features." + ) + driver2: Optional[str] = Field( + None, description="Second driver TLA, for per-pair features." + ) + lap: Optional[int] = Field( + None, ge=1, description="Lap number, for per-driver-lap features." + ) + + +class BatchRequestBody(BaseModel): + """Request body for ``POST /api/v2/batch``.""" + + year: int = Field(2025, ge=2018, le=2030, description="Season year.") + gp: Union[int, str] = Field(1, description="Round number, Event Key, or Official Name.") + session: str = Field("Q", description="Session identifier, e.g. FP1, Q, SQ, S, R.") + features: List[BatchFeatureRequest] = Field( + default_factory=list, + description="Features to fetch for this session. The endpoint caps how many " + "may be requested at once and returns 400 past that cap.", + ) + + +class BatchFeatureResult(BaseModel): + """One feature's outcome. ``data`` is set on success, ``error`` on failure -- + a single failing feature does not fail the whole batch.""" + + key: str = Field(..., description="Echoes the requested feature key.") + status: str = Field(..., description="'ok' or 'error'.") + data: Optional[Any] = Field(None, description="The feature's JSON payload, when status is 'ok'.") + error: Optional[str] = Field(None, description="Failure detail, when status is 'error'.") + + +class BatchResponse(BaseModel): + """Response body for ``POST /api/v2/batch``.""" + + year: int + gp: Union[int, str] + session: str = Field(..., description="Normalized session abbreviation (e.g. 'Q', 'R').") + results: List[BatchFeatureResult] diff --git a/src/api/schemas/common.py b/src/api/schemas/common.py new file mode 100644 index 0000000..cced613 --- /dev/null +++ b/src/api/schemas/common.py @@ -0,0 +1,121 @@ +"""Shared response/error contracts for the public API. + +Before this module the API emitted **six** mutually incompatible error shapes +(five from the handlers in ``src/api/app.py`` plus an ``ErrorResponse`` in +``health.py`` that matched none of them and was referenced nowhere). Clients +therefore could not write a single error parser. + +These models mirror *exactly* what the handlers in ``app.py`` actually return — +they are documentation of real behaviour, not an aspiration. If you change a +handler, change the matching model here. + +``COMMON_ERROR_RESPONSES`` is meant to be spread into a route's ``responses=`` +so Swagger documents the failure modes instead of showing only ``200``/``422``: + + @router.get("/x", responses={**COMMON_ERROR_RESPONSES, **not_found()}) +""" +from __future__ import annotations + +from typing import Any, Dict, List, Optional + +from pydantic import BaseModel, Field + + +class ErrorEnvelope(BaseModel): + """The default error body (generic handler, HTTPException, ValueError). + + Emitted by ``app.py`` for 400/401/403/404/409/422/500. + """ + + detail: str = Field(description="Human-readable description of the failure.") + request_id: str = Field(description="Correlates this response with server logs.") + timestamp: str = Field(description="UTC ISO-8601 timestamp of the failure.") + + model_config = { + "json_schema_extra": { + "example": { + "detail": "Invalid API key", + "request_id": "3f2a9c14", + "timestamp": "2026-09-02T10:15:30.123456+00:00", + } + } + } + + +class SessionNotFoundEnvelope(BaseModel): + """404 raised when the schedule says the session does not exist.""" + + error: str = Field(default="session_not_found") + detail: str + year: Optional[int] = None + gp: Optional[Any] = None + session: Optional[str] = None + valid_rounds: Optional[List[int]] = Field( + default=None, description="Rounds that do exist for this season." + ) + suggestions: Optional[List[str]] = Field( + default=None, description="Near-miss identifiers, when the input looks like a typo." + ) + request_id: str + timestamp: str + + +class DataNotAvailableEnvelope(BaseModel): + """503 — the session exists but no source can supply its data yet. + + Retryable: the session may simply not have been published upstream. + """ + + error: str = Field(default="data_not_available") + detail: str + year: Optional[int] = None + gp: Optional[Any] = None + session: Optional[str] = None + sources_tried: Optional[List[str]] = None + retry_after_seconds: int = 300 + request_id: str + timestamp: str + + +class UpstreamUnavailableEnvelope(BaseModel): + """503 — an upstream dependency (livetiming, FastF1) is down.""" + + error: str = Field(default="upstream_unavailable") + detail: str + source: Optional[str] = None + retry_after_seconds: int = 60 + request_id: str + timestamp: str + + +def _resp(model: type[BaseModel], description: str) -> Dict[str, Any]: + return {"model": model, "description": description} + + +#: Failure modes essentially every authenticated endpoint can produce. +COMMON_ERROR_RESPONSES: Dict[int | str, Dict[str, Any]] = { + 401: _resp(ErrorEnvelope, "API key missing."), + 403: _resp(ErrorEnvelope, "API key invalid, or insufficient privileges."), + 429: _resp(ErrorEnvelope, "Rate limit exceeded for the caller's tier."), + 500: _resp(ErrorEnvelope, "Unhandled server error."), +} + + +def session_error_responses() -> Dict[int | str, Dict[str, Any]]: + """Extra failure modes for endpoints addressed by (year, gp, session).""" + return { + 400: _resp(ErrorEnvelope, "Malformed parameter."), + 404: _resp(SessionNotFoundEnvelope, "No such session in the schedule."), + 503: _resp( + DataNotAvailableEnvelope, + "Session data not yet available upstream, or an upstream source is down. " + "Honour the `Retry-After` header.", + ), + } + + +#: Convenience: the full set for a session-addressed analysis endpoint. +ANALYSIS_ERROR_RESPONSES: Dict[int | str, Dict[str, Any]] = { + **COMMON_ERROR_RESPONSES, + **session_error_responses(), +} diff --git a/src/api/schemas/discovery.py b/src/api/schemas/discovery.py new file mode 100644 index 0000000..c96fee9 --- /dev/null +++ b/src/api/schemas/discovery.py @@ -0,0 +1,77 @@ +"""Documentation-only response schemas for the V2 discovery endpoints. + +Attached via ``responses={200: {"model": ...}}`` in ``discovery_v2.py`` -- +**never** via ``response_model=`` -- so they document the shape without +filtering the live payload. See ``src/services/analysis/v2/registry.py`` +(``FeatureEntry.as_dict()``) and ``src/workers/plot_inventory.py`` +(``compute_inventory``) for the data these mirror. +""" +from __future__ import annotations + +from typing import Any, List, Optional + +from pydantic import BaseModel, Field + + +class FeatureCatalogEntry(BaseModel): + """One selectable V2 feature, exactly as produced by ``FeatureEntry.as_dict()``.""" + + key: str = Field(description="Stable selection slug (e.g. a data_type, or a parameterized feature name).") + label: str = Field(description="Human-readable name.") + kind: str = Field( + description="One of: singleton, per_driver, per_pair, per_driver_lap, season, career." + ) + group: str = Field(description="UI section heading, e.g. 'Field-wide' or 'Per driver'.") + applies_to: List[str] = Field( + description="Session abbreviations this feature applies to. Empty means every session type." + ) + cost: str = Field(description="Relative generation cost: light | heavy | extreme.") + session_scoped: bool = Field( + description="False for season/career-scope features, which are not tied to one session." + ) + + +class FeatureGroupSummary(BaseModel): + """Count of catalog entries in one ``group``, for a quick overview.""" + + group: str + count: int + + +class FeatureCatalogResponse(BaseModel): + """Response for ``GET /api/v2/features``.""" + + features: List[FeatureCatalogEntry] + count: int = Field(description="Number of entries in `features` after any filtering.") + groups: List[FeatureGroupSummary] = Field( + description="Per-group counts of the (possibly filtered) `features` list, sorted by group name." + ) + + +class SessionFeatureAvailability(BaseModel): + """Whether one singleton feature's data is already stored for a session.""" + + data_type: str = Field(description="The MongoDB data_type key this feature is stored under.") + label: str + available: bool + + +class SessionAvailabilityResponse(BaseModel): + """Response for ``GET /api/v2/sessions/{year}/{gp}/{session}/availability``.""" + + year: int + gp: Any = Field(description="The resolved event name.") + round_nr: Optional[int] = None + session: str = Field(description="Normalized session abbreviation, e.g. Q, R, FP1.") + available: List[str] = Field(description="Singleton data_type keys already stored for this session.") + missing: List[str] = Field(description="Singleton data_type keys not yet generated for this session.") + features: List[SessionFeatureAvailability] = Field( + description="Every expected singleton feature for this session type, with its availability." + ) + drivers: Optional[List[str]] = Field( + default=None, + description=( + "Participating driver TLAs, only when `include_drivers=true` was requested. " + "`null` otherwise." + ), + ) diff --git a/src/api/schemas/legacy_v1.py b/src/api/schemas/legacy_v1.py new file mode 100644 index 0000000..a286b84 --- /dev/null +++ b/src/api/schemas/legacy_v1.py @@ -0,0 +1,401 @@ +"""Documentation-only response schemas for the deprecated V1 (FastF1-backed) routers. + +Per ``src/api/routers/analysis_v1.py`` / ``seasonal_v1.py`` these models are attached via +``responses={200: {"model": ...}}`` — **never** via ``response_model=`` — so they cannot +filter or otherwise alter the live payload (see the module docstring on +``src/api/schemas/common.py`` for why that distinction matters). Each model is derived from +the actual ``return`` statements of the ``src/services/analysis/v1/*`` function it +documents; nothing here is guessed, and V1 shapes are **not** assumed to match their V2 +counterparts even when the two features carry the same name (e.g. V1 qualifying results +include a ``Team`` column V2 does not; V1's lap-times-distribution record spells the lap +number field ``lap_numbers``, singular value, where V2 spells it ``lap_number``). + +A few payloads are genuinely dynamic (the ``/dashboard`` aggregate mirrors its V2 sibling's +per-session-type extra keys; the Mongo-backed season summary document has no fixed schema +in the code that writes it). Those use a permissive shape (``model_config = {"extra": +"allow"}``) rather than a guessed fixed schema — see the docstring on each for why. +""" +from __future__ import annotations + +from typing import Any, Dict, List, Optional + +from pydantic import BaseModel, Field, RootModel + + +# --------------------------------------------------------------------------- +# Dashboard / daily (Latest Session, General) +# --------------------------------------------------------------------------- + +class LegacyDashboardResponse(BaseModel): + """Latest finished session, routed by session category — from ``orchestrator.py``. + + Genuinely dynamic: the extra keys present depend on ``session_type`` + (``practice``/``qualifying``/``sprint_qualifying``/``sprint``/``race``), and each data + block (``top_speed``, ``throttle_comparison``, ``qualifying_results`` for qualifying + sessions) is *either* that feature's normal payload or ``{"error": ""}`` if + that block failed to generate. Only the four keys common to every session type are + declared; the rest is left permissive. Identical shape to the V2 ``/dashboard`` + response — see ``src/api/schemas/analysis.py:DashboardResponse``. + """ + + session_type: str + year: int + round: int + session_name: str + + model_config = {"extra": "allow"} + + +class LegacyDailyDataResponse(BaseModel): + """Random daily "featured" plot data bundle — from ``src/workers/daily.py``. + + ``top_speed`` / ``throttle_comparison`` are each that feature's normal list payload + (see :class:`LegacyTopSpeedEntry` / :class:`LegacyThrottleComparisonEntry`); left as + ``List[Dict[str, Any]]`` here since the exact record shape is documented on those + dedicated endpoints. + """ + + top_speed: List[Dict[str, Any]] + throttle_comparison: List[Dict[str, Any]] + date: str + round: int + event: str + + +class LegacyDailyStatsResponse(BaseModel): + """Session-tracker analytics for a day or in aggregate — from ``SessionTracker``. + + The tracker's ``get_daily_stats`` / ``get_total_stats`` build their result from a + SQLite aggregation whose exact column set is an internal analytics implementation + detail, not a documented contract. Left permissive rather than guessed. + """ + + model_config = {"extra": "allow"} + + +# --------------------------------------------------------------------------- +# Simple Analysis +# --------------------------------------------------------------------------- + +class LegacyTopSpeedEntry(BaseModel): + """One team's top speed for a session (CarData telemetry) — from ``top_speed.py``.""" + + Team: str + top_speed_kmh: float = Field(alias="Top Speed (km/h)") + Color: str = Field(description="Team hex color") + + model_config = {"populate_by_name": True} + + +LegacyTopSpeedDataResponse = RootModel[List[LegacyTopSpeedEntry]] + + +class LegacyThrottleComparisonEntry(BaseModel): + """One driver's average throttle over their fastest lap — from ``throttle_comparison.py``.""" + + Driver: str + avg_throttle_pct: float = Field(alias="Average Throttle (%)") + Color: str = Field(description="Driver hex color") + + model_config = {"populate_by_name": True} + + +LegacyThrottleComparisonDataResponse = RootModel[List[LegacyThrottleComparisonEntry]] + + +class LegacySpeedDistributionPoint(BaseModel): + """One telemetry sample along a driver's fastest lap — from ``speed_distribution.py``.""" + + time_s: float = Field(alias="Time (s)") + speed_kmh: float = Field(alias="Speed (km/h)") + Driver: str + Color: str + + model_config = {"populate_by_name": True} + + +LegacySpeedDistributionDataResponse = RootModel[List[LegacySpeedDistributionPoint]] + + +class LegacyLaptimesEntry(BaseModel): + """One completed lap for a driver — from ``laptimes_distribution.py``. + + Note the field is ``lap_numbers`` (plural), not ``lap_number``: the source builds a + dict of parallel lists keyed ``lap_numbers`` and converts it with + ``DataFrame.to_dict(orient='records')``, so each record still carries a single int + under that plural key. The V2 sibling (``LaptimesDistributionEntry``) spells it + ``lap_number`` — the two are not the same shape. + """ + + driver: str + lap_times_formatted: Optional[str] = Field( + default=None, description="mm:ss.sss, or null when the lap time itself was NaN." + ) + lap_times_seconds: float + lap_numbers: int = Field(description="1-based lap number; field name kept as stored (plural).") + compound: str + + +LegacyLaptimesDataResponse = RootModel[List[LegacyLaptimesEntry]] + + +# --------------------------------------------------------------------------- +# Qualifying +# --------------------------------------------------------------------------- + +class LegacyQualifyingResultEntry(BaseModel): + """One driver's qualifying classification row — from ``qualifying_results.py``. + + Unlike the V2 equivalent, V1 includes ``Team`` directly on each row. + """ + + Driver: str + Team: str + LapTime: str = Field(description="Formatted lap time, e.g. '1:23.456'; pole shows its own time.") + LapTimeDelta: float = Field(description="Gap to pole in seconds; 0.0 for the pole row.") + Color: str = Field(description="Team hex color") + + +LegacyQualifyingResultsDataResponse = RootModel[List[LegacyQualifyingResultEntry]] + + +# --------------------------------------------------------------------------- +# Driver Comparison (2 drivers) +# --------------------------------------------------------------------------- + +class LegacyTrackComparisonTelemetryPoint(BaseModel): + """One merged telemetry sample for the minisector comparison — from ``track_comparison.py``.""" + + x: float + y: float + distance: float + speed: float + driver: str + minisector: int + fastest_driver: str + fastest_driver_int: int = Field(description="1 for driver1, 2 for driver2.") + + +class LegacyTrackComparisonSessionInfo(BaseModel): + year: int + race: int = Field(description="Round number, as passed to the endpoint.") + event: str = Field(description="Session identifier, as passed to the endpoint (e.g. 'Q').") + event_name: str + session_name: str + + +class LegacyTrackComparisonResponse(BaseModel): + """Minisector track comparison for two drivers — from ``track_comparison.py``.""" + + driver1: str + driver2: str + driver1_color: str + driver2_color: str + telemetry: List[LegacyTrackComparisonTelemetryPoint] + session_info: LegacyTrackComparisonSessionInfo + + +class LegacyThrottleBrakeTelemetryPoint(BaseModel): + """One telemetry sample along a driver's fastest lap — from ``throttle_brake_comparison.py``.""" + + distance: float + speed: float + throttle: float + brake: float + lap_time: float = Field(description="Seconds elapsed since the start of the lap.") + driver: str + + +class LegacyThrottleBrakeSessionInfo(BaseModel): + year: int + race: str = Field(description="Event name (the source assigns the event name here, not the round).") + event: str = Field(description="Session identifier, as passed to the endpoint (e.g. 'Q').") + event_name: str + session_name: str + + +class LegacyThrottleBrakeComparisonResponse(BaseModel): + """Speed/throttle/brake vs distance for two drivers' fastest laps — from + ``throttle_brake_comparison.py``.""" + + driver1: str + driver2: str + driver1_color: str + driver2_color: str + telemetry: List[LegacyThrottleBrakeTelemetryPoint] + session_info: LegacyThrottleBrakeSessionInfo + + +class LegacyLapTimeAnalysisTelemetryPoint(BaseModel): + """One telemetry sample along a driver's fastest lap — from ``lap_time_analysis.py``.""" + + distance: float + speed: float + throttle: float + lap_time: float = Field(description="Seconds elapsed since the start of the lap.") + driver: str + + +class LegacyLapTimeAnalysisDeltaPoint(BaseModel): + """One delta-time sample, on driver1's distance axis.""" + + distance: float + delta: float = Field(description="Positive: driver2 is behind driver1 at this point.") + + +class LegacyLapTimeAnalysisSessionInfo(BaseModel): + year: int + event: str = Field(description="Session identifier, as passed to the endpoint (e.g. 'Q').") + event_name: str + session_name: str + + +class LegacyLapTimeAnalysisResponse(BaseModel): + """Speed / delta-time / throttle comparison for two drivers' fastest laps — from + ``lap_time_analysis.py``. Falls back to V2 (livetiming) when FastF1 lacks data.""" + + driver1: str + driver2: str + driver1_color: str + driver2_color: str + driver1_laptime: Optional[float] = Field(default=None, description="Fastest lap time, seconds.") + driver2_laptime: Optional[float] = Field(default=None, description="Fastest lap time, seconds.") + reference_driver: str = Field(description="Always driver1; delta is computed on its distance axis.") + telemetry: List[LegacyLapTimeAnalysisTelemetryPoint] + delta: List[LegacyLapTimeAnalysisDeltaPoint] + session_info: LegacyLapTimeAnalysisSessionInfo + + +# --------------------------------------------------------------------------- +# Pace Analysis +# --------------------------------------------------------------------------- + +class LegacyDriverPaceEntry(BaseModel): + """One driver's lap-time distribution for the session (107% quicklap filter) — from + ``driver_pace.py``.""" + + driver: str + team: str + color: str + lap_times_seconds: List[float] + lap_count: int + min: float + q1: float + median: float + q3: float + max: float + + +LegacyDriverPaceDataResponse = RootModel[List[LegacyDriverPaceEntry]] + + +class LegacyTeamsPaceEntry(BaseModel): + """One team's lap-time distribution for the session (both drivers aggregated) — from + ``teams_pace.py``.""" + + team: str + color: str + lap_times_seconds: List[float] + lap_count: int + min: float + q1: float + median: float + q3: float + max: float + + +LegacyTeamsPaceDataResponse = RootModel[List[LegacyTeamsPaceEntry]] + + +class LegacyTyreStintUsageEntry(BaseModel): + """One driver's stint on one compound — from ``tyre_stint_usage.py``.""" + + driver: str + team: str + position: int = Field(description="Finishing position, or 99 if unavailable.") + stint_number: int + compound: str + start_lap: int + end_lap: int + lap_count: int + tyre_life_end: Optional[int] = Field(default=None, description="Tyre age (laps) at the end of the stint.") + color: str = Field(description="Compound hex color") + + +LegacyTyreStintUsageDataResponse = RootModel[List[LegacyTyreStintUsageEntry]] + + +# --------------------------------------------------------------------------- +# Seasonal Data (seasonal_v1.py) — MongoDB SeasonsDataManager documents +# --------------------------------------------------------------------------- + +class LegacySeasonsListResponse(BaseModel): + """Years with a stored season document in MongoDB — from ``seasonal_data.get_available_seasons``.""" + + seasons: List[int] + + +class LegacySeasonSummaryResponse(BaseModel): + """Complete season document (drivers, teams, races) — from + ``SeasonsDataManager.get_season_data``. + + Genuinely dynamic: this is a raw MongoDB document (minus ``_id``) whose full field set + is defined by whatever populated it (``src/repositories/populate_seasons.py``) and is + not validated against a schema anywhere in the code. ``year``, ``drivers`` and ``teams`` + are the fields every other endpoint in this router reads back out of it; the rest is + left permissive. + """ + + year: Optional[int] = None + drivers: Optional[List[Dict[str, Any]]] = None + teams: Optional[List[Dict[str, Any]]] = None + + model_config = {"extra": "allow"} + + +class LegacySeasonDriverEntry(BaseModel): + """One driver record embedded in a season document. + + Fields per the ``seasonal_data.get_drivers_for_season`` docstring; stored as a plain + Mongo sub-document so extra keys are passed through rather than dropped. + """ + + code: Optional[str] = None + name: Optional[str] = None + full_name: Optional[str] = None + team: Optional[str] = None + color: Optional[str] = None + number: Optional[int] = None + + model_config = {"extra": "allow"} + + +class LegacySeasonDriversResponse(BaseModel): + year: int + drivers: List[LegacySeasonDriverEntry] + + +class LegacySeasonTeamEntry(BaseModel): + """One team record embedded in a season document. + + Fields per the ``seasonal_data.get_teams_for_season`` docstring; stored as a plain + Mongo sub-document so extra keys are passed through rather than dropped. + """ + + name: Optional[str] = None + color: Optional[str] = None + drivers: Optional[List[str]] = None + + model_config = {"extra": "allow"} + + +class LegacySeasonTeamsResponse(BaseModel): + year: int + teams: List[LegacySeasonTeamEntry] + + +#: `/season/{year}/driver/{driver_code}` returns the driver sub-document directly (unwrapped). +LegacyDriverInfoResponse = LegacySeasonDriverEntry + +#: `/season/{year}/team/{team_name}` returns the team sub-document directly (unwrapped). +LegacyTeamInfoResponse = LegacySeasonTeamEntry diff --git a/src/api/schemas/media.py b/src/api/schemas/media.py new file mode 100644 index 0000000..b575482 --- /dev/null +++ b/src/api/schemas/media.py @@ -0,0 +1,33 @@ +"""Response schemas for the static media endpoints (driver images, team logos).""" +from __future__ import annotations + +from typing import List, Optional + +from pydantic import BaseModel, Field + + +class DriverImageItem(BaseModel): + code: str = Field(description="Three-letter driver code, e.g. VER") + name: Optional[str] = Field(default=None, description="Driver full name") + team: Optional[str] = None + number: Optional[int] = None + image_url: str = Field(description="Path to the PNG under the /assets mount") + available: bool = Field(description="Whether the image file is present on disk") + + +class TeamLogoItem(BaseModel): + name: str + short_name: str = Field(description="Short team code the logo file is named after, e.g. RBR") + color: Optional[str] = None + logo_url: str = Field(description="Path to the PNG under the /assets mount") + available: bool = Field(description="Whether the logo file is present on disk") + + +class DriverImagesResponse(BaseModel): + year: int + images: List[DriverImageItem] + + +class TeamLogosResponse(BaseModel): + year: int + logos: List[TeamLogoItem] diff --git a/src/api/schemas/monitoring.py b/src/api/schemas/monitoring.py new file mode 100644 index 0000000..ee0715a --- /dev/null +++ b/src/api/schemas/monitoring.py @@ -0,0 +1,235 @@ +"""Documentation-only response models for ``src/api/routers/monitoring.py``. + +Never attached as a bare ``response_model=`` (see ``src/api/schemas/common.py`` +for why) — these exist purely so Swagger can show a schema in ``responses=``. + +Shapes are traced from ``src/core/observability/monitoring.py`` +(``RequestTracker`` / ``SystemMonitor``) and the inline dicts each handler in +``monitoring.py`` builds around them. +""" +from __future__ import annotations + +from typing import Any, Dict, List, Optional + +from pydantic import BaseModel, Field + + +class CpuMetrics(BaseModel): + process_percent: float + system_percent: float + count: Optional[int] = None + + +class MemoryMetrics(BaseModel): + process_mb: float + process_percent: float + system_total_mb: float + system_available_mb: float + system_percent: float + + +class DiskMetrics(BaseModel): + total_gb: float + used_gb: float + free_gb: float + percent: float + + +class NetworkMetrics(BaseModel): + bytes_sent: int + bytes_received: int + packets_sent: int + packets_received: int + + +class SystemMetricsResponse(BaseModel): + """``SystemMonitor.get_metrics()``. + + All fields are optional because the method swallows its own exceptions + and returns ``{"error": "..."}`` instead of raising — that shape is + genuinely dynamic, so ``extra`` is left open rather than guessed at. + """ + + timestamp: Optional[str] = None + uptime_seconds: Optional[int] = None + uptime_human: Optional[str] = None + cpu: Optional[CpuMetrics] = None + memory: Optional[MemoryMetrics] = None + disk: Optional[DiskMetrics] = None + network: Optional[NetworkMetrics] = Field(default=None, description="Null when psutil network counters fail.") + error: Optional[str] = Field(default=None, description="Present instead of the metrics above on failure.") + + model_config = {"extra": "allow"} + + +class RequestRecord(BaseModel): + """One entry from ``RequestTracker.get_recent_requests`` (built in ``RequestTracingMiddleware``).""" + + request_id: str + timestamp: str + method: str + endpoint: str + full_url: str + client_ip: str + user_agent: str + tier: str + status_code: int + duration: float = Field(description="Seconds, float precision.") + duration_ms: float + error: Optional[Dict[str, Any]] = Field( + default=None, description="`{type, message, traceback}` when the request raised; null otherwise." + ) + + +class RecentRequestsResponse(BaseModel): + count: int + limit: int + requests: List[RequestRecord] + + +class ErrorRecord(RequestRecord): + """A ``RequestRecord`` for a failed/erroring request, plus its `error_details` copy.""" + + error_details: Optional[Dict[str, Any]] = None + + +class RecentErrorsResponse(BaseModel): + count: int + limit: int + errors: List[ErrorRecord] + + +class EndpointStat(BaseModel): + total_requests: int + total_errors: int + error_rate: float = Field(description="Percent, e.g. 2.5 for 2.5%.") + avg_duration_ms: float + min_duration_ms: float + max_duration_ms: float + + +class TrackerSummary(BaseModel): + total_requests: int + total_errors: int + error_rate_percent: float + tracked_requests_in_memory: int + tracked_errors_in_memory: int + unique_endpoints: int + + +class EndpointStatsResponse(BaseModel): + summary: TrackerSummary + endpoints: Dict[str, EndpointStat] = Field(description="Keyed by request path.") + + +class LoadSystemInfo(BaseModel): + cpu_percent: float + memory_percent: float + memory_mb: float + + +class LoadRequestsInfo(BaseModel): + total: int + total_errors: int + error_rate_percent: float + + +class CurrentLoadResponse(BaseModel): + timestamp: str + active_requests: float = Field(description="Current value of the `api_active_requests` Prometheus gauge.") + system: LoadSystemInfo + requests: LoadRequestsInfo + uptime: str + + +class ServicesStatus(BaseModel): + api: str + session_tracker: str + background_processor: str + monitoring: str + request_tracking: str + + +class BackgroundProcessorStatus(BaseModel): + running: bool + processed_sessions: int + + +class DetailedHealthRequestsInfo(BaseModel): + active: float + total: int + total_errors: int + error_rate_percent: float + tracked_in_memory: int + unique_endpoints: int + + +class DetailedHealthResponse(BaseModel): + """``GET /api/monitoring/health-detailed``.""" + + status: str + timestamp: str + version: str + environment: str + services: ServicesStatus + system: SystemMetricsResponse + requests: DetailedHealthRequestsInfo + background_processor: BackgroundProcessorStatus + + +class TestPingResponse(BaseModel): + status: str + request_id: str + timestamp: str + message: str + + +class TopEndpointEntry(BaseModel): + endpoint: str + requests: int + + +class ErrorProneEndpointEntry(BaseModel): + endpoint: str + error_rate_percent: float + + +class RecentErrorSample(BaseModel): + request_id: Optional[str] = None + endpoint: Optional[str] = None + status_code: Optional[int] = None + timestamp: Optional[str] = None + error_type: Optional[str] = None + + +class DiagnosticsSystemInfo(BaseModel): + uptime: str + cpu_percent: float + memory_mb: float + memory_percent: float + + +class DiagnosticsRequestsInfo(BaseModel): + active: float + total: int + total_errors: int + error_rate_percent: float + unique_endpoints: int + tracked_in_memory: int + + +class DiagnosticsResponse(BaseModel): + """``GET /api/diagnostics`` — everything from the other monitoring endpoints in one call.""" + + request_id: str + timestamp: str + status: str + version: str + environment: str + system: DiagnosticsSystemInfo + requests: DiagnosticsRequestsInfo + top_endpoints: List[TopEndpointEntry] + error_prone_endpoints: List[ErrorProneEndpointEntry] + recent_errors_sample: List[RecentErrorSample] + background_processor: BackgroundProcessorStatus + services: ServicesStatus diff --git a/src/api/schemas/seasonal.py b/src/api/schemas/seasonal.py new file mode 100644 index 0000000..e1273f7 --- /dev/null +++ b/src/api/schemas/seasonal.py @@ -0,0 +1,225 @@ +"""Response schemas for the V2 seasonal endpoints (``src/api/routers/seasonal_v2.py``) +and the unauthenticated static-reference endpoints (``drivers_api.py``, ``teams_api.py``, +``circuits_api.py``). + +These models are attached via ``responses={200: {"model": ...}}`` for documentation +only — never as a bare ``response_model=`` — since the handlers below return +hand-built dicts and a merely-incomplete model would silently filter live traffic. + +Two of the models (``SeasonEventItem`` / ``EventSessionItem``) wrap fields lifted +verbatim from the official, externally-controlled formula1.com season index; that +upstream shape is not ours to pin down, so those two allow extra fields rather +than rejecting/dropping anything the upstream adds. The static-reference models +below (``DriverItem``, ``TeamItem``, ``CircuitSummaryItem``) wrap our own curated +JSON files (``src/domain/data/{drivers,teams}.json``, ``src/domain/data/circuits/``) +but still allow extra fields since those files are hand-maintained and grow ad hoc. +""" +from __future__ import annotations + +from typing import Any, Dict, List, Optional + +from pydantic import BaseModel, Field + + +class SeasonEventItem(BaseModel): + """One meeting (Grand Prix weekend) from the official F1 season index.""" + + name: Optional[str] = None + official_name: Optional[str] = None + location: Optional[str] = None + country: Optional[str] = None + key: Optional[int] = Field(default=None, description="Meeting key; use as `event_name` to list its sessions") + code: Optional[str] = None + + model_config = {"extra": "allow"} + + +class SeasonEventsResponse(BaseModel): + """All meetings for a season, fetched live from formula1.com (not cached).""" + + year: int + events: List[SeasonEventItem] + + +class EventSessionItem(BaseModel): + """One session (Practice, Qualifying, Race, ...) within a meeting.""" + + name: Optional[str] = None + type: Optional[str] = None + number: Optional[int] = None + start_date: Optional[str] = None + end_date: Optional[str] = None + path: Optional[str] = None + key: Optional[int] = None + + model_config = {"extra": "allow"} + + +class EventSessionsResponse(BaseModel): + """All sessions for one season event, fetched live from formula1.com.""" + + year: int + event_name: Optional[str] = Field(default=None, description="Full meeting name matched from `event_name`") + event_key: Optional[int] = None + sessions: List[EventSessionItem] + + +class TeammateBattleTeamItem(BaseModel): + """One constructor's season-long teammate head-to-head.""" + + team: str + color: Optional[str] = None + driver_a: str + driver_b: str + quali_h2h: List[int] = Field(description="[wins_a, wins_b] qualifying head-to-head across the season") + race_h2h: List[int] = Field(description="[wins_a, wins_b] race head-to-head; DNFs excluded from either side") + avg_quali_gap_s: Optional[float] = Field( + default=None, description="Mean quali gap (driver_b - driver_a); positive means driver_a was faster" + ) + rounds_counted: int = Field(description="Number of rounds contributing to avg_quali_gap_s") + + +class TeammateBattleResponse(BaseModel): + """Season-long teammate battle scorecard, one row per constructor, alphabetical by team.""" + + teams: List[TeammateBattleTeamItem] + + +class SeasonFormDriverItem(BaseModel): + """One driver's rolling race/qualifying form across the season.""" + + tla: str + team: str + color: str + rounds: List[int] = Field(description="Round numbers with any race/quali result this season") + finish: List[Optional[int]] = Field(description="Raw finishing position per round; null where the driver sat out") + quali: List[Optional[int]] = Field(description="Raw qualifying position per round; null where absent") + finish_rolling: List[Optional[float]] = Field(description="Rolling-average finish position over `window` races") + quali_rolling: List[Optional[float]] = Field(description="Rolling-average qualifying position over `window`") + + +class SeasonFormResponse(BaseModel): + """Rolling-average race/qualifying form guide for the selected (or default top-10) drivers.""" + + window: int = Field(description="Rolling-average window size, in races") + rounds: List[int] + drivers: List[SeasonFormDriverItem] + + +class DriverRadarDriverItem(BaseModel): + """One driver's scaled radar spokes plus the raw metric behind each spoke.""" + + tla: str + team: str + color: str + values: List[Optional[float]] = Field(description="0-100 scaled value per axis, aligned to `axes` order") + raw: Dict[str, Optional[float]] = Field(description="Underlying raw metric for each axis key, before scaling") + + +class SeasonDriverRadarResponse(BaseModel): + """Season or career driver performance radar; `scope` distinguishes the two. + + Shared by ``/seasons/{year}/driver-radar-data`` (``scope="season"``) and + ``/career/driver-radar-data`` (``scope="career"``) — both endpoints return + this same shape. + """ + + scope: str = Field(description="'season' or 'career'") + axes: List[str] = Field(description="Axis display names, in the order `values` is aligned to") + drivers: List[DriverRadarDriverItem] + hero: bool = Field(description="True when exactly one driver is charted (single-driver hero layout)") + + +# ============================================================================ +# Static reference data (src/api/routers/{drivers,teams,circuits}_api.py) +# ============================================================================ + +class DriverItem(BaseModel): + """One driver entry from ``src/domain/data/drivers.json``.""" + + code: Optional[str] = None + name: Optional[str] = None + full_name: Optional[str] = None + team: Optional[str] = None + color: Optional[str] = None + number: Optional[int] = None + + model_config = {"extra": "allow"} + + +class SeasonDriversResponse(BaseModel): + """All drivers for a season year.""" + + drivers: List[DriverItem] + + +class DriverDetailResponse(BaseModel): + """A single driver, matched by name/code/number. + + The field is named ``team`` in the live response even though it holds the + driver record, not a team — that is existing handler behaviour and is + documented as-is rather than changed. + """ + + team: DriverItem + + +class TeamItem(BaseModel): + """One constructor entry from ``src/domain/data/teams.json``.""" + + name: Optional[str] = None + alt_name: Optional[str] = None + short_name: Optional[str] = None + color: Optional[str] = None + drivers: Optional[List[str]] = Field(default=None, description="Driver codes for this team") + + model_config = {"extra": "allow"} + + +class SeasonTeamsResponse(BaseModel): + """All constructors for a season year.""" + + teams: List[TeamItem] + + +class TeamDetailResponse(BaseModel): + """A single constructor, matched by name or short name.""" + + team: TeamItem + + +class CircuitSummaryItem(BaseModel): + """One circuit summary from ``src/domain/data/circuits/{year}/all_circuits.json``.""" + + circuit_id: Optional[str] = None + name: Optional[str] = None + country: Optional[str] = None + country_code: Optional[str] = None + circuit_key: Optional[int] = None + years_available: Optional[List[int]] = None + + model_config = {"extra": "allow"} + + +class YearlyCircuitsResponse(BaseModel): + """All circuit summaries for a season year.""" + + circuits: List[CircuitSummaryItem] + + +class CircuitInfoResponse(BaseModel): + """A single circuit summary, matched by circuit ID.""" + + circuit: CircuitSummaryItem + + +class CircuitDataResponse(BaseModel): + """Full circuit layout (corners, rotation, marshal lights/sectors, track outline) + in our own schema, as stored per-circuit under ``src/domain/data/circuits/{year}/``. + + Deliberately permissive: the layout schema is internal and evolves per circuit, + so this does not pin down its keys — see + ``src/ingestion/circuits_loader.py:get_circuit_data_file``. + """ + + data: Dict[str, Any] diff --git a/src/api/schemas/telemetry.py b/src/api/schemas/telemetry.py new file mode 100644 index 0000000..c28764a --- /dev/null +++ b/src/api/schemas/telemetry.py @@ -0,0 +1,151 @@ +"""Documentation-only response schemas for the V2 telemetry router. + +These models exist purely so Swagger can show a real shape for every +``/api/v2/telemetry/...`` JSON endpoint. Per ``src/api/routers/telemetry_v2.py`` +they are attached via ``responses={200: {"model": ...}}`` — **never** via +``response_model=`` — so they cannot filter or otherwise alter the live +payload. Each model mirrors the actual payload produced by +``src/services/analysis/v2/lap_frames.py`` (``LapsData`` / ``TrackMapData``). +""" +from __future__ import annotations + +from typing import Any, Dict, List, Optional + +from pydantic import BaseModel, Field + + +class TelemetrySessionInfo(BaseModel): + """Session identity echoed back inside both telemetry payloads.""" + + year: int + event_name: str + session_name: str + round: int + + +class LapsDataRange(BaseModel): + """Echo of the request's lap/format/rate knobs, plus the resulting size.""" + + lap_from: int + lap_to: int + hz: int + format: str = Field( + description="'frames' or 'columnar' — selects which field is populated on each driver block below." + ) + precision: Optional[int] = None + frame_count: int + driver_laps: int + + +class LapsDataDriverInfo(BaseModel): + tla: str + car_number: str + name: str + team: str + color: str + + +class LapsDataLap(BaseModel): + number: int + lap_time_s: float + start_s: float + end_s: float + pit_in: bool + pit_out: bool + position: Optional[int] = None + compound: Optional[str] = None + tyre_life: Optional[int] = None + frame_from: Optional[int] = None + frame_to: Optional[int] = None + + +class LapsDataGap(BaseModel): + """One window inside the resampled range where position data was unavailable.""" + + from_: float = Field(alias="from") + to: float + reason: str + + model_config = {"populate_by_name": True} + + +class LapFrame(BaseModel): + """One sample on the uniform output grid built by ``build_frames``.""" + + t: float + lap: Optional[int] = None + session_time: float + d: float + x: Optional[float] = None + y: Optional[float] = None + z: Optional[float] = None + speed: Optional[float] = None + throttle: Optional[float] = None + brake: Optional[float] = None + gear: Optional[int] = None + rpm: Optional[float] = None + drs: Optional[int] = None + status: str + + +class LapsDataDriverBlock(BaseModel): + """One driver's laps, frames/columns, and gap report. + + ``frames`` and ``columns`` are mutually exclusive — the ``format`` query + parameter on ``GET /api/v2/telemetry/laps-data`` selects which one is + populated: ``frames`` (array of :class:`LapFrame`) or ``columnar`` (one + array per field, same values as ``frames`` transposed). + """ + + driver: LapsDataDriverInfo + laps: List[LapsDataLap] + gaps: List[LapsDataGap] + frames: Optional[List[LapFrame]] = None + columns: Optional[Dict[str, List[Any]]] = None + + +class TelemetryTrack(BaseModel): + """Session-level circuit geometry, driver-free.""" + + rotation: int + corners: List[Any] + outline: List[List[float]] + + +class LapsDataResponse(BaseModel): + """Uniform-grid, multi-driver, multi-lap telemetry — from ``lap_frames.py:LapsData``. + + Any session. ``track`` is ``null`` unless ``include_track=true`` was + requested. + """ + + session_info: TelemetrySessionInfo + range: LapsDataRange + drivers: List[LapsDataDriverBlock] + track: Optional[TelemetryTrack] = None + + +class TrackMapResponse(BaseModel): + """Session-level circuit geometry — from ``lap_frames.py:TrackMapData``. + + Deliberately distinct from the existing per-driver ``/api/v2/track-map-data``, + which colours one driver's fastest lap by speed or gear; this endpoint + carries no driver and no lap timing, only the circuit outline itself. + """ + + session_info: TelemetrySessionInfo + track: TelemetryTrack + + +__all__ = [ + "TelemetrySessionInfo", + "LapsDataRange", + "LapsDataDriverInfo", + "LapsDataLap", + "LapsDataGap", + "LapFrame", + "LapsDataDriverBlock", + "TelemetryTrack", + "LapsDataResponse", + "TrackMapResponse", +] diff --git a/src/api/static/admin/admin.css b/src/api/static/admin/admin.css new file mode 100644 index 0000000..5d53721 --- /dev/null +++ b/src/api/static/admin/admin.css @@ -0,0 +1,309 @@ +/* T1API admin console — single stylesheet for every /admin page. + * + * Replaces the per-template - - -
-

T1API Admin · v{{ version }}

- Logout -
+{% extends "admin/_base.html" %} +{% set active_page = 'dashboard' %} +{% block title %}T1API Admin · Dashboard{% endblock %} +{% block content %}
Total requests
{{ summary.total_requests }}
Errors
{{ summary.total_errors }}
@@ -94,8 +34,8 @@

Platform usage (UTC)

Peak hours (UTC, last 30 days)

{% if peak_max > 0 %} -

Peak at {{ '%02d:00'|format(peak_hour.hour) }} UTC · {{ peak_hour.count }} requests

-
+

Peak at {{ '%02d:00'|format(peak_hour.hour) }} UTC · {{ peak_hour.count }} requests

+

Top API keys (last 24h)

{% if top_usage %} - +
+
{% for r in top_usage %} @@ -151,6 +94,7 @@

Top API keys (last 24h)

{% endfor %}
PrefixLabelTierRequestsErrorsAvg ms
+
{% else %}

No usage recorded yet.

{% endif %} @@ -159,14 +103,15 @@

Search

All API keys

- - +
+
PrefixLabelTierOwnerCreatedLast usedStatus
+ {% for k in keys %} @@ -174,11 +119,12 @@

All API keys

- - + +
PrefixLabelTierOwnerCreatedLast usedStatus
{{ k.label }} {{ k.tier }} {{ k.owner_id[:8] }}…{{ k.created_at }}{{ k.last_used_at or '—' }}{{ k.created_at }}{{ k.last_used_at or '—' }} {% if k.revoked_at %}revoked{% else %}active{% endif %} {% if not k.revoked_at %} -
+
{% endif %} @@ -187,21 +133,24 @@

All API keys

{% endfor %}
+

Users

- - +
+
EmailCreatedAdminDisabled
+ {% for u in users %} - +
EmailCreatedAdminDisabled
{{ u.email }}{{ u.created_at }}{{ u.created_at }} {{ 'yes' if u.is_admin else 'no' }} {{ 'yes' if u.disabled else 'no' }} {% if not u.is_admin %} -
+
{% endif %} @@ -210,11 +159,13 @@

Users

{% endfor %}
+

Endpoint performance (in-memory, since boot)

- +
+
{% for p in performance %} @@ -230,7 +181,6 @@

Endpoint performance (in-memory, since boot)

{% endfor %}
EndpointRequestsErrorsError %Avg msMin msMax ms
+
- - - +{% endblock %} diff --git a/src/api/templates/admin/data.html b/src/api/templates/admin/data.html new file mode 100644 index 0000000..52bc8b0 --- /dev/null +++ b/src/api/templates/admin/data.html @@ -0,0 +1,77 @@ +{% extends "admin/_base.html" %} +{% set active_page = 'data' %} +{% block title %}T1API Admin · Data{% endblock %} + +{% block content %} +
+

Stored V2 data

+

+ Everything actually persisted, including parameterized and legacy keys the completeness + inventory says nothing about. Deleting a key makes the backfill regenerate it — otherwise + a payload built from bad upstream data is reported as present forever. +

+
+
+ + +
+
+ + +
+
+ + +
+ +
+
+ +
+
Sessions with data
{{ browse.total_sessions }}
+
Stored data types
{{ browse.total_data_types }}
+
+ +{% if browse.rows %} + {% for row in browse.rows %} +
+
+

{{ row.event_name or row.gp_id }} · {{ row.session_type }}

+ R{{ row.round_nr }} · {{ row.gp_id }} · {{ row.count }} keys +
+
+ + + + {% for dt in row.data_types %} + + + + + {% endfor %} + +
Data type
{{ dt }} +
+ + + + + + +
+
+
+
+ {% endfor %} +{% else %} +

Nothing stored for this scope.

+{% endif %} +{% endblock %} diff --git a/src/api/templates/admin/job_detail.html b/src/api/templates/admin/job_detail.html new file mode 100644 index 0000000..f69a4f0 --- /dev/null +++ b/src/api/templates/admin/job_detail.html @@ -0,0 +1,107 @@ +{% extends "admin/_base.html" %} +{% set active_page = 'jobs' %} +{% block title %}T1API Admin · Job {{ job.job_id }}{% endblock %} + +{% block content %} +
+
+

Job {{ job.job_id }}

+ ← All jobs +
+ +
+
+
Status
+
{{ job.status }}
+
+
Progress
{{ job.done }} / {{ job.total }}
+
Generated
{{ job.success }}
+
Failed
{{ job.failed }}
+
Skipped
{{ job.skipped }}
+
Duration
{{ duration }}
+
+ + {% if job.status in ('queued', 'running') %} +
+ + +
+ This page auto-refreshes while the job runs. + {% endif %} +
+ +
+

Scope & selection

+
+ + + + + + + + + {% if job.selection and job.selection.drivers %} + + {% endif %} + {% if job.selection and job.selection.lap_from %} + + {% endif %} + + +
Year{{ job.scope.year or 'all' }}
Grand Prix{{ job.scope.gp or 'all rounds' }}
Session{{ job.scope.session or 'all sessions' }}
Force{{ 'yes' if job.scope.force else 'no' }}
Parallel sessions{{ job.scope.concurrency or 1 }}
Features + {% if job.selection and job.selection.features %} + {% for f in job.selection.features %}{{ f }}{% endfor %} + {% elif job.selection and job.selection.include_kinds %} + {% for k in job.selection.include_kinds %}all {{ k }}{% endfor %} + {% else %}field-wide defaults{% endif %} +
Drivers{% for d in job.selection.drivers %}{{ d }}{% endfor %}
Lap range{{ job.selection.lap_from }} – {{ job.selection.lap_to }}
Worker{{ job.worker or '—' }}
+
+
+ +{% if job.per_feature %} +
+

Outcome per feature

+
+ + + + {% for key, counts in job.per_feature.items() %} + + + + + + + {% endfor %} + +
FeatureGeneratedFailedSkipped
{{ key }}{{ counts.success }}{{ counts.failed }}{{ counts.skipped }}
+
+
+{% endif %} + +{% if job.warnings %} +
+

Warnings

+ {% for w in job.warnings %}
{{ w }}
{% endfor %} +
+{% endif %} + +
+

Errors ({{ job.errors | length }}{% if job.errors | length >= 200 %}, most recent{% endif %})

+ {% if job.errors %} +
{{ job.errors | join('\n') }}
+ {% else %}

No errors recorded.

{% endif %} +
+{% endblock %} + +{% block scripts %} +{% if job.status in ('queued', 'running') %} + +{% endif %} +{% endblock %} diff --git a/src/api/templates/admin/jobs.html b/src/api/templates/admin/jobs.html new file mode 100644 index 0000000..e274826 --- /dev/null +++ b/src/api/templates/admin/jobs.html @@ -0,0 +1,52 @@ +{% extends "admin/_base.html" %} +{% set active_page = 'jobs' %} +{% block title %}T1API Admin · Jobs{% endblock %} + +{% block content %} +
+
+

Backfill jobs

+
+
+ + +
+
+
+

+ Stored in MongoDB, so history survives restarts and is visible from every worker. +

+ + {% if jobs %} +
+ + + + + + {% for j in jobs %} + + + + + + + + + + + + {% endfor %} + +
JobScopeStatusDone✓✗⊘StartedFinished
{{ j.job_id }} + {{ j.scope.year }}{% if j.scope.gp %} · {{ j.scope.gp }}{% endif %}{% if j.scope.session %} · {{ j.scope.session }}{% endif %} + {{ j.status }}{{ j.done }} / {{ j.total }}{{ j.success }}{{ j.failed }}{{ j.skipped }}{{ j.started_at or j.created_at or '—' }}{{ j.finished_at or '—' }}
+
+ {% else %}

No jobs recorded.

{% endif %} +
+{% endblock %} diff --git a/src/api/templates/admin/key_analytics.html b/src/api/templates/admin/key_analytics.html index bcc227e..91b3679 100644 --- a/src/api/templates/admin/key_analytics.html +++ b/src/api/templates/admin/key_analytics.html @@ -1,93 +1,44 @@ - - - - - - -T1API Admin · {{ key.key_prefix }} - - - -
-
-

Key · {{ key.key_prefix }}

-
- ← Admin - {% if owner %} · owner: {{ owner.email }}{% endif %} -
-
- Logout -
+{% extends "admin/_base.html" %} +{% set active_page = 'dashboard' %} +{% block title %}T1API Admin · Key {{ key.key_prefix }}{% endblock %} +{% block content %}
-

Key info

-
-
Prefix{{ key.key_prefix }}
-
Label{{ key.label or '—' }}
-
Tier{{ key.tier }}
-
Status{% if key.revoked_at %}revoked{% else %}active{% endif %}
-
Owner{% if owner %}{{ owner.email }}{% else %}{{ key.owner_id[:8] }}…{% endif %}
-
Created{{ key.created_at }}
-
Last used{{ key.last_used_at or '—' }}
+
+

Key · {{ key.key_prefix }}

+
+ ← Admin + {% if owner %} · owner: {{ owner.email }}{% endif %} +
+
+
Prefix
{{ key.key_prefix }}
+
Label
{{ key.label or '—' }}
+
Tier
{{ key.tier }}
+
Status
{% if key.revoked_at %}revoked{% else %}active{% endif %}
+
Created
{{ key.created_at }}
+
Last used
{{ key.last_used_at or '—' }}
+
+ {% if not key.revoked_at %} +
+ + +
+ {% endif %}

Usage

- Window: + Window: 24h 7d 30d 90d
- +
@@ -117,7 +68,7 @@

Usage

Hourly series ({{ window_label }})

{% if bucket_max > 0 %} -
+