Error Handling

Nadzoring follows a consistent error-handling pattern across all Python APIs: functions never raise exceptions for expected failures (DNS errors, network timeouts, missing PTR records, SSL connection errors). All such failures are returned as structured data, making the library safe to use in automation scripts without wrapping every call in try/except.

Only truly unexpected errors (programming mistakes, missing system commands, unsupported operating systems) are allowed to propagate as exceptions.

---

DNS Result Pattern

Functions that perform DNS lookups (resolve_with_timer, reverse_dns) return a dictionary with an "error" key. Always check it before using other fields:

from nadzoring.dns_lookup.utils import resolve_with_timer

result = resolve_with_timer("example.com", "A")

if result["error"]:
    # Handle the error
    print("DNS error:", result["error"])
else:
    # Safe to use records and response_time
    print(result["records"])
    print(f"RTT: {result['response_time']} ms")

Possible error values for resolve_with_timer:

• "Domain does not exist" — NXDOMAIN response

• "No A records" (or any record type) — domain exists but has no records of the requested type

• "Query timeout" — nameserver did not respond within the timeout

• Any other string — unexpected resolver error (e.g. malformed response)

Reverse DNS:

from nadzoring.dns_lookup.reverse import reverse_dns

result = reverse_dns("8.8.8.8")

if result["error"]:
    print("Reverse lookup failed:", result["error"])
    # "No PTR record", "No reverse DNS", "Query timeout",
    # "Invalid IP address: …"
else:
    print(result["hostname"])

---

Timeout Errors

The OperationTimeoutError exception is raised when a lifetime timeout is exceeded. This is an expected failure — it should be caught and handled by converting to an error field in the result dict, not allowed to propagate to the user.

from nadzoring.utils.timeout import TimeoutConfig, timeout_context, OperationTimeoutError

config = TimeoutConfig(lifetime=5.0)

try:
    with timeout_context(config):
        result = long_running_operation()
except OperationTimeoutError:
    result = {"error": "Operation exceeded lifetime timeout"}

When to use: Lifetime timeouts are useful for operations that may hang indefinitely (e.g., DNS queries to unresponsive servers, socket connections to firewalled hosts). Phase-specific timeouts (connect/read) are handled by socket timeouts and do not raise OperationTimeoutError.

Platform differences: On Unix systems, timeout_context uses SIGALRM which can interrupt blocking system calls. On Windows, the timeout is checked only after the operation completes (best-effort).

---

Empty-Result Pattern

Some functions return an empty dict (or empty list) when the result cannot be partially valid. This is common for geolocation, WHOIS, or system information commands.

from nadzoring.network_base.geolocation_ip import geo_ip

result = geo_ip("8.8.8.8")
if not result:
    print("Geolocation unavailable (private IP, rate-limit, or network error)")
else:
    print(result["city"], result["country"])

from nadzoring.network_base.whois_lookup import whois_lookup

result = whois_lookup("example.com")
if result.get("error"):
    print("WHOIS lookup failed:", result["error"])
    # "WHOIS lookup failed. Ensure 'whois' is installed."

---

Exception Pattern

Exceptions are reserved for system-level failures that the caller cannot reasonably handle inline. All custom exceptions inherit from nadzoring.utils.errors.NadzoringError.

from nadzoring.arp.cache import ARPCache, ARPCacheRetrievalError
from nadzoring.utils.errors import ARPError, DNSError, NetworkError

try:
    cache = ARPCache()
    entries = cache.get_cache()
except ARPCacheRetrievalError as exc:
    # System command missing, permission denied, etc.
    print("Cannot read ARP cache:", exc)

# Catch any Nadzoring error at any granularity
try:
    # some operation
    pass
except NadzoringError as exc:
    print("A Nadzoring operation failed:", exc)
except DNSError as exc:
    # Handle only DNS-related errors
    print("DNS operation failed:", exc)

Common exception types:

• DNSError — base for all DNS errors - DNSResolutionError — resolution failed - DNSTimeoutError — query timed out - DNSDomainNotFoundError — NXDOMAIN - DNSNoRecordsError — record type not present

• NetworkError — base for network errors - HostResolutionError — hostname resolution failed - ConnectionTimeoutError — connection timed out - UnsupportedPlatformError — OS not supported

• ARPError — base for ARP errors - ARPCacheRetrievalError — failed to read ARP cache

• ValidationError — input validation failed - InvalidIPAddressError — not a valid IP - InvalidDomainError — not a valid domain name - InvalidPortError — port out of range

---

Command-Line Error Handling

When using the CLI, errors are displayed in red and the command exits with a non-zero status code. Use --quiet to suppress all output except the error message.

$ nadzoring dns resolve non-existent-domain.example
DNS error: Domain does not exist
$ echo $?
1

$ nadzoring dns resolve -o json non-existent-domain.example
{"error": "Domain does not exist", ...}
$ echo $?
1

Timeout errors in CLI:

When a lifetime timeout is exceeded, the command exits with an error message and a non-zero status code. Phase-specific timeouts (connect/read) are handled within the operation and returned as error fields where applicable.

$ nadzoring dns resolve --timeout 1 slow-domain.example
DNS error: Operation exceeded lifetime timeout
$ echo $?
1

---

Best Practices for Scripts

1. Always check the error field for DNS/network operations.

2. Use truthiness checks for functions that return empty dicts/lists.

3. Catch specific exceptions only for system-level failures.

4. Use timeout contexts for operations that may hang.

5. Use the structured error values for logging and alerting.

Example robust monitoring script with timeout support:

from nadzoring.dns_lookup.utils import resolve_with_timer
from nadzoring.dns_lookup.health import health_check_dns
from nadzoring.utils.errors import NadzoringError
from nadzoring.utils.timeout import TimeoutConfig

def check_domain(domain: str, timeout_sec: float = 30.0) -> dict:
    """Safe domain checker — never raises."""
    timeout_config = TimeoutConfig(lifetime=timeout_sec)

    result = {
        "domain": domain,
        "a_record": None,
        "health_score": None,
        "error": None,
    }

    # DNS resolution with timeout
    a_result = resolve_with_timer(
        domain, "A",
        timeout_config=timeout_config,
    )
    if a_result["error"]:
        result["error"] = f"A record failed: {a_result['error']}"
        return result
    result["a_record"] = a_result["records"][0]

    # Health check
    try:
        health = health_check_dns(domain, timeout_config=timeout_config)
        result["health_score"] = health["score"]
    except NadzoringError as exc:
        # System-level failure (unlikely, but possible)
        result["error"] = f"Health check system error: {exc}"

    return result

# Use it
data = check_domain("example.com", timeout_sec=10.0)
if data["error"]:
    print(f"Check failed: {data['error']}")
else:
    print(f"OK: {data['a_record']}  score={data['health_score']}")