granny-devops 0.4.0__py3-none-any.whl

granny/dns/factory.py

@@ -0,0 +1,72 @@
+"""DNS provider factory — name -> DNSProvider instance.
+
+Providers are instantiated lazily so importing :mod:`granny.dns` does not
+trigger credential lookups until someone actually wants to use a provider.
+"""
+
+from collections.abc import Callable
+
+from granny.dns.base import DNSProvider
+
+
+def _bunny() -> DNSProvider:
+    from granny.dns.bunny import BunnyDNSProvider
+
+    return BunnyDNSProvider()
+
+
+def _cloudflare() -> DNSProvider:
+    from granny.dns.cloudflare import CloudflareDNSProvider
+
+    return CloudflareDNSProvider()
+
+
+def _hetzner() -> DNSProvider:
+    from granny.dns.hetzner import HetznerDNSProvider
+
+    return HetznerDNSProvider()
+
+
+def _desec() -> DNSProvider:
+    from granny.dns.desec import DeSECDNSProvider
+
+    return DeSECDNSProvider()
+
+
+def _cloudns() -> DNSProvider:
+    from granny.dns.cloudns import ClouDNSDNSProvider
+
+    return ClouDNSDNSProvider()
+
+
+def _manual() -> DNSProvider:
+    from granny.dns.manual import ManualDNSProvider
+
+    return ManualDNSProvider()
+
+
+_PROVIDERS: dict[str, Callable[[], DNSProvider]] = {
+    "bunny": _bunny,
+    "cloudflare": _cloudflare,
+    "hetzner": _hetzner,
+    "desec": _desec,
+    "cloudns": _cloudns,
+    "manual": _manual,
+}
+
+
+def provider_choices() -> list[str]:
+    """Return the list of provider names for argparse/click."""
+    return sorted(_PROVIDERS.keys())
+
+
+def get_provider(name: str) -> DNSProvider:
+    """Instantiate the named provider. Raises ``ValueError`` if unknown."""
+    key = (name or "").strip().lower()
+    factory = _PROVIDERS.get(key)
+    if factory is None:
+        raise ValueError(
+            f"Unknown DNS provider: {name!r}. "
+            f"Choices: {', '.join(provider_choices())}"
+        )
+    return factory()

granny/dns/hetzner.py

@@ -0,0 +1,165 @@
+"""Hetzner DNS provider — CRUD via the new Cloud API.
+
+The legacy ``dns.hetzner.com`` API (``Auth-API-Token``) is deprecated. This
+adapter uses the Hetzner Cloud API (``api.hetzner.cloud/v1``, Bearer auth,
+rrset-based record management). One rrset bundles all records of the same
+``(name, type)`` pair, so individual ``DNSRecord`` rows are synthesised from
+each rrset's ``records`` list, with ``id`` formatted as ``"{name}/{type}"``.
+"""
+
+import logging
+
+import requests
+
+from granny.credentials.secrets import get_secret
+from granny.dns.base import DNSProvider
+from granny.dns.records import DNSRecord
+
+logger = logging.getLogger(__name__)
+
+API_BASE = "https://api.hetzner.cloud/v1"
+
+
+class HetznerDNSProvider(DNSProvider):
+    name = "hetzner"
+
+    def __init__(self, api_token: str | None = None) -> None:
+        api_token = api_token or get_secret("HETZNER_DNS_API_TOKEN")
+        if not api_token:
+            raise ValueError("HETZNER_DNS_API_TOKEN not set (env or vault).")
+        self.session = requests.Session()
+        self.session.headers.update(
+            {"Authorization": f"Bearer {api_token}", "Content-Type": "application/json"}
+        )
+        self._zone_cache: dict[str, str] = {}
+        self._ns_cache: dict[str, list[str]] = {}
+
+    def _request(
+        self, method: str, path: str, *, params: dict | None = None, json: dict | None = None
+    ) -> dict:
+        url = f"{API_BASE}{path}"
+        resp = getattr(self.session, method.lower())(
+            url, params=params, json=json, timeout=30
+        )
+        if resp.status_code >= 400:
+            raise RuntimeError(
+                f"Hetzner DNS {method} {path} failed: {resp.status_code} {resp.text}"
+            )
+        if resp.status_code == 204 or not resp.text:
+            return {}
+        return resp.json()
+
+    def get_zone_id(self, zone_name: str) -> str:
+        if zone_name in self._zone_cache:
+            return self._zone_cache[zone_name]
+        body = self._request("GET", "/zones", params={"name": zone_name})
+        for zone in body.get("zones") or []:
+            if zone.get("name") == zone_name:
+                zone_id = str(zone["id"])
+                self._zone_cache[zone_name] = zone_id
+                ns = zone.get("authoritative_nameservers", {}).get("assigned", [])
+                self._ns_cache[zone_name] = [n.rstrip(".") for n in ns]
+                return zone_id
+        raise RuntimeError(f"Hetzner DNS zone not found: {zone_name}")
+
+    def get_nameservers(self, zone_name: str) -> list[str]:
+        self.get_zone_id(zone_name)
+        return list(self._ns_cache.get(zone_name, []))
+
+    def list_records(
+        self,
+        zone_id: str,
+        name: str | None = None,
+        record_type: str | None = None,
+    ) -> list[DNSRecord]:
+        body = self._request("GET", f"/zones/{zone_id}/rrsets")
+        out: list[DNSRecord] = []
+        rtype = record_type.upper() if record_type else None
+        for rrset in body.get("rrsets") or []:
+            if name is not None and rrset.get("name") != name:
+                continue
+            if rtype is not None and rrset.get("type") != rtype:
+                continue
+            ttl = rrset.get("ttl") or 300
+            for rec in rrset.get("records") or []:
+                out.append(
+                    DNSRecord(
+                        name=rrset.get("name", ""),
+                        type=rrset.get("type", ""),
+                        value=rec.get("value", ""),
+                        ttl=int(ttl),
+                        id=rrset.get("id"),  # "{name}/{type}"
+                        provider_data=rrset,
+                    )
+                )
+        return out
+
+    def _short_name(self, name: str) -> str:
+        return "@" if not name or name == "@" else name
+
+    def _normalise_value(self, record_type: str, value: str) -> str:
+        # CNAME / NS / MX targets must be FQDN with trailing dot.
+        if record_type.upper() in ("CNAME", "NS"):
+            return value if value.endswith(".") else f"{value}."
+        return value
+
+    def create_record(
+        self,
+        zone_id: str,
+        name: str,
+        record_type: str,
+        value: str,
+        ttl: int = 300,
+        proxied: bool = False,
+    ) -> DNSRecord:
+        short = self._short_name(name)
+        rtype = record_type.upper()
+        normalised = self._normalise_value(rtype, value)
+        payload = {
+            "name": short,
+            "type": rtype,
+            "ttl": ttl,
+            "records": [{"value": normalised}],
+        }
+        body = self._request("POST", f"/zones/{zone_id}/rrsets", json=payload)
+        rrset = body.get("rrset") or {}
+        logger.info("Hetzner DNS: created %s %s -> %s", rtype, short, normalised)
+        return DNSRecord(
+            name=rrset.get("name", short),
+            type=rrset.get("type", rtype),
+            value=normalised,
+            ttl=int(rrset.get("ttl") or ttl),
+            id=rrset.get("id", f"{short}/{rtype}"),
+            provider_data=rrset,
+        )
+
+    def update_record(
+        self,
+        zone_id: str,
+        record_id: str,
+        name: str,
+        record_type: str,
+        value: str,
+        ttl: int = 300,
+        proxied: bool = False,
+    ) -> DNSRecord:
+        short = self._short_name(name)
+        rtype = record_type.upper()
+        rrset_id = record_id if "/" in str(record_id) else f"{short}/{rtype}"
+        normalised = self._normalise_value(rtype, value)
+        payload = {"ttl": ttl, "records": [{"value": normalised}]}
+        body = self._request("PUT", f"/zones/{zone_id}/rrsets/{rrset_id}", json=payload)
+        rrset = body.get("rrset") or {}
+        return DNSRecord(
+            name=rrset.get("name", short),
+            type=rrset.get("type", rtype),
+            value=normalised,
+            ttl=int(rrset.get("ttl") or ttl),
+            id=rrset.get("id", rrset_id),
+            provider_data=rrset,
+        )
+
+    def delete_record(self, zone_id: str, record_id: str) -> None:
+        # record_id is the rrset id "{name}/{type}"
+        self._request("DELETE", f"/zones/{zone_id}/rrsets/{record_id}")
+        logger.info("Hetzner DNS: deleted rrset %s", record_id)

granny/dns/manual.py

@@ -0,0 +1,64 @@
+"""ManualDNSProvider — no-op provider that prints instructions.
+
+Use when the authoritative DNS lives with a provider granny does not
+support via API (e.g. easyname's web-UI-only DNS). Every mutating call
+logs the record the operator must configure manually.
+"""
+
+import logging
+
+from granny.dns.base import DNSProvider
+from granny.dns.records import DNSRecord
+
+logger = logging.getLogger(__name__)
+
+
+class ManualDNSProvider(DNSProvider):
+    name = "manual"
+
+    def get_zone_id(self, zone_name: str) -> str:
+        return zone_name
+
+    def get_nameservers(self, zone_name: str) -> list[str]:
+        return []
+
+    def list_records(
+        self,
+        zone_id: str,
+        name: str | None = None,
+        record_type: str | None = None,
+    ) -> list[DNSRecord]:
+        logger.warning("ManualDNSProvider: cannot list records for %s", zone_id)
+        return []
+
+    def _announce(self, action: str, record: DNSRecord) -> None:
+        logger.warning("=" * 70)
+        logger.warning("MANUAL DNS ACTION REQUIRED (%s)", action)
+        logger.warning("Configure at your DNS provider:")
+        logger.warning("  %s", record)
+        logger.warning("=" * 70)
+
+    def create_record(
+        self,
+        zone_id: str,
+        name: str,
+        record_type: str,
+        value: str,
+        ttl: int = 300,
+        proxied: bool = False,
+    ) -> DNSRecord:
+        short = "@" if not name or name == "@" else name
+        record = DNSRecord(
+            name=short,
+            type=record_type.upper(),
+            value=value,
+            ttl=ttl,
+            fqdn=(
+                f"{short}.{zone_id}" if short != "@" else zone_id
+            ),
+        )
+        self._announce("create", record)
+        return record
+
+    def delete_record(self, zone_id: str, record_id: str) -> None:
+        logger.warning("MANUAL DNS ACTION REQUIRED (delete): remove record %s", record_id)

granny/dns/records.py

@@ -0,0 +1,29 @@
+"""DNSRecord — provider-agnostic record representation."""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class DNSRecord:
+    """A DNS record as returned by any provider.
+
+    ``name`` is always the short name (subname) relative to the zone — ``""``
+    or ``"@"`` for apex, ``"api"`` for ``api.example.com``. ``fqdn`` carries
+    the full name for display. ``id`` is the provider-specific record id used
+    for updates and deletes. ``provider_data`` holds the raw provider payload
+    for anything the generic shape doesn't capture (Cloudflare ``proxied``,
+    Bunny ``Disabled``, etc.).
+    """
+
+    name: str
+    type: str
+    value: str
+    ttl: int = 300
+    id: str | None = None
+    fqdn: str | None = None
+    provider_data: dict[str, Any] = field(default_factory=dict)
+
+    def __str__(self) -> str:
+        display = self.fqdn or self.name or "@"
+        return f"{self.type:<6} {display:<40} {self.value}  (ttl={self.ttl})"

granny/docker/__init__.py

@@ -0,0 +1,5 @@
+"""Docker helpers: multi-arch base image builds with deterministic tagging."""
+
+from granny.docker.build_base import build_base_image, compute_deps_hash
+
+__all__ = ["build_base_image", "compute_deps_hash"]

granny/docker/build_base.py

@@ -0,0 +1,204 @@
+"""Build and push a multi-arch Docker base image with deterministic tagging.
+
+Pattern:
+  1. Hash the files that affect the base image (deps, Dockerfile, etc.) into
+     a short DEPS_HASH used as an image tag.
+  2. Check if `<image>:<hash>` already exists in the registry. If yes, skip.
+  3. Otherwise build multi-arch via `docker buildx` and push.
+
+Secrets (GitLab PyPI token, etc.) are passed via BuildKit `--mount=type=secret`
+so they never enter image history. Credentials needed for `docker login` come
+from granny.credentials (env-var resolution), not from .netrc.
+
+Typical usage from another project's CLAUDE.md:
+
+    granny docker build-base \\
+        --context T:\\projects\\LuLarge\\icaap-climaterisk \\
+        --dockerfile Dockerfile.base \\
+        --image budelius/icaap-climaterisk-base \\
+        --hash-file environment.docker.yml \\
+        --hash-file pyproject.toml \\
+        --hash-file Dockerfile.base \\
+        --secret gitlab_token=GITLAB_PYPI_PASSWORD
+"""
+from __future__ import annotations
+
+import hashlib
+import logging
+import os
+import subprocess
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class BuildBaseConfig:
+    """Inputs for a multi-arch base image build."""
+
+    context: Path
+    dockerfile: Path
+    image: str
+    hash_files: list[Path] = field(default_factory=list)
+    platforms: str = "linux/amd64,linux/arm64"
+    builder: str = "granny-multiarch"
+    # secret_id -> env var name (value read from env; env should be populated
+    # via granny.credentials.load_secrets_into_env before calling).
+    secrets: dict[str, str] = field(default_factory=dict)
+    force: bool = False
+    hash_length: int = 16
+
+
+def compute_deps_hash(files: list[Path], length: int = 16) -> str:
+    """Compute a short hex sha256 over the concatenated raw bytes of files.
+
+    Order matters - pass files in a stable order. Matches the shell equivalent:
+        cat <files> | sha256sum | cut -c1-<length>
+    """
+    if not files:
+        raise ValueError("hash_files must not be empty")
+    h = hashlib.sha256()
+    for path in files:
+        h.update(path.read_bytes())
+    return h.hexdigest()[:length]
+
+
+def _run(cmd: list[str], check: bool = True, capture: bool = False) -> subprocess.CompletedProcess:
+    """Run a subprocess and log it (without leaking secret flag values)."""
+    # Redact anything after --build-arg or --secret for logging only
+    safe_cmd = []
+    i = 0
+    while i < len(cmd):
+        token = cmd[i]
+        safe_cmd.append(token)
+        if token in ("--build-arg", "--secret") and i + 1 < len(cmd):
+            next_tok = cmd[i + 1]
+            # For --secret id=foo,src=/tmp/xyz keep as-is (src is a file path, not a value)
+            # For --build-arg KEY=VALUE, redact VALUE
+            if token == "--build-arg" and "=" in next_tok:
+                key, _ = next_tok.split("=", 1)
+                safe_cmd.append(f"{key}=***")
+            else:
+                safe_cmd.append(next_tok)
+            i += 2
+            continue
+        i += 1
+    logger.debug("run: %s", " ".join(safe_cmd))
+    return subprocess.run(
+        cmd,
+        check=check,
+        capture_output=capture,
+        text=True,
+    )
+
+
+def _manifest_exists(image_ref: str) -> bool:
+    """Return True if the image exists in the remote registry."""
+    try:
+        result = subprocess.run(
+            ["docker", "manifest", "inspect", image_ref],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        return result.returncode == 0
+    except FileNotFoundError:
+        raise RuntimeError("docker CLI not found on PATH")
+
+
+def _ensure_builder(name: str) -> None:
+    """Create a docker-container buildx builder if it doesn't exist."""
+    result = subprocess.run(
+        ["docker", "buildx", "ls"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode == 0 and name in result.stdout:
+        subprocess.run(["docker", "buildx", "use", name], check=False, capture_output=True)
+        return
+    logger.info("Creating buildx builder %s", name)
+    subprocess.run(
+        ["docker", "buildx", "create", "--name", name, "--driver", "docker-container", "--use"],
+        check=True,
+        capture_output=True,
+    )
+    subprocess.run(["docker", "buildx", "inspect", "--bootstrap"], check=True, capture_output=True)
+
+
+def build_base_image(config: BuildBaseConfig) -> tuple[str, bool]:
+    """Build and push a multi-arch base image.
+
+    Returns:
+        (deps_hash, was_built): tuple of the computed hash and whether a new
+        build was actually performed (False means it already existed in registry).
+    """
+    # Resolve files relative to context
+    ctx = config.context.resolve()
+    if not ctx.is_dir():
+        raise FileNotFoundError(f"Context directory not found: {ctx}")
+
+    dockerfile = (ctx / config.dockerfile).resolve() if not config.dockerfile.is_absolute() else config.dockerfile
+    if not dockerfile.is_file():
+        raise FileNotFoundError(f"Dockerfile not found: {dockerfile}")
+
+    hash_paths = [
+        (ctx / p).resolve() if not p.is_absolute() else p
+        for p in config.hash_files
+    ]
+    for p in hash_paths:
+        if not p.is_file():
+            raise FileNotFoundError(f"Hash file not found: {p}")
+
+    deps_hash = compute_deps_hash(hash_paths, length=config.hash_length)
+    tagged = f"{config.image}:{deps_hash}"
+    latest = f"{config.image}:latest"
+    logger.info("DEPS_HASH=%s", deps_hash)
+
+    if not config.force and _manifest_exists(tagged):
+        logger.info("%s already exists in registry - skipping build", tagged)
+        return deps_hash, False
+
+    _ensure_builder(config.builder)
+
+    # Write each secret to a tempfile so BuildKit can mount them without
+    # exposing values on the command line.
+    secret_files: dict[str, Path] = {}
+    try:
+        for secret_id, env_var in config.secrets.items():
+            value = os.environ.get(env_var)
+            if value is None:
+                raise RuntimeError(
+                    f"Required secret env var {env_var!r} is not set. "
+                    f"Ensure granny.credentials.load_secrets_into_env() was called."
+                )
+            tmp = Path(tempfile.mkstemp(prefix=f"granny-secret-{secret_id}-")[1])
+            tmp.write_text(value, encoding="utf-8")
+            secret_files[secret_id] = tmp
+
+        cmd: list[str] = [
+            "docker", "buildx", "build",
+            "--builder", config.builder,
+            "--platform", config.platforms,
+            "-t", tagged,
+            "-t", latest,
+            "-f", str(dockerfile),
+        ]
+        for secret_id, path in secret_files.items():
+            cmd += ["--secret", f"id={secret_id},src={path}"]
+        cmd += [
+            "--cache-from", f"type=registry,ref={config.image}:cache",
+            "--push",
+            str(ctx),
+        ]
+        _run(cmd)
+    finally:
+        for p in secret_files.values():
+            try:
+                p.unlink()
+            except OSError:
+                pass
+
+    return deps_hash, True

granny/edge/__init__.py

@@ -0,0 +1,5 @@
+"""Edge scripting clients — Bunny Edge Scripting."""
+
+from granny.edge.bunny import BunnyEdgeScriptClient
+
+__all__ = ["BunnyEdgeScriptClient"]

granny/edge/bunny.py

@@ -0,0 +1,147 @@
+"""Bunny Edge Scripting client — script CRUD, code deploy, variables, publish.
+
+Lifted from ``tools/create/setup_bunny_edge_script.py:BunnyEdgeScriptClient``.
+"""
+
+import logging
+from typing import Any
+
+import requests
+
+from granny.credentials.secrets import get_bunny_api_key
+
+logger = logging.getLogger(__name__)
+
+API_BASE = "https://api.bunny.net"
+EDGE_SCRIPTING_API = "/api/v1/edgescripting"
+
+SCRIPT_TYPES = {
+    "standalone": 0,
+    "middleware": 3,
+}
+
+
+class BunnyEdgeScriptClient:
+    """Bunny.net Edge Scripting management.
+
+    API reference: https://docs.bunny.net/docs/edge-scripting-overview
+    """
+
+    def __init__(self, api_key: str | None = None, customer: str | None = None) -> None:
+        api_key = api_key or get_bunny_api_key(customer)
+        if not api_key:
+            raise ValueError("BUNNY_API_KEY not set (env or vault).")
+        self.session = requests.Session()
+        self.session.headers.update(
+            {
+                "AccessKey": api_key,
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+            }
+        )
+
+    def _request(self, method: str, path: str, data: Any = None) -> Any:
+        url = f"{API_BASE}{path}"
+        kwargs: dict = {"timeout": 60}
+        if data is not None:
+            kwargs["json"] = data
+        resp = getattr(self.session, method.lower())(url, **kwargs)
+        if resp.status_code >= 400:
+            raise RuntimeError(
+                f"Bunny Edge {method} {path}: {resp.status_code} {resp.text[:500]}"
+            )
+        if resp.status_code == 204 or not resp.text:
+            return {}
+        return resp.json()
+
+    # -- Script CRUD -----------------------------------------------------------
+
+    def list_scripts(self, search: str | None = None) -> list[dict]:
+        params = f"?search={requests.utils.quote(search)}" if search else ""
+        result = self._request("GET", f"{EDGE_SCRIPTING_API}{params}")
+        if isinstance(result, list):
+            return result
+        return result.get("Items", result.get("items", []))
+
+    def find_script(self, name: str) -> dict | None:
+        for s in self.list_scripts(search=name):
+            if s.get("Name") == name:
+                return s
+        return None
+
+    def get_script(self, script_id: int) -> dict:
+        return self._request("GET", f"{EDGE_SCRIPTING_API}/{script_id}")
+
+    def create_script(
+        self,
+        name: str,
+        *,
+        code: str = "",
+        script_type: str = "standalone",
+        create_linked_pull_zone: bool = True,
+        linked_pull_zone_name: str | None = None,
+    ) -> dict:
+        type_id = SCRIPT_TYPES.get(script_type, 0)
+        payload: dict[str, Any] = {"Name": name, "ScriptType": type_id}
+        if code:
+            payload["Code"] = code
+        if type_id == 0:
+            payload["CreateLinkedPullZone"] = create_linked_pull_zone
+            if linked_pull_zone_name:
+                payload["LinkedPullZoneName"] = linked_pull_zone_name
+        result = self._request("POST", EDGE_SCRIPTING_API, payload)
+        logger.info("Created edge script %s (ID %s)", name, result.get("Id"))
+        return result
+
+    def delete_script(
+        self, script_id: int, *, delete_linked_pull_zones: bool = False
+    ) -> None:
+        flag = "true" if delete_linked_pull_zones else "false"
+        self._request(
+            "DELETE",
+            f"{EDGE_SCRIPTING_API}/{script_id}?deleteLinkedPullZones={flag}",
+        )
+
+    # -- Code deployment -------------------------------------------------------
+
+    def get_code(self, script_id: int) -> str:
+        result = self._request("GET", f"{EDGE_SCRIPTING_API}/{script_id}/code")
+        return result.get("Code", "")
+
+    def deploy_code(self, script_id: int, code: str) -> dict:
+        logger.info("Deploying code to script %s (%d bytes)", script_id, len(code))
+        return self._request(
+            "POST", f"{EDGE_SCRIPTING_API}/{script_id}/code", {"Code": code}
+        )
+
+    # -- Releases --------------------------------------------------------------
+
+    def list_releases(self, script_id: int) -> list[dict]:
+        result = self._request("GET", f"{EDGE_SCRIPTING_API}/{script_id}/releases")
+        if isinstance(result, list):
+            return result
+        return result.get("Items", result.get("items", []))
+
+    def publish(self, script_id: int) -> None:
+        self._request("POST", f"{EDGE_SCRIPTING_API}/{script_id}/publish", {})
+        logger.info("Published edge script %s", script_id)
+
+    # -- Variables (env + secrets share the same endpoint) ----------------------
+
+    def list_variables(self, script_id: int) -> list[dict]:
+        detail = self.get_script(script_id)
+        return detail.get("EdgeScriptVariables", [])
+
+    def upsert_variable(
+        self, script_id: int, name: str, value: str, *, required: bool = True
+    ) -> dict:
+        return self._request(
+            "PUT",
+            f"{EDGE_SCRIPTING_API}/{script_id}/variables",
+            {"Name": name, "DefaultValue": value, "Required": required},
+        )
+
+    def delete_variable(self, script_id: int, var_id: int) -> None:
+        self._request(
+            "DELETE", f"{EDGE_SCRIPTING_API}/{script_id}/variables/{var_id}"
+        )