"""Egress-aware URL fetch validation.

A thin wrapper over the general SSRF validator that threads the egress
*scope* through, so this layer (egress) depends on the SSRF validator rather
than the SSRF validator depending on egress.
"""

from loguru import logger

from ..ssrf_validator import validate_url
from .policy import EgressScope


def policy_aware_validate_url(url: str, egress_context=None) -> bool:
    """Validate ``url`` for SSRF, taking the egress policy scope into account.

    Under ``EgressScope.PRIVATE_ONLY`` the policy lets the user reach
    private hosts (local lab deployments — Ollama on 127.0.0.1, SearXNG
    on 192.168.x). Plain ``validate_url(url)`` would reject those at
    the SSRF layer even though policy explicitly permits them. This
    wrapper threads the scope through so a PRIVATE_ONLY run can reach
    private hosts WITHOUT requiring the operator to set
    ``SSRF_ALLOW_PRIVATE_IPS=1`` globally.

    Cloud-metadata IPs in ``ALWAYS_BLOCKED_METADATA_IPS`` remain blocked
    regardless of scope (handled inside ``is_ip_blocked``).

    When ``egress_context`` is ``None`` the call is equivalent to
    ``validate_url(url)`` (strict defaults).
    """
    if egress_context is None:
        return validate_url(url)
    try:
        if egress_context.scope == EgressScope.PRIVATE_ONLY:
            return validate_url(url, allow_private_ips=True)
    except Exception:  # noqa: silent-exception
        # Defensive: any attribute error here means the context is
        # malformed; treat as if no policy was supplied and fall back to
        # strict defaults. Logging is intentionally suppressed to avoid
        # leaking policy state via timing.
        logger.debug("policy_aware_validate_url defensive fallback")
    return validate_url(url)
