cf53 0.1.0__py3-none-any.whl

cf53/__init__.py

@@ -0,0 +1,17 @@
+from . import local, record
+from .diff import Diff
+from .local import load_zones_dir
+from .main import main
+from .record import Record, RecordType
+from .remote import load_remote_zones
+
+__all__ = [
+    "Diff",
+    "Record",
+    "RecordType",
+    "load_remote_zones",
+    "load_zones_dir",
+    "local",
+    "main",
+    "record",
+]

cf53/__main__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from .main import main
+
+main()

cf53/console.py

@@ -0,0 +1,3 @@
+from rich.console import Console
+
+console = Console()

cf53/diff.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Self
+
+from .console import console
+from .record import Record, RecordType
+
+
+@dataclass(frozen=True, slots=True)
+class Update:
+    initial: Record
+    desired: Record
+
+
+@dataclass(frozen=True, slots=True)
+class Diff:
+    domain: str
+    zone_id: str
+    to_create: set[Record]
+    to_update: set[Update]
+    to_delete: set[Record]
+    in_sync: set[Record]
+
+    @classmethod
+    def from_zones(
+        cls,
+        *,
+        domain: str,
+        zone_id: str,
+        local_zone: set[Record],
+        remote_zone: set[Record],
+    ) -> Self:
+        to_create = set()
+        to_update = set()
+        to_delete = set()
+        in_sync = set()
+
+        # lookup to match remote records semantically identical to local records, where
+        # records match in this way we can do an update rather than create/delete
+        unmatched_remote_records: dict[
+            tuple[RecordType, str, str, int | None], Record
+        ] = {_semantic_key(r): r for r in remote_zone}
+
+        # local records must be created or matched to a remote record to update in-place
+        for local_record in local_zone:
+            key = _semantic_key(local_record)
+
+            if matching_remote_record := unmatched_remote_records.get(key):
+                del unmatched_remote_records[key]
+
+                if local_record == matching_remote_record:
+                    in_sync.add(matching_remote_record)
+                else:
+                    to_update.add(
+                        Update(
+                            initial=matching_remote_record,
+                            desired=local_record,
+                        )
+                    )
+            else:
+                to_create.add(local_record)
+
+        to_delete = set(unmatched_remote_records.values())
+
+        return cls(
+            domain=domain,
+            zone_id=zone_id,
+            to_create=to_create,
+            to_update=to_update,
+            to_delete=to_delete,
+            in_sync=in_sync,
+        )
+
+    def print(self) -> None:
+        if not self:
+            console.print(f"✓ {self.domain}", style="dim white")
+            return
+
+        console.print(f"~ {self.domain}", style="bold blue")
+        for r in self.to_create:
+            self._print_record(r, icon="+", style="bold green")
+        for update in self.to_update:
+            r = update.desired
+            self._print_record(r, icon="~", style="bold yellow")
+        for r in self.to_delete:
+            self._print_record(r, icon="-", style="bold red")
+
+    def _print_record(self, r: Record, icon: str, style: str):
+        proxied = "    proxied"
+        if not r.proxied:
+            proxied = "not proxied"
+        priority = ""
+        if r.type == "mx":
+            priority = f"{r.priority:4} "
+        ttl = int(r.ttl)
+        if ttl == 1:
+            ttl = "auto"
+        console.print(f"  {icon} {r.type.upper():5} {r.name}", style=style)
+        console.print(f'    {proxied}  | {ttl:4} |  "{r.comment}"')
+        console.print(f"      {priority}{r.content}", style="italic")
+
+    def __bool__(self) -> bool:
+        return any((self.to_create, self.to_delete, self.to_update))
+
+
+def _semantic_key(record: Record) -> tuple[RecordType, str, str, int | None]:
+    return (record.type, record.name, record.content, record.priority)

cf53/local.py

@@ -0,0 +1,51 @@
+from collections.abc import Iterable
+from pathlib import Path
+import tomllib
+
+from .record import Record, RecordType
+
+
+def load_zones_dir(
+    *,
+    zones_dir: Path,
+    default_comment: str = "",
+    only_domains: Iterable[str] | None = None,
+) -> dict[str, set[Record]]:
+    """Map of domains to records in <zones_dir>/<domain>.toml"""
+    zones: dict[str, set[Record]] = {}
+    only_domains = set(only_domains or set())
+
+    for toml_file in zones_dir.glob("*.toml"):
+        domain = toml_file.stem
+
+        if only_domains and domain not in only_domains:
+            continue
+
+        with open(toml_file, "rb") as f:
+            toml = tomllib.load(f)
+
+        zones[toml_file.stem] = {
+            Record(
+                type=record_type,
+                name=_normalize_name(record["name"], domain),
+                content=f'"{record["content"]}"'
+                if record_type == "txt"
+                else record["content"],
+                ttl=record.get("ttl", 1),  # 1=auto
+                proxied=record.get("proxied", False),
+                comment=record.get("comment", default_comment),
+                priority=record.get("priority") if record_type == "mx" else None,
+            )
+            for record_type in RecordType
+            for record in toml.get(record_type.value, [])
+        }
+
+    return zones
+
+
+def _normalize_name(toml_name: str, domain: str) -> str:
+    if toml_name == "@":
+        return domain
+    if not toml_name.endswith(domain):
+        return f"{toml_name}.{domain}"
+    return toml_name

cf53/main.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+import asyncio
+import os
+from pathlib import Path
+
+import click
+from cloudflare import AsyncCloudflare
+
+from .console import console
+from .diff import Diff
+from .local import load_zones_dir
+from .reconcile import reconcile_diffs
+from .remote import load_remote_zones
+
+
+@click.command()
+@click.argument("zones_dir", type=click.Path(exists=True, file_okay=False))
+@click.option(
+    "--domain",
+    "domains",
+    multiple=True,
+    help="Only process these domains (can be specified multiple times)",
+)
+@click.option(
+    "--default-comment",
+    "default_comment",
+    help="Comment to append to any record not explicitly commented",
+)
+def main(zones_dir: str, domains: tuple[str, ...], default_comment: str = "") -> None:
+    zones_dir_path = Path(zones_dir)
+    client = _client()
+
+    with console.status("fetching zones..."):
+        local_zones = load_zones_dir(
+            zones_dir=zones_dir_path,
+            default_comment=default_comment,
+            only_domains=domains,
+        )
+        remote_zones = asyncio.run(
+            load_remote_zones(client=client, domains=set(local_zones.keys()))
+        )
+
+    diffs = [
+        Diff.from_zones(
+            domain=domain,
+            zone_id=zone_id,
+            local_zone=local_zones[domain],
+            remote_zone=remote_zone,
+        )
+        for (domain, zone_id), remote_zone in remote_zones.items()
+    ]
+
+    for diff in diffs:
+        diff.print()
+
+    if any(diffs) and _user_confirmation():
+        reconcile_diffs(diffs, client)
+
+
+def _user_confirmation() -> bool:
+    while True:
+        response = input("Apply these changes? [y/N] ").strip().lower()
+        if response in ("y", "yes"):
+            return True
+        elif response in ("n", "no", ""):
+            return False
+
+
+def _client() -> AsyncCloudflare:
+    if not (api_token := os.environ.get("CLOUDFLARE_API_TOKEN")):
+        raise RuntimeError("CLOUDFLARE_API_TOKEN must be defined")
+    return AsyncCloudflare(api_token=api_token)

cf53/reconcile.py

@@ -0,0 +1,68 @@
+import asyncio
+from collections.abc import Iterable
+
+from cloudflare import AsyncCloudflare
+
+from .diff import Diff
+
+
+async def _reconcile_diff(diff: Diff, client: AsyncCloudflare) -> None:
+    async with asyncio.TaskGroup() as tg:
+        tg.create_task(_apply_creates_async(diff, client))
+        tg.create_task(_apply_updates_async(diff, client))
+        tg.create_task(_apply_deletes_async(diff, client))
+
+
+def reconcile_diffs(diffs: Iterable[Diff], client: AsyncCloudflare) -> None:
+    async def main():
+        async with asyncio.TaskGroup() as tg:
+            for diff in diffs:
+                tg.create_task(_reconcile_diff(diff, client))
+
+    asyncio.run(main())
+
+
+async def _apply_creates_async(diff: Diff, client: AsyncCloudflare) -> None:
+    for record in diff.to_create:
+        record_data = {
+            "type": record.type.value,
+            "name": record.name,
+            "content": record.content,
+            "ttl": record.ttl,
+            "proxied": record.proxied,
+            "comment": record.comment,
+        }
+        if record.priority is not None:
+            record_data["priority"] = record.priority
+
+        await client.dns.records.create(zone_id=diff.zone_id, **record_data)  # type: ignore[no-matching-overload]
+
+
+async def _apply_updates_async(diff: Diff, client: AsyncCloudflare) -> None:
+    for update in diff.to_update:
+        record_data = {
+            "type": update.desired.type.value,
+            "name": update.desired.name,
+            "content": update.desired.content,
+            "ttl": update.desired.ttl,
+            "proxied": update.desired.proxied,
+            "comment": update.desired.comment,
+        }
+
+        if update.desired.priority is not None:
+            record_data["priority"] = update.desired.priority
+
+        await client.dns.records.update(  # type: ignore[no-matching-overload]
+            update.initial.cloudflare_id,
+            zone_id=diff.zone_id,
+            **record_data,
+        )
+
+
+async def _apply_deletes_async(diff: Diff, client: AsyncCloudflare) -> None:
+    for record in diff.to_delete:
+        assert record.cloudflare_id
+        await client.dns.records.delete(
+            record.cloudflare_id,
+            zone_id=diff.zone_id,
+        )

cf53/record.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum, auto
+from typing import Any
+
+
+class RecordType(StrEnum):
+    a = auto()
+    aaaa = auto()
+    mx = auto()
+    txt = auto()
+    cname = auto()
+
+
+@dataclass(frozen=True, slots=True)
+class Record:
+    type: RecordType
+    name: str
+    content: str
+    ttl: int
+    proxied: bool
+    comment: str
+    priority: int | None = None
+    cloudflare_id: str | None = None
+
+    def __post_init__(self) -> None:
+        if self.priority and not self.type == "mx":
+            raise ValueError("priority can only be set for mx records")
+
+    def __eq__(self, other: Any) -> bool:
+        """Equality should ignore a `None` cloudflare_id."""
+        if not isinstance(other, Record):
+            return False
+        return (
+            self.type == other.type
+            and self.name == other.name
+            and self.content == other.content
+            and self.ttl == other.ttl
+            and self.proxied == other.proxied
+            and self.comment == other.comment
+            and self.priority == other.priority
+            and (
+                self.cloudflare_id == other.cloudflare_id
+                or self.cloudflare_id is None
+                or other.cloudflare_id is None
+            )
+        )

cf53/remote.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import asyncio
+
+from cloudflare import AsyncCloudflare
+
+from .record import Record, RecordType
+
+
+async def load_remote_zones(
+    client: AsyncCloudflare, domains: set[str]
+) -> dict[tuple[str, str], set[Record]]:
+    """Map of (domain, zone_id) to records in cloudflare"""
+    domain_to_zone_id = {
+        zone.name: zone.id
+        for zone in _unpage(await client.zones.list())
+        if zone.name in domains
+    }
+
+    tasks = []
+    async with asyncio.TaskGroup() as tg:
+        for domain, zone_id in domain_to_zone_id.items():
+            task = tg.create_task(_load_remote_zone(client, domain, zone_id))
+            tasks.append(task)
+
+    remote_zones: dict[tuple[str, str], set[Record]] = {}
+    for task in tasks:
+        domain, records = task.result()
+        remote_zones[(domain, domain_to_zone_id[domain])] = records
+
+    return remote_zones
+
+
+async def _load_remote_zone(
+    client, domain: str, zone_id: str
+) -> tuple[str, set[Record]]:
+    records_page = await client.dns.records.list(zone_id=zone_id)
+    return (
+        domain,
+        {
+            Record(
+                type=RecordType(record.type.lower()),
+                name=record.name,
+                content=record.content,
+                ttl=record.ttl,
+                proxied=record.proxied,
+                comment=record.comment,
+                priority=int(record.priority) if hasattr(record, "priority") else None,
+                cloudflare_id=record.id,
+            )
+            for record in _unpage(records_page)
+        },
+    )
+
+
+def _unpage(page):
+    for item in page:
+        values_type, values = item
+        if values_type != "result":
+            continue
+        yield from values

cf53-0.1.0.dist-info/METADATA

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: cf53
+Version: 0.1.0
+Summary: Cloudflare DNS client for humans
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.3.1
+Requires-Dist: cloudflare>=4.3.1
+Requires-Dist: rich>=14.2.0
+
+# cf53
+
+A human-oriented cloudflare DNS updater. This provide a way to IaC cloudflare DNS records with a simple toml file, and get a good visual feedback of the diffs to make it actual.
+
+Think terraform, but smarter. No need to keep a local state or copy/paste ids around, just say what records you want, provide an API token, that's it.

cf53-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+cf53/__init__.py,sha256=ha6P1ewET-Ry0vAHGAAXAtpwFtZVK5j2BtPvUlsaDn0,330
+cf53/__main__.py,sha256=yJhoRW6QD7AkgTIh5zXngIO8HjbJek4rgBnkzhCym88,67
+cf53/console.py,sha256=UpMqeJ0C8i0pkue1AHnnyyX0bFJ9zZeJ7HBR6yhuA8A,54
+cf53/diff.py,sha256=5gkGXZJgXRHZ8Gp47jhwwe3aiaAJsJCx1y4aZFEK1IM,3374
+cf53/local.py,sha256=UyUtqPQARwnDO4tr-0FSuotW35fIzMKWs1NsB1lLdk8,1538
+cf53/main.py,sha256=lrGgIRobIB9_Gh21UrMqpqm-2yzwy6QxEqn5-HGB7as,2013
+cf53/reconcile.py,sha256=5Ae30CwX5mtHLjpAkgwcWOuXPd9jeg9leqrFcciVCkI,2238
+cf53/record.py,sha256=lfYtRqrkXSTOm1VzshxHEJlZJnbeVCtpMgVWhgdww8Y,1302
+cf53/remote.py,sha256=0Rj4dZDbcHzYb8HvSR6cazpHyU4reOFsSuX4FUwHyRk,1729
+cf53-0.1.0.dist-info/METADATA,sha256=EF1R0tO0HrWATqV2lk93H8IjhL3yugwCpd-diOTpmxI,582
+cf53-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+cf53-0.1.0.dist-info/top_level.txt,sha256=q9lyH7cRV3yAHA7thCX_RLr3Xo_u0a7a7Ajp4ijhbp8,5
+cf53-0.1.0.dist-info/RECORD,,

cf53-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cf53-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+cf53