domainhack 0.2.0__py3-none-any.whl

domainhack/adapters/rdap_bootstrap.py

@@ -0,0 +1,223 @@
+"""Resolve a TLD to its RDAP base URL.
+
+Order: denylist (servers whose answers this tool cannot use) -> overrides (working
+servers missing from IANA's bootstrap) -> IANA bootstrap file
+(https://data.iana.org/rdap/dns.json), fetched lazily and cached on disk
+for ``ttl_seconds`` -> the snapshot of that file bundled with the package
+(``domainhack/data/rdap_dns.json``).
+
+The bundled snapshot makes the backend choice independent of the network:
+offline, every TLD resolves exactly as it did when the snapshot was taken,
+and a fresh bootstrap only adds or updates entries on top of it. When the
+refresh fails, one warning goes to stderr and the snapshot alone is used; a
+stale on-disk cache is deliberately *not* used, so offline runs are
+deterministic whatever happens to be in ``~/.cache``.
+
+Refresh the snapshot by downloading the IANA file and re-serialising it
+minified (``json.dump(data, f, separators=(",", ":"))``) into
+``src/domainhack/data/rdap_dns.json``. It is kept whole (about 32 KB) so any
+TLD, not just the catalog's, resolves offline exactly as online.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+from collections.abc import Callable, Mapping
+from importlib import resources
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from domainhack.adapters._http import identity_headers
+from domainhack.adapters.registry_sources import load_registry_sources
+
+IANA_BOOTSTRAP_URL = "https://data.iana.org/rdap/dns.json"
+DEFAULT_TTL_SECONDS: float = 24 * 60 * 60
+
+
+# Registries missing from the IANA bootstrap (verified live) and RDAP servers
+# whose answers this tool cannot use live in data/registry_sources.json. "to" is
+# pinned there too so the most important TLD works even if the bootstrap fetch
+# fails; .gg and .la are checked over WHOIS instead (their RDAP replies did not
+# distinguish registered from unregistered names when verified).
+RDAP_OVERRIDES: Mapping[str, str] = load_registry_sources().rdap_overrides()
+RDAP_DENYLIST: frozenset[str] = load_registry_sources().rdap_denylist
+
+# Aggregators/redirectors are never a source of truth (rdap.org says
+# "No RDAP service" for .io, which would read as AVAILABLE).
+_DENIED_HOSTS: frozenset[str] = frozenset({"rdap.org", "www.rdap.org"})
+
+Fetcher = Callable[[], bytes]
+SnapshotLoader = Callable[[], Any]
+Warn = Callable[[str], None]
+
+BUNDLED_SNAPSHOT = "data/rdap_dns.json"
+
+
+def load_bundled_snapshot() -> Any:
+    """The IANA bootstrap document shipped as package data."""
+    resource = resources.files("domainhack").joinpath(BUNDLED_SNAPSHOT)
+    return json.loads(resource.read_text(encoding="utf-8"))
+
+
+def snapshot_date(data: Any) -> str:
+    """``YYYY-MM-DD`` from a bootstrap document's ``publication`` field, or ``unknown``."""
+    publication = data.get("publication") if isinstance(data, dict) else None
+    return publication[:10] if isinstance(publication, str) and publication else "unknown"
+
+
+def _stderr_warn(message: str) -> None:
+    print(f"warning: {message}", file=sys.stderr)
+
+
+def default_bootstrap_cache_path() -> Path:
+    """Return ``$XDG_CACHE_HOME/domainhack/rdap_dns.json`` (or ``~/.cache/...``)."""
+    base = os.environ.get("XDG_CACHE_HOME") or str(Path.home() / ".cache")
+    return Path(base) / "domainhack" / "rdap_dns.json"
+
+
+def fetch_iana_bootstrap(timeout: float = 10.0) -> bytes:
+    response = httpx.get(
+        IANA_BOOTSTRAP_URL, headers=identity_headers(), timeout=timeout, follow_redirects=True
+    )
+    response.raise_for_status()
+    return response.content
+
+
+def parse_bootstrap(data: Any) -> dict[str, str]:
+    """Map each TLD in an RFC 9224 bootstrap document to its preferred base URL."""
+    result: dict[str, str] = {}
+    services = data.get("services", []) if isinstance(data, dict) else []
+    for service in services:
+        if not (isinstance(service, list) and len(service) >= 2):
+            continue
+        tlds, urls = service[0], service[1]
+        if not (isinstance(tlds, list) and isinstance(urls, list)):
+            continue
+        url = _pick_url([u for u in urls if isinstance(u, str)])
+        if url is None:
+            continue
+        for tld in tlds:
+            if isinstance(tld, str):
+                result[tld.lower()] = url
+    return result
+
+
+def _pick_url(urls: list[str]) -> str | None:
+    usable = [u for u in urls if httpx.URL(u).host not in _DENIED_HOSTS]
+    https = [u for u in usable if u.startswith("https://")]
+    candidates = https or usable
+    if not candidates:
+        return None
+    chosen = candidates[0]
+    return chosen if chosen.endswith("/") else chosen + "/"
+
+
+class RdapBootstrap:
+    """TLD -> RDAP base URL resolver with a lazily loaded, disk-cached IANA file.
+
+    Lookups go overrides -> fresh bootstrap (disk cache younger than the TTL,
+    or a new fetch) -> bundled snapshot. A failed fetch emits one warning
+    through ``warn`` and leaves the snapshot as the only source. The fetch is
+    attempted at most once per instance, so a network outage does not cost
+    one timeout per TLD.
+    """
+
+    def __init__(
+        self,
+        cache_path: Path | None = None,
+        ttl_seconds: float = DEFAULT_TTL_SECONDS,
+        fetcher: Fetcher | None = None,
+        clock: Callable[[], float] = time.time,
+        overrides: Mapping[str, str] = RDAP_OVERRIDES,
+        denylist: frozenset[str] = RDAP_DENYLIST,
+        snapshot: SnapshotLoader = load_bundled_snapshot,
+        warn: Warn = _stderr_warn,
+    ) -> None:
+        self._cache_path = cache_path if cache_path is not None else default_bootstrap_cache_path()
+        self._ttl = ttl_seconds
+        self._fetcher: Fetcher = fetcher if fetcher is not None else fetch_iana_bootstrap
+        self._clock = clock
+        self._overrides = {k.lower(): v for k, v in overrides.items()}
+        self._denylist = frozenset(t.lower() for t in denylist)
+        self._snapshot_loader = snapshot
+        self._warn = warn
+        self._services: dict[str, str] | None = None
+
+    def base_url_for(self, tld: str) -> str | None:
+        """The RDAP base URL for ``tld``, or None.
+
+        A multi-label suffix (``com.ar``) is served by the registry of its
+        top-level domain (``ar`` -> https://rdap.nic.ar/) unless it has an
+        entry of its own; the query still names the whole domain
+        (``{base}domain/sumanda.com.ar``).
+        """
+        key = tld.lower().lstrip(".")
+        url = self._resolve(key)
+        if url is None and "." in key:
+            url = self._resolve(key.rsplit(".", 1)[1])
+        return url
+
+    def _resolve(self, key: str) -> str | None:
+        if key in self._denylist:
+            return None
+        if key in self._overrides:
+            return self._overrides[key]
+        return self._load().get(key)
+
+    def known_tlds(self) -> set[str]:
+        tlds = set(self._overrides) | set(self._load())
+        return tlds - self._denylist
+
+    def _load(self) -> dict[str, str]:
+        if self._services is None:
+            snapshot_data = self._snapshot_loader()
+            services = parse_bootstrap(snapshot_data)
+            services.update(self._load_fresh(snapshot_date(snapshot_data)))
+            self._services = services
+        return self._services
+
+    def _load_fresh(self, snapshot_day: str) -> dict[str, str]:
+        """Entries from a fresh cache or a new fetch; {} (with a warning) on failure."""
+        cached = self._read_cache()
+        if cached is not None and self._clock() - cached[0] <= self._ttl:
+            return parse_bootstrap(cached[1])
+
+        try:
+            raw = self._fetcher()
+            data = json.loads(raw)
+            services = parse_bootstrap(data)
+            if not services:
+                raise ValueError("empty RDAP bootstrap")
+        except (httpx.HTTPError, OSError, ValueError) as exc:
+            reason = str(exc) or type(exc).__name__
+            self._warn(
+                f"could not refresh RDAP bootstrap ({reason}); "
+                f"using bundled snapshot from {snapshot_day}"
+            )
+            return {}
+
+        self._write_cache(data)
+        return services
+
+    def _read_cache(self) -> tuple[float, Any] | None:
+        try:
+            wrapper = json.loads(self._cache_path.read_text(encoding="utf-8"))
+            return float(wrapper["fetched_at"]), wrapper["data"]
+        except (OSError, ValueError, KeyError, TypeError):
+            return None
+
+    def _write_cache(self, data: Any) -> None:
+        try:
+            self._cache_path.parent.mkdir(parents=True, exist_ok=True)
+            tmp = self._cache_path.with_suffix(".tmp")
+            tmp.write_text(
+                json.dumps({"fetched_at": self._clock(), "data": data}), encoding="utf-8"
+            )
+            tmp.replace(self._cache_path)
+        except OSError:
+            pass

domainhack/adapters/rdap_registrar.py

@@ -0,0 +1,328 @@
+"""RDAP (RFC 9082/9083) availability checks: GET {base}domain/{fqdn}."""
+
+from __future__ import annotations
+
+import json
+import random as _random
+import time
+from collections.abc import Callable
+from datetime import datetime
+from email.utils import parsedate_to_datetime
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+from domainhack.adapters._circuit import HostCircuitBreaker
+from domainhack.adapters._http import identity_headers
+from domainhack.adapters._registration import (
+    normalize_name,
+    normalize_nameservers,
+    normalize_statuses,
+    parse_datetime_utc,
+)
+from domainhack.adapters._throttle import (
+    DEFAULT_BACKOFF_BASE,
+    DEFAULT_BACKOFF_CAP,
+    DEFAULT_MAX_INTERVAL,
+    DEFAULT_THROTTLE,
+    HostThrottle,
+    full_jitter_backoff,
+)
+from domainhack.domain.entities import Availability, DomainCheckResult, DomainHack
+from domainhack.domain.parking import parking_hint_for
+from domainhack.ports.registrar import RegistrarClient
+
+_ACCEPT = {"Accept": "application/rdap+json, application/json"}
+_STATUS_TAKEN = 200
+_STATUS_AVAILABLE = 404
+_STATUS_TOO_MANY = 429
+_STATUS_SERVER_ERROR = 500
+_STATUS_UNAVAILABLE = 503
+# Answers that tell us to send less: they slow the host's throttle down.
+_SLOW_DOWN_STATUSES = frozenset({_STATUS_TOO_MANY, _STATUS_UNAVAILABLE})
+# Transport errors worth one more try: timeouts and dropped connections.
+_RETRYABLE_ERRORS = (httpx.TimeoutException, httpx.NetworkError, httpx.RemoteProtocolError)
+DEFAULT_CONNECT_TIMEOUT = 5.0
+
+
+def parse_retry_after(value: str | None, now: float | None = None) -> float | None:
+    """Parse a Retry-After header (delta-seconds or HTTP-date) into seconds."""
+    if not value:
+        return None
+    value = value.strip()
+    if value.isdigit():
+        return float(value)
+    try:
+        when = parsedate_to_datetime(value)
+    except (TypeError, ValueError):
+        return None
+    current = time.time() if now is None else now
+    return max(when.timestamp() - current, 0.0)
+
+
+class RdapRegistrarClient(RegistrarClient):
+    """Checks availability against one RDAP base URL.
+
+    The HTTP status decides: 404 -> AVAILABLE, 200 with a JSON domain object
+    whose ``ldhName`` matches -> TAKEN, anything else (429, 5xx, timeouts,
+    HTML 200 pages) -> ERROR. ``raw_title`` holds ``"HTTP <status>"``.
+    TAKEN results carry the domain's ``status`` values, its ``registration``
+    and ``expiration`` events, its nameservers (plus the parking service they
+    point to, if recognised) and the sponsoring registrar's name, when the
+    body has them; malformed parts are ignored.
+
+    429, 5xx, timeouts and dropped connections are retried up to
+    ``max_retries`` times. A ``Retry-After`` header is honored (it defers the
+    host on the shared ``throttle``); a 429 whose ``Retry-After`` exceeds
+    ``max_retry_after`` is not retried. Without the header the retry waits a
+    full-jitter exponential backoff, ``random(0, min(backoff_cap,
+    backoff_base * 2**n))``. A 429, a 503 or a timeout also slows the host's
+    throttle down; a real answer helps it recover.
+
+    A check that still fails after its retries counts as one failure for the
+    per-host circuit ``breaker`` (transport errors, 429, 5xx); while a host's
+    circuit is open its domains get an ERROR without any network call.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        delay: float = 1.0,
+        timeout: float = 10.0,
+        client: httpx.Client | None = None,
+        *,
+        max_retries: int = 2,
+        max_retry_after: float = 30.0,
+        throttle: HostThrottle | None = None,
+        breaker: HostCircuitBreaker | None = None,
+        random: Callable[[], float] = _random.random,
+        backoff_base: float = DEFAULT_BACKOFF_BASE,
+        backoff_cap: float = DEFAULT_BACKOFF_CAP,
+        contact: str | None = None,
+    ) -> None:
+        self._headers = {**_ACCEPT, **identity_headers(contact)}
+        self._base_url = base_url if base_url.endswith("/") else base_url + "/"
+        self._host = httpx.URL(self._base_url).host
+        self._delay = delay
+        self._timeout = timeout
+        self._owns_client = client is None
+        self._client = client or httpx.Client(
+            headers=self._headers,
+            timeout=httpx.Timeout(timeout, connect=min(DEFAULT_CONNECT_TIMEOUT, timeout)),
+            follow_redirects=True,
+        )
+        self._max_retries = max_retries
+        self._max_retry_after = max_retry_after
+        self._throttle = throttle if throttle is not None else DEFAULT_THROTTLE
+        self._breaker = breaker if breaker is not None else HostCircuitBreaker()
+        self._random = random
+        self._backoff_base = backoff_base
+        self._backoff_cap = backoff_cap
+
+    @property
+    def base_url(self) -> str:
+        return self._base_url
+
+    @property
+    def http_client(self) -> httpx.Client:
+        """The underlying HTTP client: the injected one, or the one this instance owns."""
+        return self._client
+
+    def check_availability(self, domain: DomainHack) -> DomainCheckResult:
+        if not self._breaker.allow(self._host):
+            return _error(domain, self._breaker.skip_message(self._host))
+        # fqdn is already a validated ASCII name; quoting the path segment is
+        # defence in depth so no name can add path segments or a query string.
+        url = f"{self._base_url}domain/{quote(domain.fqdn, safe='')}"
+        # One check is one outcome: however many attempts it takes, it slows
+        # the host down at most once and counts at most once for the breaker.
+        slowed = False
+        attempt = 0
+        while True:
+            self._throttle.wait(self._host, self._delay)
+            try:
+                response = self._client.get(url, headers=self._headers)
+            except httpx.HTTPError as e:
+                if isinstance(e, httpx.TimeoutException) and not slowed:
+                    slowed = True
+                    self._throttle.slow_down(self._host)
+                if isinstance(e, _RETRYABLE_ERRORS) and attempt < self._max_retries:
+                    self._backoff(attempt)
+                    attempt += 1
+                    continue
+                self._breaker.record_failure(self._host)
+                return _error(domain, f"RDAP request failed: {e or type(e).__name__}")
+
+            status = response.status_code
+            if status != _STATUS_TOO_MANY and status < _STATUS_SERVER_ERROR:
+                self._throttle.record_success(self._host)
+                self._breaker.record_success(self._host)
+                return self._interpret(domain, response)
+
+            if status in _SLOW_DOWN_STATUSES and not slowed:
+                slowed = True
+                self._throttle.slow_down(self._host)
+            retry_after = parse_retry_after(response.headers.get("Retry-After"))
+            if retry_after is not None:
+                # RFC 7480 §5.5: honor Retry-After, for every client of this host.
+                self._throttle.defer(self._host, min(retry_after, DEFAULT_MAX_INTERVAL))
+            may_retry = retry_after is None or retry_after <= self._max_retry_after
+            if may_retry and attempt < self._max_retries:
+                if retry_after is None:
+                    self._backoff(attempt)
+                attempt += 1
+                continue
+            self._breaker.record_failure(self._host)
+            if status == _STATUS_TOO_MANY:
+                return _error(domain, "RDAP rate limited (429)", status)
+            return self._interpret(domain, response)
+
+    def _backoff(self, attempt: int) -> None:
+        """Full-jitter exponential backoff before retry ``attempt`` (0-based).
+
+        The wait goes through the throttle, so it overlaps with (rather than
+        adds to) any slow-down already pending for the host.
+        """
+        delay = full_jitter_backoff(
+            attempt, self._random, base=self._backoff_base, cap=self._backoff_cap
+        )
+        self._throttle.defer(self._host, delay)
+
+    def _interpret(self, domain: DomainHack, response: httpx.Response) -> DomainCheckResult:
+        status = response.status_code
+        title = f"HTTP {status}"
+        if status == _STATUS_AVAILABLE:
+            return DomainCheckResult(
+                domain=domain, availability=Availability.AVAILABLE, raw_title=title
+            )
+        if status != _STATUS_TAKEN:
+            return _error(domain, f"Unexpected RDAP status {status}", status)
+
+        try:
+            body: Any = response.json()
+        except (json.JSONDecodeError, UnicodeDecodeError):
+            return _error(domain, "RDAP 200 response is not JSON", status)
+        if not isinstance(body, dict):
+            return _error(domain, "RDAP 200 response is not a JSON object", status)
+
+        ldh = body.get("ldhName")
+        if isinstance(ldh, str):
+            if ldh.rstrip(".").lower() == domain.fqdn.lower():
+                return _taken(domain, title, body)
+            return _error(domain, f"RDAP ldhName mismatch: {ldh!r}", status)
+        if body.get("objectClassName") == "domain":
+            return _taken(domain, title, body)
+        return _error(domain, "RDAP 200 response is not a domain object", status)
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+
+def _taken(domain: DomainHack, title: str, body: dict[str, Any]) -> DomainCheckResult:
+    nameservers = parse_rdap_nameservers(body)
+    return DomainCheckResult(
+        domain=domain,
+        availability=Availability.TAKEN,
+        raw_title=title,
+        statuses=parse_rdap_statuses(body),
+        expires_at=parse_rdap_expiration(body),
+        registered_at=parse_rdap_registration(body),
+        registrar=parse_rdap_registrar(body),
+        nameservers=nameservers,
+        parked_hint=parking_hint_for(nameservers),
+    )
+
+
+def parse_rdap_statuses(body: dict[str, Any]) -> tuple[str, ...]:
+    """The domain's ``status`` array (RFC 9083 §4.6), normalized; ``()`` if absent or malformed."""
+    values = body.get("status")
+    if not isinstance(values, list):
+        return ()
+    return normalize_statuses(values)
+
+
+def _event_date(body: dict[str, Any], action: str) -> datetime | None:
+    """The date of the first valid event with ``eventAction == action`` (RFC 9083 §4.5)."""
+    events = body.get("events")
+    if not isinstance(events, list):
+        return None
+    for event in events:
+        if not isinstance(event, dict):
+            continue
+        event_action = event.get("eventAction")
+        if not isinstance(event_action, str) or event_action.strip().lower() != action:
+            continue
+        when = parse_datetime_utc(event.get("eventDate"))
+        if when is not None:
+            return when
+    return None
+
+
+def parse_rdap_expiration(body: dict[str, Any]) -> datetime | None:
+    """The date of the first valid ``expiration`` event, in UTC, or None."""
+    return _event_date(body, "expiration")
+
+
+def parse_rdap_registration(body: dict[str, Any]) -> datetime | None:
+    """The date of the first valid ``registration`` event, in UTC, or None."""
+    return _event_date(body, "registration")
+
+
+def parse_rdap_nameservers(body: dict[str, Any]) -> tuple[str, ...]:
+    """``ldhName`` of each ``nameservers`` entry (RFC 9083 §5.2), or ``()``.
+
+    Lowercase, without the trailing dot, deduplicated, in registry order;
+    malformed entries are skipped.
+    """
+    entries = body.get("nameservers")
+    if not isinstance(entries, list):
+        return ()
+    return normalize_nameservers(
+        entry.get("ldhName") for entry in entries if isinstance(entry, dict)
+    )
+
+
+def parse_rdap_registrar(body: dict[str, Any]) -> str:
+    """The name of the top-level entity with role ``registrar`` (RFC 9083 §5.1).
+
+    Its vCard ``fn`` (RFC 7095 jCard) when non-empty, else its ``handle``
+    (for gTLDs, the IANA registrar ID); ``""`` if there is none.
+    """
+    entities = body.get("entities")
+    if not isinstance(entities, list):
+        return ""
+    for entity in entities:
+        if not isinstance(entity, dict):
+            continue
+        roles = entity.get("roles")
+        if not isinstance(roles, list) or not any(
+            isinstance(role, str) and role.strip().lower() == "registrar" for role in roles
+        ):
+            continue
+        name = _vcard_fn(entity.get("vcardArray")) or normalize_name(entity.get("handle"))
+        if name:
+            return name
+    return ""
+
+
+def _vcard_fn(vcard: object) -> str | None:
+    """The first non-empty ``fn`` of a jCard ``["vcard", [[name, params, type, value]...]]``."""
+    if not isinstance(vcard, list) or len(vcard) < 2 or not isinstance(vcard[1], list):
+        return None
+    for prop in vcard[1]:
+        if isinstance(prop, list) and len(prop) >= 4 and prop[0] == "fn":
+            name = normalize_name(prop[3])
+            if name:
+                return name
+    return None
+
+
+def _error(domain: DomainHack, message: str, status: int | None = None) -> DomainCheckResult:
+    return DomainCheckResult(
+        domain=domain,
+        availability=Availability.ERROR,
+        raw_title=f"HTTP {status}" if status is not None else "",
+        error_message=message,
+    )

domainhack/adapters/registrar_catalog.py

@@ -0,0 +1,120 @@
+"""Pick the best availability source for a TLD.
+
+Priority: RDAP (hard-coded override, then IANA bootstrap, then the bundled
+bootstrap snapshot) -> WHOIS_SERVERS (TLDs without usable RDAP) ->
+WHOIS_FALLBACK_SERVERS (RDAP TLDs; used only if RDAP resolution yields
+nothing, with a stderr warning) -> unsupported (None).
+
+Thanks to the bundled snapshot the choice does not depend on the network:
+offline and online runs pick the same backend for every catalog TLD.
+
+``.to`` is served by RDAP too (rdap.tonicregistry.to): it is the
+registry's official protocol, it agreed with the Tonic web form on 23/23
+test names (including registered names without NS records), and it gives
+proper status codes and Retry-After, which a web form does not.
+"""
+
+from __future__ import annotations
+
+import functools
+import sys
+from dataclasses import dataclass
+from urllib.parse import urlsplit
+
+from domainhack.adapters._circuit import HostCircuitBreaker
+from domainhack.adapters.rdap_bootstrap import RdapBootstrap
+from domainhack.adapters.rdap_registrar import RdapRegistrarClient
+from domainhack.adapters.registry_sources import load_registry_sources
+from domainhack.adapters.whois_registrar import (
+    WHOIS_FALLBACK_SERVERS,
+    WHOIS_SERVERS,
+    WhoisRegistrarClient,
+)
+from domainhack.domain.entities import TLD
+from domainhack.ports.registrar import RegistrarClient
+
+
+@functools.cache
+def _default_bootstrap() -> RdapBootstrap:
+    return RdapBootstrap()
+
+
+def build_registrar_for(
+    tld: TLD,
+    delay: float,
+    timeout: float = 10.0,
+    breaker: HostCircuitBreaker | None = None,
+    contact: str | None = None,
+    bootstrap: RdapBootstrap | None = None,
+) -> RegistrarClient | None:
+    """Return a new client able to check domains under ``tld``, or None if unsupported.
+
+    Pass one ``breaker`` to every call of a run so clients that share a host
+    (e.g. .io/.sh/.ac/.me) also share its circuit. ``contact`` (an email) is
+    sent as the ``From`` header on RDAP requests. A multi-label ``tld``
+    (``com.ar``) is routed to the registry of its top-level domain (``ar``).
+    ``bootstrap`` replaces the
+    process-wide default RDAP bootstrap (tests pass one with a fake fetcher).
+    """
+    rdap = bootstrap if bootstrap is not None else _default_bootstrap()
+    base_url = rdap.base_url_for(tld.suffix)
+    if base_url is not None:
+        return RdapRegistrarClient(
+            base_url, delay=delay, timeout=timeout, breaker=breaker, contact=contact
+        )
+    # Multi-label suffixes (com.mx) are served by their top-level registry.
+    suffix = tld.top_level.lower()
+    if suffix in WHOIS_SERVERS:
+        return WhoisRegistrarClient(
+            delay=delay, timeout=timeout, servers=WHOIS_SERVERS, breaker=breaker
+        )
+    if suffix in WHOIS_FALLBACK_SERVERS:
+        host = WHOIS_FALLBACK_SERVERS[suffix].host
+        print(
+            f"warning: no RDAP server found for .{tld.suffix}; falling back to WHOIS ({host})",
+            file=sys.stderr,
+        )
+        return WhoisRegistrarClient(
+            delay=delay, timeout=timeout, servers=WHOIS_FALLBACK_SERVERS, breaker=breaker
+        )
+    return None
+
+
+def supported_tlds(bootstrap: RdapBootstrap | None = None) -> set[str]:
+    """All TLDs ``build_registrar_for`` can serve (may fetch the IANA bootstrap)."""
+    rdap = bootstrap if bootstrap is not None else _default_bootstrap()
+    return rdap.known_tlds() | set(WHOIS_SERVERS) | set(WHOIS_FALLBACK_SERVERS)
+
+
+@dataclass(frozen=True)
+class Backend:
+    """How ``build_registrar_for`` would check a TLD, without creating a client.
+
+    ``kind`` is ``"rdap"``, ``"whois"``, ``"whois-fallback"`` (RDAP TLD whose
+    RDAP server could not be resolved) or ``"unsupported"``. ``detail`` is the
+    date the source was verified, or the reason a TLD is unsupported.
+    """
+
+    tld: str
+    kind: str
+    host: str
+    detail: str
+
+
+def describe_backend(suffix: str, bootstrap: RdapBootstrap | None = None) -> Backend:
+    """The backend for ``suffix`` (``"cl"``, ``"com.ar"``), mirroring ``build_registrar_for``."""
+    rdap = bootstrap if bootstrap is not None else _default_bootstrap()
+    sources = load_registry_sources()
+    suffix = suffix.lower().lstrip(".")
+    top = suffix.rsplit(".", 1)[-1]
+    entry = sources.get(suffix) or sources.get(top)
+    verified = entry.verified_on if entry is not None and entry.verified_on else ""
+    base_url = rdap.base_url_for(suffix)
+    if base_url is not None:
+        detail = verified or "IANA RDAP bootstrap"
+        return Backend(suffix, "rdap", urlsplit(base_url).hostname or base_url, detail)
+    if top in WHOIS_SERVERS:
+        return Backend(suffix, "whois", WHOIS_SERVERS[top].host, verified)
+    if top in WHOIS_FALLBACK_SERVERS:
+        return Backend(suffix, "whois-fallback", WHOIS_FALLBACK_SERVERS[top].host, verified)
+    return Backend(suffix, "unsupported", "", sources.unsupported_reason(top) or "no source known")