server-motd 0.1.0__py3-none-any.whl

server_motd/__init__.py

@@ -0,0 +1 @@
+"""server-motd: login MOTD for media servers."""

server_motd/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from server_motd.cli import main
+
+sys.exit(main())

server_motd/cli.py

@@ -0,0 +1,126 @@
+"""Command line entry point. The login invocation always exits 0."""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import socket
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from server_motd import config, profile, render, runner, terminal
+from server_motd.config import BadEntry, ConfigError, ModuleSpec
+from server_motd.model import Module, Result, Status
+from server_motd.modules import REGISTRY
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="server-motd")
+    p.add_argument("--config", type=Path, help="config file (overrides discovery)")
+    p.add_argument("--width", type=int, help="output width in columns")
+    p.add_argument("--color", choices=["auto", "always", "never"], default="auto")
+    p.add_argument("--verbose", action="store_true", help="show exception detail")
+    sub = p.add_subparsers(dest="command")  # no subcommand = render
+    check = sub.add_parser("check", help="validate the config and probe every module")
+    # SUPPRESS keeps values given before the subcommand from being overwritten.
+    check.add_argument("--config", type=Path, default=argparse.SUPPRESS)
+    check.add_argument("--verbose", action="store_true", default=argparse.SUPPRESS)
+    sub.add_parser("install-profile", help="add the profile block")
+    sub.add_parser("uninstall-profile", help="remove the profile block")
+    return p
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        if args.command == "check":
+            return _check(args)
+        if args.command in ("install-profile", "uninstall-profile"):
+            return profile.run(args.command)
+        return _render(args)
+    except Exception as exc:  # never block login
+        print(f"server-motd: {exc}", file=sys.stderr)
+        return 0
+
+
+def _bad(title: str, message: str) -> Result:
+    return runner.unavailable(title, f"invalid config: {message}")
+
+
+def _build_items(
+    entries: list[ModuleSpec | BadEntry],
+) -> list[tuple[str, Module | Result]]:
+    # Config order is preserved: each item is a ready Result or a Module to run.
+    items: list[tuple[str, Module | Result]] = []
+    for entry in entries:
+        if isinstance(entry, BadEntry):
+            items.append((entry.label, _bad(entry.label, entry.message)))
+            continue
+        if not entry.enabled:
+            continue
+        title = entry.name or entry.kind
+        factory = REGISTRY.get(entry.kind)
+        if factory is None:
+            items.append((title, _bad(title, f"unknown kind '{entry.kind}'")))
+            continue
+        try:
+            items.append((title, factory(entry)))
+        except ConfigError as exc:
+            items.append((title, _bad(title, str(exc))))
+    return items
+
+
+def _check(args: argparse.Namespace) -> int:
+    try:
+        entries = config.load(args.config)
+    except ConfigError as exc:
+        print(f"server-motd: {exc}", file=sys.stderr)
+        return 1
+    items = _build_items(entries)
+    log: list[str] = []
+    to_run = [(t, m) for t, m in items if not isinstance(m, Result)]
+    fetched = iter(runner.run(to_run, log))
+    failed = False
+    for title, item in items:
+        result = item if isinstance(item, Result) else next(fetched)
+        if result.status is Status.UNAVAILABLE:
+            failed = True
+            reason = result.rows[0].value.removeprefix("UNAVAILABLE: ")
+            print(f"FAIL  {title}: {reason}")
+        else:
+            print(f"ok    {title}")
+    if args.verbose:
+        for entry_log in log:
+            print(entry_log, file=sys.stderr)
+    return 1 if failed else 0
+
+
+def _render(args: argparse.Namespace) -> int:
+    try:
+        entries = config.load(args.config)
+        settings = config.load_settings(args.config)
+    except ConfigError as exc:
+        print(f"server-motd: {exc}", file=sys.stderr)
+        return 0
+    items = _build_items(entries)
+
+    log: list[str] = []
+    to_run = [(t, m) for t, m in items if not isinstance(m, Result)]
+    fetched = iter(runner.run(to_run, log))
+    results = [m if isinstance(m, Result) else next(fetched) for _, m in items]
+
+    width = args.width or shutil.get_terminal_size((80, 24)).columns
+    color = args.color == "always" or (args.color == "auto" and sys.stdout.isatty())
+    if color and not terminal.enable_vt() and args.color == "auto":
+        color = False  # console cannot render escape codes: plain text
+    box = settings.box
+    if box not in render.BOX_STYLES:
+        print(f"server-motd: unknown box style '{box}', using single", file=sys.stderr)
+        box = "single"
+    title = settings.title or socket.gethostname()
+    sys.stdout.write(render.render(results, width, color, title, box))
+    if args.verbose:
+        for entry_log in log:
+            print(entry_log, file=sys.stderr)
+    return 0

server_motd/config.py

@@ -0,0 +1,155 @@
+"""TOML config loading, strict per-module validation and secret resolution.
+
+Config shape: an ordered `[[modules]]` array. Each entry has `kind`, optional
+`name`, `enabled` (default true) and any kind-specific keys, including
+`warn`/`crit`. Those are left in `ModuleSpec.options`; a module consumes what
+it supports with the `take_*` helpers and then calls `done()`, which rejects
+any key left over. Errors are raised as `ConfigError` and reported only for
+the module they belong to.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import sys
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+class ConfigError(Exception):
+    """Invalid configuration (file level or for a single module)."""
+
+
+@dataclass
+class ModuleSpec:
+    kind: str
+    name: str | None
+    enabled: bool
+    options: dict[str, Any] = field(default_factory=dict)
+
+    def take(self, key: str, typ: type, default: Any = None) -> Any:
+        """Pop an optional option, checking its type."""
+        if key not in self.options:
+            return default
+        value = self.options.pop(key)
+        if typ is float and isinstance(value, int) and not isinstance(value, bool):
+            value = float(value)
+        if not isinstance(value, typ) or (typ is not bool and isinstance(value, bool)):
+            raise ConfigError(f"'{key}' must be {typ.__name__}")
+        return value
+
+    def take_secret(self, key: str) -> str | None:
+        """Resolve a secret given inline, as `${ENV_VAR}`, or via `<key>_file`."""
+        value = self.take(key, str)
+        file_key = f"{key}_file"
+        path = self.take(file_key, str)
+        if value is not None and path is not None:
+            raise ConfigError(f"set only one of '{key}' and '{file_key}'")
+        if path is not None:
+            try:
+                return Path(path).read_text(encoding="utf-8").strip()
+            except OSError as exc:
+                raise ConfigError(f"cannot read '{file_key}': {exc.strerror}") from exc
+        if value is None:
+            return None
+        return _expand_env(value, key)
+
+    def done(self) -> None:
+        if self.options:
+            keys = ", ".join(sorted(self.options))
+            raise ConfigError(f"unknown option(s): {keys}")
+
+
+_ENV = re.compile(r"\$\{([A-Za-z_][A-Za-z0-9_]*)\}")
+
+
+def _expand_env(value: str, key: str) -> str:
+    def sub(m: re.Match[str]) -> str:
+        name = m.group(1)
+        if name not in os.environ:
+            raise ConfigError(f"'{key}' references unset variable {name}")
+        return os.environ[name]
+
+    return _ENV.sub(sub, value)
+
+
+@dataclass
+class BadEntry:
+    """A `[[modules]]` entry too malformed to build a ModuleSpec from."""
+
+    label: str
+    message: str
+
+
+def default_config_paths() -> list[Path]:
+    if sys.platform == "win32":
+        paths = []
+        for var in ("APPDATA", "ProgramData"):
+            if os.environ.get(var):
+                paths.append(Path(os.environ[var]) / "server-motd" / "config.toml")
+        return paths
+    return [Path("/etc/server-motd/config.toml")]
+
+
+@dataclass
+class Settings:
+    """Top-level (non-module) config keys: `title` and `box`."""
+
+    title: str | None = None
+    box: str = "single"
+
+
+def load_settings(path: Path | None) -> Settings:
+    """Read the top-level keys; invalid values raise ConfigError."""
+    data = _read(path)
+    title, box = data.get("title"), data.get("box", "single")
+    if title is not None and not isinstance(title, str):
+        raise ConfigError("'title' must be a string")
+    if not isinstance(box, str):
+        raise ConfigError("'box' must be a string")
+    return Settings(title, box)
+
+
+def load(path: Path | None) -> list[ModuleSpec | BadEntry]:
+    """Parse the config. Each entry is a ModuleSpec, or a BadEntry."""
+    data = _read(path)
+    entries = data.get("modules", [])
+    if not isinstance(entries, list):
+        raise ConfigError("'modules' must be an array of tables")
+    return [_parse_entry(e) for e in entries]
+
+
+def _read(path: Path | None) -> dict[str, Any]:
+    candidates = [path] if path else default_config_paths()
+    for candidate in candidates:
+        if candidate.is_file():
+            chosen = candidate
+            break
+    else:
+        shown = ", ".join(str(c) for c in candidates) or "(none)"
+        raise ConfigError(f"no config file found (looked in {shown})")
+    try:
+        data = tomllib.loads(chosen.read_text(encoding="utf-8"))
+    except (OSError, tomllib.TOMLDecodeError) as exc:
+        raise ConfigError(f"{chosen}: {exc}") from exc
+    return data
+
+
+def _parse_entry(entry: Any) -> ModuleSpec | BadEntry:
+    if not isinstance(entry, dict):
+        return BadEntry("?", "module entry must be a table")
+    entry = dict(entry)
+    kind = entry.pop("kind", None)
+    name = entry.pop("name", None)
+    enabled = entry.pop("enabled", True)
+    label = name if isinstance(name, str) else (kind if isinstance(kind, str) else "?")
+    if not isinstance(kind, str):
+        return BadEntry(label, "'kind' is required and must be a string")
+    if name is not None and not isinstance(name, str):
+        return BadEntry(label, "'name' must be a string")
+    if not isinstance(enabled, bool):
+        return BadEntry(label, "'enabled' must be a boolean")
+    return ModuleSpec(kind=kind, name=name, enabled=enabled, options=entry)

server_motd/model.py

@@ -0,0 +1,38 @@
+"""Core schema: Status, Row, Result and the Module protocol.
+
+The schema carries no layout. The renderer maps Status to colour.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Protocol
+
+
+class Status(Enum):
+    INFO = "info"
+    OK = "ok"
+    WARN = "warn"
+    CRIT = "crit"
+    UNAVAILABLE = "unavailable"
+
+
+@dataclass(frozen=True)
+class Row:
+    label: str
+    value: str
+    status: Status = Status.INFO
+
+
+@dataclass(frozen=True)
+class Result:
+    title: str
+    rows: list[Row] = field(default_factory=list)
+    status: Status = Status.INFO
+
+
+class Module(Protocol):
+    """A synchronous unit of MOTD output. `fetch` raises on failure."""
+
+    def fetch(self) -> Result: ...

server_motd/modules/__init__.py

@@ -0,0 +1,54 @@
+"""Module registry. Extension conventions for adding a module kind:
+
+1. Create one file, `modules/<kind>.py`, defining a class with
+   `__init__(self, spec: ModuleSpec)` (read options with `spec.take*`, then call
+   `spec.done()`; raise `ConfigError` for bad config) and `fetch() -> Result`
+   (raise on failure; the runner turns that into UNAVAILABLE).
+2. Add ONE import and ONE line to `REGISTRY` below: `"<kind>": <kind>.Class,`.
+   Keep entries alphabetical so parallel tickets merge cleanly.
+3. Test only through the CLI (tests/conftest.py `run_cli`, `write_config`,
+   `assert_golden`). Pin anything non-deterministic at the boundary it comes
+   from (e.g. monkeypatch `psutil` / `time`), not inside the module.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from server_motd.config import ModuleSpec
+from server_motd.model import Module
+from server_motd.modules import (
+    cpu,
+    disks,
+    ips,
+    load,
+    logins,
+    memory,
+    processes,
+    qbittorrent,
+    rtorrent,
+    sabnzbd,
+    servarr,
+    tautulli,
+    updates,
+    uptime,
+)
+
+REGISTRY: dict[str, Callable[[ModuleSpec], Module]] = {
+    "cpu": cpu.Cpu,
+    "disks": disks.Disks,
+    "ips": ips.Ips,
+    "lidarr": servarr.Lidarr,
+    "load": load.Load,
+    "logins": logins.Logins,
+    "memory": memory.Memory,
+    "processes": processes.Processes,
+    "qbittorrent": qbittorrent.QBittorrent,
+    "radarr": servarr.Radarr,
+    "rtorrent": rtorrent.Rtorrent,
+    "sabnzbd": sabnzbd.Sabnzbd,
+    "sonarr": servarr.Sonarr,
+    "tautulli": tautulli.Tautulli,
+    "updates": updates.Updates,
+    "uptime": uptime.Uptime,
+}

server_motd/modules/_common.py

@@ -0,0 +1,42 @@
+"""Helpers shared by the modules: thresholds, status ranking, size formatting."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from server_motd.config import ConfigError, ModuleSpec
+from server_motd.model import Row, Status
+
+_SEVERITY = [Status.INFO, Status.OK, Status.WARN, Status.CRIT, Status.UNAVAILABLE]
+
+
+class Thresholds:
+    """Optional `warn` / `crit` options; a value >= a limit takes that status."""
+
+    def __init__(self, spec: ModuleSpec) -> None:
+        self.warn: float | None = spec.take("warn", float)
+        self.crit: float | None = spec.take("crit", float)
+        if self.warn is not None and self.crit is not None and self.warn > self.crit:
+            raise ConfigError("'warn' must not exceed 'crit'")
+
+    def status(self, value: float) -> Status:
+        if self.warn is None and self.crit is None:
+            return Status.INFO
+        if self.crit is not None and value >= self.crit:
+            return Status.CRIT
+        if self.warn is not None and value >= self.warn:
+            return Status.WARN
+        return Status.OK
+
+
+def worst(rows: Iterable[Row]) -> Status:
+    """Overall status: the most severe row status."""
+    return max((r.status for r in rows), key=_SEVERITY.index, default=Status.INFO)
+
+
+def human_bytes(n: float) -> str:
+    for unit in "BKMGT":
+        if n < 1024 or unit == "T":
+            return f"{n:.0f}{unit}" if unit == "B" else f"{n:.1f}{unit}"
+        n /= 1024
+    raise AssertionError("unreachable")

server_motd/modules/_http.py

@@ -0,0 +1,78 @@
+"""Helpers shared by the HTTP service modules.
+
+One request timeout (kept within the runner's per-module limit), the common
+`url` / `api_key` options, and the mapping of transport failures to short
+user-visible messages.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from collections.abc import Callable
+from typing import Any
+
+from server_motd.config import ConfigError, ModuleSpec
+
+REQUEST_TIMEOUT = 2.5
+
+
+def take_url_and_key(spec: ModuleSpec) -> tuple[str, str]:
+    """Take the required `url` (trailing slash stripped) and `api_key` options."""
+    url = spec.take("url", str)
+    key = spec.take_secret("api_key")
+    if not url:
+        raise ConfigError("'url' is required")
+    if not key:
+        raise ConfigError("'api_key' is required")
+    return url.rstrip("/"), key
+
+
+def request(
+    opener: Callable[..., Any],
+    *args: Any,
+    auth_error: str = "bad API key",
+) -> Any:
+    """Call `opener(*args, timeout=REQUEST_TIMEOUT)` and return the response.
+
+    Failures raise RuntimeError with the message shown in the MOTD. Use as a
+    context manager result: the caller closes the response.
+    """
+    try:
+        return opener(*args, timeout=REQUEST_TIMEOUT)
+    except urllib.error.HTTPError as exc:
+        if exc.code in (401, 403):
+            raise RuntimeError(f"{auth_error} (HTTP {exc.code})") from exc
+        raise RuntimeError(f"HTTP {exc.code}") from exc
+    except urllib.error.URLError as exc:
+        raise RuntimeError(f"unreachable: {exc.reason}") from exc
+    except (OSError, ValueError) as exc:
+        raise RuntimeError(f"bad response: {exc}") from exc
+
+
+def read(
+    opener: Callable[..., Any],
+    *args: Any,
+    auth_error: str = "bad API key",
+) -> bytes:
+    """Open, read fully and close; transport failures map as in `request`."""
+    try:
+        with request(opener, *args, auth_error=auth_error) as resp:
+            data: bytes = resp.read()
+            return data
+    except RuntimeError:
+        raise
+    except (OSError, ValueError) as exc:  # failure while reading the body
+        raise RuntimeError(f"bad response: {exc}") from exc
+
+
+def get_json(
+    target: str | urllib.request.Request, *, auth_error: str = "bad API key"
+) -> Any:
+    """GET a URL (or Request) and parse the JSON body."""
+    body = read(urllib.request.urlopen, target, auth_error=auth_error)
+    try:
+        return json.loads(body)
+    except ValueError as exc:
+        raise RuntimeError(f"bad response: {exc}") from exc

server_motd/modules/cpu.py

@@ -0,0 +1,31 @@
+"""System module: CPU utilisation percent (works everywhere; replaces load on Windows).
+
+Thresholds apply to the utilisation percentage.
+"""
+
+from __future__ import annotations
+
+import psutil
+
+from server_motd.config import ModuleSpec
+from server_motd.model import Result, Row
+from server_motd.modules._common import Thresholds
+
+SAMPLE_SECONDS = 0.2  # cpu_percent(None) reports a meaningless 0.0 on first call
+
+
+class Cpu:
+    def __init__(self, spec: ModuleSpec) -> None:
+        self.title = spec.name or "CPU"
+        self.limits = Thresholds(spec)
+        spec.done()
+
+    def fetch(self) -> Result:
+        percent = psutil.cpu_percent(interval=SAMPLE_SECONDS)
+        cores = psutil.cpu_count() or 1
+        status = self.limits.status(percent)
+        return Result(
+            self.title,
+            [Row("Usage", f"{percent:.0f}% ({cores} cores)", status)],
+            status,
+        )

server_motd/modules/disks.py

@@ -0,0 +1,32 @@
+"""System module: usage per mounted filesystem. Thresholds on percent used."""
+
+from __future__ import annotations
+
+import psutil
+
+from server_motd.config import ModuleSpec
+from server_motd.model import Result, Row
+from server_motd.modules._common import Thresholds, human_bytes, worst
+
+
+class Disks:
+    def __init__(self, spec: ModuleSpec) -> None:
+        self.title = spec.name or "Disks"
+        self.limits = Thresholds(spec)
+        spec.done()
+
+    def fetch(self) -> Result:
+        rows = []
+        for part in psutil.disk_partitions(all=False):
+            try:
+                usage = psutil.disk_usage(part.mountpoint)
+            except OSError:
+                continue  # unreadable mount (e.g. empty drive): not worth a row
+            value = (
+                f"{human_bytes(usage.used)} / {human_bytes(usage.total)} "
+                f"({usage.percent:.0f}%)"
+            )
+            rows.append(Row(part.mountpoint, value, self.limits.status(usage.percent)))
+        if not rows:
+            raise RuntimeError("no mounted filesystems found")
+        return Result(self.title, rows, worst(rows))

server_motd/modules/ips.py

@@ -0,0 +1,31 @@
+"""System module: IP addresses per interface (loopback and link-local skipped)."""
+
+from __future__ import annotations
+
+import ipaddress
+import socket
+
+import psutil
+
+from server_motd.config import ModuleSpec
+from server_motd.model import Result, Row
+
+
+class Ips:
+    def __init__(self, spec: ModuleSpec) -> None:
+        self.title = spec.name or "IPs"
+        spec.done()
+
+    def fetch(self) -> Result:
+        rows = []
+        for iface, addrs in sorted(psutil.net_if_addrs().items()):
+            for addr in addrs:
+                if addr.family not in (socket.AF_INET, socket.AF_INET6):
+                    continue
+                ip = ipaddress.ip_address(addr.address.split("%")[0])
+                if ip.is_loopback or ip.is_link_local:
+                    continue
+                rows.append(Row(iface, str(ip)))
+        if not rows:
+            raise RuntimeError("no non-loopback addresses found")
+        return Result(self.title, rows)

server_motd/modules/load.py

@@ -0,0 +1,30 @@
+"""System module: load average (Linux only; Windows uses the cpu module).
+
+Thresholds apply to the 1-minute load average divided by the CPU count.
+"""
+
+from __future__ import annotations
+
+import sys
+
+import psutil
+
+from server_motd.config import ConfigError, ModuleSpec
+from server_motd.model import Result, Row
+from server_motd.modules._common import Thresholds
+
+
+class Load:
+    def __init__(self, spec: ModuleSpec) -> None:
+        self.title = spec.name or "Load"
+        self.limits = Thresholds(spec)
+        if sys.platform == "win32":
+            raise ConfigError("load is not available on Windows; use the cpu module")
+        spec.done()
+
+    def fetch(self) -> Result:
+        one, five, fifteen = psutil.getloadavg()
+        per_core = one / (psutil.cpu_count() or 1)
+        status = self.limits.status(per_core)
+        value = f"{one:.2f} {five:.2f} {fifteen:.2f}"
+        return Result(self.title, [Row("Load", value, status)], status)

server_motd/modules/logins.py

@@ -0,0 +1,29 @@
+"""System module: logged-in sessions. Thresholds on the session count."""
+
+from __future__ import annotations
+
+import psutil
+
+from server_motd.config import ModuleSpec
+from server_motd.model import Result, Row, Status
+from server_motd.modules._common import Thresholds
+
+
+class Logins:
+    def __init__(self, spec: ModuleSpec) -> None:
+        self.title = spec.name or "Logins"
+        self.limits = Thresholds(spec)
+        spec.done()
+
+    def fetch(self) -> Result:
+        users = psutil.users()
+        status = self.limits.status(len(users))
+        if not users:
+            return Result(self.title, [Row("Sessions", "none", status)], status)
+        rows = []
+        for u in users:
+            where = u.terminal or "-"
+            if u.host:
+                where += f" ({u.host})"
+            rows.append(Row(u.name, where, Status.INFO))
+        return Result(self.title, rows, status)