nullforge 0.1.0__py3-none-any.whl

nullforge/smithy/monitoring/nezha/deploy.py

@@ -0,0 +1,81 @@
+"""Nezha agent deploy orchestration."""
+
+from pyinfra.context import host
+from pyinfra.facts.files import File
+from pyinfra.facts.server import Hostname
+from pyinfra.operations import python, server, systemd
+
+from nullforge.molds.monitoring import NezhaBackend
+from nullforge.molds.system import SystemMold
+from nullforge.smithy.http import CURL_ARGS_STR
+from nullforge.smithy.versions import STATIC_URLS
+
+from .agent import agent_uuid_for_hostname, build_nezha_install_command
+from .dashboard import rename_nezha_server, server_name_matches
+
+
+def _resolve_hostname(cfg: NezhaBackend) -> str:
+    system: SystemMold = host.data.system
+    if isinstance(system.hostname, str) and system.hostname:
+        return system.hostname
+
+    fact = host.get_fact(Hostname)
+    if isinstance(fact, str) and fact:
+        return fact
+    return cfg.layout.systemd_service_name
+
+
+def deploy_nezha(cfg: NezhaBackend) -> None:
+    """Deploy Nezha agent and align dashboard name with hostname."""
+
+    layout = cfg.layout
+    hostname = _resolve_hostname(cfg)
+    agent_uuid = agent_uuid_for_hostname(hostname, namespace=cfg.uuid_namespace)
+
+    if not host.get_fact(File, layout.config_path):
+        install_command = build_nezha_install_command(
+            install_url=STATIC_URLS["nezha_agent_install"],
+            curl_args=CURL_ARGS_STR,
+            server=cfg.server,
+            tls=cfg.tls,
+            client_secret=cfg.client_secret,
+            agent_uuid=agent_uuid,
+            disable_auto_update=cfg.disable_auto_update,
+            disable_command_execute=cfg.disable_command_execute,
+        )
+        server.shell(
+            name="Install Nezha agent",
+            commands=[install_command],
+            _sudo=True,
+            _retries=3,
+            _retry_delay=10,
+        )
+
+    systemd.service(
+        name="Ensure Nezha agent is running",
+        service=layout.systemd_service_name,
+        running=True,
+        enabled=True,
+        _sudo=True,
+    )
+
+    if not cfg.set_name_to_hostname:
+        return
+
+    if server_name_matches(
+        dashboard_url=cfg.dashboard_url,
+        api_token=cfg.api_token,
+        agent_uuid=agent_uuid,
+        desired_name=hostname,
+    ):
+        host.noop(f"Nezha dashboard already names {agent_uuid} '{hostname}'")
+        return
+
+    python.call(
+        name="Set Nezha dashboard name to hostname",
+        function=rename_nezha_server,
+        dashboard_url=cfg.dashboard_url,
+        api_token=cfg.api_token,
+        agent_uuid=agent_uuid,
+        desired_name=hostname,
+    )

nullforge/smithy/network.py

@@ -0,0 +1,95 @@
+"""Network utilities for NullForge."""
+
+import re
+
+from pyinfra.context import host
+from pyinfra.facts.files import FileContents
+from pyinfra.facts.server import Command, KernelModules
+
+
+def conntrack_max_for(ram_mb: int) -> int:
+    """Cap conntrack to ~2% of RAM as a backpressure ceiling (~300 B/entry)."""
+
+    entries = int(ram_mb * 1024 * 1024 * 0.02 / 300)
+    return max(16384, min(entries, 512 * 1024))
+
+
+def module_loaded(module: str) -> bool:
+    """Return True if named kernel module is currently loaded."""
+
+    return module in _loaded_kernel_modules()
+
+
+def _loaded_kernel_modules() -> dict[str, dict]:
+    cache_key = "_nullforge_kernel_modules"
+    if hasattr(host.data, cache_key):
+        return getattr(host.data, cache_key)
+
+    modules: dict[str, dict] = host.get_fact(KernelModules) or {}
+
+    setattr(host.data, cache_key, modules)
+    return modules
+
+
+_TUNNEL_IFACE_RE = re.compile(
+    r"^(?:warp|tun\d*|tap\d*|wg\d*|zt[0-9a-f]*|tailscale|ts\d|"
+    r"docker\d*|br-[0-9a-f]+|veth[0-9a-f]+|cni\d*|cali[0-9a-f]+|"
+    r"flannel|weave|ipip|sit|gre|ip6tnl|ip6gre)"
+)
+
+
+def _ipv6_grub_disabled() -> bool:
+    """Return True if GRUB is configured with ipv6.disable=1."""
+
+    cache_key = "_nullforge_ipv6_grub_disabled"
+    if hasattr(host.data, cache_key):
+        return getattr(host.data, cache_key)
+
+    grub_contents = host.get_fact(FileContents, path="/etc/default/grub") or []
+    disabled = any("ipv6.disable=1" in line for line in grub_contents)
+
+    setattr(host.data, cache_key, disabled)
+    return disabled
+
+
+def _ipv6_global_addrs_raw() -> str:
+    cache_key = "_nullforge_ipv6_global_raw"
+    if hasattr(host.data, cache_key):
+        return getattr(host.data, cache_key)
+
+    raw = host.get_fact(Command, "ip -6 -o addr show scope global 2>/dev/null || true") or ""
+    setattr(host.data, cache_key, raw)
+    return raw
+
+
+def has_ipv6(*, exclude_iface: str | None = None) -> bool:
+    """Return whether the host has usable global IPv6."""
+
+    if exclude_iface is None:
+        cache_key = "_nullforge_ipv6_enabled"
+        if hasattr(host.data, cache_key):
+            return getattr(host.data, cache_key)
+
+    if _ipv6_grub_disabled():
+        setattr(host.data, "_nullforge_ipv6_enabled", False)
+        return False
+
+    raw = _ipv6_global_addrs_raw()
+
+    result = False
+    for line in raw.splitlines():
+        parts = line.split(maxsplit=3)
+        if len(parts) < 3:
+            continue
+        iface = parts[1].rstrip(":")
+        if exclude_iface and iface == exclude_iface:
+            continue
+        if _TUNNEL_IFACE_RE.match(iface):
+            continue
+        if parts[2] == "inet6":
+            result = True
+            break
+
+    if exclude_iface is None:
+        setattr(host.data, "_nullforge_ipv6_enabled", result)
+    return result

nullforge/smithy/packages.py

@@ -0,0 +1,176 @@
+"""Package management utilities for NullForge."""
+
+from typing import TYPE_CHECKING, Any, Protocol, cast
+
+from pyinfra.context import host
+from pyinfra.facts.server import LinuxDistribution
+from pyinfra.operations import apt, dnf
+
+
+if TYPE_CHECKING:
+    from pyinfra.api.host import Host
+
+UBUNTU_OVERRIDES = {
+    "ifupdown2": "ifupdown",
+}
+"""Specific overrides for Ubuntu"""
+
+RHEL_OVERRIDES = {
+    "aha": None,
+    "apt-transport-https": None,
+    "bat": "bat",
+    "bind9-host": "bind-utils",
+    "build-essential": "@Development Tools",
+    "dnsutils": "bind-utils",
+    "g++": "gcc-c++",
+    "gnupg": "gnupg2",
+    "ifupdown2": None,
+    "iputils-ping": "iputils",
+    "libevent-dev": "libevent-devel",
+    "libnss-resolve": "systemd-resolved",
+    "libssl-dev": "openssl-devel",
+    "locales": "glibc-langpack-en",
+    "mtr-tiny": "mtr",
+    "ncat": "nmap-ncat",
+    "ncurses-dev": "ncurses-devel",
+    "pkg-config": "pkgconfig",
+    "python3-dev": "python3-devel",
+    "software-properties-common": None,
+    "ufw": "firewalld",
+}
+"""Package overrides for RHEL/CentOS/Fedora families
+Key: Canonical name (Debian/Ubuntu style)
+Value: RHEL equivalent (or None to skip)
+"""
+
+
+class SystemPackageModule(Protocol):
+    """Protocol for pyinfra package manager modules (apt, dnf, etc)."""
+
+    def packages(self, packages: list[str] | None = None, **kwargs: Any) -> Any: ...
+    def update(self, **kwargs: Any) -> Any: ...
+
+
+class AptModule(SystemPackageModule, Protocol):
+    """Protocol for apt module which includes upgrade."""
+
+    def upgrade(self, **kwargs: Any) -> Any: ...
+
+
+class PackageManager:
+    def __init__(self, host: "Host"):
+        self.host = host
+        self.distro_info = host.get_fact(LinuxDistribution)
+        self.distro_name = (self.distro_info.get("name") or "").lower()
+        self.distro_major = self.distro_info.get("major", 0) or 0
+
+    @property
+    def is_debian_based(self) -> bool:
+        return any(x in self.distro_name for x in ["debian", "ubuntu"])
+
+    @property
+    def is_rhel_based(self) -> bool:
+        return any(x in self.distro_name for x in ["centos", "redhat", "rhel", "fedora", "rocky", "alma"])
+
+    @property
+    def is_ubuntu(self) -> bool:
+        return "ubuntu" in self.distro_name
+
+    @property
+    def is_debian(self) -> bool:
+        return "debian" in self.distro_name
+
+    def _get_module(self) -> SystemPackageModule:
+        if self.is_debian_based:
+            return cast(SystemPackageModule, apt)
+        elif self.is_rhel_based:
+            return cast(SystemPackageModule, dnf)
+        else:
+            raise NotImplementedError(f"Unsupported distribution: {self.distro_name}")
+
+    def map_package(self, package: str) -> str | None:
+        """Map a package name to the current distro's equivalent."""
+
+        if self.is_ubuntu and package in UBUNTU_OVERRIDES:
+            return UBUNTU_OVERRIDES[package]
+
+        if self.is_debian_based:
+            return package
+
+        if self.is_rhel_based and package in RHEL_OVERRIDES:
+            return RHEL_OVERRIDES[package]
+
+        # TODO: Maybe make better fallback mechanism
+        return package
+
+    def map_packages(self, packages: list[str]) -> list[str]:
+        """Map a list of packages."""
+
+        mapped = set()
+        for p in packages:
+            m = self.map_package(p)
+            if m:
+                mapped.add(m)
+        return list(mapped)
+
+    def update(self, **kwargs: Any) -> Any:
+        """Refresh the package repository cache.
+
+        On Debian/Ubuntu: runs `apt update`.
+        On RHEL/Fedora: no-op — dnf has no separate cache refresh step;
+        `dnf upgrade` fetches fresh metadata automatically.
+        """
+
+        mod = self._get_module()
+        if self.is_debian_based:
+            return mod.update(**kwargs)
+        return None
+
+    def upgrade(self, **kwargs: Any) -> Any:
+        """Upgrade all installed packages.
+
+        On Debian/Ubuntu: runs `apt upgrade`.
+        On RHEL/Fedora: runs `dnf upgrade`, which also refreshes metadata.
+        """
+
+        call_kwargs = kwargs.copy()
+        mod = self._get_module()
+
+        if not self.is_debian_based:
+            call_kwargs.pop("auto_remove", None)
+
+        if self.is_debian_based:
+            return cast(AptModule, mod).upgrade(**call_kwargs)
+        elif self.is_rhel_based:
+            return mod.update(**call_kwargs)
+        return None
+
+    def install(self, packages: list[str], **kwargs: Any) -> Any:
+        """Install packages."""
+
+        mod = self._get_module()
+        mapped_packages = self.map_packages(packages)
+        if not mapped_packages:
+            return None
+
+        call_kwargs = kwargs.copy()
+
+        # Remove apt-specific kwargs if not apt
+        if not self.is_debian_based:
+            call_kwargs.pop("no_recommends", None)
+            call_kwargs.pop("force", None)
+            call_kwargs.pop("cache_time", None)
+            call_kwargs.pop("extra_uninstall_args", None)
+
+        return mod.packages(packages=mapped_packages, **call_kwargs)
+
+
+def get_pm() -> PackageManager:
+    """Get or create the PackageManager for the current host."""
+
+    if hasattr(host.data, "_nullforge_package_manager"):
+        return getattr(host.data, "_nullforge_package_manager")
+
+    pm = PackageManager(host)
+    setattr(host.data, "_nullforge_package_manager", pm)
+    return pm

nullforge/smithy/service.py

@@ -0,0 +1,37 @@
+"""Shared helpers for provisioning system service users and config directories."""
+
+from pyinfra.context import host
+from pyinfra.facts.server import Groups, Users
+from pyinfra.operations import files, server
+
+
+def ensure_service_user(user: str, group: str, config_dir: str) -> None:
+    """Ensure a system service user, group, and config directory exist."""
+
+    if group not in host.get_fact(Groups):
+        server.group(
+            name=f"Ensure {group} group exists",
+            group=group,
+            system=True,
+            _sudo=True,
+        )
+
+    if user not in host.get_fact(Users):
+        server.user(  # noqa: S604
+            name=f"Ensure {user} system user exists",
+            user=user,
+            system=True,
+            group=group,
+            shell="/bin/false",
+            create_home=False,
+            _sudo=True,
+        )
+
+    files.directory(
+        name=f"Ensure {config_dir} configuration directory exists",
+        path=config_dir,
+        user=user,
+        group=group,
+        mode="0755",
+        _sudo=True,
+    )