"""DNS resolution types and utilities."""

from enum import Enum, auto
from typing import Sequence, final
from ipaddress import IPv4Address, IPv6Address

__all__ = [
    "LookupIpStrategy",
    "ResolverOptions",
]


@final
class LookupIpStrategy(Enum):
    """IP lookup strategy for DNS resolution.

    Determines the order and types of IP addresses to resolve.
    """

    IPV4_ONLY = auto()
    """Only resolve IPv4 addresses."""

    IPV6_ONLY = auto()
    """Only resolve IPv6 addresses."""

    IPV4_AND_IPV6 = auto()
    """Resolve both IPv4 and IPv6 addresses."""

    IPV6_THEN_IPV4 = auto()
    """Prefer IPv6, fall back to IPv4."""

    IPV4_THEN_IPV6 = auto()
    """Prefer IPv4, fall back to IPv6."""


class ResolverOptions:
    """DNS resolver options for customizing DNS resolution behavior.

    Args:
        lookup_ip_strategy: The IP lookup strategy to use. Defaults to IPV4_AND_IPV6.

    Example:
        >>> from rnet import ResolverOptions, LookupIpStrategy
        >>> from ipaddress import IPv4Address
        >>> options = ResolverOptions(LookupIpStrategy.Ipv4Only)
        >>> options.add_resolve("example.com", [IPv4Address("127.0.0.1")])
    """

    def __init__(
        self,
        lookup_ip_strategy: LookupIpStrategy = LookupIpStrategy.IPV4_AND_IPV6,
    ) -> None:
        """Create a new ResolverOptions with the given lookup IP strategy.

        Args:
            lookup_ip_strategy: The IP lookup strategy to use.
        """
        ...

    def add_resolve(
        self,
        domain: str,
        addrs: Sequence[IPv4Address | IPv6Address],
    ) -> None:
        """Add a custom DNS resolve mapping.

        Maps a domain name to a list of IP addresses, bypassing normal DNS resolution.

        Args:
            domain: The domain name to map.
            addrs: List of IP addresses to resolve the domain to.

        Example:
            >>> from ipaddress import IPv4Address, IPv6Address
            >>> options = ResolverOptions()
            >>> options.add_resolve("api.example.com", [IPv4Address("192.168.1.1")])
            >>> options.add_resolve("cdn.example.com", [
            ...     IPv6Address("2001:db8::1"),
            ...     IPv4Address("203.0.113.1"),
            ... ])
        """
        ...
