ReticulumTelemetryHub 0.1.0__py3-none-any.whl → 0.143.0__py3-none-any.whl

reticulum_telemetry_hub/config/models.py

@@ -0,0 +1,215 @@
+"""Data models representing configuration shapes for the hub."""
+
+from __future__ import annotations
+
+from configparser import ConfigParser
+from dataclasses import dataclass, field
+from importlib import metadata
+from pathlib import Path
+from typing import Optional, Tuple
+
+from reticulum_telemetry_hub.config.constants import (
+    DEFAULT_ANNOUNCE_INTERVAL,
+    DEFAULT_HUB_TELEMETRY_INTERVAL,
+    DEFAULT_LOG_LEVEL_NAME,
+    DEFAULT_SERVICE_TELEMETRY_INTERVAL,
+)
+
+
+@dataclass
+class RNSInterfaceConfig:
+    """Represents the minimal subset of the TCP server interface configuration."""
+
+    listen_ip: str = "0.0.0.0"
+    listen_port: int = 4242
+    interface_enabled: bool = True
+    interface_type: str = "TCPServerInterface"
+
+    def to_dict(self) -> dict:
+        """Serialise the TCP interface configuration.
+
+        Returns:
+            dict: Mapping consumable by Reticulum configuration writers.
+        """
+
+        return {
+            "listen_ip": self.listen_ip,
+            "listen_port": self.listen_port,
+            "interface_enabled": self.interface_enabled,
+            "type": self.interface_type,
+        }
+
+
+@dataclass
+class ReticulumConfig:
+    """Object view of the Reticulum configuration file."""
+
+    path: Path
+    enable_transport: bool = True
+    share_instance: bool = True
+    tcp_interface: RNSInterfaceConfig = field(default_factory=RNSInterfaceConfig)
+
+    def to_dict(self) -> dict:
+        """Serialise the Reticulum configuration values.
+
+        Returns:
+            dict: Flattened representation including nested interfaces.
+        """
+
+        data = {
+            "path": str(self.path),
+            "enable_transport": self.enable_transport,
+            "share_instance": self.share_instance,
+        }
+        data["tcp_interface"] = self.tcp_interface.to_dict()
+        return data
+
+
+@dataclass
+class LXMFRouterConfig:
+    """Object view of the LXMF router/propagation configuration."""
+
+    path: Path
+    enable_node: bool = True
+    announce_interval_minutes: int = 10
+    display_name: str = "RTH_router"
+
+    def to_dict(self) -> dict:
+        """Serialise LXMF router configuration fields.
+
+        Returns:
+            dict: Mapping used by the embedded LXMF daemon.
+        """
+
+        return {
+            "path": str(self.path),
+            "enable_node": self.enable_node,
+            "announce_interval_minutes": self.announce_interval_minutes,
+            "display_name": self.display_name,
+        }
+
+
+@dataclass
+class HubRuntimeConfig:  # pylint: disable=too-many-instance-attributes
+    """Configuration values that guide the hub runtime defaults."""
+
+    display_name: str = "RTH"
+    announce_interval: int = DEFAULT_ANNOUNCE_INTERVAL
+    hub_telemetry_interval: int = DEFAULT_HUB_TELEMETRY_INTERVAL
+    service_telemetry_interval: int = DEFAULT_SERVICE_TELEMETRY_INTERVAL
+    log_level: str = DEFAULT_LOG_LEVEL_NAME
+    embedded_lxmd: bool = False
+    default_services: Tuple[str, ...] = ()
+    gpsd_host: str = "127.0.0.1"
+    gpsd_port: int = 2947
+    reticulum_config_path: Path | None = None
+    lxmf_router_config_path: Path | None = None
+    telemetry_filename: str = "telemetry.ini"
+    file_storage_path: Path | None = None
+    image_storage_path: Path | None = None
+
+
+@dataclass
+class HubAppConfig:  # pylint: disable=too-many-instance-attributes
+    """Aggregated configuration for the telemetry hub runtime."""
+
+    storage_path: Path
+    database_path: Path
+    hub_database_path: Path
+    file_storage_path: Path
+    image_storage_path: Path
+    runtime: "HubRuntimeConfig"
+    reticulum: ReticulumConfig
+    lxmf_router: LXMFRouterConfig
+    app_name: str = "ReticulumTelemetryHub"
+    app_version: Optional[str] = None
+    app_description: str = ""
+    tak_connection: "TakConnectionConfig | None" = None
+
+    def to_reticulum_info_dict(self) -> dict:
+        """Return a dict compatible with the ReticulumInfo schema.
+
+        Returns:
+            dict: Snapshot of the Reticulum runtime configuration.
+        """
+        return {
+            "is_transport_enabled": self.reticulum.enable_transport,
+            "is_connected_to_shared_instance": self.reticulum.share_instance,
+            "reticulum_config_path": str(self.reticulum.path),
+            "database_path": str(self.database_path),
+            "storage_path": str(self.storage_path),
+            "file_storage_path": str(self.file_storage_path),
+            "image_storage_path": str(self.image_storage_path),
+            "rns_version": self._safe_get_version("RNS"),
+            "lxmf_version": self._safe_get_version("LXMF"),
+            "app_name": self.app_name or "ReticulumTelemetryHub",
+            "app_version": self.app_version
+            or self._safe_get_version("ReticulumTelemetryHub"),
+            "app_description": self.app_description or "",
+        }
+
+    @staticmethod
+    def _safe_get_version(distribution: str) -> str:
+        try:
+            return metadata.version(distribution)
+        except metadata.PackageNotFoundError:
+            return "unknown"
+        # Reason: metadata providers may raise unexpected runtime errors in constrained environments.
+        except Exception:  # pylint: disable=broad-exception-caught
+            return "unknown"
+
+
+@dataclass
+class TakConnectionConfig:  # pylint: disable=too-many-instance-attributes
+    """Settings that control TAK/CoT connectivity."""
+
+    cot_url: str = "tcp://127.0.0.1:8087"
+    callsign: str = "RTH"
+    poll_interval_seconds: float = 30.0
+    keepalive_interval_seconds: float = 60.0
+    tls_client_cert: str | None = None
+    tls_client_key: str | None = None
+    tls_ca: str | None = None
+    tls_insecure: bool = False
+    tak_proto: int = 0
+    fts_compat: int = 1
+
+    def to_config_parser(self) -> ConfigParser:
+        """Return a ConfigParser that PyTAK understands.
+
+        Returns:
+            ConfigParser: Parser configured with PyTAK-compatible values.
+        """
+
+        parser = ConfigParser()
+        parser["fts"] = {
+            "COT_URL": self.cot_url,
+            "CALLSIGN": self.callsign,
+            "SSL_CLIENT_CERT": self.tls_client_cert or "",
+            "SSL_CLIENT_KEY": self.tls_client_key or "",
+            "SSL_CLIENT_CAFILE": self.tls_ca or "",
+            "SSL_VERIFY": "false" if self.tls_insecure else "true",
+            "TAK_PROTO": str(self.tak_proto),
+            "FTS_COMPAT": str(self.fts_compat),
+        }
+        return parser
+
+    def to_dict(self) -> dict:
+        """Return a serialisable representation for debugging or logs.
+
+        Returns:
+            dict: Copy of the connector settings for display purposes.
+        """
+
+        return {
+            "cot_url": self.cot_url,
+            "callsign": self.callsign,
+            "poll_interval_seconds": self.poll_interval_seconds,
+            "keepalive_interval_seconds": self.keepalive_interval_seconds,
+            "tls_client_cert": self.tls_client_cert,
+            "tls_client_key": self.tls_client_key,
+            "tls_ca": self.tls_ca,
+            "tls_insecure": self.tls_insecure,
+            "tak_proto": self.tak_proto,
+            "fts_compat": self.fts_compat,
+        }

reticulum_telemetry_hub/embedded_lxmd/__init__.py

@@ -0,0 +1,5 @@
+"""Utilities for running the LXMF daemon in-process."""
+
+from .embedded import EmbeddedLxmd
+
+__all__ = ["EmbeddedLxmd"]

reticulum_telemetry_hub/embedded_lxmd/embedded.py

@@ -0,0 +1,418 @@
+from __future__ import annotations
+
+import threading
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Any, Optional
+
+import LXMF
+import RNS
+from msgpack import packb
+
+from reticulum_telemetry_hub.config.manager import HubConfigurationManager
+from reticulum_telemetry_hub.lxmf_telemetry.model.persistance.sensors.lxmf_propagation import (
+    LXMFPropagation,
+)
+from reticulum_telemetry_hub.lxmf_telemetry.model.persistance.sensors.sensor_enum import (
+    SID_LXMF_PROPAGATION,
+)
+
+if TYPE_CHECKING:
+    from reticulum_telemetry_hub.lxmf_telemetry.telemetry_controller import (
+        TelemetryController,
+    )
+
+
+def _utcnow() -> datetime:
+    return datetime.now(timezone.utc).replace(tzinfo=None)
+
+
+@dataclass
+class EmbeddedLxmdConfig:
+    """Runtime configuration for the embedded LXMD service."""
+
+    enable_propagation_node: bool
+    announce_interval_seconds: int
+
+    @classmethod
+    def from_manager(cls, manager: HubConfigurationManager) -> "EmbeddedLxmdConfig":
+        lxmf_config = manager.config.lxmf_router
+        interval = max(1, int(lxmf_config.announce_interval_minutes) * 60)
+        return cls(
+            enable_propagation_node=lxmf_config.enable_node,
+            announce_interval_seconds=interval,
+        )
+
+
+class EmbeddedLxmd:
+    """Run the LXMF router propagation loop within the current process.
+
+    The stock ``lxmd`` daemon starts a couple of helper threads that periodically
+    announces the delivery destination and, when configured, runs the propagation
+    node loop. When the hub is executed in *embedded* mode those responsibilities
+    need to run side-by-side with the main application instead of being spawned
+    as a separate process. ``EmbeddedLxmd`` mirrors the subset of ``lxmd``'s
+    behaviour that ReticulumTelemetryHub relies on and provides an explicit
+    lifecycle so the threads can be shut down gracefully.
+    """
+
+    DEFERRED_JOBS_DELAY = 10
+    JOBS_INTERVAL_SECONDS = 5
+
+    PROPAGATION_UPTIME_GRANULARITY = 30
+
+    def __init__(
+        self,
+        router: LXMF.LXMRouter,
+        destination: RNS.Destination,
+        config_manager: Optional[HubConfigurationManager] = None,
+        telemetry_controller: Optional[TelemetryController] = None,
+    ) -> None:
+        self.router = router
+        self.destination = destination
+        self.config_manager = config_manager or HubConfigurationManager()
+        self.config = EmbeddedLxmdConfig.from_manager(self.config_manager)
+        self.telemetry_controller = telemetry_controller
+        self._propagation_observers: list[Callable[[dict[str, Any]], None]] = []
+        self._propagation_snapshot: bytes | None = None
+        self._propagation_lock = threading.Lock()
+        if self.telemetry_controller is not None:
+            self.add_propagation_observer(self._persist_propagation_snapshot)
+        self._stop_event = threading.Event()
+        self._threads: list[threading.Thread] = []
+        self._started = False
+        self._last_peer_announce: float | None = None
+        self._last_node_announce: float | None = None
+
+    def start(self) -> None:
+        """Start the embedded propagation threads if not already running."""
+
+        if self._started:
+            return
+
+        if self.config.enable_propagation_node:
+            try:
+                self.router.enable_propagation()
+            except Exception as exc:  # pragma: no cover - defensive logging
+                RNS.log(
+                    f"Failed to enable LXMF propagation node in embedded mode: {exc}",
+                    RNS.LOG_ERROR,
+                )
+
+        self._started = True
+        self._start_thread(self._deferred_start_jobs)
+
+    def stop(self) -> None:
+        """Request the helper threads to stop and wait for them to finish."""
+
+        if not self._started:
+            return
+
+        self._stop_event.set()
+        for thread in self._threads:
+            thread.join()
+        self._threads.clear()
+        # Allow future ``start`` calls to run the deferred jobs loop again.
+        self._stop_event.clear()
+        self._started = False
+        self._maybe_emit_propagation_update(force=True)
+
+    def add_propagation_observer(
+        self, observer: Callable[[dict[str, Any]], None]
+    ) -> None:
+        """Register a callback notified whenever propagation state changes."""
+
+        self._propagation_observers.append(observer)
+
+    # ------------------------------------------------------------------ #
+    # private helpers
+    # ------------------------------------------------------------------ #
+    def _start_thread(self, target) -> None:
+        thread = threading.Thread(target=target, daemon=True)
+        thread.start()
+        self._threads.append(thread)
+
+    def _announce_delivery(self) -> None:
+        try:
+            self.router.announce(self.destination.hash)
+        except Exception as exc:  # pragma: no cover - logging guard
+            RNS.log(
+                f"Failed to announce embedded LXMF destination: {exc}",
+                RNS.LOG_ERROR,
+            )
+
+    def _announce_propagation(self) -> None:
+        try:
+            self.router.announce_propagation_node()
+        except Exception as exc:  # pragma: no cover - logging guard
+            RNS.log(
+                f"Failed to announce embedded propagation node: {exc}",
+                RNS.LOG_ERROR,
+            )
+
+    def _baseline_propagation_payload(self) -> dict[str, Any]:
+        peers = getattr(self.router, "peers", {}) or {}
+        static_peers = getattr(self.router, "static_peers", []) or []
+        destination_hash = getattr(
+            getattr(self.router, "propagation_destination", None), "hash", None
+        )
+        identity_hash = getattr(getattr(self.router, "identity", None), "hash", None)
+
+        total_peers = len(peers)
+        return {
+            "destination_hash": destination_hash,
+            "identity_hash": identity_hash,
+            "uptime": None,
+            "delivery_limit": getattr(self.router, "delivery_per_transfer_limit", None),
+            "propagation_limit": getattr(
+                self.router, "propagation_per_transfer_limit", None
+            ),
+            "autopeer_maxdepth": getattr(self.router, "autopeer_maxdepth", None),
+            "from_static_only": getattr(self.router, "from_static_only", None),
+            "messagestore": None,
+            "clients": None,
+            "unpeered_propagation_incoming": getattr(
+                self.router, "unpeered_propagation_incoming", None
+            ),
+            "unpeered_propagation_rx_bytes": getattr(
+                self.router, "unpeered_propagation_rx_bytes", None
+            ),
+            "static_peers": len(static_peers),
+            "total_peers": total_peers,
+            "active_peers": 0,
+            "unreachable_peers": total_peers,
+            "max_peers": getattr(self.router, "max_peers", None),
+            "peered_propagation_rx_bytes": 0,
+            "peered_propagation_tx_bytes": 0,
+            "peered_propagation_offered": 0,
+            "peered_propagation_outgoing": 0,
+            "peered_propagation_incoming": 0,
+            "peered_propagation_unhandled": 0,
+            "peered_propagation_max_unhandled": 0,
+            "peers": {},
+        }
+
+    def _normalize_propagation_stats(
+        self, stats: dict[str, Any] | None
+    ) -> dict[str, Any]:
+        payload = self._baseline_propagation_payload()
+        if not stats:
+            return payload
+
+        payload.update(
+            {
+                "destination_hash": stats.get("destination_hash")
+                or payload["destination_hash"],
+                "identity_hash": stats.get("identity_hash") or payload["identity_hash"],
+                "uptime": stats.get("uptime"),
+                "delivery_limit": stats.get("delivery_limit"),
+                "propagation_limit": stats.get("propagation_limit"),
+                "autopeer_maxdepth": stats.get("autopeer_maxdepth"),
+                "from_static_only": stats.get("from_static_only"),
+                "messagestore": stats.get("messagestore"),
+                "clients": stats.get("clients"),
+                "unpeered_propagation_incoming": stats.get(
+                    "unpeered_propagation_incoming"
+                ),
+                "unpeered_propagation_rx_bytes": stats.get(
+                    "unpeered_propagation_rx_bytes"
+                ),
+                "static_peers": stats.get("static_peers", payload["static_peers"]),
+                "max_peers": stats.get("max_peers", payload["max_peers"]),
+            }
+        )
+
+        peers_payload: dict[bytes, dict[str, Any]] = {}
+        active = 0
+        rx_sum = tx_sum = offered_sum = outgoing_sum = incoming_sum = unhandled_sum = 0
+        max_unhandled = 0
+
+        peer_stats = stats.get("peers") or {}
+        for peer_hash, peer_data in sorted(
+            peer_stats.items(), key=lambda item: item[0]
+        ):
+            if not isinstance(peer_hash, (bytes, bytearray, memoryview)):
+                continue
+            key = bytes(peer_hash)
+            messages = peer_data.get("messages") or {}
+            peers_payload[key] = {
+                "type": peer_data.get("type"),
+                "state": peer_data.get("state"),
+                "alive": peer_data.get("alive"),
+                "last_heard": peer_data.get("last_heard"),
+                "next_sync_attempt": peer_data.get("next_sync_attempt"),
+                "last_sync_attempt": peer_data.get("last_sync_attempt"),
+                "sync_backoff": peer_data.get("sync_backoff"),
+                "peering_timebase": peer_data.get("peering_timebase"),
+                "ler": peer_data.get("ler"),
+                "str": peer_data.get("str"),
+                "transfer_limit": peer_data.get("transfer_limit"),
+                "network_distance": peer_data.get("network_distance"),
+                "rx_bytes": peer_data.get("rx_bytes"),
+                "tx_bytes": peer_data.get("tx_bytes"),
+                "messages": {
+                    "offered": messages.get("offered"),
+                    "outgoing": messages.get("outgoing"),
+                    "incoming": messages.get("incoming"),
+                    "unhandled": messages.get("unhandled"),
+                },
+            }
+
+            if peer_data.get("alive"):
+                active += 1
+
+            rx_sum += peer_data.get("rx_bytes") or 0
+            tx_sum += peer_data.get("tx_bytes") or 0
+            offered = messages.get("offered") or 0
+            outgoing = messages.get("outgoing") or 0
+            incoming = messages.get("incoming") or 0
+            unhandled = messages.get("unhandled") or 0
+
+            offered_sum += offered
+            outgoing_sum += outgoing
+            incoming_sum += incoming
+            unhandled_sum += unhandled
+            if unhandled > max_unhandled:
+                max_unhandled = unhandled
+
+        total_peers = stats.get("total_peers")
+        if total_peers is None:
+            total_peers = len(peers_payload)
+
+        payload.update(
+            {
+                "peers": peers_payload,
+                "total_peers": total_peers,
+                "active_peers": active,
+                "unreachable_peers": max(total_peers - active, 0),
+                "peered_propagation_rx_bytes": rx_sum,
+                "peered_propagation_tx_bytes": tx_sum,
+                "peered_propagation_offered": offered_sum,
+                "peered_propagation_outgoing": outgoing_sum,
+                "peered_propagation_incoming": incoming_sum,
+                "peered_propagation_unhandled": unhandled_sum,
+                "peered_propagation_max_unhandled": max_unhandled,
+            }
+        )
+
+        return payload
+
+    def _build_propagation_payload(self) -> dict[str, Any] | None:
+        try:
+            stats = self.router.compile_stats()
+        except Exception as exc:  # pragma: no cover - defensive logging
+            RNS.log(
+                f"Failed to compile LXMF propagation stats: {exc}",
+                RNS.LOG_ERROR,
+            )
+            return None
+
+        return self._normalize_propagation_stats(stats)
+
+    def _maybe_emit_propagation_update(self, *, force: bool = False) -> None:
+        if not self._propagation_observers:
+            return
+
+        payload = self._build_propagation_payload()
+        if payload is None:
+            return
+
+        comparison_payload = dict(payload)
+        uptime = comparison_payload.get("uptime")
+        if uptime is not None:
+            comparison_payload["uptime"] = (
+                int(uptime) // self.PROPAGATION_UPTIME_GRANULARITY
+            )
+
+        packed = packb(comparison_payload, use_bin_type=True)
+
+        with self._propagation_lock:
+            if not force and packed == self._propagation_snapshot:
+                return
+            self._propagation_snapshot = packed
+
+        self._notify_propagation_observers(payload)
+
+    def _notify_propagation_observers(self, payload: dict[str, Any]) -> None:
+        for observer in list(self._propagation_observers):
+            try:
+                observer(payload)
+            except Exception as exc:  # pragma: no cover - defensive logging
+                RNS.log(
+                    f"Propagation observer failed: {exc}",
+                    RNS.LOG_ERROR,
+                )
+
+    def _persist_propagation_snapshot(self, payload: dict[str, Any]) -> None:
+        if self.telemetry_controller is None:
+            return
+
+        sensor = LXMFPropagation()
+        sensor.unpack(payload)
+        packed_payload = sensor.pack()
+        if packed_payload is None:
+            return
+
+        peer_hash = (
+            RNS.hexrep(self.destination.hash, False)
+            if hasattr(self.destination, "hash")
+            else ""
+        )
+
+        try:
+            self.telemetry_controller.save_telemetry(
+                {SID_LXMF_PROPAGATION: packed_payload},
+                peer_hash,
+                _utcnow(),
+            )
+        except Exception as exc:  # pragma: no cover - defensive logging
+            RNS.log(
+                f"Failed to persist propagation telemetry: {exc}",
+                RNS.LOG_ERROR,
+            )
+
+    def _deferred_start_jobs(self) -> None:
+        if self._stop_event.wait(self.DEFERRED_JOBS_DELAY):
+            return
+
+        self._announce_delivery()
+        self._last_peer_announce = time.monotonic()
+
+        if self.config.enable_propagation_node:
+            self._announce_propagation()
+            self._last_node_announce = self._last_peer_announce
+
+        self._maybe_emit_propagation_update(force=True)
+        self._start_thread(self._jobs)
+
+    def _jobs(self) -> None:
+        interval = self.config.announce_interval_seconds
+        while not self._stop_event.wait(self.JOBS_INTERVAL_SECONDS):
+            self._maybe_emit_propagation_update()
+            now = time.monotonic()
+            if (
+                self._last_peer_announce is None
+                or now - self._last_peer_announce >= interval
+            ):
+                self._announce_delivery()
+                self._last_peer_announce = now
+
+            if not self.config.enable_propagation_node:
+                continue
+
+            if (
+                self._last_node_announce is None
+                or now - self._last_node_announce >= interval
+            ):
+                self._announce_propagation()
+                self._last_node_announce = now
+
+    # Allow usage as a context manager for convenience
+    def __enter__(self) -> "EmbeddedLxmd":
+        self.start()
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.stop()

reticulum_telemetry_hub/internal_api/__init__.py

@@ -0,0 +1,21 @@
+"""Internal API package for process-boundary contracts."""
+
+from reticulum_telemetry_hub.internal_api.bus import CommandBus as CommandBus
+from reticulum_telemetry_hub.internal_api.bus import EventBus as EventBus
+from reticulum_telemetry_hub.internal_api.bus import (
+    InProcessCommandBus as InProcessCommandBus,
+)
+from reticulum_telemetry_hub.internal_api.bus import InProcessEventBus as InProcessEventBus
+from reticulum_telemetry_hub.internal_api.bus import InProcessQueryBus as InProcessQueryBus
+from reticulum_telemetry_hub.internal_api.bus import QueryBus as QueryBus
+from reticulum_telemetry_hub.internal_api.core import InternalApiCore as InternalApiCore
+
+__all__ = [
+    "CommandBus",
+    "EventBus",
+    "InProcessCommandBus",
+    "InProcessEventBus",
+    "InProcessQueryBus",
+    "QueryBus",
+    "InternalApiCore",
+]