"""Shared dependency utilities — request parsing helpers used across all API routers."""
from __future__ import annotations

import uuid
from typing import Optional

from fastapi import HTTPException, Request


def get_client_ip(request: Request) -> Optional[str]:
    """Extract best-effort client IP from request for audit logging.

    TRUST BOUNDARY: X-Forwarded-For is a client-controlled header and can be
    forged by any caller. This value is used for forensic audit logging only —
    not for authentication or access control decisions. In production, deploy
    behind a trusted reverse proxy (e.g. nginx with
    ``proxy_set_header X-Forwarded-For $remote_addr;``) which overwrites this
    header with the real remote IP before it reaches FastAPI.
    """
    return request.headers.get("X-Forwarded-For") or (
        request.client.host if request.client else None
    )


def parse_uuid(value: str, detail: str = "Not found") -> uuid.UUID:
    """Parse *value* as a UUID, raising HTTP 404 with *detail* on failure.

    Use at API boundaries to convert path/body string IDs to UUID objects.
    Returns the parsed UUID so callers can use it directly without a try/except.
    """
    try:
        return uuid.UUID(value)
    except ValueError:
        raise HTTPException(status_code=404, detail=detail)