ip-reporter 0.1.1__py3-none-any.whl

ip_reporter/__init__.py

@@ -0,0 +1,85 @@
+"""WAN/LAN IP discovery and Cloudflare DNS synchronization."""
+
+from .cloudflare import (
+    CloudflareAPIError,
+    CloudflareClient,
+    CloudflareError,
+    HTTPResponse,
+    HTTPTransport,
+    RecordNotFoundError,
+    UrllibTransport,
+)
+from .curl import (
+    CurlClient,
+    CurlError,
+    CurlFeatureError,
+    CurlProbeError,
+    CurlUnavailableError,
+    CurlVersion,
+    find_curl,
+)
+from .discovery import (
+    DEFAULT_WAN_ENDPOINTS,
+    AddressDiscovery,
+    DiscoveryFailedError,
+    LocalAddressProvider,
+    RemoteEndpoint,
+    SocketLocalAddressProvider,
+    WanProbe,
+)
+from .models import (
+    AddressFamily,
+    DiscoveredAddress,
+    DiscoveryError,
+    DiscoveryResult,
+    DNSUpdate,
+    DNSUpdateResult,
+    ProbeProtocol,
+    Scope,
+    normalize_families,
+)
+from .reporter import (
+    IPReporter,
+    discover,
+    get_lan,
+    get_wan,
+    update_cloudflare_dns,
+)
+
+__all__ = [
+    "AddressDiscovery",
+    "AddressFamily",
+    "CloudflareAPIError",
+    "CloudflareClient",
+    "CloudflareError",
+    "CurlClient",
+    "CurlError",
+    "CurlFeatureError",
+    "CurlProbeError",
+    "CurlUnavailableError",
+    "CurlVersion",
+    "DEFAULT_WAN_ENDPOINTS",
+    "DNSUpdate",
+    "DNSUpdateResult",
+    "DiscoveryError",
+    "DiscoveryFailedError",
+    "DiscoveryResult",
+    "DiscoveredAddress",
+    "HTTPResponse",
+    "HTTPTransport",
+    "IPReporter",
+    "LocalAddressProvider",
+    "ProbeProtocol",
+    "RecordNotFoundError",
+    "RemoteEndpoint",
+    "Scope",
+    "SocketLocalAddressProvider",
+    "UrllibTransport",
+    "WanProbe",
+    "discover",
+    "find_curl",
+    "get_lan",
+    "get_wan",
+    "normalize_families",
+    "update_cloudflare_dns",
+]

ip_reporter/cli.py

@@ -0,0 +1,246 @@
+"""Command-line interface for ``ip-reporter``."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Iterable
+
+from .cloudflare import CloudflareClient
+from .curl import CurlClient
+from .discovery import AddressDiscovery, RemoteEndpoint
+from .models import AddressFamily, Scope, coerce_scope
+from .reporter import IPReporter
+
+
+def _add_discovery_options(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--scope",
+        choices=[scope.value for scope in Scope],
+        default=Scope.BOTH.value,
+        help="report wan, lan, or both (default: both)",
+    )
+    parser.add_argument(
+        "--family",
+        action="append",
+        metavar="FAMILY",
+        help="ipv4, ipv6, h3ipv4, h3ipv6, or all; repeat for multiple families (default: ipv4)",
+    )
+    parser.add_argument(
+        "--format",
+        choices=("text", "values", "json"),
+        default="text",
+        help="output format (default: text)",
+    )
+    parser.add_argument(
+        "--curl-path",
+        help="curl executable; defaults to Homebrew curl on macOS or IP_REPORTER_CURL",
+    )
+    parser.add_argument("--timeout", type=float, default=10.0, help="probe timeout in seconds")
+    parser.add_argument(
+        "--wan-endpoint",
+        action="append",
+        help="override WAN endpoint; repeat for failover endpoints",
+    )
+    parser.add_argument(
+        "--strict",
+        action="store_true",
+        help="fail if any requested family cannot be discovered",
+    )
+
+
+def _add_dns_options(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--record", action="append", required=True, help="DNS name; repeat for many"
+    )
+    parser.add_argument("--zone-id", help="Cloudflare zone ID; or use CLOUDFLARE_ZONE_ID")
+    parser.add_argument(
+        "--zone-name",
+        help="zone name, useful with --zone-id for relative names or for zone lookup",
+    )
+    parser.add_argument(
+        "--scope",
+        choices=[scope.value for scope in Scope],
+        default=Scope.WAN.value,
+        help="address scope to write (default: wan)",
+    )
+    parser.add_argument(
+        "--family",
+        action="append",
+        metavar="FAMILY",
+        help="ipv4, ipv6, h3ipv4, h3ipv6, or all; repeat for multiple families (default: ipv4)",
+    )
+    parser.add_argument("--ttl", type=int, default=1, help="TTL in seconds; 1 means automatic")
+    proxy = parser.add_mutually_exclusive_group()
+    proxy.add_argument("--proxied", dest="proxied", action="store_true")
+    proxy.add_argument("--not-proxied", dest="proxied", action="store_false")
+    parser.set_defaults(proxied=None)
+    parser.add_argument("--comment", help="Cloudflare record comment")
+    parser.add_argument(
+        "--create-missing",
+        action="store_true",
+        help="create a missing A/AAAA record; otherwise only existing records are changed",
+    )
+    parser.add_argument("--curl-path", help="curl executable for WAN probes")
+    parser.add_argument("--timeout", type=float, default=10.0, help="probe/API timeout in seconds")
+    parser.add_argument("--api-token", help="Cloudflare API token; prefer CLOUDFLARE_API_TOKEN")
+    parser.add_argument("--api-email", help="legacy Cloudflare API email")
+    parser.add_argument("--api-key", help="legacy Cloudflare Global API key")
+    parser.add_argument(
+        "--format", choices=("text", "json"), default="text", help="output format (default: text)"
+    )
+    parser.add_argument(
+        "--dry-run", action="store_true", help="discover and print without changing DNS"
+    )
+
+
+def _parse_families(raw: Iterable[str] | None) -> tuple[AddressFamily, ...]:
+    if not raw:
+        return (AddressFamily.IPV4,)
+    values: list[AddressFamily] = []
+    all_families = tuple(AddressFamily)
+    for item in raw:
+        for value in item.split(","):
+            normalized = value.strip().lower()
+            if normalized == "all":
+                candidates = all_families
+            else:
+                try:
+                    candidates = (AddressFamily(normalized),)
+                except ValueError as exc:
+                    raise ValueError(
+                        f"unknown family {value!r}; use ipv4, ipv6, h3ipv4, h3ipv6, or all"
+                    ) from exc
+            for family in candidates:
+                if family not in values:
+                    values.append(family)
+    if not values:
+        raise ValueError("at least one family is required")
+    return tuple(values)
+
+
+def _make_reporter(args: argparse.Namespace) -> IPReporter:
+    scope = coerce_scope(args.scope)
+    wan_probe = None
+    if scope in (Scope.WAN, Scope.BOTH):
+        wan_probe = CurlClient(args.curl_path, timeout=args.timeout)
+    endpoint_values = getattr(args, "wan_endpoint", None)
+    endpoints = None
+    if endpoint_values:
+        endpoints = tuple(RemoteEndpoint(value) for value in endpoint_values)
+    discovery = (
+        AddressDiscovery(wan_probe=wan_probe, endpoints=endpoints or ())
+        if endpoints
+        else AddressDiscovery(wan_probe=wan_probe)
+    )
+    return IPReporter(discovery)
+
+
+def _print_discovery(result, output_format: str) -> None:
+    if output_format == "json":
+        print(result.to_json())
+        return
+    if output_format == "values":
+        for address in result.wan + result.lan:
+            print(address.value)
+    else:
+        for scope, addresses in (("wan", result.wan), ("lan", result.lan)):
+            for address in addresses:
+                print(f"{scope} {address.family.value} {address.value} [{address.protocol.value}]")
+    for error in result.errors:
+        print(
+            f"error {error.scope.value} {error.family.value}: {error.message}",
+            file=sys.stderr,
+        )
+
+
+def _run_discover(args: argparse.Namespace) -> int:
+    reporter = _make_reporter(args)
+    result = reporter.discover(
+        scope=args.scope,
+        families=_parse_families(args.family),
+        strict=args.strict,
+    )
+    _print_discovery(result, args.format)
+    return 0 if result.wan or result.lan else 1
+
+
+def _run_dns_update(args: argparse.Namespace) -> int:
+    reporter = _make_reporter(args)
+    families = _parse_families(args.family)
+    result = reporter.discover(scope=args.scope, families=families, strict=True)
+    addresses = result.addresses(scope=args.scope, families=families)
+    if not addresses:
+        raise RuntimeError("no addresses were discovered; DNS was not changed")
+    if args.dry_run:
+        _print_discovery(result, "json" if args.format == "json" else "text")
+        return 0
+
+    if args.api_token or args.api_email or args.api_key:
+        cloudflare = CloudflareClient(
+            api_token=args.api_token,
+            api_email=args.api_email,
+            api_key=args.api_key,
+            timeout=args.timeout,
+        )
+    else:
+        cloudflare = CloudflareClient.from_env(timeout=args.timeout)
+    zone_id = args.zone_id
+    if not zone_id:
+        import os
+
+        zone_id = os.environ.get("CLOUDFLARE_ZONE_ID")
+    update = cloudflare.sync_addresses(
+        zone_id,
+        args.record,
+        addresses,
+        zone_name=args.zone_name,
+        ttl=args.ttl,
+        proxied=args.proxied,
+        comment=args.comment,
+        create_missing=args.create_missing,
+    )
+    if args.format == "json":
+        print(json.dumps(update.as_dict(), indent=2, sort_keys=True))
+    else:
+        print(f"created={update.created} updated={update.updated} unchanged={update.unchanged}")
+        for item in update.updates:
+            print(f"{item.action} {item.record_type} {item.name} {item.address}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="ip-reporter",
+        description="Discover WAN/LAN IPv4, IPv6, HTTP/3 IPv4, and HTTP/3 IPv6 addresses.",
+    )
+    _add_discovery_options(parser)
+    subparsers = parser.add_subparsers(dest="command")
+
+    discover_parser = subparsers.add_parser("discover", help="discover addresses")
+    _add_discovery_options(discover_parser)
+
+    dns_parser = subparsers.add_parser("dns", help="Cloudflare DNS operations")
+    dns_subparsers = dns_parser.add_subparsers(dest="dns_command", required=True)
+    update_parser = dns_subparsers.add_parser("update", help="sync discovered addresses to records")
+    _add_dns_options(update_parser)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "dns":
+            if args.dns_command != "update":
+                parser.error("a DNS operation is required")
+            return _run_dns_update(args)
+        return _run_discover(args)
+    except Exception as exc:  # noqa: BLE001 - CLI must produce a clean one-line error
+        print(f"ip-reporter: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())