nullforge 0.1.0__py3-none-any.whl

nullforge/molds/utils.py

@@ -0,0 +1,115 @@
+"""Utility functions for merging and ensuring models."""
+
+from collections.abc import Mapping
+from typing import Any
+
+from .base_mold import BaseMold
+from .features import ALLOWED_FEATURES_LAYERS, FEATURE_MOLD_MAPPING, FeaturesMold
+from .system import SystemMold
+
+
+def _deep_merge_dicts(a: Mapping[str, Any], b: Mapping[str, Any]) -> dict[str, Any]:
+    """
+    Recursively merge dict b into dict a without mutating a.
+    None/empty containers in b will overwrite a.
+    """
+
+    out = dict(a)
+    for k, v in b.items():
+        if k in out and isinstance(out[k], dict) and isinstance(v, dict):
+            out[k] = _deep_merge_dicts(out[k], v)
+        else:
+            out[k] = v
+    return out
+
+
+def _to_features_fragment(value: object) -> dict[str, Any]:
+    """
+    Accept a full FeaturesMold, any sub-mold (UserMold, WarpMold, ...), a mapping,
+    or None; return a dict fragment suitable for deep-merge into FeaturesMold.
+    """
+
+    match value:
+        case None:
+            return {}
+        case FeaturesMold():
+            return value.model_dump()
+        case BaseMold():
+            for attr, cls in FEATURE_MOLD_MAPPING.items():
+                if isinstance(value, cls):
+                    return {attr: value.model_dump()}
+            raise TypeError(f"Unsupported features layer type: {type(value)!r}")
+        case Mapping():
+            prepared = {k: (v.model_dump() if isinstance(v, ALLOWED_FEATURES_LAYERS) else v) for k, v in value.items()}
+            return FeaturesMold.model_validate(prepared).model_dump(exclude_unset=True)
+        case _:
+            raise TypeError(f"Unsupported features layer type: {type(value)!r}")
+
+
+def merge_features(base: FeaturesMold, *layers: object | None) -> FeaturesMold:
+    """Start from base FeaturesMold, deep-merge each layer (full mold, sub-mold, dict, or None)."""
+
+    acc = base.model_dump()
+    for layer in layers:
+        if layer is None:
+            continue
+        acc = _deep_merge_dicts(acc, _to_features_fragment(layer))
+    return FeaturesMold.model_validate(acc)
+
+
+def ensure_features(value: object) -> FeaturesMold:
+    """
+    Coerce whatever is in inventory (None/dict/Features) into a Features instance,
+    falling back to model defaults when absent.
+    """
+
+    match value:
+        case None:
+            return FeaturesMold()
+        case FeaturesMold():
+            return value
+        case Mapping():
+            return FeaturesMold.model_validate(value)
+        case _:
+            raise TypeError(f"Unsupported features layer type: {type(value)!r}")
+
+
+def _to_system_dict(value: SystemMold | Mapping[str, Any]) -> dict[str, Any]:
+    match value:
+        case SystemMold():
+            return value.model_dump()
+        case Mapping():
+            return SystemMold.model_validate(value).model_dump(exclude_unset=True)
+        case _:
+            raise TypeError(f"Unsupported system layer type: {type(value)!r}")
+
+
+def merge_system(base: SystemMold, *layers: SystemMold | Mapping[str, Any] | None) -> SystemMold:
+    """
+    - start from base SystemMold
+    - apply each layer (dict or SystemMold), deep-merging into the accumulated dict
+    """
+
+    acc = base.model_dump()
+    for layer in layers:
+        if layer is None:
+            continue
+        acc = _deep_merge_dicts(acc, _to_system_dict(layer))
+    return SystemMold.model_validate(acc)
+
+
+def ensure_system(value: object) -> SystemMold:
+    """
+    Coerce whatever is in inventory (None/dict/SystemMold) into a SystemMold instance,
+    falling back to model defaults when absent.
+    """
+
+    match value:
+        case None:
+            return SystemMold()
+        case SystemMold():
+            return value
+        case Mapping():
+            return SystemMold.model_validate(value)
+        case _:
+            raise TypeError(f"Unsupported system layer type: {type(value)!r}")

nullforge/molds/warp.py

@@ -0,0 +1,54 @@
+"""WARP configuration mold."""
+
+from functools import cached_property
+from typing import TYPE_CHECKING, Literal
+
+from pydantic import Field, field_validator
+
+from nullforge.models.warp import WarpEngineType, warp_engine_factory
+
+from .base_mold import BaseMold
+
+
+if TYPE_CHECKING:
+    from nullforge.models.warp import WarpEngine
+
+
+class WarpMold(BaseMold):
+    install: bool = Field(
+        default=False,
+        description="Whether to deploy WARP",
+    )
+    engine_type: WarpEngineType = Field(
+        default=WarpEngineType.MASQUE,
+        description="The WARP engine to use",
+    )
+    iface: str = Field(
+        default="warp",
+        description="The name of the network interface for WARP",
+    )
+    mtu: int = Field(
+        default=1280,
+        ge=1280,
+        le=9216,
+        description="The MTU for the WARP interface",
+    )
+    zero_trust: Literal[False] = Field(
+        default=False,
+        description="ZeroTrust enrollment — not yet implemented, always False",
+    )
+
+    @property
+    def is_active(self) -> bool:
+        return self.install
+
+    @field_validator("iface")
+    @classmethod
+    def _validate_iface(cls, v: str) -> str:
+        if not v or any(ch.isspace() for ch in v):
+            raise ValueError("iface must be a non-empty string without spaces")
+        return v
+
+    @cached_property
+    def engine(self) -> "WarpEngine":
+        return warp_engine_factory(self.engine_type)

nullforge/molds/xray.py

@@ -0,0 +1,16 @@
+"""Xray-core configuration mold."""
+
+from pydantic import Field
+
+from .base_mold import BaseMold
+
+
+class XrayCoreMold(BaseMold):
+    install: bool = Field(
+        default=False,
+        description="Whether to install Xray core",
+    )
+
+    @property
+    def is_active(self) -> bool:
+        return self.install

nullforge/molds/zerotrust.py

@@ -0,0 +1,59 @@
+"""Zero Trust Tunnel configuration mold."""
+
+from pydantic import Field, field_validator, model_validator
+
+from nullforge.models.zerotrust import ZeroTrustTunnelProtocol
+
+from .base_mold import BaseMold
+
+
+class ZeroTrustTunnelMold(BaseMold):
+    install: bool = Field(
+        default=False,
+        description="Whether to deploy Zero Trust Tunnel",
+    )
+    token: str | None = Field(
+        default=None,
+        description="Tunnel token for authentication",
+    )
+    protocol: ZeroTrustTunnelProtocol = Field(
+        default=ZeroTrustTunnelProtocol.AUTO,
+        description="Tunnel protocol",
+    )
+    post_quantum: bool = Field(
+        default=False,
+        description="Whether to use post-quantum protocol",
+    )
+    ha_connections: int = Field(
+        default=2,
+        ge=1,
+        le=4,
+        description="Number of high-availability connections",
+    )
+    route_through_warp: bool = Field(
+        default=False,
+        description="Whether to route tunnel traffic through WARP interface",
+    )
+
+    @property
+    def is_active(self) -> bool:
+        return self.install
+
+    @field_validator("token")
+    @classmethod
+    def _strip_token(cls, v: str | None) -> str | None:
+        return v.strip() if v is not None else None
+
+    @model_validator(mode="after")
+    def validate_install_requires_token(self) -> "ZeroTrustTunnelMold":
+        if self.install and not self.token:
+            raise ValueError("token is required when install is True")
+        return self
+
+    @model_validator(mode="after")
+    def validate_post_quantum_requires_protocol(self) -> "ZeroTrustTunnelMold":
+        if self.post_quantum and self.route_through_warp:
+            raise ValueError("post-quantum protocol is not supported when routing through WARP")
+        if self.post_quantum and self.protocol == ZeroTrustTunnelProtocol.HTTP2:
+            raise ValueError("post-quantum key agreement requires QUIC protocol")
+        return self

nullforge/runes/__init__.py

@@ -0,0 +1,46 @@
+"""Rune metadata."""
+
+import ast
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Final
+
+
+RUNES_DIR: Final[Path] = Path(__file__).parent
+
+
+@dataclass(frozen=True, slots=True)
+class RuneInfo:
+    name: str
+    path: Path
+    summary: str
+
+
+def rune_path(name: str) -> Path:
+    """Absolute path of built-in rune."""
+
+    return RUNES_DIR / f"{name}.py"
+
+
+def rune_summary(path: Path) -> str:
+    """First line of the rune docstring, extracted via ast."""
+
+    try:
+        module = ast.parse(path.read_text(encoding="utf-8"))
+    except (OSError, SyntaxError, ValueError):
+        return ""
+    docstring = ast.get_docstring(module)
+    if not docstring:
+        return ""
+    return docstring.strip().splitlines()[0]
+
+
+def discover_runes(directory: Path | None = None) -> tuple[RuneInfo, ...]:
+    """Built-in runes: sorted *.py files in *directory*, skipping _-prefixed names."""
+
+    directory = directory if directory is not None else RUNES_DIR
+    try:
+        candidates = sorted(path for path in directory.glob("*.py") if not path.name.startswith("_"))
+    except OSError:
+        return ()
+    return tuple(RuneInfo(name=path.stem, path=path, summary=rune_summary(path)) for path in candidates)

nullforge/runes/base.py

@@ -0,0 +1,327 @@
+"""Base system configuration deployment module."""
+
+import re
+
+from pyinfra.context import host
+from pyinfra.facts.files import File, FileContents
+from pyinfra.facts.server import Command, Hostname, Locales
+from pyinfra.operations import files, server, systemd
+
+from nullforge.molds import SystemMold
+from nullforge.smithy.install import install_release_binary
+from nullforge.smithy.packages import get_pm
+from nullforge.smithy.swap import configure_swap
+from nullforge.smithy.system import detect_best_locale
+from nullforge.smithy.versions import get_versions, is_pinned_version_installed
+
+
+def deploy_base_system() -> None:
+    """Deploy base system configuration."""
+
+    system: SystemMold = host.data.system
+
+    if system.ensure_ipv6:
+        _ensure_ipv6_stack()
+
+    if system.hostname:
+        _configure_hostname(system.hostname)
+
+    _install_packages(system)
+
+    _set_locale(system)
+
+    _set_timezone(system)
+
+    _configure_ntp()
+
+    configure_swap(system)
+
+
+def _configure_hostname(hostname: str) -> None:
+    """Configure system hostname."""
+
+    short_hostname = hostname.split(".")[0]
+
+    ip_fact = host.get_fact(Command, "hostname -I | awk '{print $1}'") or ""
+    ip = ip_fact.strip() or "127.0.1.1"
+
+    if host.get_fact(Hostname) != hostname:
+        server.hostname(
+            name="Set system hostname",
+            hostname=hostname,
+            _sudo=True,
+        )
+
+    server.etc_hosts(
+        name="Ensure hostname in hosts file",
+        ip=ip,
+        hostnames=[hostname, short_hostname],
+        _sudo=True,
+    )
+
+    _disable_cloud_init_hostname()
+
+
+def _disable_cloud_init_hostname() -> None:
+    """Prevent cloud-init from overriding the configured hostname on reboot."""
+
+    cloud_cfg = "/etc/cloud/cloud.cfg"
+    if not host.get_fact(File, cloud_cfg):
+        return
+
+    files.line(
+        name="Preserve hostname across cloud-init runs",
+        path=cloud_cfg,
+        line=r"^preserve_hostname:.*",
+        replace="preserve_hostname: true",
+        _sudo=True,
+    )
+
+    for module in host.loop(("set_hostname", "update_hostname")):
+        files.line(
+            name=f"Remove {module} from cloud_init_modules",
+            path=cloud_cfg,
+            line=rf"^\s*-\s+{module}\s*$",
+            present=False,
+            _sudo=True,
+        )
+
+
+def _install_packages(system: SystemMold) -> None:
+    """Install base system packages."""
+
+    pm = get_pm()
+
+    pm.update(
+        name="Update package repositories",
+        _sudo=True,
+    )
+
+    pm.upgrade(
+        name="Update packages",
+        _sudo=True,
+    )
+
+    pm.install(
+        name="Install base system packages",
+        packages=system.packages_base,
+        no_recommends=True,
+        _sudo=True,
+    )
+
+    _install_curl()
+
+    _install_doggo()
+
+
+def _install_curl() -> None:
+    """Install curl package."""
+
+    pm = get_pm()
+    curl_exec_path = "/usr/local/bin/curl"
+    if is_pinned_version_installed("curl", curl_exec_path):
+        return
+
+    try:
+        curl_url = get_versions().curl_tar()
+    except ValueError:
+        pm.install(
+            name="Install curl package from repo",
+            packages=["curl"],
+            _sudo=True,
+        )
+        return
+
+    install_release_binary(
+        name="Install curl binary from static-curl",
+        url=curl_url,
+        dest=curl_exec_path,
+        binary_name="curl",
+    )
+
+    if not pm.is_debian_based:
+        files.link(
+            name="Symlink Debian-style CA bundle path for static curl",
+            path="/etc/ssl/certs/ca-certificates.crt",
+            target="/etc/pki/tls/certs/ca-bundle.crt",
+            _sudo=True,
+        )
+        return
+
+    pm.install(
+        name="Remove curl package",
+        packages=["curl"],
+        present=False,
+        _sudo=True,
+    )
+
+    pm.upgrade(
+        name="Clean up unused packages",
+        auto_remove=True,
+        _sudo=True,
+    )
+
+
+def _install_doggo() -> None:
+    """Install doggo package."""
+
+    if is_pinned_version_installed("doggo", "/usr/local/bin/doggo"):
+        return
+
+    install_release_binary(
+        name="Download and extract doggo",
+        url=get_versions().doggo_tar(),
+        dest="/usr/local/bin/doggo",
+        binary_name="doggo",
+    )
+
+
+def _set_locale(system: SystemMold) -> None:
+    """Set system locale."""
+
+    resolved_locales = set[str]()
+
+    for locale in system.locales:
+        best = detect_best_locale(preferred=locale)
+        if best:
+            resolved_locales.add(best)
+
+    if not resolved_locales:
+        return
+
+    installed = host.get_fact(Locales)
+    needs_gen = False
+
+    for gen_line in host.loop(sorted(resolved_locales)):
+        name = gen_line.split()[0]
+        files.line(
+            name=f"Enable locale {name}",
+            path="/etc/locale.gen",
+            line=rf"^#?\s*{re.escape(gen_line)}$",
+            replace=gen_line,
+            _sudo=True,
+        )
+        if name not in installed:
+            needs_gen = True
+
+    if needs_gen:
+        server.shell(
+            name="Generate locales",
+            commands=["locale-gen"],
+            _sudo=True,
+        )
+
+
+def _configure_ntp() -> None:
+    """Install and configure NTP synchronization."""
+
+    pm = get_pm()
+
+    if pm.is_debian_based:
+        pm.install(
+            name="Install systemd-timesyncd",
+            packages=["systemd-timesyncd"],
+            _sudo=True,
+        )
+        systemd.service(
+            name="Ensure systemd-timesyncd is running and enabled",
+            service="systemd-timesyncd",
+            running=True,
+            enabled=True,
+            _sudo=True,
+        )
+    elif pm.is_rhel_based:
+        pm.install(
+            name="Install chrony",
+            packages=["chrony"],
+            _sudo=True,
+        )
+        systemd.service(
+            name="Ensure chronyd is running and enabled",
+            service="chronyd",
+            running=True,
+            enabled=True,
+            _sudo=True,
+        )
+        server.shell(
+            name="Force NTP sync",
+            commands=["chronyc makestep"],
+            _sudo=True,
+            _retries=3,
+            _retry_delay=5,
+        )
+    else:
+        raise NotImplementedError(f"NTP configuration is not supported for distro: {pm.distro_name}")
+
+
+def _set_timezone(system: SystemMold) -> None:
+    """Set system timezone."""
+
+    server.timezone(
+        name=f"Set system timezone to {system.timezone}",
+        timezone=system.timezone,
+        _sudo=True,
+    )
+
+
+def _ensure_ipv6_stack() -> None:
+    """Ensure the kernel IPv6 stack is not disabled at boot."""
+
+    grub_path = "/etc/default/grub"
+    grub_contents = host.get_fact(FileContents, path=grub_path)
+
+    if not grub_contents or not any("ipv6.disable=" in line for line in grub_contents):
+        return
+
+    remove_op = files.replace(
+        name="Remove ipv6.disable=... from GRUB kernel command lines",
+        path=grub_path,
+        text=r"""(^|[ "])ipv6\.disable=[^"']*""",
+        replace=r"\1",
+        extended_regex=True,
+        flags=["g"],
+        _sudo=True,
+    )
+
+    collapse_op = files.replace(
+        name="Collapse repeated spaces in GRUB_CMDLINE_LINUX* values",
+        path=grub_path,
+        text=r'(GRUB_CMDLINE_LINUX(_DEFAULT)?="[^"]*?) {2,}([^"]*?")',
+        replace=r"\1 \2",
+        extended_regex=True,
+        flags=["g"],
+        _sudo=True,
+    )
+
+    if remove_op.will_change or collapse_op.will_change:
+        _update_grub_config()
+
+
+def _update_grub_config() -> None:
+    pm = get_pm()
+    if pm.is_debian_based:
+        server.shell(
+            name="Regenerate GRUB config (update-grub)",
+            commands=["update-grub"],
+            _sudo=True,
+        )
+    elif pm.is_rhel_based:
+        # try most common locations; failures for non-applicable paths are ignored.
+        server.shell(
+            name="Regenerate GRUB config (grub2-mkconfig)",
+            commands=[
+                (
+                    "grub2-mkconfig -o /boot/grub2/grub.cfg 2>/dev/null || "
+                    "grub2-mkconfig -o /boot/efi/EFI/redhat/grub.cfg 2>/dev/null || "
+                    "grub2-mkconfig -o /boot/efi/EFI/centos/grub.cfg 2>/dev/null || "
+                    "grub2-mkconfig -o /boot/efi/EFI/fedora/grub.cfg 2>/dev/null || "
+                    "grub2-mkconfig -o /boot/efi/EFI/rocky/grub.cfg 2>/dev/null || "
+                    "grub2-mkconfig -o /boot/efi/EFI/alma/grub.cfg 2>/dev/null || "
+                    "true"
+                )
+            ],
+            _sudo=True,
+        )
+
+
+deploy_base_system()