from fastapi import Request


def client_ip(request: Request) -> str:
    """The caller's real IP, from Caddy's X-Forwarded-For (see Caddyfile) —
    request.client.host would otherwise be the reverse proxy's own address, not
    the caller's. Falls back to request.client.host only if the header is
    somehow missing (e.g. the app container hit directly, bypassing Caddy).

    Shared by the login/registration throttles (B-33) and the SSE per-IP
    subscriber cap (B-38) so the two can't drift into different notions of
    "the client's IP".
    """
    forwarded = request.headers.get("x-forwarded-for")
    if forwarded:
        return forwarded.split(",")[0].strip()
    return request.client.host if request.client else "unknown"