labpulse 0.3.6__py3-none-any.whl

labpulse/README.md

@@ -0,0 +1,35 @@
+# LabPulse Python package
+
+This directory is the maintained Python implementation. The installed package
+supplies commands that run on the Raspberry Pi host and processes that run in
+Docker containers.
+
+| Path | Responsibility | Runs in |
+|---|---|---|
+| `control.py` | Public `labpulse` command: setup, lifecycle, configuration, backup, restore and diagnostics | Pi host |
+| `installer.py` | Locate packaged assets and launch the Linux bootstrap | Pi host |
+| `backup.py` | Create, validate and restore checksummed state archives | Pi host |
+| `doctor.py` | Read-only installation, hardware, Docker and endpoint checks | Pi host |
+| `common/` | Configuration, identity, MQTT, logging and file contracts | Host and containers |
+| `deployment/` | Generate Compose and staged Home Assistant output | Pi host |
+| `hardware/` | Acquire and publish one sensor service | One container per service |
+| `homeassistant/` | Generate dashboards, helpers and alarms | Pi host during generation |
+| `output/` | Apply MQTT commands to one configured output | One container per output |
+| `sms/` | Validate requests and deliver or dry-run SMS messages | SMS container |
+
+`__init__.py` exposes the installed version. Executable subpackages use
+`__main__.py` so Compose can run them with `python -m`.
+
+Each process loads the validated configuration independently and coordinates
+through MQTT rather than shared Python memory. The operator-owned source is
+`~/labpulse-live/config.yaml`; the repository `config.yaml` is only an
+installation template.
+
+Configuration is validated at process boundaries. Drivers normalize hardware,
+runners own retry and freshness, Home Assistant owns alarm decisions, and SMS
+and output workers own their side effects. Do not recreate YAML, identity or
+topic rules inside individual services.
+
+Tests are mapped in [`testing/`](../../testing/README.md). Read the
+[User Guide](../../docs/USER_GUIDE.md), [Architecture](../../docs/ARCHITECTURE.md)
+and [Development guide](../../docs/DEVELOPMENT.md) for cross-package behaviour.

labpulse/__init__.py

@@ -0,0 +1,9 @@
+"""LabPulse monitoring, generation, and alert-delivery packages."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+
+try:
+    __version__ = version("labpulse")
+except PackageNotFoundError:
+    __version__ = "0+unknown"

labpulse/backup.py

@@ -0,0 +1,524 @@
+"""Create and restore guarded LabPulse state archives."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from contextlib import contextmanager
+from datetime import datetime, timezone
+import hashlib
+from importlib.metadata import PackageNotFoundError, version
+import json
+import os
+from pathlib import Path, PurePosixPath
+import platform
+import shutil
+import subprocess
+import tarfile
+from typing import Any, Iterator
+from uuid import uuid4
+
+
+BACKUP_FORMAT_VERSION = 1
+MANIFEST_NAME = "manifest.json"
+PAYLOAD_DIRECTORY = "payload"
+SNAPSHOT_PATHS = (
+    "config.yaml",
+    "config.d",
+    "homeassistant/config",
+    "mosquitto/data",
+    "logs/sms_subscriptions.json",
+    "logs/sms_processed_requests.json",
+)
+MANDATORY_PATHS = ("config.yaml", "homeassistant/config")
+CONTAINER_SNAPSHOT_PATHS = {
+    "homeassistant/config": ("homeassistant", "/config"),
+    "mosquitto/data": ("mosquitto", "/mosquitto/data"),
+}
+class BackupError(RuntimeError):
+    """Raised when a backup or restore cannot complete safely."""
+
+
+@contextmanager
+def _temporary_directory(parent: Path, prefix: str) -> Iterator[Path]:
+    """Create a private disposable directory without tempfile ACL surprises."""
+
+    path = parent / f".{prefix}{uuid4().hex}"
+    path.mkdir(parents=True)
+    if os.name != "nt":
+        path.chmod(0o700)
+    try:
+        yield path
+    finally:
+        shutil.rmtree(path, ignore_errors=False)
+
+
+def _sha256(path: Path) -> str:
+    """Return the SHA-256 digest of one regular file."""
+
+    digest = hashlib.sha256()
+    with path.open("rb") as stream:
+        for block in iter(lambda: stream.read(1024 * 1024), b""):
+            digest.update(block)
+    return digest.hexdigest()
+
+
+def _capture_host_command(command: Sequence[str]) -> str:
+    """Capture one optional host-setting command without failing backup creation."""
+
+    try:
+        result = subprocess.run(
+            list(command),
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=10,
+        )
+    except (OSError, subprocess.SubprocessError) as error:
+        return f"unavailable: {error}"
+    output = (result.stdout or result.stderr).strip()
+    return output or f"exit {result.returncode}"
+
+
+def _compose(
+    live_dir: Path,
+    docker_prefix: Sequence[str],
+    arguments: Sequence[str],
+) -> subprocess.CompletedProcess[str]:
+    """Run one bounded Compose command or raise an actionable error."""
+
+    command = [*docker_prefix, "compose", *arguments]
+    try:
+        result = subprocess.run(
+            command,
+            cwd=live_dir,
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=120,
+        )
+    except (OSError, subprocess.SubprocessError) as error:
+        raise BackupError(f"Cannot run {' '.join(command)}: {error}") from error
+    if result.returncode != 0:
+        detail = (result.stderr or result.stdout).strip()
+        raise BackupError(
+            f"{' '.join(command)} failed: {detail or f'exit {result.returncode}'}"
+        )
+    return result
+
+
+def running_services(
+    live_dir: Path,
+    docker_prefix: Sequence[str],
+) -> tuple[str, ...]:
+    """Return the currently running Compose services in stable order."""
+
+    result = _compose(
+        live_dir,
+        docker_prefix,
+        ("ps", "--status", "running", "--services"),
+    )
+    return tuple(line.strip() for line in result.stdout.splitlines() if line.strip())
+
+
+def stop_services(
+    live_dir: Path,
+    docker_prefix: Sequence[str],
+    services: Sequence[str],
+) -> None:
+    """Stop selected services for a consistent state snapshot."""
+
+    if services:
+        _compose(live_dir, docker_prefix, ("stop", *services))
+
+
+def start_services(
+    live_dir: Path,
+    docker_prefix: Sequence[str],
+    services: Sequence[str],
+) -> None:
+    """Restart exactly the services stopped for a snapshot."""
+
+    if services:
+        _compose(live_dir, docker_prefix, ("start", *services))
+
+
+def _copy_snapshot_path(source: Path, destination: Path) -> None:
+    """Copy one state path while rejecting links and special files."""
+
+    # A symbolic link could point outside ~/labpulse-live and pull an unrelated
+    # file into the archive, so backups only follow ordinary files/directories.
+    if source.is_symlink():
+        raise BackupError(f"Refusing to follow state symlink: {source}")
+    if source.is_file():
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(source, destination)
+        return
+    if not source.is_dir():
+        raise BackupError(f"Unsupported state path type: {source}")
+
+    destination.mkdir(parents=True, exist_ok=True)
+    for child in sorted(source.iterdir(), key=lambda item: item.name):
+        if child.is_symlink():
+            raise BackupError(f"Refusing to follow state symlink: {child}")
+        target = destination / child.name
+        if child.is_dir():
+            _copy_snapshot_path(child, target)
+        elif child.is_file():
+            target.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(child, target)
+        else:
+            raise BackupError(f"Unsupported state path type: {child}")
+
+
+def _validate_snapshot_path(path: Path) -> None:
+    """Reject links and special files in a container-assisted snapshot copy."""
+
+    if path.is_symlink():
+        raise BackupError(f"Refusing to archive state symlink: {path}")
+    if path.is_file():
+        return
+    if not path.is_dir():
+        raise BackupError(f"Unsupported state path type: {path}")
+    for child in sorted(path.iterdir(), key=lambda item: item.name):
+        _validate_snapshot_path(child)
+
+
+def _copy_snapshot_from_container(
+    live_dir: Path,
+    relative: str,
+    destination: Path,
+    docker_prefix: Sequence[str],
+) -> None:
+    """Copy container-owned bind-mount state through its stopped service."""
+
+    service, container_path = CONTAINER_SNAPSHOT_PATHS[relative]
+    shutil.rmtree(destination, ignore_errors=False)
+    destination.mkdir(parents=True)
+    try:
+        _compose(
+            live_dir,
+            docker_prefix,
+            ("cp", f"{service}:{container_path}/.", str(destination)),
+        )
+    except BackupError as error:
+        raise BackupError(
+            f"Cannot read {live_dir / relative} as the current user and "
+            f"could not copy it through the {service} container: {error}"
+        ) from error
+    _validate_snapshot_path(destination)
+
+
+def _assemble_snapshot(
+    live_dir: Path,
+    staging_root: Path,
+    docker_prefix: Sequence[str],
+) -> None:
+    """Copy selected state and write its checksum manifest."""
+
+    payload_root = staging_root / PAYLOAD_DIRECTORY
+    included: list[str] = []
+    for relative in SNAPSHOT_PATHS:
+        source = live_dir / relative
+        if not source.exists():
+            if relative in MANDATORY_PATHS:
+                raise BackupError(f"Required backup state is missing: {source}")
+            continue
+        destination = payload_root / relative
+        try:
+            _copy_snapshot_path(source, destination)
+        except PermissionError as error:
+            # Home Assistant and Mosquitto may create files owned by their
+            # container user. A stopped container can still copy that mounted
+            # state when the host user is not allowed to read it directly.
+            if relative not in CONTAINER_SNAPSHOT_PATHS:
+                raise BackupError(f"Cannot read backup state: {error.filename}") from error
+            _copy_snapshot_from_container(
+                live_dir,
+                relative,
+                destination,
+                docker_prefix,
+            )
+        included.append(relative)
+
+    # Record the digest of every file so restore can detect a missing, added,
+    # or modified payload before replacing live state.
+    checksums = {
+        path.relative_to(staging_root).as_posix(): _sha256(path)
+        for path in sorted(payload_root.rglob("*"))
+        if path.is_file()
+    }
+    try:
+        labpulse_version = version("labpulse")
+    except PackageNotFoundError:
+        labpulse_version = "source-checkout"
+    try:
+        compose_text = (live_dir / "compose.yaml").read_text(encoding="utf-8")
+    except OSError:
+        compose_text = ""
+    runtime_mode = "fake_usb" if "config.fake.yaml:/app/config.yaml" in compose_text else "real_hardware"
+    manifest: dict[str, Any] = {
+        "format_version": BACKUP_FORMAT_VERSION,
+        "created_at": datetime.now(timezone.utc).isoformat(),
+        "labpulse_version": labpulse_version,
+        "source_live_directory": str(live_dir),
+        "runtime_mode": runtime_mode,
+        "included_paths": included,
+        "files": checksums,
+        "host": {
+            "platform": platform.platform(),
+            "python": platform.python_version(),
+            "docker_command": " ".join(docker_prefix),
+            "clock": _capture_host_command(
+                ("timedatectl", "show", "--property=Timezone", "--property=NTPSynchronized")
+            ),
+            "watchdog": _capture_host_command(
+                ("systemctl", "show", "--property=RuntimeWatchdogUSec", "--value")
+            ),
+        },
+    }
+    (staging_root / MANIFEST_NAME).write_text(
+        json.dumps(manifest, indent=2, sort_keys=True) + "\n",
+        encoding="utf-8",
+    )
+
+
+def create_backup(
+    live_dir: Path,
+    archive_path: Path,
+    docker_prefix: Sequence[str],
+    *,
+    force: bool = False,
+    quiesce: bool = True,
+) -> Path:
+    """Create one checksummed private archive, restarting quiesced services."""
+
+    live_dir = live_dir.expanduser().resolve()
+    archive_path = archive_path.expanduser().resolve()
+    if not live_dir.is_dir() or not (live_dir / "compose.yaml").is_file():
+        raise BackupError(
+            f"LabPulse is not set up at {live_dir}; run 'labpulse setup' first"
+        )
+    if archive_path.is_relative_to(live_dir):
+        raise BackupError("Backup archive must be stored outside the live directory")
+    if archive_path.exists() and not force:
+        raise BackupError(f"Backup archive already exists: {archive_path}")
+    archive_path.parent.mkdir(parents=True, exist_ok=True)
+
+    active_services: tuple[str, ...] = ()
+    if quiesce:
+        active_services = running_services(live_dir, docker_prefix)
+
+    temporary_archive = archive_path.parent / (
+        f".{archive_path.name}.creating-{uuid4().hex}"
+    )
+    try:
+        # Services are stopped only while their mutable state is copied. The
+        # finally block restarts exactly those that were running beforehand.
+        if quiesce:
+            stop_services(live_dir, docker_prefix, active_services)
+        with _temporary_directory(
+            archive_path.parent,
+            "labpulse-backup-",
+        ) as staging_root:
+            _assemble_snapshot(live_dir, staging_root, docker_prefix)
+            with tarfile.open(temporary_archive, "w:gz") as archive:
+                archive.add(staging_root / MANIFEST_NAME, arcname=MANIFEST_NAME)
+                archive.add(staging_root / PAYLOAD_DIRECTORY, arcname=PAYLOAD_DIRECTORY)
+        os.chmod(temporary_archive, 0o600)
+        os.replace(temporary_archive, archive_path)
+    finally:
+        if temporary_archive.exists():
+            temporary_archive.unlink()
+        if quiesce:
+            start_services(live_dir, docker_prefix, active_services)
+
+    return archive_path
+
+
+def _load_manifest(archive: tarfile.TarFile) -> dict[str, Any]:
+    """Read and minimally validate the archive manifest."""
+
+    try:
+        member = archive.getmember(MANIFEST_NAME)
+        stream = archive.extractfile(member)
+    except (KeyError, tarfile.TarError) as error:
+        raise BackupError("Backup manifest is missing") from error
+    if stream is None or not member.isreg():
+        raise BackupError("Backup manifest is not a regular file")
+    try:
+        manifest = json.load(stream)
+    except (UnicodeDecodeError, json.JSONDecodeError) as error:
+        raise BackupError(f"Backup manifest is invalid: {error}") from error
+    if not isinstance(manifest, dict):
+        raise BackupError("Backup manifest must be a JSON object")
+    if manifest.get("format_version") != BACKUP_FORMAT_VERSION:
+        raise BackupError(
+            f"Unsupported backup format: {manifest.get('format_version')!r}"
+        )
+    if manifest.get("runtime_mode") not in {"real_hardware", "fake_usb"}:
+        raise BackupError("Backup manifest has an invalid runtime mode")
+    files = manifest.get("files")
+    included = manifest.get("included_paths")
+    if not isinstance(files, dict) or not all(
+        isinstance(key, str) and isinstance(value, str)
+        for key, value in files.items()
+    ):
+        raise BackupError("Backup manifest has invalid file checksums")
+    if not isinstance(included, list) or not all(
+        isinstance(value, str) for value in included
+    ):
+        raise BackupError("Backup manifest has invalid included paths")
+    for mandatory in MANDATORY_PATHS:
+        if mandatory not in included:
+            raise BackupError(f"Backup is incomplete: missing {mandatory}")
+    return manifest
+
+
+def inspect_backup(archive_path: Path) -> dict[str, Any]:
+    """Validate archive structure and every payload checksum."""
+
+    archive_path = archive_path.expanduser().resolve()
+    if not archive_path.is_file():
+        raise BackupError(f"Backup archive does not exist: {archive_path}")
+    try:
+        archive = tarfile.open(archive_path, "r:*")
+    except (OSError, tarfile.TarError) as error:
+        raise BackupError(f"Cannot open backup archive: {error}") from error
+
+    with archive:
+        manifest = _load_manifest(archive)
+        checksums: dict[str, str] = manifest["files"]
+        archive_files: set[str] = set()
+        for member in archive.getmembers():
+            member_path = PurePosixPath(member.name)
+            # Absolute paths or ".." components could make extraction write
+            # outside its temporary directory. Only the manifest and payload
+            # tree are valid members of a LabPulse archive.
+            safe_name = (
+                not member_path.is_absolute()
+                and ".." not in member_path.parts
+                and "." not in member_path.parts
+                and (
+                    member.name == MANIFEST_NAME
+                    or (bool(member_path.parts) and member_path.parts[0] == PAYLOAD_DIRECTORY)
+                )
+            )
+            if not safe_name:
+                raise BackupError(f"Unsafe archive path: {member.name}")
+            if not (member.isdir() or member.isreg()):
+                raise BackupError(f"Unsafe archive member type: {member.name}")
+            if member.isreg() and member.name.startswith(f"{PAYLOAD_DIRECTORY}/"):
+                archive_files.add(member.name)
+                if member.name not in checksums:
+                    raise BackupError(f"Unmanifested backup file: {member.name}")
+                stream = archive.extractfile(member)
+                if stream is None:
+                    raise BackupError(f"Cannot read backup file: {member.name}")
+                digest = hashlib.sha256()
+                for block in iter(lambda: stream.read(1024 * 1024), b""):
+                    digest.update(block)
+                if digest.hexdigest() != checksums[member.name]:
+                    raise BackupError(f"Checksum mismatch: {member.name}")
+        if archive_files != set(checksums):
+            missing = sorted(set(checksums) - archive_files)
+            raise BackupError("Backup payload is missing: " + ", ".join(missing))
+    return manifest
+
+
+def _extract_validated(archive_path: Path, destination: Path) -> dict[str, Any]:
+    """Validate and manually extract regular payload files."""
+
+    manifest = inspect_backup(archive_path)
+    with tarfile.open(archive_path, "r:*") as archive:
+        # Extract members ourselves instead of using tarfile.extract(). Their
+        # names and file types were checked above, and every destination remains
+        # visibly rooted in this temporary directory.
+        members = archive.getmembers()
+        for member in members:
+            if not member.isdir():
+                continue
+            target = destination.joinpath(*PurePosixPath(member.name).parts)
+            target.mkdir(parents=True, exist_ok=True)
+        for member in members:
+            if not member.isreg():
+                continue
+            target = destination.joinpath(*PurePosixPath(member.name).parts)
+            target.parent.mkdir(parents=True, exist_ok=True)
+            stream = archive.extractfile(member)
+            if stream is None:
+                raise BackupError(f"Cannot extract backup file: {member.name}")
+            with target.open("wb") as output:
+                shutil.copyfileobj(stream, output)
+            try:
+                os.chmod(target, member.mode & 0o777)
+            except OSError:
+                pass
+    return manifest
+
+
+def _remove_path(path: Path) -> None:
+    """Remove one exact file, link, or directory target."""
+
+    if path.is_symlink() or path.is_file():
+        path.unlink()
+    elif path.is_dir():
+        shutil.rmtree(path)
+
+
+def _copy_local_path(source: Path, destination: Path) -> None:
+    """Copy a staged or rollback path without following stored symlinks."""
+
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    if source.is_symlink():
+        destination.symlink_to(os.readlink(source))
+    elif source.is_dir():
+        shutil.copytree(source, destination, symlinks=True)
+    else:
+        shutil.copy2(source, destination, follow_symlinks=False)
+
+
+def _apply_payload(live_dir: Path, payload_root: Path) -> None:
+    """Replace snapshot-owned paths and roll back the filesystem on failure."""
+
+    with _temporary_directory(
+        live_dir.parent,
+        "labpulse-restore-rollback-",
+    ) as local_rollback:
+        # Copy the current state aside before removing anything. If any later
+        # copy fails, the except block can put the complete old state back.
+        existing: list[str] = []
+        for relative in SNAPSHOT_PATHS:
+            target = live_dir / relative
+            if target.exists() or target.is_symlink():
+                _copy_local_path(target, local_rollback / relative)
+                existing.append(relative)
+
+        try:
+            for relative in SNAPSHOT_PATHS:
+                target = live_dir / relative
+                _remove_path(target)
+                source = payload_root / relative
+                if source.exists() or source.is_symlink():
+                    _copy_local_path(source, target)
+        except Exception as error:
+            for relative in SNAPSHOT_PATHS:
+                _remove_path(live_dir / relative)
+            for relative in existing:
+                _copy_local_path(local_rollback / relative, live_dir / relative)
+            raise BackupError(f"Restore failed and local state was rolled back: {error}") from error
+
+
+def restore_backup(live_dir: Path, archive_path: Path) -> dict[str, Any]:
+    """Validate and apply archive state to an existing scaffolded live directory."""
+
+    live_dir = live_dir.expanduser().resolve()
+    archive_path = archive_path.expanduser().resolve()
+    if not live_dir.is_dir():
+        raise BackupError(f"Restore target does not exist: {live_dir}")
+    with _temporary_directory(
+        live_dir.parent,
+        "labpulse-restore-",
+    ) as extracted:
+        manifest = _extract_validated(archive_path, extracted)
+        _apply_payload(live_dir, extracted / PAYLOAD_DIRECTORY)
+    return manifest

labpulse/common/README.md

@@ -0,0 +1,32 @@
+# Shared contracts
+
+`labpulse.common` contains definitions that must remain identical across host
+generation, sensor workers, Home Assistant, SMS and outputs. It runs wherever
+the Python package runs and deliberately has no hardware access.
+
+| File | Contract |
+|---|---|
+| `config.py` | Central YAML loader, global models, cross-references and source-aware errors |
+| `service_config.py` | Driver selection, service timing, measurements and power-service rules |
+| `measurement_config.py` | Physical/calculated measurements and restricted formulas |
+| `output_config.py` | Output-driver and safe-state configuration |
+| `identity.py` | Stable slugs, IDs, titles and Home Assistant entity IDs |
+| `mqtt_contracts.py` | Topic constructors and strict SMS requests |
+| `fake_config.py` | Preserve the complete resolved fake-hardware runtime document |
+| `logging_config.py` | Stdout and optional persistent logging |
+| `generated_files.py` | Atomically replace one complete file |
+| `sms_templates.py` / `sms_templates.yaml` | Validate and supply notification text |
+
+Unknown fields are rejected. Driver options are converted to the selected
+driver's typed model during the central load; consumers should not parse YAML
+again. Calculated formulas accept only finite arithmetic and physical inputs.
+Single-file replacement is atomic, but replacing several generated files is
+not one filesystem transaction.
+
+Keep reusable configuration, identity, topic and small shared utilities here.
+Do not add hardware access, CLI parsing, dashboard policy or delivery effects.
+
+Relevant tests include `test_config_pipeline.py`, `test_common_contracts.py`,
+`test_custom_measurements.py` and `test_deployment_generation.py`. See
+[Configuration](../../../docs/CONFIGURATION.md) and
+[Architecture](../../../docs/ARCHITECTURE.md).

labpulse/common/__init__.py

@@ -0,0 +1 @@
+"""Shared contracts and infrastructure used by LabPulse services."""