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

reticulum_telemetry_hub/northbound/__init__.py

@@ -0,0 +1,5 @@
+"""Northbound FastAPI interface for the Reticulum Telemetry Hub."""
+
+from .app import create_app
+
+__all__ = ["create_app"]

reticulum_telemetry_hub/northbound/app.py

@@ -0,0 +1,195 @@
+"""FastAPI application for the northbound interface."""
+# pylint: disable=import-error
+
+from __future__ import annotations
+
+from datetime import datetime
+from datetime import timezone
+import os
+from pathlib import Path
+from typing import Any
+from typing import Callable
+from typing import Optional
+
+from dotenv import load_dotenv as load_env
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from reticulum_telemetry_hub.api.models import ChatMessage
+from reticulum_telemetry_hub.api.service import ReticulumTelemetryHubAPI
+from reticulum_telemetry_hub.config.manager import HubConfigurationManager
+from reticulum_telemetry_hub.lxmf_telemetry.telemetry_controller import (
+    TelemetryController,
+)
+from reticulum_telemetry_hub.reticulum_server.event_log import EventLog
+from reticulum_telemetry_hub.reticulum_server.event_log import resolve_event_log_path
+
+from .auth import ApiAuth
+from .auth import build_protected_dependency
+from .routes_files import register_file_routes
+from .routes_chat import register_chat_routes
+from .routes_rest import register_core_routes
+from .routes_subscribers import register_subscriber_routes
+from .routes_topics import register_topic_routes
+from .routes_ws import register_ws_routes
+from .internal_adapter import build_internal_adapter
+from .internal_adapter import InternalAdapter
+from .internal_adapter import register_internal_adapter
+from .services import NorthboundServices
+from .websocket import EventBroadcaster
+from .websocket import MessageBroadcaster
+from .websocket import TelemetryBroadcaster
+
+
+def _resolve_openapi_spec() -> Optional[Path]:
+    """Return the OpenAPI YAML path when available.
+
+    Returns:
+        Optional[Path]: Path to the OpenAPI YAML file when present.
+    """
+
+    repo_root = Path(__file__).resolve().parents[2]
+    spec_path = repo_root / "API" / "ReticulumCommunityHub-OAS.yaml"
+    if spec_path.exists():
+        return spec_path
+    return None
+
+
+def _resolve_storage_path() -> Path:
+    """Return the storage path from environment defaults."""
+
+    storage_dir = os.environ.get("RTH_STORAGE_DIR")
+    if storage_dir:
+        return Path(storage_dir).expanduser().resolve()
+    repo_root = Path(__file__).resolve().parents[2]
+    repo_storage = repo_root / "RTH_Store"
+    if repo_storage.exists():
+        return repo_storage
+    return HubConfigurationManager().storage_path.resolve()
+
+
+def create_app(
+    *,
+    api: Optional[ReticulumTelemetryHubAPI] = None,
+    telemetry_controller: Optional[TelemetryController] = None,
+    event_log: Optional[EventLog] = None,
+    command_manager: Optional[Any] = None,
+    routing_provider: Optional[Callable[[], list[str]]] = None,
+    started_at: Optional[datetime] = None,
+    auth: Optional[ApiAuth] = None,
+    message_dispatcher: Optional[
+        Callable[[str, Optional[str], Optional[str], Optional[dict]], ChatMessage | None]
+    ] = None,
+    message_listener: Optional[
+        Callable[[Callable[[dict[str, object]], None]], Callable[[], None]]
+    ] = None,
+    internal_adapter: Optional[InternalAdapter] = None,
+) -> FastAPI:
+    """Create the northbound FastAPI application.
+
+    Args:
+        api (Optional[ReticulumTelemetryHubAPI]): API service instance.
+        telemetry_controller (Optional[TelemetryController]): Telemetry controller instance.
+        event_log (Optional[EventLog]): Event log instance.
+        command_manager (Optional[Any]): Command manager for help/examples text.
+        routing_provider (Optional[Callable[[], list[str]]]): Provider for routing destinations.
+        started_at (Optional[datetime]): Start time for uptime calculations.
+        auth (Optional[ApiAuth]): Auth validator.
+
+    Returns:
+        FastAPI: Configured FastAPI application.
+    """
+
+    load_env()
+    config_manager = None
+    storage_path = None
+    if api is None:
+        storage_path = _resolve_storage_path()
+        config_manager = HubConfigurationManager(storage_path=storage_path)
+        api = ReticulumTelemetryHubAPI(config_manager=config_manager)
+    else:
+        config_manager = getattr(api, "_config_manager", None)
+        storage_path = getattr(config_manager, "storage_path", None)
+
+    if storage_path is None:
+        storage_path = _resolve_storage_path()
+
+    if event_log is None:
+        event_log_path = resolve_event_log_path(storage_path)
+        event_log = EventLog(event_path=event_log_path, tail=True)
+
+    if telemetry_controller is None:
+        telemetry_db_path = storage_path / "telemetry.db"
+        telemetry_controller = TelemetryController(
+            api=api,
+            event_log=event_log,
+            db_path=telemetry_db_path,
+        )
+    else:
+        telemetry_controller.set_event_log(event_log)
+    services = NorthboundServices(
+        api=api,
+        telemetry=telemetry_controller,
+        event_log=event_log,
+        started_at=started_at or datetime.now(timezone.utc),
+        command_manager=command_manager,
+        routing_provider=routing_provider,
+        message_dispatcher=message_dispatcher,
+    )
+    auth = auth or ApiAuth()
+    require_protected = build_protected_dependency(auth)
+
+    app = FastAPI(title="ReticulumCommunityHub", version="northbound")
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["*"],
+        allow_credentials=False,
+        allow_methods=["*"],
+        allow_headers=["*"],
+        max_age=86400,
+    )
+    event_broadcaster = EventBroadcaster(event_log)
+    telemetry_broadcaster = TelemetryBroadcaster(telemetry_controller, api)
+    message_broadcaster = MessageBroadcaster(message_listener)
+
+    register_core_routes(
+        app,
+        services=services,
+        api=api,
+        telemetry_controller=telemetry_controller,
+        require_protected=require_protected,
+        resolve_openapi_spec=_resolve_openapi_spec,
+    )
+    register_file_routes(app, services=services, api=api)
+    register_chat_routes(
+        app,
+        services=services,
+        require_protected=require_protected,
+    )
+    register_topic_routes(
+        app,
+        services=services,
+        api=api,
+        require_protected=require_protected,
+    )
+    register_subscriber_routes(
+        app,
+        services=services,
+        api=api,
+        require_protected=require_protected,
+    )
+    register_ws_routes(
+        app,
+        services=services,
+        auth=auth,
+        event_broadcaster=event_broadcaster,
+        telemetry_broadcaster=telemetry_broadcaster,
+        message_broadcaster=message_broadcaster,
+    )
+    adapter = internal_adapter or build_internal_adapter()
+    register_internal_adapter(app, adapter=adapter)
+
+    return app
+
+
+app = create_app()

reticulum_telemetry_hub/northbound/auth.py

@@ -0,0 +1,119 @@
+"""Authentication helpers for the northbound API."""
+# pylint: disable=import-error
+
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+from dotenv import load_dotenv as load_env
+from fastapi import Header
+from fastapi import HTTPException
+from fastapi import status
+
+
+class ApiAuth:
+    """Validate API key or bearer token credentials."""
+
+    def __init__(self, api_key: Optional[str] = None) -> None:
+        """Initialize the auth validator.
+
+        Args:
+            api_key (Optional[str]): API key override. When omitted, the
+                validator reads ``RTH_API_KEY`` from the environment.
+        """
+
+        load_env()
+        self._api_key = api_key
+
+    def is_enabled(self) -> bool:
+        """Return ``True`` when an API key is configured.
+
+        Returns:
+            bool: ``True`` when protected endpoints require credentials.
+        """
+
+        return bool(self._api_key or self._env_api_key())
+
+    def validate_credentials(
+        self, api_key: Optional[str], token: Optional[str]
+    ) -> bool:
+        """Validate provided credentials.
+
+        Args:
+            api_key (Optional[str]): API key header value.
+            token (Optional[str]): Bearer token value.
+
+        Returns:
+            bool: ``True`` when credentials are valid or auth is disabled.
+        """
+
+        expected = self._api_key or self._env_api_key()
+        if not expected:
+            return True
+        return api_key == expected or token == expected
+
+    @staticmethod
+    def _env_api_key() -> Optional[str]:
+        """Return the configured API key from the environment.
+
+        Returns:
+            Optional[str]: API key string if defined.
+        """
+
+        return os.environ.get("RTH_API_KEY")
+
+
+def _parse_bearer_token(authorization: Optional[str]) -> Optional[str]:
+    """Extract a bearer token from an authorization header.
+
+    Args:
+        authorization (Optional[str]): Authorization header value.
+
+    Returns:
+        Optional[str]: Parsed bearer token, if present.
+    """
+
+    if not authorization:
+        return None
+    parts = authorization.split()
+    if len(parts) != 2:
+        return None
+    if parts[0].lower() != "bearer":
+        return None
+    return parts[1]
+
+
+def build_protected_dependency(auth: ApiAuth):
+    """Return a dependency that enforces protected access.
+
+    Args:
+        auth (ApiAuth): Auth validator instance.
+
+    Returns:
+        Callable: Dependency function for FastAPI routes.
+    """
+
+    async def _require_protected(
+        x_api_key: Optional[str] = Header(default=None, alias="X-API-Key"),
+        authorization: Optional[str] = Header(default=None, alias="Authorization"),
+    ) -> None:
+        """Validate protected endpoint credentials.
+
+        Args:
+            x_api_key (Optional[str]): API key header value.
+            authorization (Optional[str]): Authorization header value.
+
+        Returns:
+            None: This dependency raises on invalid credentials.
+        """
+
+        token = _parse_bearer_token(authorization)
+        if auth.validate_credentials(x_api_key, token):
+            return
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Unauthorized",
+        )
+
+    return _require_protected

reticulum_telemetry_hub/northbound/gateway.py

@@ -0,0 +1,310 @@
+"""Run the Reticulum hub and northbound API in a single process."""
+# pylint: disable=import-error
+
+from __future__ import annotations
+
+import argparse
+import threading
+from dataclasses import dataclass
+from datetime import datetime
+from datetime import timezone
+from pathlib import Path
+from typing import Callable
+from typing import Optional
+from typing import Protocol
+
+import RNS
+import uvicorn
+from fastapi import FastAPI
+
+from reticulum_telemetry_hub.config.constants import DEFAULT_ANNOUNCE_INTERVAL
+from reticulum_telemetry_hub.config.constants import DEFAULT_HUB_TELEMETRY_INTERVAL
+from reticulum_telemetry_hub.config.constants import DEFAULT_LOG_LEVEL_NAME
+from reticulum_telemetry_hub.config.constants import DEFAULT_SERVICE_TELEMETRY_INTERVAL
+from reticulum_telemetry_hub.config.constants import DEFAULT_STORAGE_PATH
+from reticulum_telemetry_hub.config.manager import HubConfigurationManager
+from reticulum_telemetry_hub.config.manager import _expand_user_path
+from reticulum_telemetry_hub.northbound.app import create_app
+from reticulum_telemetry_hub.northbound.auth import ApiAuth
+from reticulum_telemetry_hub.reticulum_server.__main__ import ReticulumTelemetryHub
+
+
+class GatewayHub(Protocol):
+    """Protocol for hub dependencies consumed by the gateway app."""
+
+    api: object
+    tel_controller: object
+    event_log: object
+    command_manager: Optional[object]
+
+    def dispatch_northbound_message(
+        self,
+        message: str,
+        topic_id: Optional[str] = None,
+        destination: Optional[str] = None,
+        fields: Optional[dict] = None,
+    ) -> object:
+        """Send a northbound message through the hub."""
+
+    def register_message_listener(
+        self, listener: Callable[[dict[str, object]], None]
+    ) -> Callable[[], None]:
+        """Register an inbound message listener."""
+
+
+@dataclass(frozen=True)
+class GatewayConfig:
+    """Configuration bundle for the gateway runner."""
+
+    storage_path: Path
+    identity_path: Path
+    config_path: Path
+    display_name: str
+    announce_interval: int
+    hub_telemetry_interval: int
+    service_telemetry_interval: int
+    loglevel: int
+    embedded: bool
+    daemon_mode: bool
+    services: list[str]
+    api_host: str
+    api_port: int
+
+
+def _resolve_interval(value: int | None, fallback: int) -> int:
+    """Return the positive interval derived from CLI/config values."""
+
+    if value is not None:
+        return max(0, int(value))
+    return max(0, int(fallback))
+
+
+def _build_log_levels() -> dict[str, int]:
+    """Return the supported log level mapping for RNS."""
+
+    default_level = getattr(RNS, "LOG_DEBUG", getattr(RNS, "LOG_INFO", 3))
+    return {
+        "error": getattr(RNS, "LOG_ERROR", 1),
+        "warning": getattr(RNS, "LOG_WARNING", 2),
+        "info": getattr(RNS, "LOG_INFO", 3),
+        "debug": getattr(RNS, "LOG_DEBUG", default_level),
+    }
+
+
+def _parse_args() -> argparse.Namespace:
+    """Parse CLI arguments for the gateway runner."""
+
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "-c",
+        "--config",
+        dest="config_path",
+        help="Path to a unified config.ini file",
+        default=None,
+    )
+    parser.add_argument("-s", "--storage_dir", help="Storage directory path", default=None)
+    parser.add_argument("--display_name", help="Display name for the server", default=None)
+    parser.add_argument(
+        "--announce-interval",
+        type=int,
+        default=None,
+        help="Seconds between announcement broadcasts",
+    )
+    parser.add_argument(
+        "--hub-telemetry-interval",
+        type=int,
+        default=None,
+        help="Seconds between local telemetry snapshots.",
+    )
+    parser.add_argument(
+        "--service-telemetry-interval",
+        type=int,
+        default=None,
+        help="Seconds between remote telemetry collector polls.",
+    )
+    parser.add_argument(
+        "--log-level",
+        choices=list(_build_log_levels().keys()),
+        default=None,
+        help="Log level to emit RNS traffic to stdout",
+    )
+    parser.add_argument(
+        "--embedded",
+        "--embedded-lxmd",
+        dest="embedded",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help="Run the LXMF router/propagation threads in-process.",
+    )
+    parser.add_argument(
+        "--daemon",
+        dest="daemon",
+        action="store_true",
+        help="Start local telemetry collectors and optional services.",
+    )
+    parser.add_argument(
+        "--service",
+        dest="services",
+        action="append",
+        default=[],
+        metavar="NAME",
+        help=(
+            "Enable an optional daemon service (e.g., gpsd). Repeat the flag for"
+            " multiple services."
+        ),
+    )
+    parser.add_argument(
+        "--api-host",
+        dest="api_host",
+        default="127.0.0.1",
+        help="Host address for the northbound API.",
+    )
+    parser.add_argument(
+        "--api-port",
+        dest="api_port",
+        type=int,
+        default=8000,
+        help="Port for the northbound API.",
+    )
+    return parser.parse_args()
+
+
+def _build_gateway_config(args: argparse.Namespace) -> GatewayConfig:
+    """Build runtime configuration for the gateway runner."""
+
+    storage_path = _expand_user_path(args.storage_dir or DEFAULT_STORAGE_PATH)
+    identity_path = storage_path / "identity"
+    config_path = (
+        _expand_user_path(args.config_path)
+        if args.config_path
+        else storage_path / "config.ini"
+    )
+    config_manager = HubConfigurationManager(
+        storage_path=storage_path,
+        config_path=config_path,
+    )
+    runtime_config = config_manager.config.runtime
+    display_name = args.display_name or runtime_config.display_name
+    announce_interval = args.announce_interval or runtime_config.announce_interval
+    hub_interval = _resolve_interval(
+        args.hub_telemetry_interval,
+        runtime_config.hub_telemetry_interval or DEFAULT_HUB_TELEMETRY_INTERVAL,
+    )
+    service_interval = _resolve_interval(
+        args.service_telemetry_interval,
+        runtime_config.service_telemetry_interval or DEFAULT_SERVICE_TELEMETRY_INTERVAL,
+    )
+    log_level_name = (
+        args.log_level or runtime_config.log_level or DEFAULT_LOG_LEVEL_NAME
+    ).lower()
+    log_levels = _build_log_levels()
+    loglevel = log_levels.get(log_level_name, log_levels["info"])
+    embedded = runtime_config.embedded_lxmd if args.embedded is None else args.embedded
+    requested_services = list(runtime_config.default_services)
+    requested_services.extend(args.services or [])
+    services = list(dict.fromkeys(requested_services))
+    return GatewayConfig(
+        storage_path=storage_path,
+        identity_path=identity_path,
+        config_path=config_path,
+        display_name=display_name,
+        announce_interval=announce_interval,
+        hub_telemetry_interval=hub_interval,
+        service_telemetry_interval=service_interval,
+        loglevel=loglevel,
+        embedded=embedded,
+        daemon_mode=bool(args.daemon),
+        services=services,
+        api_host=str(args.api_host),
+        api_port=int(args.api_port),
+    )
+
+
+def build_gateway_app(
+    hub: GatewayHub,
+    *,
+    auth: Optional[ApiAuth] = None,
+    started_at: Optional[datetime] = None,
+) -> FastAPI:
+    """Create a northbound API app wired to the hub instance.
+
+    Args:
+        hub (GatewayHub): Active hub instance used for dispatching messages.
+        auth (Optional[ApiAuth]): Auth override.
+        started_at (Optional[datetime]): Optional start time override.
+
+    Returns:
+        FastAPI: Configured FastAPI application.
+    """
+
+    app = create_app(
+        api=hub.api,
+        telemetry_controller=hub.tel_controller,
+        event_log=hub.event_log,
+        command_manager=hub.command_manager,
+        message_dispatcher=hub.dispatch_northbound_message,
+        message_listener=hub.register_message_listener,
+        started_at=started_at or datetime.now(timezone.utc),
+        auth=auth,
+    )
+    app.state.hub = hub
+    return app
+
+
+def _start_hub_thread(
+    hub: ReticulumTelemetryHub,
+    *,
+    daemon_mode: bool,
+    services: list[str],
+) -> threading.Thread:
+    """Start the hub run loop in a background thread."""
+
+    thread = threading.Thread(
+        target=hub.run,
+        kwargs={"daemon_mode": daemon_mode, "services": services},
+        daemon=True,
+    )
+    thread.start()
+    return thread
+
+
+def main() -> None:
+    """Start the hub + northbound API gateway."""
+
+    args = _parse_args()
+    config = _build_gateway_config(args)
+    config_manager = HubConfigurationManager(
+        storage_path=config.storage_path,
+        config_path=config.config_path,
+    )
+    hub = ReticulumTelemetryHub(
+        config.display_name,
+        config.storage_path,
+        config.identity_path,
+        embedded=config.embedded,
+        announce_interval=config.announce_interval,
+        loglevel=config.loglevel,
+        hub_telemetry_interval=config.hub_telemetry_interval,
+        service_telemetry_interval=config.service_telemetry_interval,
+        config_manager=config_manager,
+    )
+    hub_thread = _start_hub_thread(
+        hub,
+        daemon_mode=config.daemon_mode,
+        services=config.services,
+    )
+    app = build_gateway_app(hub)
+    try:
+        uvicorn.run(
+            app,
+            host=config.api_host,
+            port=config.api_port,
+            log_level="info",
+        )
+    finally:
+        hub.shutdown()
+        hub_thread.join(timeout=5)
+
+
+if __name__ == "__main__":
+    main()