domainhack 0.2.0__py3-none-any.whl

domainhack/adapters/registrar_router.py

@@ -0,0 +1,72 @@
+"""Routes each domain to the RegistrarClient responsible for its TLD."""
+
+from __future__ import annotations
+
+import threading
+from collections.abc import Callable
+
+from domainhack.adapters.registry_sources import unsupported_message
+from domainhack.domain.entities import TLD, Availability, DomainCheckResult, DomainHack
+from domainhack.ports.registrar import RegistrarClient
+
+RegistrarFactory = Callable[[TLD], RegistrarClient | None]
+
+
+class RegistrarRouter(RegistrarClient):
+    """A RegistrarClient that dispatches by TLD to per-TLD clients.
+
+    Clients are created lazily through ``factory`` the first time a TLD is seen
+    and memoized (including "no client" answers, so the factory runs at most
+    once per TLD). Domains whose TLD has no client get an ERROR result without
+    any network access.
+
+    Thread-safe: parallel checks call it from several worker threads. Client
+    creation is serialized by a lock, so the factory still runs at most once
+    per TLD; the clients themselves are called concurrently only for TLDs in
+    different lanes (see ``pacing.lane_for``).
+    """
+
+    def __init__(self, factory: RegistrarFactory) -> None:
+        self._factory = factory
+        self._clients: dict[TLD, RegistrarClient | None] = {}
+        self._lock = threading.Lock()
+
+    def client_for(self, tld: TLD) -> RegistrarClient | None:
+        """The client for ``tld`` (created on first use), or None if unsupported."""
+        with self._lock:
+            if tld not in self._clients:
+                self._clients[tld] = self._factory(tld)
+            return self._clients[tld]
+
+    def supports(self, tld: TLD) -> bool:
+        """True if some registrar client can check domains under ``tld``."""
+        return self.client_for(tld) is not None
+
+    def check_availability(self, domain: DomainHack) -> DomainCheckResult:
+        client = self.client_for(domain.tld)
+        if client is None:
+            return DomainCheckResult(
+                domain=domain,
+                availability=Availability.ERROR,
+                error_message=_capitalized(unsupported_message(domain.tld.suffix)),
+            )
+        return client.check_availability(domain)
+
+    def close(self) -> None:
+        """Close every client created so far; re-raise the first failure, if any."""
+        with self._lock:
+            clients = [c for c in self._clients.values() if c is not None]
+            self._clients.clear()
+        first_error: Exception | None = None
+        for client in clients:
+            try:
+                client.close()
+            except Exception as exc:
+                if first_error is None:
+                    first_error = exc
+        if first_error is not None:
+            raise first_error
+
+
+def _capitalized(message: str) -> str:
+    return message[:1].upper() + message[1:]

domainhack/adapters/registry_sources.py

@@ -0,0 +1,192 @@
+"""Registry backends per TLD, loaded from ``data/registry_sources.json``.
+
+The JSON is the single source of truth for TLDs the IANA RDAP bootstrap does
+not cover (or covers badly): RDAP overrides, the RDAP denylist, WHOIS servers
+with their verified "not found" patterns, and TLDs that cannot be checked at
+all, with the reason why. Keeping it as data means adding a registry is a
+reviewed data change, not a code change.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+from functools import cache
+from importlib import resources
+from typing import Any
+
+REGISTRY_SOURCES = "data/registry_sources.json"
+STATUSES = frozenset({"rdap", "whois", "restricted", "unavailable"})
+
+
+@dataclass(frozen=True)
+class WhoisSpec:
+    """A port-43 server and how to read its replies (patterns as strings)."""
+
+    host: str
+    not_found: str
+    taken: str | None
+    query_format: str
+    min_interval: float
+
+
+@dataclass(frozen=True)
+class RegistrySource:
+    """How one TLD is checked, or why it cannot be."""
+
+    tld: str
+    status: str
+    rdap: str | None
+    whois: WhoisSpec | None
+    reason: str
+    verified_on: str | None
+    source: str
+    verified_taken: str = ""
+    verified_free: str = ""
+
+
+@dataclass(frozen=True)
+class RegistrySources:
+    tlds: Mapping[str, RegistrySource]
+    rdap_denylist: frozenset[str]
+    rdap_denylist_reason: str
+
+    def get(self, tld: str) -> RegistrySource | None:
+        return self.tlds.get(tld.lower())
+
+    def rdap_overrides(self) -> dict[str, str]:
+        """TLD -> RDAP base URL for registries missing from the IANA bootstrap."""
+        return {t: s.rdap for t, s in self.tlds.items() if s.status == "rdap" and s.rdap}
+
+    def whois_primary(self) -> dict[str, WhoisSpec]:
+        """TLDs whose only backend is WHOIS."""
+        return {t: s.whois for t, s in self.tlds.items() if s.status == "whois" and s.whois}
+
+    def whois_fallback(self) -> dict[str, WhoisSpec]:
+        """RDAP TLDs with a WHOIS server kept as a fallback."""
+        return {t: s.whois for t, s in self.tlds.items() if s.status == "rdap" and s.whois}
+
+    def unsupported_reason(self, tld: str) -> str:
+        """The user-facing reason a TLD cannot be checked, or ``""`` if none is recorded."""
+        source = self.get(tld)
+        if source is None or source.status not in ("restricted", "unavailable"):
+            return ""
+        return f"{source.status}: {source.reason}"
+
+
+class RegistrySourcesError(ValueError):
+    """The bundled registry data is malformed (a packaging bug, caught by tests)."""
+
+
+def parse_registry_sources(doc: Any) -> RegistrySources:
+    """Validate and convert the JSON document; raises RegistrySourcesError."""
+    if not isinstance(doc, dict) or not isinstance(doc.get("tlds"), dict):
+        raise RegistrySourcesError("registry sources: missing 'tlds' object")
+    tlds: dict[str, RegistrySource] = {}
+    for tld, raw in doc["tlds"].items():
+        tlds[tld] = _parse_entry(tld, raw)
+    deny = doc.get("rdap_denylist") or {}
+    return RegistrySources(
+        tlds=tlds,
+        rdap_denylist=frozenset(t.lower() for t in deny.get("tlds", ())),
+        rdap_denylist_reason=str(deny.get("reason", "")),
+    )
+
+
+def _parse_entry(tld: str, raw: Any) -> RegistrySource:
+    def fail(message: str) -> RegistrySourcesError:
+        return RegistrySourcesError(f"registry sources: .{tld}: {message}")
+
+    if not isinstance(raw, dict):
+        raise fail("entry must be an object")
+    status = raw.get("status")
+    if status not in STATUSES:
+        raise fail(f"unknown status {status!r}")
+    rdap = raw.get("rdap")
+    if rdap is not None and not (isinstance(rdap, str) and rdap.startswith("https://")):
+        raise fail("rdap must be an https:// base URL")
+    if isinstance(rdap, str) and not rdap.endswith("/"):
+        raise fail("rdap base URL must end with '/'")
+    whois = _parse_whois(raw.get("whois"), fail)
+    reason = str(raw.get("reason") or "")
+    if status == "whois" and whois is None:
+        raise fail("status whois needs a whois server")
+    if status in ("restricted", "unavailable") and not reason:
+        raise fail(f"status {status} needs a reason")
+    verified = raw.get("verified")
+    if status in ("rdap", "whois") and not verified:
+        raise fail("rdap/whois entries must record when they were verified")
+    return RegistrySource(
+        tld=tld.lower(),
+        status=status,
+        rdap=rdap,
+        whois=whois,
+        reason=reason,
+        verified_on=verified.get("date") if isinstance(verified, dict) else None,
+        source=str(raw.get("source") or ""),
+        verified_taken=str(verified.get("taken_probe") or "") if isinstance(verified, dict) else "",
+        verified_free=str(verified.get("free_probe") or "") if isinstance(verified, dict) else "",
+    )
+
+
+def _parse_whois(raw: Any, fail: Any) -> WhoisSpec | None:
+    if raw is None:
+        return None
+    if not isinstance(raw, dict) or not raw.get("host") or not raw.get("not_found"):
+        raise fail("whois needs host and not_found")
+    for key in ("not_found", "taken"):
+        pattern = raw.get(key)
+        if pattern is not None:
+            try:
+                re.compile(pattern)
+            except re.error as exc:
+                raise fail(f"invalid {key} regex: {exc}") from exc
+    query_format = raw.get("query_format") or "{fqdn}\r\n"
+    if "{fqdn}" not in query_format or not query_format.endswith("\r\n"):
+        raise fail("query_format must contain {fqdn} and end with CRLF")
+    return WhoisSpec(
+        host=str(raw["host"]),
+        not_found=str(raw["not_found"]),
+        taken=raw.get("taken"),
+        query_format=query_format,
+        min_interval=float(raw.get("min_interval") or 1.0),
+    )
+
+
+@cache
+def load_registry_sources() -> RegistrySources:
+    """The bundled registry data (parsed once per process)."""
+    text = resources.files("domainhack").joinpath(REGISTRY_SOURCES).read_text(encoding="utf-8")
+    return parse_registry_sources(json.loads(text))
+
+
+def unsupported_message(suffix: str) -> str:
+    """``"no registrar supports .es"``, plus the recorded reason when there is one.
+
+    For a multi-label suffix (``com.xx``) the reason recorded for its top-level
+    domain applies.
+    """
+    sources = load_registry_sources()
+    reason = sources.unsupported_reason(suffix) or sources.unsupported_reason(
+        suffix.rsplit(".", 1)[-1]
+    )
+    message = f"no registrar supports .{suffix}"
+    return f"{message} ({reason})" if reason else message
+
+
+def describe_unsupported(suffixes: Iterable[str]) -> list[str]:
+    """Messages for TLDs that cannot be checked: the ones without a recorded
+    reason grouped (``"no registrar supports .in, .io"``), then one message per
+    TLD whose reason is known (``"no registrar supports .es (restricted: ...)"``)."""
+    plain: list[str] = []
+    explained: list[str] = []
+    for suffix in suffixes:
+        message = unsupported_message(suffix)
+        if message == f"no registrar supports .{suffix}":
+            plain.append(f".{suffix}")
+        else:
+            explained.append(message)
+    grouped = [f"no registrar supports {', '.join(plain)}"] if plain else []
+    return grouped + explained

domainhack/adapters/tqdm_progress.py

@@ -0,0 +1,101 @@
+import sys
+from typing import Any, TextIO
+
+from tqdm import tqdm
+
+from domainhack.domain.entities import Availability, DomainCheckResult
+from domainhack.ports.progress import ProgressReporter
+
+
+class _TqdmLineWriter:
+    """File-like proxy installed as ``sys.stdout`` while a bar is visible.
+
+    Complete lines are written inside ``tqdm.external_write_mode()``, which clears the
+    bar, lets the line through to the real stream and redraws the bar, so ``print()``
+    output on stdout doesn't get mangled by a bar on stderr.
+    """
+
+    def __init__(self, target: TextIO) -> None:
+        self._target = target
+        self._buffer = ""
+
+    def write(self, text: str) -> int:
+        self._buffer += text
+        if "\n" in self._buffer:
+            complete, _, self._buffer = self._buffer.rpartition("\n")
+            self._emit(complete + "\n")
+        return len(text)
+
+    def flush(self) -> None:
+        if self._buffer:
+            self._emit(self._buffer)
+            self._buffer = ""
+        self._target.flush()
+
+    def _emit(self, text: str) -> None:
+        # external_write_mode() defaults to sys.stdout (this proxy), which tqdm treats
+        # as sharing the terminal with a stderr bar, so the bar gets cleared.
+        with tqdm.external_write_mode():
+            self._target.write(text)
+            self._target.flush()
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._target, name)
+
+
+class TqdmProgressReporter(ProgressReporter):
+    """Shows a tqdm progress bar (on stderr by default) with available/error counts.
+
+    ``disable=None`` lets tqdm turn the bar off automatically when ``file`` is not a TTY.
+    While the bar is visible, ``sys.stdout`` is temporarily wrapped so regular prints
+    are interleaved cleanly with the bar; it is restored on ``close()``.
+    """
+
+    def __init__(
+        self,
+        file: TextIO | None = None,
+        disable: bool | None = None,
+        desc: str = "Checking",
+    ) -> None:
+        self._file = file
+        self._disable = disable
+        self._desc = desc
+        self._bar: tqdm[Any] | None = None
+        self._saved_stdout: TextIO | None = None
+        self.available = 0
+        self.errors = 0
+
+    def start(self, total: int | None) -> None:
+        self.available = 0
+        self.errors = 0
+        self._bar = tqdm(
+            total=total,
+            file=self._file if self._file is not None else sys.stderr,
+            disable=self._disable,
+            desc=self._desc,
+            unit="dom",
+            dynamic_ncols=True,
+        )
+        if not self._bar.disable:
+            self._bar.set_postfix(available=0, errors=0, refresh=False)
+            self._saved_stdout = sys.stdout
+            sys.stdout = _TqdmLineWriter(sys.stdout)
+
+    def advance(self, result: DomainCheckResult) -> None:
+        if result.availability is Availability.AVAILABLE:
+            self.available += 1
+        elif result.availability is Availability.ERROR:
+            self.errors += 1
+        if self._bar is None:
+            return
+        self._bar.set_postfix(available=self.available, errors=self.errors, refresh=False)
+        self._bar.update(1)
+
+    def close(self) -> None:
+        if self._saved_stdout is not None:
+            sys.stdout.flush()
+            sys.stdout = self._saved_stdout
+            self._saved_stdout = None
+        if self._bar is not None:
+            self._bar.close()
+            self._bar = None