embedded-lab-control 0.2.0__py3-none-any.whl

labctl/core/safe_open.py

@@ -0,0 +1,109 @@
+"""
+Open host paths without following symlinks, for check-then-use safety.
+
+The MCP host-path allowlist resolves a path and checks it against allowed
+directories. If the file were then re-opened *by path* later (after a
+power-off, a mux switch, a wait for the reader...), anyone able to write to
+a directory on that path could swap in a symlink in between and redirect
+the read or write; raw images are even read by ``sudo dd`` (root). These
+helpers open the already-resolved path one component at a time with
+``O_NOFOLLOW``, so a symlink anywhere on the path makes the open fail
+instead of being followed. Callers then use the returned file descriptor,
+never the path, for the actual I/O.
+"""
+
+import errno
+import fcntl
+import os
+import stat
+
+# Intermediate directories need only search permission with O_PATH (Linux);
+# fall back to O_RDONLY elsewhere. O_DIRECTORY|O_NOFOLLOW makes a symlinked
+# component fail with ENOTDIR/ELOOP rather than be followed.
+_WALK_FLAGS = getattr(os, "O_PATH", os.O_RDONLY) | os.O_DIRECTORY | os.O_NOFOLLOW
+
+
+def _components(path: str) -> list[str]:
+    if not os.path.isabs(path):
+        raise ValueError(f"path must be absolute: {path!r}")
+    parts = [p for p in path.split("/") if p]
+    if any(p in (".", "..") for p in parts):
+        raise OSError(errno.EINVAL, "path must be normalized (no '.' or '..')")
+    return parts
+
+
+def _walk(parts: list[str], *, create: bool, mode: int) -> int:
+    """Open the directory reached by ``parts`` from "/", no symlinks."""
+    fd = os.open("/", _WALK_FLAGS)
+    try:
+        for name in parts:
+            try:
+                nxt = os.open(name, _WALK_FLAGS, dir_fd=fd)
+            except FileNotFoundError:
+                if not create:
+                    raise
+                try:
+                    os.mkdir(name, mode, dir_fd=fd)
+                except FileExistsError:
+                    pass  # created concurrently; the open below re-checks it
+                nxt = os.open(name, _WALK_FLAGS, dir_fd=fd)
+            os.close(fd)
+            fd = nxt
+    except BaseException:
+        os.close(fd)
+        raise
+    return fd
+
+
+def open_regular_nonblocking(
+    name: str, flags: int, mode: int = 0o644, dir_fd: int | None = None
+) -> int:
+    """Open ``name`` (O_NOFOLLOW), insisting it is a regular file.
+
+    Opened with O_NONBLOCK so a FIFO planted in a shared directory can't
+    block the open (which would hang the caller while it holds locks);
+    anything that isn't a regular file is closed and refused with OSError;
+    O_NONBLOCK is then cleared for normal I/O.
+    """
+    fd = os.open(name, flags | os.O_NOFOLLOW | os.O_NONBLOCK, mode, dir_fd=dir_fd)
+    try:
+        if not stat.S_ISREG(os.fstat(fd).st_mode):
+            raise OSError(errno.EINVAL, f"not a regular file: {name}")
+        fcntl.fcntl(fd, fcntl.F_SETFL, fcntl.fcntl(fd, fcntl.F_GETFL) & ~os.O_NONBLOCK)
+    except BaseException:
+        os.close(fd)
+        raise
+    return fd
+
+
+def open_file_nofollow(path: str, flags: int = os.O_RDONLY, mode: int = 0o644) -> int:
+    """Open the regular file at absolute, normalized ``path``, no symlinks.
+
+    Raises OSError (ELOOP/ENOTDIR) if any component is a symlink, and
+    (EINVAL) if the target isn't a regular file (e.g. a FIFO); never blocks
+    on opening a FIFO.
+    """
+    parts = _components(path)
+    if not parts:
+        raise IsADirectoryError(errno.EISDIR, "path is the root directory")
+    parent = _walk(parts[:-1], create=False, mode=0o755)
+    try:
+        return open_regular_nonblocking(parts[-1], flags, mode, dir_fd=parent)
+    finally:
+        os.close(parent)
+
+
+def open_dir_nofollow(path: str, *, create: bool = False, mode: int = 0o775) -> int:
+    """Open (optionally creating) directory ``path`` with no symlink anywhere.
+
+    Returns an ``O_RDONLY | O_DIRECTORY`` descriptor usable as ``dir_fd``
+    for creating files inside it.
+    """
+    parts = _components(path)
+    walked = _walk(parts, create=create, mode=mode)
+    try:
+        # Re-open "." relative to the walked handle as a regular directory
+        # fd (an O_PATH fd can't be used for everything on every kernel).
+        return os.open(".", os.O_RDONLY | os.O_DIRECTORY, dir_fd=walked)
+    finally:
+        os.close(walked)

labctl/extras.py

@@ -0,0 +1,128 @@
+"""Install hints for optional dependencies ("extras").
+
+A bare ``pip install embedded-lab-control`` has only the core
+dependencies; the web UI, MCP server, Kasa plugs, SDWire muxes and USB
+relays each need an extra. Code that imports one of those packages
+turns the ImportError into a one-line message naming the extra, built
+here so every surface (CLI, REST, MCP) says the same thing.
+"""
+
+import sys
+
+DIST_NAME = "embedded-lab-control"
+
+# extra -> what it enables. Keep in step with
+# [project.optional-dependencies] in pyproject.toml; a test checks the
+# names and extra_packages() against it.
+EXTRAS: dict[str, str] = {
+    "web": "Web dashboard and REST API support",
+    "mcp": "MCP support",
+    "kasa": "Kasa power control",
+    "sdwire": "SDWire support",
+    "actuators": "USB relay support",
+}
+
+# The extras' requirements, as pyproject.toml declares them, for
+# `pipx inject` (which installs packages, not extras).
+_PACKAGES: dict[str, tuple[str, ...]] = {
+    "web": ("flask>=3.0", "flask-socketio>=5.0"),
+    "mcp": ("mcp>=2.2,<3",),
+    "sdwire": ("sdwire>=0.3",),
+    "actuators": ("pyserial>=3.5",),
+}
+
+
+class MissingExtraError(RuntimeError):
+    """An optional dependency is not installed.
+
+    A RuntimeError so existing ``except RuntimeError`` reporting (CLI
+    "Error: ...", REST/MCP error results) shows the hint unchanged.
+    """
+
+    def __init__(self, extra: str, what: str | None = None):
+        self.extra = extra
+        super().__init__(missing_extra_message(extra, what))
+
+
+class BrokenExtraError(RuntimeError):
+    """An optional dependency is installed but fails to import (a
+    dependency of it is missing, or the version is incompatible).
+
+    A RuntimeError, like MissingExtraError, so callers report it the same
+    way, but with the real ImportError in the message.
+    """
+
+    def __init__(self, extra: str, error: ImportError, what: str | None = None):
+        self.extra = extra
+        super().__init__(broken_extra_message(extra, error, what))
+
+
+def broken_extra_message(
+    extra: str, error: ImportError, what: str | None = None
+) -> str:
+    """One line for an extra whose package is installed but won't import.
+
+    No install command: reinstalling brings back the same newest version
+    when that version is the incompatible one, and the right command
+    depends on how labctl was installed (pipx, a venv, a git checkout).
+    """
+    what = what or EXTRAS[extra]
+    packages = ", ".join(extra_packages(extra))
+    return (
+        f"{what} is installed but failed to import ({error}): a dependency "
+        f"is missing or the installed version is incompatible (the [{extra}] "
+        f"extra wants {packages})"
+    )
+
+
+def extra_packages(extra: str) -> tuple[str, ...]:
+    """The extra's requirements for the running interpreter."""
+    if extra == "kasa":
+        # python-kasa >= 0.8 needs Python 3.11; 3.10 stays on 0.7.x.
+        if sys.version_info >= (3, 11):
+            return ("python-kasa>=0.12",)
+        return ("python-kasa>=0.7.7,<0.8",)
+    return _PACKAGES[extra]
+
+
+def missing_extra_message(extra: str, what: str | None = None) -> str:
+    """One line: what is missing and how to install the extra.
+
+    ``what`` overrides the extra's description, for a command that
+    needs only part of it (e.g. password hashing from [web]).
+    """
+    what = what or EXTRAS[extra]
+    if extra == "sdwire" and sys.version_info < (3, 12):
+        # PyPI sdwire requires Python >= 3.12: on older interpreters the
+        # extra installs nothing, so no install command here would work.
+        running = f"{sys.version_info.major}.{sys.version_info.minor}"
+        return (
+            f"{what} needs Python 3.12+ (this is Python {running}); the "
+            f"[sdwire] extra installs nothing here. Install labctl under "
+            f"Python 3.12 or newer to use SDWire"
+        )
+    pipx = " ".join(f'"{p}"' for p in extra_packages(extra))
+    message = (
+        f"{what} is not installed. Install the [{extra}] extra: "
+        f'pip install "{DIST_NAME}[{extra}]" '
+        f"(pipx: pipx inject {DIST_NAME} {pipx})"
+    )
+    if extra == "sdwire":
+        message += "; sdwire needs Python 3.12+"
+    return message
+
+
+def is_missing(error: ImportError, *modules: str) -> bool:
+    """True when ``error`` says one of ``modules`` is not installed.
+
+    Lets callers translate only the optional package's absence. Any
+    other ImportError, including ``cannot import name`` from an
+    installed but incompatible version (a plain ImportError, not
+    ModuleNotFoundError), keeps its real cause, as does a missing
+    submodule (``kasa.iot``): the package is there, but not a version
+    labctl can use.
+    """
+    if not isinstance(error, ModuleNotFoundError):
+        return False
+    name = error.name or ""
+    return name in modules

labctl/health/__init__.py

@@ -0,0 +1,43 @@
+"""
+Health monitoring module for lab controller.
+
+Provides health checks, status tracking, and alerting for SBCs.
+"""
+
+from labctl.health.alerts import (
+    Alert,
+    AlertHandler,
+    AlertLevel,
+    AlertManager,
+    ConsoleAlertHandler,
+    EmailAlertHandler,
+    LogAlertHandler,
+    SlackAlertHandler,
+)
+from labctl.health.checks import (
+    CheckResult,
+    CheckType,
+    HealthChecker,
+    HealthCheckSummary,
+)
+from labctl.health.daemon import MonitorDaemon, format_check_table
+
+__all__ = [
+    # Checks
+    "CheckType",
+    "CheckResult",
+    "HealthChecker",
+    "HealthCheckSummary",
+    # Alerts
+    "Alert",
+    "AlertLevel",
+    "AlertHandler",
+    "AlertManager",
+    "LogAlertHandler",
+    "ConsoleAlertHandler",
+    "EmailAlertHandler",
+    "SlackAlertHandler",
+    # Daemon
+    "MonitorDaemon",
+    "format_check_table",
+]

labctl/health/alerts.py

@@ -0,0 +1,275 @@
+"""
+Alerting framework for lab controller.
+
+Provides alert handling with pluggable handlers for different notification channels.
+Currently implements log file output; email and Slack are stubs for future.
+"""
+
+import logging
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+
+class AlertLevel(Enum):
+    """Alert severity levels."""
+
+    INFO = "info"
+    WARNING = "warning"
+    CRITICAL = "critical"
+
+
+@dataclass
+class Alert:
+    """An alert to be sent to handlers."""
+
+    level: AlertLevel
+    sbc_name: str
+    message: str
+    timestamp: datetime = field(default_factory=datetime.now)
+    details: Optional[str] = None
+
+    def format(self) -> str:
+        """Format alert as a string."""
+        ts = self.timestamp.strftime("%Y-%m-%d %H:%M:%S")
+        level = self.level.value.upper()
+        msg = f"[{ts}] [{level}] {self.sbc_name}: {self.message}"
+        if self.details:
+            msg += f" - {self.details}"
+        return msg
+
+
+class AlertHandler(ABC):
+    """Abstract base class for alert handlers."""
+
+    @abstractmethod
+    def send(self, alert: Alert) -> bool:
+        """
+        Send an alert.
+
+        Args:
+            alert: Alert to send
+
+        Returns:
+            True if alert was sent successfully
+        """
+        pass
+
+    @abstractmethod
+    def close(self) -> None:
+        """Clean up handler resources."""
+        pass
+
+
+class LogAlertHandler(AlertHandler):
+    """Alert handler that writes to a log file."""
+
+    def __init__(self, log_path: Path):
+        """
+        Initialize log alert handler.
+
+        Args:
+            log_path: Path to the alert log file
+        """
+        self.log_path = log_path
+        self._file_handle: Optional[object] = None
+        self._ensure_log_dir()
+
+    def _ensure_log_dir(self) -> None:
+        """Ensure the log directory exists."""
+        self.log_path.parent.mkdir(parents=True, exist_ok=True)
+
+    def send(self, alert: Alert) -> bool:
+        """Write alert to log file."""
+        try:
+            with open(self.log_path, "a") as f:
+                f.write(alert.format() + "\n")
+            return True
+        except Exception as e:
+            logger.error(f"Failed to write alert to log: {e}")
+            return False
+
+    def close(self) -> None:
+        """No cleanup needed for file-based logging."""
+        pass
+
+
+class ConsoleAlertHandler(AlertHandler):
+    """Alert handler that prints to console."""
+
+    def __init__(self, min_level: AlertLevel = AlertLevel.INFO):
+        """
+        Initialize console alert handler.
+
+        Args:
+            min_level: Minimum alert level to display
+        """
+        self.min_level = min_level
+        self._level_order = {
+            AlertLevel.INFO: 0,
+            AlertLevel.WARNING: 1,
+            AlertLevel.CRITICAL: 2,
+        }
+
+    def send(self, alert: Alert) -> bool:
+        """Print alert to console if level meets threshold."""
+        if self._level_order[alert.level] >= self._level_order[self.min_level]:
+            # Color codes for different levels
+            colors = {
+                AlertLevel.INFO: "\033[32m",  # Green
+                AlertLevel.WARNING: "\033[33m",  # Yellow
+                AlertLevel.CRITICAL: "\033[31m",  # Red
+            }
+            reset = "\033[0m"
+            color = colors.get(alert.level, "")
+            print(f"{color}{alert.format()}{reset}")
+        return True
+
+    def close(self) -> None:
+        """No cleanup needed for console output."""
+        pass
+
+
+class EmailAlertHandler(AlertHandler):
+    """
+    Placeholder for email alert handler.
+
+    This is a stub for future implementation.
+    """
+
+    def __init__(
+        self,
+        smtp_host: str = "",
+        smtp_port: int = 587,
+        sender: str = "",
+        recipients: Optional[list[str]] = None,
+    ):
+        """Initialize email handler (stub)."""
+        self.smtp_host = smtp_host
+        self.smtp_port = smtp_port
+        self.sender = sender
+        self.recipients = recipients or []
+        logger.warning("EmailAlertHandler is a stub - emails will not be sent")
+
+    def send(self, alert: Alert) -> bool:
+        """Stub: Log that email would be sent."""
+        logger.debug(
+            f"Email alert (stub): Would send to {self.recipients}: {alert.format()}"
+        )
+        return False  # Return False since we didn't actually send
+
+    def close(self) -> None:
+        """No cleanup needed for stub."""
+        pass
+
+
+class SlackAlertHandler(AlertHandler):
+    """
+    Placeholder for Slack webhook alert handler.
+
+    This is a stub for future implementation.
+    """
+
+    def __init__(self, webhook_url: str = ""):
+        """Initialize Slack handler (stub)."""
+        self.webhook_url = webhook_url
+        logger.warning("SlackAlertHandler is a stub - Slack messages will not be sent")
+
+    def send(self, alert: Alert) -> bool:
+        """Stub: Log that Slack message would be sent."""
+        logger.debug(f"Slack alert (stub): Would post to webhook: {alert.format()}")
+        return False  # Return False since we didn't actually send
+
+    def close(self) -> None:
+        """No cleanup needed for stub."""
+        pass
+
+
+class AlertManager:
+    """Manages multiple alert handlers and dispatches alerts."""
+
+    def __init__(self):
+        """Initialize alert manager."""
+        self._handlers: list[AlertHandler] = []
+
+    def add_handler(self, handler: AlertHandler) -> None:
+        """
+        Register an alert handler.
+
+        Args:
+            handler: Handler to add
+        """
+        self._handlers.append(handler)
+
+    def remove_handler(self, handler: AlertHandler) -> None:
+        """
+        Remove an alert handler.
+
+        Args:
+            handler: Handler to remove
+        """
+        if handler in self._handlers:
+            self._handlers.remove(handler)
+
+    def trigger(self, alert: Alert) -> int:
+        """
+        Send alert to all registered handlers.
+
+        Args:
+            alert: Alert to send
+
+        Returns:
+            Number of handlers that successfully sent the alert
+        """
+        success_count = 0
+        for handler in self._handlers:
+            try:
+                if handler.send(alert):
+                    success_count += 1
+            except Exception as e:
+                logger.error(f"Handler {handler.__class__.__name__} failed: {e}")
+        return success_count
+
+    def trigger_info(self, sbc_name: str, message: str, details: str = None) -> int:
+        """Convenience method to trigger an INFO alert."""
+        alert = Alert(
+            level=AlertLevel.INFO,
+            sbc_name=sbc_name,
+            message=message,
+            details=details,
+        )
+        return self.trigger(alert)
+
+    def trigger_warning(self, sbc_name: str, message: str, details: str = None) -> int:
+        """Convenience method to trigger a WARNING alert."""
+        alert = Alert(
+            level=AlertLevel.WARNING,
+            sbc_name=sbc_name,
+            message=message,
+            details=details,
+        )
+        return self.trigger(alert)
+
+    def trigger_critical(self, sbc_name: str, message: str, details: str = None) -> int:
+        """Convenience method to trigger a CRITICAL alert."""
+        alert = Alert(
+            level=AlertLevel.CRITICAL,
+            sbc_name=sbc_name,
+            message=message,
+            details=details,
+        )
+        return self.trigger(alert)
+
+    def close(self) -> None:
+        """Close all handlers."""
+        for handler in self._handlers:
+            try:
+                handler.close()
+            except Exception as e:
+                logger.error(f"Error closing handler: {e}")
+        self._handlers.clear()