systemd-pydantic 0.1.0__py3-none-any.whl

systemd_pydantic/__init__.py

@@ -0,0 +1,17 @@
+from .client import *
+from .config import *
+from .convenience import *
+from .models import (
+    InstallConfiguration,
+    KillMode,
+    RestartPolicy,
+    ServiceConfiguration,
+    ServiceType,
+    ServiceUnitConfiguration,
+    TimerConfiguration,
+    TimerUnitConfiguration,
+    TimeSpan,
+    UnitConfiguration,
+)
+
+__version__ = "0.1.0"

systemd_pydantic/client/__init__.py

@@ -0,0 +1,19 @@
+from .systemctl import (
+    CommandResult,
+    CommandRunner,
+    SSHCommandRunner,
+    SubprocessCommandRunner,
+    SystemdClient,
+    SystemdCommandError,
+    UnitInfo,
+)
+
+__all__ = (
+    "CommandResult",
+    "CommandRunner",
+    "SSHCommandRunner",
+    "SubprocessCommandRunner",
+    "SystemdClient",
+    "SystemdCommandError",
+    "UnitInfo",
+)

systemd_pydantic/client/systemctl.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from subprocess import run
+from typing import TYPE_CHECKING, Protocol
+
+from pydantic import BaseModel, ConfigDict
+
+if TYPE_CHECKING:
+    from ..config import SystemdConfiguration
+
+
+@dataclass(frozen=True)
+class CommandResult:
+    command: list[str]
+    returncode: int
+    stdout: str = ""
+    stderr: str = ""
+
+
+class CommandRunner(Protocol):
+    def run(self, command: list[str], timeout: int) -> CommandResult: ...
+
+
+class SubprocessCommandRunner:
+    def run(self, command: list[str], timeout: int) -> CommandResult:
+        result = run(command, capture_output=True, text=True, timeout=timeout, check=False)
+        return CommandResult(command=command, returncode=result.returncode, stdout=result.stdout, stderr=result.stderr)
+
+
+class SSHCommandRunner:
+    def __init__(self, host: str, runner: CommandRunner | None = None):
+        self.host = host
+        self.runner = runner or SubprocessCommandRunner()
+
+    def run(self, command: list[str], timeout: int) -> CommandResult:
+        return self.runner.run(["ssh", self.host, *command], timeout)
+
+
+class SystemdCommandError(RuntimeError):
+    def __init__(self, result: CommandResult):
+        self.result = result
+        detail = result.stderr.strip() or result.stdout.strip()
+        super().__init__(f"command failed ({result.returncode}): {' '.join(result.command)}{': ' + detail if detail else ''}")
+
+
+class UnitInfo(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    name: str
+    load_state: str = ""
+    active_state: str = ""
+    sub_state: str = ""
+    result: str = ""
+    exec_main_code: str = ""
+    exec_main_status: int | None = None
+
+    def running(self) -> bool:
+        return self.active_state in {"active", "activating", "reloading"}
+
+    def stopped(self) -> bool:
+        return self.active_state in {"inactive", "deactivating"}
+
+    def done(self, ok_exitstatuses: list[int | str] | None = None) -> bool:
+        statuses = {str(value) for value in (ok_exitstatuses or [0])}
+        return self.stopped() and self.result in {"", "success"} and str(self.exec_main_status or 0) in statuses
+
+    def ok(self, ok_exitstatuses: list[int | str] | None = None) -> bool:
+        return self.running() or self.done(ok_exitstatuses)
+
+    def bad(self, ok_exitstatuses: list[int | str] | None = None) -> bool:
+        return self.active_state == "failed" or (self.stopped() and not self.done(ok_exitstatuses))
+
+
+class SystemdClient:
+    _SHOW_PROPERTIES = ("LoadState", "ActiveState", "SubState", "Result", "ExecMainCode", "ExecMainStatus")
+
+    def __init__(self, cfg: SystemdConfiguration, runner: CommandRunner | None = None):
+        self.cfg = cfg
+        self.runner = runner or SubprocessCommandRunner()
+        self.timeout = getattr(cfg, "command_timeout", 60)
+
+    def _run(self, *args: str, check: bool = True) -> CommandResult:
+        command = ["systemctl"]
+        if self.cfg.scope == "user":
+            command.append("--user")
+        result = self.runner.run([*command, *args], self.timeout)
+        if check and result.returncode != 0:
+            raise SystemdCommandError(result)
+        return result
+
+    def daemon_reload(self) -> CommandResult:
+        return self._run("daemon-reload")
+
+    def enable_units(self, names: list[str] | None = None) -> CommandResult:
+        return self._run("enable", *(names if names is not None else [*self.cfg.service_names, *self.cfg.timer_names]))
+
+    def disable_units(self, names: list[str] | None = None) -> CommandResult:
+        return self._run("disable", *(names if names is not None else [*self.cfg.service_names, *self.cfg.timer_names]))
+
+    def start_units(self, names: list[str]) -> dict[str, UnitInfo]:
+        if names:
+            self._run("start", *names)
+        return self.get_units_info(names)
+
+    def stop_units(self, names: list[str]) -> dict[str, UnitInfo]:
+        if names:
+            self._run("stop", *names)
+        return self.get_units_info(names)
+
+    def restart_units(self, names: list[str]) -> dict[str, UnitInfo]:
+        if names:
+            self._run("restart", *names)
+        return self.get_units_info(names)
+
+    def kill_units(self, names: list[str]) -> dict[str, UnitInfo]:
+        if names:
+            self._run("kill", "--signal=SIGKILL", *names)
+        return self.get_units_info(names)
+
+    def start_services(self) -> dict[str, UnitInfo]:
+        return self.start_units(self.cfg.service_names)
+
+    def stop_services(self) -> dict[str, UnitInfo]:
+        return self.stop_units(self.cfg.service_names)
+
+    def restart_services(self) -> dict[str, UnitInfo]:
+        return self.restart_units(self.cfg.service_names)
+
+    def kill_services(self) -> dict[str, UnitInfo]:
+        return self.kill_units(self.cfg.service_names)
+
+    def start_timers(self) -> dict[str, UnitInfo]:
+        return self.start_units(self.cfg.timer_names)
+
+    def stop_timers(self) -> dict[str, UnitInfo]:
+        return self.stop_units(self.cfg.timer_names)
+
+    def get_unit_info(self, name: str) -> UnitInfo:
+        properties = [f"--property={value}" for value in self._SHOW_PROPERTIES]
+        result = self._run("show", name, *properties, check=False)
+        values = {}
+        for line in result.stdout.splitlines():
+            key, separator, value = line.partition("=")
+            if separator:
+                values[key] = value
+        status = values.get("ExecMainStatus", "")
+        return UnitInfo(
+            name=name,
+            load_state=values.get("LoadState", "not-found" if result.returncode else ""),
+            active_state=values.get("ActiveState", "failed" if result.returncode else ""),
+            sub_state=values.get("SubState", ""),
+            result=values.get("Result", ""),
+            exec_main_code=values.get("ExecMainCode", ""),
+            exec_main_status=int(status) if status.lstrip("-").isdigit() else None,
+        )
+
+    def get_units_info(self, names: list[str]) -> dict[str, UnitInfo]:
+        return {name: self.get_unit_info(name) for name in names}
+
+    def get_all_service_info(self) -> dict[str, UnitInfo]:
+        return self.get_units_info(self.cfg.service_names)
+
+    def get_all_timer_info(self) -> dict[str, UnitInfo]:
+        return self.get_units_info(self.cfg.timer_names)

systemd_pydantic/config/__init__.py

@@ -0,0 +1,10 @@
+from .convenience import SystemdConvenienceConfiguration, load_convenience_config
+from .systemd import SystemdConfiguration, SystemdScope, load_config
+
+__all__ = (
+    "SystemdConfiguration",
+    "SystemdConvenienceConfiguration",
+    "SystemdScope",
+    "load_config",
+    "load_convenience_config",
+)

systemd_pydantic/config/convenience.py

@@ -0,0 +1,45 @@
+from pathlib import Path
+
+from pydantic import Field, PrivateAttr, model_validator
+
+from ..models import KillMode, RestartPolicy, TimeSpan
+from .systemd import SystemdConfiguration
+
+
+class SystemdConvenienceConfiguration(SystemdConfiguration):
+    """Systemd defaults and persisted state used by convenience commands."""
+
+    _pydantic_path: Path = PrivateAttr(default=Path("pydantic.json"))
+
+    restart: RestartPolicy = "no"
+    timeout_stop_sec: TimeSpan = "30s"
+    kill_mode: KillMode = "control-group"
+    kill_signal: str = "SIGTERM"
+    success_exit_status: list[int | str] = [0]
+    command_timeout: int = Field(default=60, ge=1)
+
+    @model_validator(mode="after")
+    def _set_convenience_defaults(self) -> "SystemdConvenienceConfiguration":
+        for unit in self.service.values():
+            service = unit.service
+            service.restart = service.restart or self.restart
+            service.timeout_stop_sec = service.timeout_stop_sec or self.timeout_stop_sec
+            service.kill_mode = service.kill_mode or self.kill_mode
+            service.kill_signal = service.kill_signal or self.kill_signal
+            service.success_exit_status = service.success_exit_status or self.success_exit_status
+        assert self.working_dir is not None
+        self._pydantic_path = self.working_dir / "pydantic.json"
+        return self
+
+    def _write_self(self) -> None:
+        assert self.working_dir is not None
+        self.working_dir.mkdir(parents=True, exist_ok=True)
+        self.write()
+        self._pydantic_path.write_text(self.model_dump_json(exclude_unset=True))
+
+    def rmdir(self) -> None:
+        self._pydantic_path.unlink(missing_ok=True)
+        super().rmdir()
+
+
+load_convenience_config = SystemdConvenienceConfiguration.load

systemd_pydantic/config/hydra/base.yaml

@@ -0,0 +1,5 @@
+# @package _global_
+
+_target_: systemd_pydantic.SystemdConfiguration
+service: {}
+timer: {}

systemd_pydantic/config/systemd.py

@@ -0,0 +1,182 @@
+from __future__ import annotations
+
+import inspect
+import os
+from getpass import getuser
+from pathlib import Path
+from tempfile import gettempdir
+from typing import TYPE_CHECKING, Literal, Self
+
+from hydra import compose, initialize_config_dir
+from hydra.utils import instantiate
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from ..models import ServiceUnitConfiguration, TimerUnitConfiguration
+
+SystemdScope = Literal["system", "user"]
+
+if TYPE_CHECKING:
+    from ..client import UnitInfo
+
+
+def _calling_file(offset: int) -> str:
+    return inspect.stack()[offset].filename
+
+
+def _unit_filename(name: str, suffix: str) -> str:
+    if "/" in name or name in {"", ".", ".."}:
+        raise ValueError(f"invalid unit name: {name!r}")
+    if name.endswith(suffix):
+        return name
+    if "." in name:
+        raise ValueError(f"unit {name!r} must end in {suffix}")
+    return f"{name}{suffix}"
+
+
+class SystemdConfiguration(BaseModel):
+    """Named collection of systemd service and timer unit files."""
+
+    model_config = ConfigDict(extra="forbid", validate_assignment=True)
+
+    service: dict[str, ServiceUnitConfiguration]
+    timer: dict[str, TimerUnitConfiguration] = Field(default_factory=dict)
+    unit_dir: Path | None = None
+    working_dir: Path | None = None
+    scope: SystemdScope = "system"
+
+    @model_validator(mode="after")
+    def _set_paths(self) -> SystemdConfiguration:
+        names = sorted([*self.service, *self.timer])
+        label = "-".join(names) or "units"
+        if self.working_dir is None:
+            object.__setattr__(self, "working_dir", Path(gettempdir()).resolve() / f"systemd-{getuser()}-{label}")
+        if self.unit_dir is None:
+            object.__setattr__(
+                self,
+                "unit_dir",
+                Path("/etc/systemd/system") if self.scope == "system" else Path.home() / ".config/systemd/user",
+            )
+        for name in self.service:
+            _unit_filename(name, ".service")
+        for name in self.timer:
+            _unit_filename(name, ".timer")
+        return self
+
+    def to_cfg(self) -> dict[str, str]:
+        rendered = {_unit_filename(name, ".service"): config.to_cfg() for name, config in self.service.items()}
+        rendered.update({_unit_filename(name, ".timer"): config.to_cfg() for name, config in self.timer.items()})
+        return rendered
+
+    @property
+    def service_names(self) -> list[str]:
+        return [_unit_filename(name, ".service") for name in self.service]
+
+    @property
+    def timer_names(self) -> list[str]:
+        return [_unit_filename(name, ".timer") for name in self.timer]
+
+    @property
+    def unit_paths(self) -> list[Path]:
+        assert self.unit_dir is not None
+        return [self.unit_dir / name for name in self.to_cfg()]
+
+    def write(self) -> list[Path]:
+        assert self.unit_dir is not None
+        self.unit_dir.mkdir(parents=True, exist_ok=True)
+        paths = []
+        for filename, contents in self.to_cfg().items():
+            path = self.unit_dir / filename
+            path.write_text(contents)
+            paths.append(path)
+        return paths
+
+    def rmdir(self) -> None:
+        for path in self.unit_paths:
+            path.unlink(missing_ok=True)
+        assert self.working_dir is not None
+        if self.working_dir.exists() and not any(self.working_dir.iterdir()):
+            self.working_dir.rmdir()
+
+    @classmethod
+    def _find_parent_config_folder(
+        cls,
+        config_dir: str = "config",
+        config_name: str = "",
+        *,
+        basepath: str = "",
+        _offset: int = 2,
+    ) -> tuple[Path, Path, Path | str]:
+        if basepath:
+            calling_file = Path(basepath) if basepath.endswith((".py", ".yml", ".yaml")) else Path(basepath) / "dummy.py"
+        else:
+            calling_file = Path(_calling_file(_offset))
+        folder = calling_file.parent.resolve()
+
+        while True:
+            candidate = folder / config_dir
+            if not config_name and candidate.exists():
+                return folder, candidate.resolve(), ""
+            for suffix in (".yml", ".yaml"):
+                path = candidate / f"{config_name}{suffix}"
+                if config_name and path.exists():
+                    return folder, candidate.resolve(), path.resolve()
+            if str(folder) == os.path.abspath(os.sep):
+                raise FileNotFoundError(f"could not find {config_name or config_dir!r} from {calling_file}")
+            folder = folder.parent
+
+    @classmethod
+    def load(
+        cls,
+        config_dir: str = "config",
+        config_name: str = "",
+        overrides: list[str] | None = None,
+        *,
+        basepath: str = "",
+        _offset: int = 3,
+    ) -> Self:
+        overrides = overrides or []
+        hydra_dir = Path(__file__).resolve().parent / "hydra"
+        with initialize_config_dir(config_dir=str(hydra_dir), version_base=None):
+            if config_dir:
+                hydra_folder, resolved_config_dir, _ = cls._find_parent_config_folder(
+                    config_dir=config_dir,
+                    config_name=config_name,
+                    basepath=basepath,
+                    _offset=_offset,
+                )
+                base = compose(config_name="base", return_hydra_config=True)
+                searchpaths = list(base["hydra"]["searchpath"])
+                searchpaths.extend([str(hydra_folder), str(resolved_config_dir)])
+                if config_name:
+                    overrides = [f"+config={config_name}", *overrides, f"hydra.searchpath=[{','.join(searchpaths)}]"]
+                else:
+                    overrides = [*overrides, f"hydra.searchpath=[{','.join(searchpaths)}]"]
+            config = instantiate(compose(config_name="base", overrides=overrides))
+        if isinstance(config, cls):
+            return config
+        if isinstance(config, BaseModel):
+            config = config.model_dump(exclude_unset=True)
+        return cls.model_validate(config)
+
+    def start(self) -> dict[str, UnitInfo]:
+        from ..client import SystemdClient
+
+        return SystemdClient(self).start_services()
+
+    def running(self) -> bool:
+        from ..client import SystemdClient
+
+        return all(info.running() for info in SystemdClient(self).get_all_service_info().values())
+
+    def stop(self) -> dict[str, UnitInfo]:
+        from ..client import SystemdClient
+
+        return SystemdClient(self).stop_services()
+
+    def kill(self) -> dict[str, UnitInfo]:
+        from ..client import SystemdClient
+
+        return SystemdClient(self).kill_services()
+
+
+load_config = SystemdConfiguration.load

systemd_pydantic/convenience/__init__.py

@@ -0,0 +1,21 @@
+from .commands import (
+    check_services,
+    main,
+    remove_systemd_config,
+    restart_services,
+    start_services,
+    stop_services,
+    write_systemd_config,
+)
+from .common import SystemdTaskStep
+
+__all__ = (
+    "SystemdTaskStep",
+    "check_services",
+    "main",
+    "remove_systemd_config",
+    "restart_services",
+    "start_services",
+    "stop_services",
+    "write_systemd_config",
+)

systemd_pydantic/convenience/commands.py

@@ -0,0 +1,109 @@
+from pathlib import Path
+
+from typer import Argument, Exit, Option, Typer
+from typing_extensions import Annotated
+
+from ..client import SystemdClient
+from ..config import SystemdConvenienceConfiguration
+from .common import SystemdTaskStep
+
+ConfigInput = str | Path | SystemdConvenienceConfiguration
+
+
+def _raise_or_exit(value: bool, exit: bool):
+    if exit:
+        raise Exit(int(not value))
+    return value
+
+
+def _load_or_pass(cfg: ConfigInput) -> SystemdConvenienceConfiguration:
+    if isinstance(cfg, Path):
+        cfg = cfg.read_text()
+    if isinstance(cfg, str):
+        return SystemdConvenienceConfiguration.model_validate_json(cfg)
+    if not isinstance(cfg, SystemdConvenienceConfiguration):
+        raise NotImplementedError
+    return cfg
+
+
+def write_systemd_config(cfg_json: str, _exit: Annotated[bool, Argument(hidden=True)] = True):
+    cfg = _load_or_pass(cfg_json)
+    cfg._write_self()
+    client = SystemdClient(cfg)
+    client.daemon_reload()
+    return _raise_or_exit(True, _exit)
+
+
+def start_services(
+    cfg: Annotated[Path, Option(exists=True, file_okay=True, dir_okay=False, readable=True)] = Path("pydantic.json"),
+    restart: bool = False,
+    _exit: Annotated[bool, Argument(hidden=True)] = True,
+):
+    config = _load_or_pass(cfg)
+    client = SystemdClient(config)
+    result = client.restart_services() if restart else client.start_services()
+    ok = all(info.ok(config.success_exit_status) for info in result.values())
+    return _raise_or_exit(ok, _exit)
+
+
+def check_services(
+    cfg: Annotated[Path, Option(exists=True, file_okay=True, dir_okay=False, readable=True)] = Path("pydantic.json"),
+    check_running: bool = False,
+    check_done: bool = False,
+    _exit: Annotated[bool, Argument(hidden=True)] = True,
+):
+    config = _load_or_pass(cfg)
+    infos = SystemdClient(config).get_all_service_info().values()
+    if check_running:
+        ok = all(info.running() for info in infos)
+    elif check_done:
+        ok = all(info.done(config.success_exit_status) for info in infos)
+    else:
+        ok = all(info.ok(config.success_exit_status) for info in infos)
+    return _raise_or_exit(ok, _exit)
+
+
+def stop_services(
+    cfg: Annotated[Path, Option(exists=True, file_okay=True, dir_okay=False, readable=True)] = Path("pydantic.json"),
+    _exit: Annotated[bool, Argument(hidden=True)] = True,
+):
+    config = _load_or_pass(cfg)
+    infos = SystemdClient(config).stop_services().values()
+    return _raise_or_exit(all(info.stopped() for info in infos), _exit)
+
+
+def restart_services(
+    cfg: Annotated[Path, Option(exists=True, file_okay=True, dir_okay=False, readable=True)] = Path("pydantic.json"),
+    _exit: Annotated[bool, Argument(hidden=True)] = True,
+):
+    config = _load_or_pass(cfg)
+    infos = SystemdClient(config).restart_services().values()
+    return _raise_or_exit(all(info.ok(config.success_exit_status) for info in infos), _exit)
+
+
+def remove_systemd_config(
+    cfg: Annotated[Path, Option(exists=True, file_okay=True, dir_okay=False, readable=True)] = Path("pydantic.json"),
+    _exit: Annotated[bool, Argument(hidden=True)] = True,
+):
+    config = _load_or_pass(cfg)
+    client = SystemdClient(config)
+    client.stop_timers()
+    client.stop_services()
+    config.rmdir()
+    client.daemon_reload()
+    return _raise_or_exit(True, _exit)
+
+
+def _add_to_typer(app: Typer, command: SystemdTaskStep, function) -> None:
+    app.command(command)(function)
+
+
+def main() -> None:
+    app = Typer()
+    _add_to_typer(app, "configure-systemd", write_systemd_config)
+    _add_to_typer(app, "start-services", start_services)
+    _add_to_typer(app, "check-services", check_services)
+    _add_to_typer(app, "restart-services", restart_services)
+    _add_to_typer(app, "stop-services", stop_services)
+    _add_to_typer(app, "unconfigure-systemd", remove_systemd_config)
+    app()

systemd_pydantic/convenience/common.py

@@ -0,0 +1,12 @@
+from typing import Literal
+
+SystemdTaskStep = Literal[
+    "configure-systemd",
+    "start-services",
+    "check-services",
+    "restart-services",
+    "stop-services",
+    "unconfigure-systemd",
+]
+
+__all__ = ("SystemdTaskStep",)