opskit 0.1.0__py3-none-any.whl

opskit/dns/models.py

@@ -0,0 +1,197 @@
+"""Typed data model for DNS diagnostics.
+
+All models are frozen stdlib dataclasses (no Pydantic in core) with ``to_dict()`` for the
+JSON envelope. See specs/001-dns-diagnostics/data-model.md.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Literal
+
+
+class RecordType(str, Enum):
+    """DNS record types opskit can request."""
+
+    A = "A"
+    AAAA = "AAAA"
+    MX = "MX"
+    TXT = "TXT"
+    CNAME = "CNAME"
+    NS = "NS"
+    SOA = "SOA"
+    SRV = "SRV"
+    CAA = "CAA"
+    PTR = "PTR"
+
+
+class Transport(str, Enum):
+    """Query transport: AUTO uses UDP then falls back to TCP on truncation."""
+
+    AUTO = "auto"
+    UDP = "udp"
+    TCP = "tcp"
+
+
+class Outcome(str, Enum):
+    """The outcome class of a single query (mirrors the exit-code classes)."""
+
+    OK = "ok"
+    NXDOMAIN = "nxdomain"
+    SERVFAIL = "servfail"
+    REFUSED = "refused"
+    TIMEOUT = "timeout"
+    USAGE_ERROR = "usage_error"
+
+
+@dataclass(frozen=True)
+class DnsRecord:
+    """A single returned record: its type, rendered value, and TTL in seconds."""
+
+    type: RecordType
+    value: str
+    ttl: int
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a JSON-serializable mapping."""
+        return {"type": self.type.value, "value": self.value, "ttl": self.ttl}
+
+
+@dataclass(frozen=True)
+class Resolver:
+    """A DNS server that answered a query (``"system"`` denotes the OS default)."""
+
+    address: str
+    label: str | None = None
+
+
+@dataclass(frozen=True)
+class DnsQuery:
+    """What the user asked: target, record types, resolver(s), and query controls."""
+
+    target: str
+    record_types: tuple[RecordType, ...]
+    servers: tuple[str, ...] = ()
+    transport: Transport = Transport.AUTO
+    timeout_s: float = 5.0
+    retries: int = 2
+    port: int = 53
+    trace: bool = False
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a JSON-serializable mapping of the request parameters."""
+        return {
+            "target": self.target,
+            "record_types": [t.value for t in self.record_types],
+            "servers": list(self.servers),
+            "transport": self.transport.value,
+            "timeout_s": self.timeout_s,
+            "retries": self.retries,
+            "port": self.port,
+        }
+
+
+@dataclass(frozen=True)
+class LookupResult:
+    """The successful outcome of a query against a single resolver.
+
+    Failures are raised as :class:`opskit.dns.errors.DnsError` subclasses, not represented
+    here; an empty ``records`` tuple means the name exists but has no record of that type.
+    """
+
+    query: DnsQuery
+    resolver: Resolver
+    records: tuple[DnsRecord, ...] = ()
+    elapsed_ms: float = 0.0
+    outcome: Outcome = Outcome.OK
+
+    @property
+    def ok(self) -> bool:
+        """True when the query succeeded."""
+        return self.outcome is Outcome.OK
+
+    def __bool__(self) -> bool:
+        """A result is truthy when it succeeded."""
+        return self.ok
+
+    def __iter__(self) -> Iterator[DnsRecord]:
+        """Iterating a result yields its records."""
+        return iter(self.records)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a JSON-serializable mapping of the result."""
+        return {
+            "outcome": self.outcome.value,
+            "resolver": self.resolver.address,
+            "records": [r.to_dict() for r in self.records],
+        }
+
+
+@dataclass(frozen=True)
+class TraceStep:
+    """One hop in an iterative resolution: which server was asked and what it returned."""
+
+    server: str
+    zone: str
+    response: Literal["referral", "answer", "error"]
+    referrals: tuple[str, ...] = ()
+    records: tuple[DnsRecord, ...] = ()
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a JSON-serializable mapping of this trace step."""
+        return {
+            "server": self.server,
+            "zone": self.zone,
+            "response": self.response,
+            "referrals": list(self.referrals),
+            "records": [r.to_dict() for r in self.records],
+        }
+
+
+@dataclass(frozen=True)
+class ResolverAnswer:
+    """What one resolver returned for a compared query (records, or a failure)."""
+
+    server: str
+    outcome: Outcome
+    records: tuple[DnsRecord, ...] = ()
+    error: str | None = None
+    elapsed_ms: float = 0.0
+
+    def signature(self) -> tuple[Outcome, frozenset[tuple[RecordType, str]]]:
+        """Identity for agreement checks: outcome + record set, ignoring TTLs and order."""
+        return (self.outcome, frozenset((r.type, r.value) for r in self.records))
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a JSON-serializable mapping of this resolver's answer."""
+        return {
+            "server": self.server,
+            "outcome": self.outcome.value,
+            "records": [r.to_dict() for r in self.records],
+            "error": self.error,
+            "elapsed_ms": round(self.elapsed_ms, 3),
+        }
+
+
+@dataclass(frozen=True)
+class ResolverComparison:
+    """The same query asked of several resolvers, with agreement analysis.
+
+    ``consistent`` is True only when every resolver returned the same outcome and record set.
+    """
+
+    target: str
+    record_types: tuple[RecordType, ...]
+    answers: tuple[ResolverAnswer, ...]
+    consistent: bool
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a JSON-serializable mapping of the comparison."""
+        return {
+            "target": self.target,
+            "record_types": [t.value for t in self.record_types],
+            "consistent": self.consistent,
+            "answers": [a.to_dict() for a in self.answers],
+        }

opskit/dns/output.py

@@ -0,0 +1,83 @@
+"""Rendering of DNS results to human-readable (rich) tables.
+
+Category-owned so :mod:`opskit.core` stays free of DNS models. Resolver-derived and
+user-supplied strings are escaped as rich markup before printing to avoid markup injection.
+"""
+
+from __future__ import annotations
+
+from collections import Counter
+from collections.abc import Sequence
+
+from rich.console import Console
+from rich.markup import escape
+from rich.table import Table
+
+from opskit.dns.models import DnsRecord, Outcome, ResolverComparison, TraceStep
+
+
+def render_records(records: Sequence[DnsRecord], *, console: Console) -> None:
+    """Print records as a table (or a plain notice when there are none)."""
+    if not records:
+        console.print("No records found.")
+        return
+    table = Table(show_header=True, header_style="bold")
+    table.add_column("TYPE")
+    table.add_column("VALUE")
+    table.add_column("TTL", justify="right")
+    for record in records:
+        table.add_row(record.type.value, escape(record.value), str(record.ttl))
+    console.print(table)
+
+
+def render_comparison(comparison: ResolverComparison, *, console: Console) -> None:
+    """Print a per-resolver comparison table, highlighting resolvers that disagree."""
+    status = "consistent" if comparison.consistent else "DIFFERS"
+    types = "/".join(t.value for t in comparison.record_types)
+    table = Table(
+        title=f"{escape(comparison.target)}  [{types}]  — {status}",
+        show_header=True,
+        header_style="bold",
+    )
+    table.add_column("RESOLVER")
+    table.add_column("OUTCOME")
+    table.add_column("RECORDS / ERROR")
+    signatures = [a.signature() for a in comparison.answers]
+    majority = Counter(signatures).most_common(1)[0][0] if signatures else None
+    for answer, signature in zip(comparison.answers, signatures):
+        lines = [
+            f"{r.type.value}  {escape(r.value)}  (ttl {r.ttl})" for r in answer.records
+        ]
+        cell = "\n".join(lines) if lines else escape(answer.error or "—")
+        differs = not comparison.consistent and signature != majority
+        server = escape(answer.server)
+        resolver = f"[yellow]{server}  ⚠ differs[/yellow]" if differs else server
+        outcome = (
+            answer.outcome.value
+            if answer.outcome is Outcome.OK
+            else f"[red]{answer.outcome.value}[/red]"
+        )
+        table.add_row(resolver, outcome, cell)
+    console.print(table)
+
+
+def render_trace(steps: Sequence[TraceStep], *, console: Console) -> None:
+    """Print an iterative resolution trace (root -> authoritative), one row per hop."""
+    table = Table(show_header=True, header_style="bold")
+    table.add_column("#", justify="right")
+    table.add_column("SERVER")
+    table.add_column("ZONE")
+    table.add_column("RESULT")
+    for index, step in enumerate(steps, start=1):
+        if step.response == "answer":
+            records = "\n".join(
+                f"{r.type.value}  {escape(r.value)}" for r in step.records
+            )
+            detail = records or "(answer)"
+        elif step.response == "referral":
+            referrals = ", ".join(escape(r) for r in step.referrals)
+            detail = "-> " + referrals if referrals else "-> (referral)"
+        else:
+            detail = "(no response)"
+        table.add_row(str(index), escape(step.server), escape(step.zone), detail)
+    console.print(table)

opskit/dns/resolver.py

@@ -0,0 +1,249 @@
+"""Resolver abstraction over dnspython, injectable so tests can supply a fake.
+
+The concrete :class:`DnspythonResolver` sends a query to one server, applies UDP→TCP fallback
+on truncation, and normalizes rcodes/OS errors into the DNS exception hierarchy.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from typing import Protocol, cast
+
+import dns.exception
+import dns.flags
+import dns.message
+import dns.query
+import dns.rcode
+import dns.rdata
+import dns.rdatatype
+import dns.resolver
+import dns.rrset
+
+from opskit.dns.errors import DnsError, DnsRefused, DnsTimeout, NxDomain, ServerFailure
+from opskit.dns.models import DnsRecord, RecordType, TraceStep, Transport
+
+# Root server IPs (a/b/c-root) used as the entry point for iterative --trace.
+_ROOT_SERVERS = ("198.41.0.4", "199.9.14.201", "192.33.4.12")
+_MAX_TRACE_DEPTH = 15
+
+
+class Resolver(Protocol):
+    """Answers a single ``(name, type)`` query against one server."""
+
+    def query(
+        self,
+        name: str,
+        rtype: RecordType,
+        *,
+        server: str,
+        transport: Transport,
+        timeout: float,
+        retries: int,
+        port: int,
+    ) -> tuple[DnsRecord, ...]:
+        """Return records (possibly empty) or raise a :class:`DnsError` subclass."""
+        ...
+
+
+def system_nameserver() -> str:
+    """Return the first system-configured resolver address (cross-platform via dnspython)."""
+    try:
+        servers = dns.resolver.get_default_resolver().nameservers
+    except Exception as exc:  # pragma: no cover - platform dependent
+        raise DnsError("could not determine the system resolver") from exc
+    if not servers:  # pragma: no cover - unusual
+        raise DnsError("no system resolver configured", hint="pass --server explicitly")
+    return str(servers[0])
+
+
+class DnspythonResolver:
+    """Concrete resolver using dnspython's low-level query API."""
+
+    def query(
+        self,
+        name: str,
+        rtype: RecordType,
+        *,
+        server: str,
+        transport: Transport,
+        timeout: float,
+        retries: int,
+        port: int,
+    ) -> tuple[DnsRecord, ...]:
+        """Send one query, applying rcode→exception mapping and TCP fallback."""
+        request = dns.message.make_query(name, rtype.value)
+        response = self._send(request, server, transport, timeout, retries, port)
+        rcode = response.rcode()
+        if rcode == dns.rcode.NXDOMAIN:
+            raise NxDomain(
+                f"{name} does not exist (NXDOMAIN)", hint="check the name for typos"
+            )
+        if rcode == dns.rcode.SERVFAIL:
+            raise ServerFailure(f"{server} returned SERVFAIL for {name}")
+        if rcode == dns.rcode.REFUSED:
+            raise DnsRefused(
+                f"{server} refused the query for {name}",
+                hint="the resolver may not serve this client; try a different --server",
+            )
+        if rcode != dns.rcode.NOERROR:
+            raise ServerFailure(
+                f"{server} returned {dns.rcode.to_text(rcode)} for {name}"
+            )
+        return self._extract(response)
+
+    def _send(
+        self,
+        request: dns.message.Message,
+        server: str,
+        transport: Transport,
+        timeout: float,
+        retries: int,
+        port: int,
+    ) -> dns.message.Message:
+        last_exc: BaseException | None = None
+        for _ in range(retries + 1):
+            try:
+                if transport is Transport.TCP:
+                    return dns.query.tcp(request, server, timeout=timeout, port=port)
+                response = dns.query.udp(request, server, timeout=timeout, port=port)
+                if transport is Transport.AUTO and (response.flags & dns.flags.TC):
+                    return dns.query.tcp(request, server, timeout=timeout, port=port)
+                return response
+            except (dns.exception.Timeout, OSError) as exc:
+                # Timeouts are retried; raw socket errors (refused/unreachable) also land here.
+                last_exc = exc
+        if last_exc is None or isinstance(last_exc, dns.exception.Timeout):
+            raise DnsTimeout(
+                f"no response from {server} within {timeout}s",
+                hint="the resolver may be filtered; try --transport tcp or a different --server",
+            ) from last_exc
+        raise ServerFailure(
+            f"cannot reach {server} on port {port}: {last_exc}",
+            hint="check the --server address and --port, or that the resolver is reachable",
+        ) from last_exc
+
+    def _extract(self, response: dns.message.Message) -> tuple[DnsRecord, ...]:
+        return _records_from(response.answer)
+
+
+def _records_from(rrsets: list[dns.rrset.RRset]) -> tuple[DnsRecord, ...]:
+    """Extract our supported records from a list of rrsets (skips unsupported types)."""
+    records: list[DnsRecord] = []
+    for rrset in rrsets:
+        type_text = dns.rdatatype.to_text(rrset.rdtype)
+        try:
+            rtype = RecordType(type_text)
+        except ValueError:
+            continue  # skip records outside our supported set (e.g. RRSIG)
+        ttl = int(rrset.ttl)
+        for item in cast("Iterable[dns.rdata.Rdata]", rrset):
+            records.append(DnsRecord(type=rtype, value=str(item.to_text()), ttl=ttl))
+    return tuple(records)
+
+
+def _referral(response: dns.message.Message) -> tuple[list[str], list[str], str]:
+    """Parse a delegation response into (NS names, glue IPs, delegated zone)."""
+    ns_names: list[str] = []
+    zone = ""
+    for rrset in response.authority:
+        if rrset.rdtype == dns.rdatatype.NS:
+            zone = str(rrset.name)
+            for item in cast("Iterable[dns.rdata.Rdata]", rrset):
+                ns_names.append(str(item.to_text()))
+    glue: list[str] = []
+    for rrset in response.additional:
+        if rrset.rdtype in (dns.rdatatype.A, dns.rdatatype.AAAA):
+            for item in cast("Iterable[dns.rdata.Rdata]", rrset):
+                glue.append(str(item.to_text()))
+    return ns_names, glue, zone
+
+
+def _resolve_glue(ns_name: str, timeout: float) -> str | None:
+    """Resolve an NS hostname to an address (used when a referral lacks glue).
+
+    Tries A then AAAA so IPv6-only or dual-stack NS hosts are not missed.
+    """
+    for family in ("A", "AAAA"):
+        try:
+            answer = dns.resolver.resolve(ns_name, family, lifetime=timeout)
+        except dns.exception.DNSException:
+            continue
+        for item in cast("Iterable[dns.rdata.Rdata]", answer):
+            return str(item.to_text())
+    return None
+
+
+def _next_hop_servers(
+    glue: list[str], ns_names: list[str], timeout: float
+) -> list[str]:
+    """Servers to query for the next trace hop: prefer glue, else resolve an NS name."""
+    if glue:
+        return glue
+    if ns_names:
+        resolved = _resolve_glue(ns_names[0], timeout)
+        return [resolved] if resolved else []
+    return []
+
+
+QueryFn = Callable[[str, dns.message.Message], dns.message.Message]
+
+
+def trace_resolution(
+    name: str,
+    rtype: RecordType,
+    *,
+    timeout: float = 5.0,
+    port: int = 53,
+    query_fn: QueryFn | None = None,
+) -> tuple[TraceStep, ...]:
+    """Iteratively resolve ``name`` from the root, recording each delegation hop.
+
+    ``query_fn`` (server, request) -> response is injectable for tests; by default it sends a
+    non-recursive UDP query to each server in turn.
+    """
+
+    def default_send(server: str, request: dns.message.Message) -> dns.message.Message:
+        # Fall back to TCP when the UDP answer is truncated so large referrals aren't lost.
+        response, _ = dns.query.udp_with_fallback(
+            request, server, timeout=timeout, port=port
+        )
+        return response
+
+    send = query_fn or default_send
+    qname = name if name.endswith(".") else name + "."
+    servers: list[str] = list(_ROOT_SERVERS)
+    zone = "."
+    steps: list[TraceStep] = []
+    for _ in range(_MAX_TRACE_DEPTH):
+        if not servers:
+            break
+        server = servers[0]
+        request = dns.message.make_query(qname, rtype.value)
+        request.flags &= ~dns.flags.RD
+        try:
+            response = send(server, request)
+        except (dns.exception.Timeout, OSError):
+            # A timeout or raw socket error (refused/unreachable) ends the trace at this hop
+            # rather than escaping as an unhandled exception.
+            steps.append(TraceStep(server=server, zone=zone, response="error"))
+            break
+        if response.answer:
+            steps.append(
+                TraceStep(
+                    server=server,
+                    zone=zone,
+                    response="answer",
+                    records=_records_from(response.answer),
+                )
+            )
+            break
+        ns_names, glue, delegated = _referral(response)
+        steps.append(
+            TraceStep(
+                server=server, zone=zone, response="referral", referrals=tuple(ns_names)
+            )
+        )
+        if delegated:
+            zone = delegated
+        servers = _next_hop_servers(glue, ns_names, timeout)
+    return tuple(steps)

opskit/net/__init__.py

@@ -0,0 +1,21 @@
+"""Network primitives — resolve/connect shared by socket-using categories.
+
+Library-only for now (no CLI); the future net category registers commands on top of these.
+Public surface is SemVer-governed. Failures raise; nothing here prints or exits the process.
+"""
+
+from __future__ import annotations
+
+from opskit.net.errors import ConnectRefused, ConnectTimeout, NetError, ResolutionError
+from opskit.net.tcp import AddressCandidate, TcpConnection, connect, resolve
+
+__all__ = [
+    "AddressCandidate",
+    "ConnectRefused",
+    "ConnectTimeout",
+    "NetError",
+    "ResolutionError",
+    "TcpConnection",
+    "connect",
+    "resolve",
+]

opskit/net/errors.py

@@ -0,0 +1,37 @@
+"""Network-layer exception hierarchy (subclasses of :class:`opskit.core.errors.OpskitError`).
+
+These cover the resolve/connect layers shared by every category that opens a socket
+(tls today; the future net category). Each type owns its exit code (constitution Art. VII).
+"""
+
+from __future__ import annotations
+
+from opskit.core.errors import OpskitError
+from opskit.core.exit_codes import ExitCode
+
+
+class NetError(OpskitError):
+    """Base class for name-resolution and connection failures."""
+
+    code = "net_error"
+
+
+class ResolutionError(NetError):
+    """The host name could not be resolved to any address."""
+
+    code = "resolve_failed"
+    exit_code = ExitCode.NXDOMAIN  # same outcome class as DNS "name does not exist"
+
+
+class ConnectRefused(NetError):
+    """The target actively refused the connection (or was unreachable)."""
+
+    code = "connect_refused"
+    exit_code = ExitCode.CONNECT_FAILED
+
+
+class ConnectTimeout(NetError):
+    """No connection could be established before the timeout (possibly filtered)."""
+
+    code = "connect_timeout"
+    exit_code = ExitCode.TIMEOUT