domainhack 0.2.0__py3-none-any.whl

domainhack/__init__.py

@@ -0,0 +1,5 @@
+"""domainhack - Find domain hacks hiding in real words."""
+
+# Single source of truth for the version: pyproject.toml reads it statically
+# ([tool.setuptools.dynamic]) and the HTTP User-Agent is built from it.
+__version__ = "0.2.0"

domainhack/__main__.py

@@ -0,0 +1,5 @@
+"""``python -m domainhack``."""
+
+from domainhack.cli.app import main
+
+raise SystemExit(main())

domainhack/adapters/_circuit.py

@@ -0,0 +1,105 @@
+"""Per-host circuit breaker shared by registrar adapters."""
+
+from __future__ import annotations
+
+import sys
+import threading
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from tqdm import tqdm
+
+DEFAULT_FAILURE_THRESHOLD = 3
+DEFAULT_COOLDOWN_SECONDS = 60.0
+
+
+def _warn_on_stderr(message: str) -> None:
+    # tqdm.write clears and redraws an active progress bar around the message.
+    tqdm.write(message, file=sys.stderr)
+
+
+@dataclass
+class _HostState:
+    failures: int = 0
+    retry_at: float | None = None  # set while the circuit is open
+
+
+class HostCircuitBreaker:
+    """Stops querying a host after ``threshold`` consecutive failures.
+
+    Callers ask ``allow(host)`` before each request and report the outcome
+    with ``record_success`` or ``record_failure``. A failure is a sign that
+    the host is unresponsive or refusing us: a timeout, a connection error or
+    a rate-limit answer. Any real answer counts as a success and closes the
+    circuit.
+
+    Once open, ``allow`` returns False until ``cooldown`` seconds have
+    passed. Then a single trial request is let through (half-open); if it
+    fails, the circuit stays open for another cooldown. ``cooldown=None``
+    keeps an open circuit open for the life of the breaker.
+
+    ``on_open`` is called once each time a circuit goes from closed to open
+    (by default it prints a warning on stderr). Thread-safe; like
+    ``HostThrottle``, one instance can be shared by several clients that talk
+    to the same host.
+    """
+
+    def __init__(
+        self,
+        threshold: int = DEFAULT_FAILURE_THRESHOLD,
+        cooldown: float | None = DEFAULT_COOLDOWN_SECONDS,
+        clock: Callable[[], float] = time.monotonic,
+        on_open: Callable[[str], None] = _warn_on_stderr,
+    ) -> None:
+        if threshold < 1:
+            raise ValueError("threshold must be at least 1")
+        self._threshold = threshold
+        self._cooldown = cooldown
+        self._clock = clock
+        self._on_open = on_open
+        self._hosts: dict[str, _HostState] = {}
+        self._lock = threading.Lock()
+
+    def allow(self, host: str) -> bool:
+        """True if a request to ``host`` may go out now."""
+        with self._lock:
+            state = self._hosts.get(host)
+            if state is None or state.retry_at is None:
+                return True
+            if self._cooldown is None:
+                return False
+            now = self._clock()
+            if now < state.retry_at:
+                return False
+            # Half-open: let this one request through and hold back the
+            # others until it reports back or another cooldown passes.
+            state.retry_at = now + self._cooldown
+            return True
+
+    def is_open(self, host: str) -> bool:
+        with self._lock:
+            state = self._hosts.get(host)
+            return state is not None and state.retry_at is not None
+
+    def record_success(self, host: str) -> None:
+        with self._lock:
+            self._hosts.pop(host, None)
+
+    def record_failure(self, host: str) -> None:
+        with self._lock:
+            state = self._hosts.setdefault(host, _HostState())
+            state.failures += 1
+            if state.retry_at is not None or state.failures < self._threshold:
+                return
+            cooldown = self._cooldown
+            state.retry_at = self._clock() + (cooldown if cooldown is not None else 0.0)
+            failures = state.failures
+        retry = f"retrying in {cooldown:g}s" if cooldown is not None else "not retrying"
+        self._on_open(
+            f"warning: {host} unresponsive after {failures} consecutive failures; "
+            f"skipping its remaining domains (circuit open, {retry})"
+        )
+
+    def skip_message(self, host: str) -> str:
+        return f"skipped: {host} unresponsive (circuit open)"

domainhack/adapters/_http.py

@@ -0,0 +1,22 @@
+"""HTTP identity shared by every adapter that talks to a registry over HTTP.
+
+RFC 9110 §10.1.5: the User-Agent names the client honestly (no browser
+tokens) and points to the project. §10.1.2: a robotic client SHOULD send a
+``From`` header with a contact address, so an operator can reach the user
+instead of silently blocking the IP; it is opt-in (``--contact``).
+"""
+
+from __future__ import annotations
+
+from domainhack import __version__
+
+PROJECT_URL = "https://github.com/PabloAlaniz/find-amazing-domains"
+USER_AGENT = f"domainhack/{__version__} (+{PROJECT_URL})"
+
+
+def identity_headers(contact: str | None = None) -> dict[str, str]:
+    """``User-Agent`` (always) plus ``From: <contact>`` when a contact is given."""
+    headers = {"User-Agent": USER_AGENT}
+    if contact:
+        headers["From"] = contact
+    return headers

domainhack/adapters/_registration.py

@@ -0,0 +1,128 @@
+"""Helpers for registration details shared by adapters.
+
+Statuses, dates, nameservers and the sponsoring registrar's name.
+
+Everything here is defensive: unexpected input yields ``None`` (or is
+skipped), never an exception, so a malformed detail can never turn a TAKEN
+answer into an ERROR.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+from datetime import datetime, timedelta, timezone
+
+# ISO 8601 / RFC 3339 date-times as registries write them:
+# "2026-11-30T07:38:29.000Z", "2027-09-30T01:00:00Z", "2027-01-05 10:00:00+01:00",
+# "2027-01-05". A missing offset is read as UTC. (datetime.fromisoformat
+# cannot parse "Z" or arbitrary fractions on Python 3.10.)
+_ISO_DATETIME = re.compile(
+    r"(\d{4})-(\d{2})-(\d{2})"
+    r"(?:[Tt ](\d{2}):(\d{2})(?::(\d{2})(?:[.,]\d+)?)?)?"
+    r"\s*(Z|z|[+-]\d{2}(?::?\d{2})?)?"
+)
+_CAMEL_BOUNDARY = re.compile(r"(?<=[a-z])(?=[A-Z])")
+_NON_WORD = re.compile(r"[\s_-]+")
+_MAX_STATUS_LENGTH = 64
+# A host name as registries publish it, after lowercasing and dropping the
+# trailing dot. Underscores are tolerated (some registries have them).
+_HOSTNAME = re.compile(
+    r"[a-z0-9_](?:[a-z0-9_-]*[a-z0-9_])?(?:\.[a-z0-9_](?:[a-z0-9_-]*[a-z0-9_])?)*"
+)
+_MAX_HOSTNAME_LENGTH = 253
+_MAX_NAME_LENGTH = 200
+
+
+def parse_datetime_utc(value: object) -> datetime | None:
+    """Parse an ISO 8601 date or date-time into an aware UTC datetime, or None."""
+    if not isinstance(value, str):
+        return None
+    match = _ISO_DATETIME.fullmatch(value.strip())
+    if match is None:
+        return None
+    year, month, day, hour, minute, second, offset = match.groups()
+    try:
+        parsed = datetime(
+            int(year),
+            int(month),
+            int(day),
+            int(hour or 0),
+            int(minute or 0),
+            int(second or 0),
+            tzinfo=_parse_offset(offset),
+        )
+        return parsed.astimezone(timezone.utc)
+    except (ValueError, OverflowError):
+        return None
+
+
+def _parse_offset(offset: str | None) -> timezone:
+    if offset is None or offset in ("Z", "z"):
+        return timezone.utc
+    sign = -1 if offset[0] == "-" else 1
+    digits = offset[1:].replace(":", "")
+    minutes = int(digits[:2]) * 60 + int(digits[2:4] or 0)
+    return timezone(sign * timedelta(minutes=minutes))  # ValueError if out of range
+
+
+def format_utc(value: datetime | None) -> str:
+    """ISO 8601 in UTC with a ``Z`` suffix (``2026-11-30T07:38:29Z``), or ``""``."""
+    if value is None:
+        return ""
+    utc = value.astimezone(timezone.utc).replace(tzinfo=None)
+    return utc.isoformat(timespec="seconds") + "Z"
+
+
+def normalize_status(value: object) -> str | None:
+    """Normalize a status to RFC 9083 form: ``"pendingDelete"`` -> ``"pending delete"``.
+
+    RDAP values are already in that form; EPP codes (seen in WHOIS replies)
+    are camelCase. Returns None for anything that is not a short word string.
+    """
+    if not isinstance(value, str):
+        return None
+    spaced = _NON_WORD.sub(" ", _CAMEL_BOUNDARY.sub(" ", value)).strip().lower()
+    if not spaced or len(spaced) > _MAX_STATUS_LENGTH or not spaced.isprintable():
+        return None
+    return spaced
+
+
+def normalize_statuses(values: Iterable[object]) -> tuple[str, ...]:
+    """Normalize every status, dropping invalid ones and duplicates (order kept)."""
+    seen: dict[str, None] = {}
+    for value in values:
+        status = normalize_status(value)
+        if status is not None:
+            seen.setdefault(status, None)
+    return tuple(seen)
+
+
+def normalize_hostname(value: object) -> str | None:
+    """``"NS1.Example.COM."`` -> ``"ns1.example.com"``; None if it is not a host name."""
+    if not isinstance(value, str):
+        return None
+    host = value.strip().rstrip(".").lower()
+    if not host or len(host) > _MAX_HOSTNAME_LENGTH or not _HOSTNAME.fullmatch(host):
+        return None
+    return host
+
+
+def normalize_nameservers(values: Iterable[object]) -> tuple[str, ...]:
+    """Normalize every host name, dropping invalid ones and duplicates (order kept)."""
+    seen: dict[str, None] = {}
+    for value in values:
+        host = normalize_hostname(value)
+        if host is not None:
+            seen.setdefault(host, None)
+    return tuple(seen)
+
+
+def normalize_name(value: object) -> str | None:
+    """A short single-line display name (e.g. a registrar's), stripped; None otherwise."""
+    if not isinstance(value, str):
+        return None
+    name = " ".join(value.split())
+    if not name or len(name) > _MAX_NAME_LENGTH or not name.isprintable():
+        return None
+    return name

domainhack/adapters/_stderr.py

@@ -0,0 +1,16 @@
+"""Write diagnostic lines to stderr without mangling an active progress bar."""
+
+from __future__ import annotations
+
+import sys
+
+from tqdm import tqdm
+
+
+def write_stderr(message: str) -> None:
+    """Print ``message`` on stderr; tqdm clears and redraws a visible bar around it.
+
+    ``sys.stderr`` is looked up on every call so redirection (and pytest's
+    capture) is honoured.
+    """
+    tqdm.write(message, file=sys.stderr)

domainhack/adapters/_text_sink.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TextIO, TypeAlias
+
+TextTarget: TypeAlias = str | Path | TextIO
+
+
+class TextSink:
+    """A text stream that a file writer may or may not own.
+
+    When built from a path, the file is opened eagerly (so bad paths fail fast)
+    and closed by ``close()``. When built from an existing stream, ``close()``
+    only flushes it and leaves ownership with the caller.
+    """
+
+    def __init__(self, target: TextTarget) -> None:
+        if isinstance(target, (str, Path)):
+            self.stream: TextIO = open(target, "w", encoding="utf-8", newline="")  # noqa: SIM115
+            self._owned = True
+        else:
+            self.stream = target
+            self._owned = False
+        self._closed = False
+
+    def close(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        if self._owned:
+            self.stream.close()
+        else:
+            self.stream.flush()

domainhack/adapters/_throttle.py

@@ -0,0 +1,150 @@
+"""Per-host request spacing shared by registrar adapters.
+
+The spacing adapts to how each host behaves (RFC 7480 §5.5: a client that is
+told to slow down SHOULD decrease its query rate). It is a simple
+multiplicative-increase / gradual-decrease scheme:
+
+* ``slow_down(host)`` (a 429, a 503, a timeout or WHOIS rate-limit text)
+  doubles that host's interval, up to ``max_interval``.
+* ``record_success(host)`` shrinks it by ``recovery`` (x0.9) per success,
+  back down to the configured base (the ``delay`` given to ``wait``).
+* ``defer(host, seconds)`` holds the next request to ``host`` back by at
+  least ``seconds`` (``Retry-After``, retry backoff).
+
+Every spacing gets +/-``jitter`` (20 %) so requests do not arrive on an
+exact, easily fingerprinted beat. Clock, sleep and random source are
+injectable so tests run instantly and deterministically.
+"""
+
+from __future__ import annotations
+
+import random as _random
+import threading
+import time
+from collections.abc import Callable
+
+DEFAULT_JITTER = 0.2
+DEFAULT_BACKOFF_FACTOR = 2.0
+DEFAULT_RECOVERY = 0.9
+DEFAULT_MAX_INTERVAL = 60.0
+# Slowing down a host paced at 0 s (``--delay 0``) still has to space it out.
+MIN_PENALTY_INTERVAL = 1.0
+
+# Full-jitter retry backoff (AWS "Exponential Backoff and Jitter"):
+# sleep = random(0, min(cap, base * 2**attempt)).
+DEFAULT_BACKOFF_BASE = 2.0
+DEFAULT_BACKOFF_CAP = 30.0
+
+
+def full_jitter_backoff(
+    attempt: int,
+    random: Callable[[], float],
+    base: float = DEFAULT_BACKOFF_BASE,
+    cap: float = DEFAULT_BACKOFF_CAP,
+) -> float:
+    """Seconds to wait before retry number ``attempt`` (0-based), full jitter."""
+    return random() * min(cap, base * 2.0**attempt)
+
+
+class HostThrottle:
+    """Keeps an adaptive, jittered interval between requests to the same host.
+
+    Slots are reserved under a lock and the sleep happens outside it, so
+    different hosts never wait on each other. Several client instances that
+    talk to the same host (e.g. .io/.sh/.ac/.me on Identity Digital) share one
+    throttle, so their requests are spaced, slowed down and recovered as if
+    they were a single client.
+    """
+
+    def __init__(
+        self,
+        clock: Callable[[], float] = time.monotonic,
+        sleep: Callable[[float], None] = time.sleep,
+        *,
+        random: Callable[[], float] = _random.random,
+        jitter: float = DEFAULT_JITTER,
+        backoff_factor: float = DEFAULT_BACKOFF_FACTOR,
+        recovery: float = DEFAULT_RECOVERY,
+        max_interval: float = DEFAULT_MAX_INTERVAL,
+    ) -> None:
+        if not 0 <= jitter < 1:
+            raise ValueError("jitter must be in [0, 1)")
+        if backoff_factor < 1:
+            raise ValueError("backoff_factor must be >= 1")
+        if not 0 < recovery <= 1:
+            raise ValueError("recovery must be in (0, 1]")
+        self._clock = clock
+        self._sleep = sleep
+        self._random = random
+        self._jitter = jitter
+        self._backoff_factor = backoff_factor
+        self._recovery = recovery
+        self._max_interval = max_interval
+        self._next_slot: dict[str, float] = {}
+        self._base: dict[str, float] = {}
+        self._penalty: dict[str, float] = {}  # current interval while slowed down
+        self._lock = threading.Lock()
+
+    def interval(self, host: str, delay: float | None = None) -> float:
+        """The current (un-jittered) interval for ``host``.
+
+        ``delay`` is the base to compare against; by default the base last
+        passed to ``wait`` for that host (0 if it was never seen).
+        """
+        with self._lock:
+            return self._interval(host, delay)
+
+    def _interval(self, host: str, delay: float | None = None) -> float:
+        base = self._base.get(host, 0.0) if delay is None else max(delay, 0.0)
+        return max(base, self._penalty.get(host, 0.0))
+
+    def wait(self, host: str, delay: float) -> None:
+        """Block until a request to ``host`` may go out; ``delay`` is its base interval."""
+        with self._lock:
+            self._base[host] = max(delay, 0.0)
+            now = self._clock()
+            slot = max(now, self._next_slot.get(host, now))
+            spacing = self._interval(host)
+            if spacing > 0 and self._jitter:
+                spacing *= 1 + self._jitter * (2 * self._random() - 1)
+            self._next_slot[host] = slot + spacing
+        wait_for = slot - now
+        if wait_for > 0:
+            self._sleep(wait_for)
+
+    def slow_down(self, host: str) -> float:
+        """Multiply ``host``'s interval by ``backoff_factor`` (capped); return the new one.
+
+        Takes effect at once: the next request waits at least the new
+        interval from now. Waits combine with ``defer`` by taking the later
+        slot, never by adding up.
+        """
+        with self._lock:
+            current = self._interval(host)
+            new = min(self._max_interval, max(current * self._backoff_factor, MIN_PENALTY_INTERVAL))
+            self._penalty[host] = new
+            self._push(host, self._clock() + new)
+            return new
+
+    def record_success(self, host: str) -> None:
+        """Recover gradually: shrink a slowed-down interval by ``recovery``."""
+        with self._lock:
+            penalty = self._penalty.get(host)
+            if penalty is None:
+                return
+            recovered = penalty * self._recovery
+            if recovered <= self._base.get(host, 0.0):
+                del self._penalty[host]
+            else:
+                self._penalty[host] = recovered
+
+    def defer(self, host: str, seconds: float) -> None:
+        """Hold the next request to ``host`` back until ``seconds`` from now (no jitter)."""
+        with self._lock:
+            self._push(host, self._clock() + max(seconds, 0.0))
+
+    def _push(self, host: str, target: float) -> None:
+        self._next_slot[host] = max(self._next_slot.get(host, target), target)
+
+
+DEFAULT_THROTTLE = HostThrottle()

domainhack/adapters/brand_data.py

@@ -0,0 +1,49 @@
+"""Bundled data for the ``name`` command: TLD presets and hack words.
+
+Both are JSON objects in ``domainhack/data``; keys starting with ``_`` are
+comments and ignored.
+"""
+
+from __future__ import annotations
+
+import json
+from importlib import resources
+from typing import Any
+
+from domainhack.usecases.brand_candidates import CATALOG_PRESET, HackWord, Presets
+
+TLD_PRESETS_FILE = "data/tld_presets.json"
+HACK_WORDS_FILE = "data/hack_words.json"
+DEFAULT_PRESET = "startup"
+
+
+def _load(path: str) -> dict[str, Any]:
+    text = resources.files("domainhack").joinpath(path).read_text(encoding="utf-8")
+    data = json.loads(text)
+    if not isinstance(data, dict):
+        raise ValueError(f"{path}: expected a JSON object")
+    return {k: v for k, v in data.items() if not k.startswith("_")}
+
+
+def parse_presets(data: dict[str, Any]) -> Presets:
+    """Validate a presets object: each value is a list of suffixes or ``"catalog"``."""
+    presets: dict[str, list[str] | str] = {}
+    for name, value in data.items():
+        if value == CATALOG_PRESET:
+            presets[name] = CATALOG_PRESET
+        elif isinstance(value, list) and all(isinstance(s, str) for s in value):
+            presets[name] = [s.lower() for s in value]
+        else:
+            raise ValueError(f"preset {name!r}: expected a list of suffixes or {CATALOG_PRESET!r}")
+    return presets
+
+
+def load_tld_presets() -> Presets:
+    return parse_presets(_load(TLD_PRESETS_FILE))
+
+
+def load_hack_words() -> tuple[HackWord, ...]:
+    """Hack words in file order."""
+    return tuple(
+        HackWord(word.lower(), str(meaning)) for word, meaning in _load(HACK_WORDS_FILE).items()
+    )