ftmon 2.0.0a1__py3-none-any.whl

ftmon/__init__.py

@@ -0,0 +1,3 @@
+"""FTMON v2 - lightweight local systems monitor. See SPEC.md and DESIGN.md."""
+
+__version__ = "2.0.0a1"

ftmon/__main__.py

@@ -0,0 +1,9 @@
+"""`python -m ftmon` — same entry as the `ftmon` console script. Exists so
+the e2e harness (TS-05) can spawn the daemon with sys.executable and no
+dependence on installed script shims."""
+
+import sys
+
+from ftmon.cli import main
+
+sys.exit(main())

ftmon/checks/__init__.py

@@ -0,0 +1,7 @@
+"""Bounded external-check execution and strict protocol adapters."""
+
+from ftmon.checks.model import CheckSpec, RawCheckResult
+from ftmon.checks.runner import CheckRunner
+from ftmon.checks.sampler import ExternalSampler
+
+__all__ = ["CheckRunner", "CheckSpec", "ExternalSampler", "RawCheckResult"]

ftmon/checks/jsoncheck.py

@@ -0,0 +1,55 @@
+"""Strict FTMON JSON check output adapter (EC-10)."""
+
+from __future__ import annotations
+
+import json
+import math
+
+from ftmon.checks.model import RawCheckResult, unknown
+from ftmon.checks.text import clean_message
+
+_TOP_KEYS = {"schema", "state", "message", "metrics"}
+_ASCII_WS = b" \t\r\n"
+
+
+class _DuplicateKey(ValueError):
+    pass
+
+
+def _object(pairs: list[tuple[str, object]]) -> dict[str, object]:
+    result: dict[str, object] = {}
+    for key, value in pairs:
+        if key in result:
+            # json.loads normally keeps the last value, which would let a
+            # check make parser behavior depend on duplicate-key policy.
+            raise _DuplicateKey(key)
+        result[key] = value
+    return result
+
+
+def parse(stdout: bytes, duration_s: float) -> RawCheckResult:
+    try:
+        text = stdout.strip(_ASCII_WS).decode("utf-8")
+        payload = json.loads(text, object_pairs_hook=_object)
+    except (UnicodeDecodeError, json.JSONDecodeError, _DuplicateKey):
+        return unknown(duration_s, "protocol")
+    if type(payload) is not dict or set(payload) != _TOP_KEYS:
+        return unknown(duration_s, "protocol")
+    state = payload["state"]
+    message = payload["message"]
+    metrics = payload["metrics"]
+    if payload["schema"] != 1 or type(state) is not int or state not in range(4):
+        return unknown(duration_s, "protocol")
+    if type(message) is not str or type(metrics) is not dict or len(metrics) > 64:
+        return unknown(duration_s, "protocol")
+    values: dict[str, tuple[float, str]] = {}
+    for label, metric in metrics.items():
+        if type(label) is not str or not label or type(metric) is not dict:
+            return unknown(duration_s, "protocol")
+        if set(metric) != {"value", "uom"} or type(metric["uom"]) is not str:
+            return unknown(duration_s, "protocol")
+        value = metric["value"]
+        if type(value) not in (int, float) or not math.isfinite(value):
+            return unknown(duration_s, "protocol")
+        values[label] = (float(value), metric["uom"])
+    return RawCheckResult(state, clean_message(message), duration_s, values)

ftmon/checks/model.py

@@ -0,0 +1,36 @@
+"""Protocol-neutral external check values."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import Literal
+
+
+@dataclass(frozen=True)
+class CheckSpec:
+    alias: str
+    argv: tuple[str, ...]
+    protocol: Literal["nagios", "ftmon-json"]
+    timeout_s: float
+
+
+@dataclass(frozen=True)
+class RawCheckResult:
+    state: int
+    message: str
+    duration_s: float
+    values: Mapping[str, tuple[float, str]]
+    failure: str | None = None
+
+    def __post_init__(self) -> None:
+        # A result is shared by definitions; a caller must not be able to mutate
+        # the raw value cache while another definition projects it.
+        object.__setattr__(self, "values", MappingProxyType(dict(self.values)))
+
+
+def unknown(
+    duration_s: float, failure: str, message: str = "External check failed"
+) -> RawCheckResult:
+    return RawCheckResult(3, message, duration_s, {}, failure)

ftmon/checks/nagios.py

@@ -0,0 +1,98 @@
+"""Nagios plugin output adapter (EC-03)."""
+
+from __future__ import annotations
+
+import math
+import re
+
+from ftmon.checks.model import RawCheckResult, unknown
+from ftmon.checks.text import clean_message
+
+_NUMBER = r"[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?"
+_VALUE = re.compile(rf"^(?P<number>{_NUMBER})(?P<uom>[^;\s]*)$")
+
+
+def _valid_range(value: str) -> bool:
+    value = value.removeprefix("@")
+    if ":" not in value:
+        return re.fullmatch(_NUMBER, value) is not None
+    if value.count(":") != 1:
+        return False
+    start, end = value.split(":")
+    return (
+        (not start or start == "~" or re.fullmatch(_NUMBER, start) is not None)
+        and (not end or re.fullmatch(_NUMBER, end) is not None)
+    )
+
+
+def _tokens(perfdata: str) -> list[tuple[str, str]] | None:
+    result: list[tuple[str, str]] = []
+    index = 0
+    while index < len(perfdata):
+        while index < len(perfdata) and perfdata[index].isspace():
+            index += 1
+        if index == len(perfdata):
+            break
+        if perfdata[index] == "'":
+            end = perfdata.find("'", index + 1)
+            if end < 0:
+                return None
+            label = perfdata[index + 1 : end]
+            index = end + 1
+            if index >= len(perfdata) or perfdata[index] != "=":
+                return None
+            index += 1
+        else:
+            equal = perfdata.find("=", index)
+            if equal < 0 or any(char.isspace() for char in perfdata[index:equal]):
+                return None
+            label = perfdata[index:equal]
+            index = equal + 1
+        end = index
+        while end < len(perfdata) and not perfdata[end].isspace():
+            end += 1
+        if not label or end == index:
+            return None
+        result.append((label, perfdata[index:end]))
+        index = end
+    return result
+
+
+def parse(stdout: bytes, exit_code: int, duration_s: float) -> RawCheckResult:
+    if exit_code not in range(4):
+        return unknown(duration_s, "exit_status")
+    try:
+        first_line = stdout.splitlines()[0].decode("utf-8") if stdout else ""
+    except UnicodeDecodeError:
+        return unknown(duration_s, "protocol")
+    summary, separator, perfdata = first_line.partition("|")
+    values: dict[str, tuple[float, str]] = {}
+    ambiguous: set[str] = set()
+    if separator:
+        tokens = _tokens(perfdata)
+        if tokens is None:
+            return unknown(duration_s, "protocol", clean_message(summary))
+        for label, raw_value in tokens:
+            fields = raw_value.split(";")
+            if len(fields) > 5:
+                continue
+            match = _VALUE.fullmatch(fields[0])
+            if match is None:
+                continue
+            warn_crit = fields[1:3]
+            minimum_maximum = fields[3:5]
+            if any(value and not _valid_range(value) for value in warn_crit):
+                continue
+            if any(value and re.fullmatch(_NUMBER, value) is None
+                   for value in minimum_maximum):
+                continue
+            value = float(match.group("number"))
+            if not math.isfinite(value):
+                continue
+            if label in values:
+                ambiguous.add(label)
+            else:
+                values[label] = (value, match.group("uom"))
+        for label in ambiguous:
+            values.pop(label, None)
+    return RawCheckResult(exit_code, clean_message(summary), duration_s, values)

ftmon/checks/registry.py

@@ -0,0 +1,150 @@
+"""Load the administrator-owned external-check authority (EC-01/06/07)."""
+
+from __future__ import annotations
+
+import os
+import stat
+import tomllib
+from collections.abc import Iterator, Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from types import MappingProxyType
+
+from ftmon.checks.model import CheckSpec
+from ftmon.definitions.schema import valid_name
+from ftmon.expr import ExprSyntaxError, parse_duration
+from ftmon.paths import Paths
+
+MAX_CHECKS = 64
+MAX_ARGS = 32
+MAX_ARG_BYTES = 512
+MAX_ARGV_BYTES = 8192
+PROTOCOLS = frozenset({"ftmon-json", "nagios"})
+
+
+class RegistryError(ValueError):
+    """A stable, redacted registry failure suitable for self-events."""
+
+    def __init__(self, category: str) -> None:
+        self.category = category
+        super().__init__(category)
+
+
+@dataclass(frozen=True)
+class CheckRegistry(Mapping[str, CheckSpec]):
+    """Immutable registry published only after every entry validates."""
+
+    _entries: Mapping[str, CheckSpec]
+
+    def __getitem__(self, alias: str) -> CheckSpec:
+        return self._entries[alias]
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._entries)
+
+    def __len__(self) -> int:
+        return len(self._entries)
+
+
+def empty() -> CheckRegistry:
+    """Return an immutable no-authority registry for missing/invalid setup."""
+    return CheckRegistry(MappingProxyType({}))
+
+
+def _regular_protected(path: Path, category: str) -> os.stat_result:
+    try:
+        info = path.lstat()
+    except OSError as exc:
+        raise RegistryError(category) from exc
+    if not stat.S_ISREG(info.st_mode) or path.is_symlink():
+        raise RegistryError(category)
+    if info.st_uid not in {0, os.getuid()} or info.st_mode & 0o022:
+        raise RegistryError(category)
+    return info
+
+
+def _validate_registry_file(path: Path) -> None:
+    _regular_protected(path, "registry_untrusted")
+    # The selected registry's directory is the trust root: checking above it
+    # would incorrectly reject safe user registries merely because /tmp or a
+    # shared home mount is writable outside FTMON's authority boundary.
+    try:
+        parent = path.parent.lstat()
+    except OSError as exc:
+        raise RegistryError("registry_untrusted") from exc
+    if not stat.S_ISDIR(parent.st_mode) or parent.st_mode & 0o022:
+        raise RegistryError("registry_untrusted")
+
+
+def _under(path: Path, root: Path) -> bool:
+    try:
+        path.relative_to(root)
+    except ValueError:
+        return False
+    return True
+
+
+def _timeout(value: object) -> float:
+    if value is None:
+        return 10.0
+    if not isinstance(value, str):
+        raise RegistryError("invalid_timeout")
+    try:
+        seconds = parse_duration(value)
+    except ExprSyntaxError as exc:
+        raise RegistryError("invalid_timeout") from exc
+    if not 1.0 <= seconds <= 30.0:
+        raise RegistryError("invalid_timeout")
+    return seconds
+
+
+def _entry(alias: object, value: object, paths: Paths | None) -> CheckSpec:
+    if not valid_name(alias):
+        raise RegistryError("invalid_alias")
+    if not isinstance(value, dict) or set(value) - {"argv", "protocol", "timeout"}:
+        raise RegistryError("invalid_entry")
+    argv = value.get("argv")
+    protocol = value.get("protocol")
+    if (
+        not isinstance(argv, list)
+        or not 1 <= len(argv) <= MAX_ARGS
+        or not all(isinstance(arg, str) and arg for arg in argv)
+    ):
+        raise RegistryError("invalid_argv")
+    encoded = [arg.encode("utf-8") for arg in argv]
+    if any(len(arg) > MAX_ARG_BYTES for arg in encoded) or sum(map(len, encoded)) > MAX_ARGV_BYTES:
+        raise RegistryError("invalid_argv")
+    executable = Path(argv[0])
+    if not executable.is_absolute():
+        raise RegistryError("invalid_executable")
+    if paths is not None:
+        resolved = executable.resolve(strict=False)
+        forbidden_roots = (paths.data_dir, paths.state_dir, paths.runtime_dir)
+        if any(_under(resolved, root.resolve()) for root in forbidden_roots):
+            raise RegistryError("invalid_executable")
+    info = _regular_protected(executable, "executable_unready")
+    if not info.st_mode & 0o111:
+        raise RegistryError("executable_unready")
+    if protocol not in PROTOCOLS:
+        raise RegistryError("invalid_protocol")
+    return CheckSpec(alias, tuple(argv), protocol, _timeout(value.get("timeout")))
+
+
+def load(path: Path, *, paths: Paths | None = None) -> CheckRegistry:
+    """Validate and return a complete immutable registry.
+
+    Callers retain their previous object when this raises, which makes reload
+    publication atomic without this loader owning daemon lifecycle state.
+    """
+    _validate_registry_file(path)
+    try:
+        document = tomllib.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, tomllib.TOMLDecodeError) as exc:
+        raise RegistryError("invalid_toml") from exc
+    if set(document) != {"check"} or not isinstance(document["check"], dict):
+        raise RegistryError("invalid_schema")
+    checks = document["check"]
+    if len(checks) > MAX_CHECKS:
+        raise RegistryError("too_many_checks")
+    entries = {alias: _entry(alias, value, paths) for alias, value in checks.items()}
+    return CheckRegistry(MappingProxyType(entries))

ftmon/checks/runner.py

@@ -0,0 +1,121 @@
+"""No-shell, process-group-bounded external check runner (EC-02)."""
+
+from __future__ import annotations
+
+import os
+import signal
+import stat
+import subprocess
+import threading
+from pathlib import Path
+
+from ftmon.checks import jsoncheck, nagios
+from ftmon.checks.model import CheckSpec, RawCheckResult, unknown
+from ftmon.clock import Clock, SystemClock
+
+_STDOUT_LIMIT = 64 * 1024
+_STDERR_LIMIT = 8 * 1024
+
+
+def _read_bounded(stream: object, limit: int, output: bytearray, overflow: list[bool]) -> None:
+    while True:
+        chunk = stream.read(8192)  # type: ignore[attr-defined]
+        if not chunk:
+            return
+        remaining = limit - len(output)
+        output.extend(chunk[:remaining])
+        if len(chunk) > remaining:
+            overflow[0] = True
+
+
+class CheckRunner:
+    def __init__(self, state_dir: Path, clock: Clock | None = None):
+        self._state_dir = state_dir
+        self._clock = clock or SystemClock()
+
+    def _trusted_executable(self, executable: str) -> bool:
+        path = Path(executable)
+        try:
+            info = path.lstat()
+            resolved = path.resolve(strict=True)
+            resolved_info = resolved.lstat()
+        except (OSError, RuntimeError):
+            return False
+        return (
+            path.is_absolute()
+            and not stat.S_ISLNK(info.st_mode)
+            and stat.S_ISREG(info.st_mode)
+            and resolved == path
+            and resolved_info.st_uid in {0, os.geteuid()}
+            and not resolved_info.st_mode & (stat.S_IWGRP | stat.S_IWOTH)
+            and bool(resolved_info.st_mode & (stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH))
+        )
+
+    def run(self, spec: CheckSpec, deadline_mono: float) -> RawCheckResult:
+        started = self._clock.monotonic()
+        if not spec.argv or not self._trusted_executable(spec.argv[0]):
+            return unknown(0.0, "executable")
+        timeout = min(spec.timeout_s, max(0.0, deadline_mono - started))
+        if timeout <= 0:
+            return unknown(0.0, "timeout")
+        env = {
+            "PATH": os.defpath,
+            "FTMON_CHECK_ALIAS": spec.alias,
+            "FTMON_CHECK_TIMEOUT": str(spec.timeout_s),
+        }
+        try:
+            process = subprocess.Popen(
+                spec.argv,
+                stdin=subprocess.DEVNULL,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                cwd=self._state_dir,
+                env=env,
+                close_fds=True,
+                start_new_session=True,
+            )
+        except OSError:
+            return unknown(self._clock.monotonic() - started, "launch")
+        stdout, stderr = bytearray(), bytearray()
+        stdout_overflow, stderr_overflow = [False], [False]
+        readers = [
+            threading.Thread(
+                target=_read_bounded,
+                args=(process.stdout, _STDOUT_LIMIT, stdout, stdout_overflow),
+                daemon=True,
+            ),
+            threading.Thread(
+                target=_read_bounded,
+                args=(process.stderr, _STDERR_LIMIT, stderr, stderr_overflow),
+                daemon=True,
+            ),
+        ]
+        for reader in readers:
+            reader.start()
+        timed_out = False
+        try:
+            process.wait(timeout=timeout)
+        except subprocess.TimeoutExpired:
+            timed_out = True
+            os.killpg(process.pid, signal.SIGTERM)
+            try:
+                process.wait(timeout=0.25)
+            except subprocess.TimeoutExpired:
+                os.killpg(process.pid, signal.SIGKILL)
+                process.wait()
+        for reader in readers:
+            reader.join()
+        duration = max(0.0, self._clock.monotonic() - started)
+        if timed_out:
+            return unknown(duration, "timeout")
+        if stdout_overflow[0]:
+            return unknown(duration, "output_limit")
+        if process.returncode is None or process.returncode < 0:
+            return unknown(duration, "signal")
+        if spec.protocol == "nagios":
+            return nagios.parse(bytes(stdout), process.returncode, duration)
+        if spec.protocol == "ftmon-json":
+            if process.returncode != 0:
+                return unknown(duration, "exit_status")
+            return jsoncheck.parse(bytes(stdout), duration)
+        return unknown(duration, "protocol")

ftmon/checks/sampler.py

@@ -0,0 +1,129 @@
+"""Per-cycle external alias scheduling and definition-specific projection."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Callable, Iterable, Mapping
+from typing import ClassVar, Protocol
+
+from ftmon.checks.model import CheckSpec, RawCheckResult
+from ftmon.checks.registry import CheckRegistry
+from ftmon.clock import Clock, SystemClock
+from ftmon.definitions.loader import MonitorDef
+from ftmon.model import EntitySample, Snapshot, SourceDecl
+from ftmon.sources.base import SOURCE_DECLS
+
+
+class Runner(Protocol):
+    def run(self, spec: CheckSpec, deadline_mono: float) -> RawCheckResult: ...
+
+
+class ExternalSampler:
+    """Run each due alias once, then project its immutable result per monitor.
+
+    ``prepare`` is deliberately separate from ``sample``: the scheduler knows
+    the complete due-monitor set, while the ordinary pipeline asks for one
+    monitor at a time. This boundary is what permits both fair alias ordering
+    and definition-specific metric declarations.
+    """
+
+    decl: ClassVar[SourceDecl] = SOURCE_DECLS["external"]
+
+    def __init__(
+        self,
+        registry: CheckRegistry,
+        runner: Runner,
+        counter: Callable[[str], None],
+        clock: Clock | None = None,
+    ) -> None:
+        self._registry = registry
+        self._runner = runner
+        self._counter = counter
+        self._clock = clock or SystemClock()
+        self._next_alias: str | None = None
+        self._results: dict[str, RawCheckResult] = {}
+
+    def set_registry(self, registry: CheckRegistry) -> None:
+        """Swap an already validated registry at a cycle boundary."""
+        self._registry = registry
+        if self._next_alias not in registry:
+            self._next_alias = None
+
+    def prepare(self, monitors: Iterable[MonitorDef], deadline_mono: float) -> None:
+        """Execute unique aliases for one cycle within the shared deadline."""
+        aliases = list(
+            dict.fromkeys(
+                monitor.source_options["check"]
+                for monitor in monitors
+                if monitor.source == "external"
+                and monitor.source_options.get("check") in self._registry
+            )
+        )
+        self._results = {}
+        if not aliases:
+            self._next_alias = None
+            return
+
+        start = aliases.index(self._next_alias) if self._next_alias in aliases else 0
+        ordered = aliases[start:] + aliases[:start]
+        for index, alias in enumerate(ordered):
+            if self._clock.monotonic() >= deadline_mono:
+                # Leave the first unstarted alias at the head next cycle; slow
+                # aliases therefore cannot permanently starve later entries.
+                self._next_alias = alias
+                for _ in ordered[index:]:
+                    self._counter("external_checks_skipped")
+                return
+            result = self._runner.run(self._registry[alias], deadline_mono)
+            self._results[alias] = result
+            if result.failure is not None:
+                self._counter(f"external_check_failures:{result.failure}")
+
+        self._next_alias = ordered[0]
+
+    def project(self, monitor: MonitorDef, now: float) -> Snapshot:
+        """Project a cached raw result through one monitor's declared mappings."""
+        options = monitor.source_options
+        alias = options["check"]
+        raw = self._results.get(alias)
+        if raw is None:
+            # A budget skip is absence, not synthetic UNKNOWN evidence: an
+            # absent entity cannot falsely clear or alter an incident.
+            return Snapshot(source="external", ts=now, entities=())
+
+        return self._project_options(options, raw, now)
+
+    def sample(self, now: float, deadline_mono: float, options: Mapping) -> Snapshot:
+        """Sampler-compatible projection after ``prepare`` has run."""
+        # Kept mapping-only so future pipeline wiring does not need to retain a
+        # MonitorDef just to consume the cycle cache.
+        raw = self._results.get(options["check"])
+        if raw is None:
+            return Snapshot(source="external", ts=now, entities=())
+        return self._project_options(options, raw, now)
+
+    def _project_options(self, options: Mapping, raw: RawCheckResult, now: float) -> Snapshot:
+        metrics = {
+            "plugin_state": float(raw.state),
+            "plugin_ok": float(raw.state == 0),
+            "duration_s": raw.duration_s,
+        }
+        for mapping in options.get("perfdata", ()):
+            source_value = raw.values.get(mapping["label"])
+            if source_value is None:
+                continue
+            value, uom = source_value
+            if uom != mapping["plugin_uom"]:
+                self._counter("external_perfdata_rejected:uom")
+                continue
+            scaled = value * mapping.get("scale", 1.0)
+            if not math.isfinite(value) or not math.isfinite(scaled):
+                self._counter("external_perfdata_rejected:non_finite")
+                continue
+            metrics[mapping["metric"]] = scaled
+        entity = EntitySample(
+            entity_id=options["entity"],
+            attrs={"plugin_message": raw.message},
+            metrics=metrics,
+        )
+        return Snapshot(source="external", ts=now, entities=(entity,))

ftmon/checks/text.py

@@ -0,0 +1,10 @@
+"""Untrusted plugin text normalization."""
+
+MESSAGE_LIMIT = 2048
+
+
+def clean_message(value: str) -> str:
+    # Preserve useful non-ASCII text, but remove ASCII controls that could forge
+    # terminal/log structure. Newlines never reach here from the protocol adapters.
+    cleaned = "".join(char for char in value if ord(char) >= 32 and ord(char) != 127)
+    return cleaned.encode("utf-8")[:MESSAGE_LIMIT].decode("utf-8", errors="ignore")