hiac-utils 0.1.0__py3-none-any.whl

hiac_utils/__init__.py

@@ -0,0 +1,30 @@
+# Scripts for automated Nextcloud setup.
+# Copyright (C) 2026 Guillermo López Alejos
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+"""hiac_utils — shared HIAC utilities."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+from hiac_utils.log_context import LogContext
+
+try:
+    __version__ = _pkg_version("hiac_utils")
+except PackageNotFoundError:  # pragma: no cover - running from an uninstalled checkout
+    __version__ = "0+unknown"
+
+__all__ = ["__version__", "LogContext"]

hiac_utils/__main__.py

@@ -0,0 +1,49 @@
+# Scripts for automated Nextcloud setup.
+# Copyright (C) 2026 Guillermo López Alejos
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+"""Entry point: ``python -m hiac_utils``.
+
+hiac_utils is primarily an Ansible filter-plugin library with no operational
+CLI of its own; this entry point exists so the component can report its own
+version, per AGENTS.md's "Version file" section.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from . import __version__
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="python -m hiac_utils",
+        description="HIAC shared utility library (Ansible filter plugins).",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"hiac_utils {__version__}",
+    )
+    return parser
+
+
+def main() -> None:
+    build_parser().parse_args()
+
+
+if __name__ == "__main__":
+    main()

hiac_utils/log_context.py

@@ -0,0 +1,81 @@
+# Scripts for automated Nextcloud setup.
+# Copyright (C) 2026 Guillermo López Alejos
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+"""Per-thread logging context labels, stackable via context managers."""
+
+from __future__ import annotations
+
+import contextvars
+import logging
+from types import TracebackType
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    pass
+
+__all__ = ["LogContext"]
+
+
+class LogContext:
+    """Push a label onto the logging context stack (thread-safe via ContextVar).
+
+    Labels from nested contexts are joined with ".":
+
+        with LogContext("SCN0004"):
+            with LogContext("hiac_entrypoint"):
+                # log records carry ctx="SCN0004.hiac_entrypoint"
+
+    Use `install_filter` once per handler to inject ``record.ctx`` into every
+    log record that passes through it. Then include ``%(ctx)s`` in the format
+    string; the value is ``"[label] "`` when a context is active, ``""`` when
+    not, so existing format strings need only a ``%(ctx)s`` prefix added.
+    """
+
+    _var: contextvars.ContextVar[str] = contextvars.ContextVar(
+        "hiac_log_ctx", default=""
+    )
+
+    class _Filter(logging.Filter):
+        def filter(self, record: logging.LogRecord) -> bool:
+            ctx = LogContext._var.get()
+            record.ctx = f"[{ctx}] " if ctx else ""  # type: ignore[attr-defined]
+            return True
+
+    def __init__(self, label: str) -> None:
+        current = self._var.get()
+        new = (f"{current}.{label}" if current else label) if label else current
+        self._token = self._var.set(new)
+
+    def __enter__(self) -> "LogContext":
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        self._var.reset(self._token)
+
+    @classmethod
+    def current(cls) -> str:
+        """Return the active context string for propagation to child threads."""
+        return cls._var.get()
+
+    @classmethod
+    def install_filter(cls, handler: logging.Handler) -> None:
+        """Attach the ctx-injecting filter to *handler*. Call once per handler."""
+        handler.addFilter(cls._Filter())

hiac_utils/log_monitor/__init__.py

@@ -0,0 +1,27 @@
+# Scripts for automated Nextcloud setup.
+# Copyright (C) 2026 Guillermo López Alejos
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+"""hiac_utils.log_monitor — log monitoring and early-error-detection engine."""
+
+from .profile import GroupRule, MessageRule, Profile, load_profile
+from .engine import LogMonitorEngine
+from .thread import LogMonitorThread
+
+__all__ = [
+    "GroupRule", "MessageRule", "Profile", "load_profile",
+    "LogMonitorEngine",
+    "LogMonitorThread",
+]

hiac_utils/log_monitor/__main__.py

@@ -0,0 +1,197 @@
+# Scripts for automated Nextcloud setup.
+# Copyright (C) 2026 Guillermo López Alejos
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+"""CLI entry point: python -m hiac_utils.log_monitor <subcommand>
+
+Subcommands
+-----------
+process
+    Read log lines from stdin, evaluate profile rules, emit D-Bus signals.
+    Also writes human-friendly log output to --human-friendly-log-path.
+
+    Usage::
+
+        python -m hiac_utils.log_monitor process \\
+            --profile /path/to/log_monitor_profile.yml \\
+            --log-processor-id hiac_server_journalctl \\
+            --dbus-address unix:path=/run/user/1000/bus \\
+            --human-friendly-log-path /evidence/nodes/hiac_server_1/journalctl.log
+
+listen
+    Subscribe to D-Bus, write all events to --events-log, and print
+    CRITICAL events to stdout (one line per event).
+
+    Usage::
+
+        python -m hiac_utils.log_monitor listen \\
+            --dbus-address unix:path=/run/user/1000/bus \\
+            --events-log /evidence/log/events.log
+"""
+
+from __future__ import annotations
+
+import argparse
+import select
+import signal
+import sys
+import threading
+import time
+from pathlib import Path
+
+
+def _process_stdin(engine, human_fh) -> None:
+    """Read log lines from stdin until EOF, feeding each line to the engine."""
+    stdin = sys.stdin
+    # 1-second select timeout so tick() fires even during idle periods.
+    while True:
+        ready, _, _ = select.select([stdin], [], [], 1.0)
+        if ready:
+            line = stdin.readline()
+            if not line:  # EOF — SSH process terminated
+                break
+            human_fh.write(line)
+            human_fh.flush()
+            engine.process_line(line)
+        else:
+            engine.tick()
+
+
+def _process_file(path: str, retry_sleep: float, retry_max: int,
+                  engine, human_fh) -> None:
+    """Wait for `path` to exist, then follow it line by line until SIGTERM/SIGINT.
+
+    retry_sleep: seconds to wait between existence checks.
+    retry_max:   max number of sleep cycles before giving up (0 = wait forever).
+    """
+    _stop = threading.Event()
+
+    def _on_signal(signum, frame):
+        _stop.set()
+
+    signal.signal(signal.SIGTERM, _on_signal)
+    signal.signal(signal.SIGINT, _on_signal)
+
+    file_path = Path(path)
+    attempts = 0
+    while not file_path.exists() and not _stop.is_set():
+        if retry_max > 0 and attempts >= retry_max:
+            return  # file never appeared within the retry budget
+        engine.tick()
+        _stop.wait(retry_sleep)  # interruptible sleep — wakes immediately on SIGTERM
+        attempts += 1
+
+    if _stop.is_set() or not file_path.exists():
+        return
+
+    with file_path.open("r", encoding="utf-8", errors="replace") as fh:
+        while not _stop.is_set():
+            line = fh.readline()
+            if line:
+                human_fh.write(line)
+                human_fh.flush()
+                engine.process_line(line)
+            else:
+                engine.tick()
+                _stop.wait(0.5)
+
+
+def _cmd_process(args: argparse.Namespace) -> int:
+    from .engine import LogMonitorEngine
+    from .profile import load_profile
+    from .signals import make_dbus_sender
+
+    profile = load_profile(Path(args.profile), timeout_factor=args.timeout_factor)
+    signal_fn = make_dbus_sender(args.dbus_address, args.log_processor_id)
+    engine = LogMonitorEngine(profile, signal_fn)
+
+    human_fh = open(args.human_friendly_log_path, "w", encoding="utf-8")
+    try:
+        if args.file:
+            _process_file(
+                args.file, args.retry_sleep, args.retry_max, engine, human_fh,
+            )
+        else:
+            _process_stdin(engine, human_fh)
+    finally:
+        human_fh.close()
+
+    return 0
+
+
+def _cmd_listen(args: argparse.Namespace) -> int:
+    from .listener import run_listener
+
+    run_listener(
+        dbus_address=args.dbus_address,
+        events_log_path=Path(args.events_log),
+    )
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="python -m hiac_utils.log_monitor",
+        description="HIAC log monitor — process log streams or listen for D-Bus events.",
+    )
+    sub = parser.add_subparsers(dest="subcommand", required=True)
+
+    # process subcommand
+    p = sub.add_parser("process", help="Read stdin or a file, evaluate rules, emit D-Bus signals")
+    p.add_argument("--profile", required=True, help="Path to log_monitor_profile.yml")
+    p.add_argument("--log-processor-id", required=True, help="Identifier for this processor")
+    p.add_argument("--dbus-address", required=True, help="D-Bus session bus address")
+    p.add_argument(
+        "--human-friendly-log-path", required=True,
+        help="Path to write human-readable log output",
+    )
+    p.add_argument(
+        "--timeout-factor", type=float, default=1.0, metavar="F",
+        help="Multiply all non-zero timeouts by F (default: 1.0)",
+    )
+    p.add_argument(
+        "--file", default=None, metavar="PATH",
+        help="Follow a log file instead of stdin (waits for the file to appear)",
+    )
+    p.add_argument(
+        "--retry-sleep", type=float, default=15.0, metavar="S",
+        help="Seconds between file-existence checks when --file is used (default: 15)",
+    )
+    p.add_argument(
+        "--retry-max", type=int, default=3, metavar="N",
+        help="Max existence-check cycles before giving up; 0 = wait forever (default: 3)",
+    )
+
+    # listen subcommand
+    ls = sub.add_parser("listen", help="Subscribe to D-Bus and write events.log")
+    ls.add_argument("--dbus-address", required=True, help="D-Bus session bus address")
+    ls.add_argument("--events-log", required=True, help="Path to events log file")
+
+    return parser
+
+
+def main(argv=None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.subcommand == "process":
+        return _cmd_process(args)
+    if args.subcommand == "listen":
+        return _cmd_listen(args)
+    parser.print_help()
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

hiac_utils/log_monitor/engine.py

@@ -0,0 +1,252 @@
+# Scripts for automated Nextcloud setup.
+# Copyright (C) 2026 Guillermo López Alejos
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+"""Stateful rule evaluator for the log monitor engine.
+
+The engine processes log lines one at a time.  On each line (or on a
+periodic tick) it:
+
+1. Tries to match the line against currently-active rules.
+2. Checks whether any active rule has exceeded its timeout.
+3. Emits events via a signal_fn callback for completed or timed-out nodes.
+
+signal_fn signature::
+
+    signal_fn(event_name: str, status: str, time_to_complete: float) -> None
+
+``time_to_complete`` is the wall-clock seconds from when the node was
+entered until the event fired.
+"""
+
+from __future__ import annotations
+
+import re
+import time as _time
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Callable
+
+from .profile import GroupRule, MessageRule, Profile, RuleNode
+
+SignalFn = Callable[[str, str, float], None]
+
+_TIMEOUT_STATUS = "ERROR"  # fallback; prefer rule.timeout_status when available
+
+
+# ── Node states ───────────────────────────────────────────────────────────────
+
+class _NodeState(ABC):
+    def __init__(self, rule: RuleNode, entered_at: float) -> None:
+        self._rule = rule
+        self._entered_at = entered_at
+        self._done = False
+
+    @property
+    def done(self) -> bool:
+        return self._done
+
+    @abstractmethod
+    def check(self, content: str | None, now: float, signal_fn: SignalFn) -> None:
+        """Process one log line (or a tick if content is None)."""
+
+
+class _MessageState(_NodeState):
+    def __init__(self, rule: MessageRule, entered_at: float) -> None:
+        super().__init__(rule, entered_at)
+        self._rule: MessageRule
+
+    def check(self, content: str | None, now: float, signal_fn: SignalFn) -> None:
+        if self._done:
+            return
+        # Timeout check first.
+        if self._rule.timeout > 0 and (now - self._entered_at) >= self._rule.timeout:
+            self._done = True
+            if self._rule.notify:
+                signal_fn(
+                    self._rule.name,
+                    getattr(self._rule, "timeout_status", _TIMEOUT_STATUS),
+                    now - self._entered_at,
+                )
+            return
+        if content is not None and self._rule.pattern.search(content):
+            self._done = True
+            if self._rule.notify:
+                signal_fn(
+                    self._rule.name,
+                    self._rule.status,
+                    now - self._entered_at,
+                )
+
+
+class _GroupState(_NodeState):
+    def __init__(self, rule: GroupRule, entered_at: float) -> None:
+        super().__init__(rule, entered_at)
+        self._rule: GroupRule
+        self._children: list[_NodeState] = [
+            _make_state(child, entered_at) for child in rule.children
+        ]
+        # sequence: index of the currently-active child
+        self._seq_index: int = 0
+        # all_any_order: set of child indices already matched
+        self._matched_indices: set[int] = set()
+
+    def check(self, content: str | None, now: float, signal_fn: SignalFn) -> None:
+        if self._done:
+            return
+
+        # Group-level timeout.
+        if self._rule.timeout > 0 and (now - self._entered_at) >= self._rule.timeout:
+            self._done = True
+            if self._rule.notify:
+                signal_fn(
+                    self._rule.name,
+                    getattr(self._rule, "timeout_status", _TIMEOUT_STATUS),
+                    now - self._entered_at,
+                )
+            return
+
+        if self._rule.constraint == "sequence":
+            self._check_sequence(content, now, signal_fn)
+        elif self._rule.constraint == "at_least_one":
+            self._check_at_least_one(content, now, signal_fn)
+        else:  # all_any_order
+            self._check_all_any_order(content, now, signal_fn)
+
+    def _check_sequence(
+        self, content: str | None, now: float, signal_fn: SignalFn
+    ) -> None:
+        """Advance through children in order; each must match before the next starts."""
+        if self._seq_index >= len(self._children):
+            return
+
+        active = self._children[self._seq_index]
+        was_done = active.done
+        active.check(content, now, signal_fn)
+
+        if active.done and not was_done:
+            self._seq_index += 1
+            if self._seq_index < len(self._children):
+                # Reset the next child's clock to now.
+                self._children[self._seq_index] = _make_state(
+                    self._rule.children[self._seq_index], now
+                )
+            else:
+                # All children matched.
+                self._done = True
+                if self._rule.notify:
+                    signal_fn(
+                        self._rule.name,
+                        self._rule.status,
+                        now - self._entered_at,
+                    )
+
+    def _check_at_least_one(
+        self, content: str | None, now: float, signal_fn: SignalFn
+    ) -> None:
+        """Done when any single child matches."""
+        for child in self._children:
+            if child.done:
+                continue
+            was_done = child.done
+            child.check(content, now, signal_fn)
+            if child.done and not was_done:
+                self._done = True
+                if self._rule.notify:
+                    signal_fn(
+                        self._rule.name,
+                        self._rule.status,
+                        now - self._entered_at,
+                    )
+                return
+
+    def _check_all_any_order(
+        self, content: str | None, now: float, signal_fn: SignalFn
+    ) -> None:
+        """Done when every child has matched (in any order)."""
+        for i, child in enumerate(self._children):
+            if i in self._matched_indices:
+                continue
+            was_done = child.done
+            child.check(content, now, signal_fn)
+            if child.done and not was_done:
+                self._matched_indices.add(i)
+
+        if len(self._matched_indices) == len(self._children):
+            self._done = True
+            if self._rule.notify:
+                signal_fn(
+                    self._rule.name,
+                    self._rule.status,
+                    now - self._entered_at,
+                )
+
+
+def _make_state(rule: RuleNode, entered_at: float) -> _NodeState:
+    if isinstance(rule, GroupRule):
+        return _GroupState(rule, entered_at)
+    return _MessageState(rule, entered_at)
+
+
+# ── Log line parsers ──────────────────────────────────────────────────────────
+
+# dmesg --follow default format: "[timestamp] content" or "content"
+_DMESG_RE = re.compile(r"^\[\s*\d+\.\d+\]\s*(.*)$")
+# journalctl default format: "MMM DD HH:MM:SS hostname proc[pid]: content"
+_JOURNALCTL_RE = re.compile(
+    r"^\w{3}\s+\d{1,2}\s+\d{2}:\d{2}:\d{2}\s+\S+\s+[^:]+:\s*(.*)$"
+)
+# docker service logs --follow --timestamps: "YYYY-MM-DDTHH:MM:SS.nZ svc.N.id | content"
+_DOCKER_RE = re.compile(r"^\S+\s+\S+\s*\|\s*(.*)$")
+
+
+def _extract_content(line: str, fmt: str) -> str:
+    """Strip format-specific prefix from a log line; return the raw message content."""
+    line = line.rstrip("\n\r")
+    if fmt == "dmesg":
+        m = _DMESG_RE.match(line)
+        return m.group(1) if m else line
+    if fmt == "journalctl":
+        m = _JOURNALCTL_RE.match(line)
+        return m.group(1) if m else line
+    if fmt == "docker":
+        m = _DOCKER_RE.match(line)
+        return m.group(1) if m else line
+    return line
+
+
+# ── Public engine ─────────────────────────────────────────────────────────────
+
+class LogMonitorEngine:
+    """Feed log lines into the rule tree and emit events via signal_fn."""
+
+    def __init__(self, profile: Profile, signal_fn: SignalFn) -> None:
+        self._format = profile.format
+        self._signal_fn = signal_fn
+        self._root = _make_state(profile.root_rule, _time.monotonic())
+
+    @property
+    def done(self) -> bool:
+        """True when the root rule has fully matched or timed out."""
+        return self._root.done
+
+    def process_line(self, line: str) -> None:
+        """Feed one log line to the engine."""
+        content = _extract_content(line, self._format)
+        self._root.check(content, _time.monotonic(), self._signal_fn)
+
+    def tick(self) -> None:
+        """Check timeouts without a new log line (called on read timeout)."""
+        self._root.check(None, _time.monotonic(), self._signal_fn)