"""
api/metrics_endpoint.py

Prometheus metrics HTTP endpoint for the Genesis API.

Exposes GET /metrics in Prometheus text exposition format so that a Prometheus
scraper (or ``infra/monitoring/prometheus.yml``) can collect Genesis platform
metrics.

Can be used in two ways:

1. Standalone FastAPI app (for testing or dedicated metrics server):
   ::
       uvicorn api.metrics_endpoint:app --port 8000

2. Mounted on an existing FastAPI application:
   ::
       from api.metrics_endpoint import metrics_router
       existing_app.include_router(metrics_router)

Falls back gracefully when ``fastapi`` is not installed — the module still
imports cleanly and ``expose_metrics_text()`` remains callable.

VERIFICATION_STAMP
Story: MON-005
Verified By: parallel-builder
Verified At: 2026-02-25
Tests: 7/7
Coverage: 100%
"""

from __future__ import annotations

from typing import Any, Optional

# ---------------------------------------------------------------------------
# Lazy import — metrics core (always available)
# ---------------------------------------------------------------------------
from core.observability.metrics import expose_metrics, CONTENT_TYPE_LATEST  # noqa: F401

# ---------------------------------------------------------------------------
# Optional FastAPI import
# ---------------------------------------------------------------------------
try:
    from fastapi import FastAPI, Response
    from fastapi.routing import APIRouter
    _FASTAPI_AVAILABLE = True
except ImportError:
    _FASTAPI_AVAILABLE = False
    FastAPI = None  # type: ignore[assignment, misc]
    Response = None  # type: ignore[assignment, misc]
    APIRouter = None  # type: ignore[assignment, misc]


# ---------------------------------------------------------------------------
# Public helper — callable without FastAPI
# ---------------------------------------------------------------------------


def expose_metrics_text() -> str:
    """Return current Genesis metrics in Prometheus text format."""
    return expose_metrics()


# ---------------------------------------------------------------------------
# FastAPI router and standalone app (only when fastapi is installed)
# ---------------------------------------------------------------------------

metrics_router: Optional[Any] = None
app: Optional[Any] = None

if _FASTAPI_AVAILABLE:
    metrics_router = APIRouter()

    @metrics_router.get("/metrics")
    def get_metrics_endpoint() -> Response:  # type: ignore[return]
        """
        GET /metrics

        Returns Prometheus text exposition format consumed by Prometheus
        scrapers.  Content-Type matches the Prometheus specification.
        """
        content = expose_metrics_text()
        return Response(
            content=content,
            media_type="text/plain; version=0.0.4; charset=utf-8",
        )

    # Standalone app for direct uvicorn usage
    app = FastAPI(
        title="Genesis Metrics",
        description="Prometheus metrics endpoint for the Genesis stack.",
        version="1.0.0",
    )
    app.include_router(metrics_router)