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

reticulum_telemetry_hub/northbound/routes_files.py

@@ -0,0 +1,119 @@
+"""File and image routes for the northbound API."""
+# pylint: disable=import-error
+
+from __future__ import annotations
+
+from fastapi import FastAPI
+from fastapi import HTTPException
+from fastapi import status
+from fastapi.responses import FileResponse
+
+from reticulum_telemetry_hub.api.service import ReticulumTelemetryHubAPI
+
+from .services import NorthboundServices
+
+
+def register_file_routes(
+    app: FastAPI,
+    *,
+    services: NorthboundServices,
+    api: ReticulumTelemetryHubAPI,
+) -> None:
+    """Register file and image routes on the FastAPI app.
+
+    Args:
+        app (FastAPI): FastAPI application instance.
+        services (NorthboundServices): Aggregated services.
+        api (ReticulumTelemetryHubAPI): API service instance.
+
+    Returns:
+        None: Routes are registered on the application.
+    """
+
+    @app.get("/File")
+    def list_files() -> list[dict]:
+        """List stored files.
+
+        Returns:
+            list[dict]: File attachment entries.
+        """
+
+        return [attachment.to_dict() for attachment in services.list_files()]
+
+    @app.get("/File/{file_id}")
+    def retrieve_file(file_id: int) -> dict:
+        """Retrieve file metadata by ID.
+
+        Args:
+            file_id (int): File record identifier.
+
+        Returns:
+            dict: File attachment payload.
+        """
+
+        try:
+            attachment = api.retrieve_file(file_id)
+        except KeyError as exc:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)) from exc
+        return attachment.to_dict()
+
+    @app.get("/File/{file_id}/raw")
+    def retrieve_file_raw(file_id: int) -> FileResponse:
+        """Return raw file bytes by ID.
+
+        Args:
+            file_id (int): File record identifier.
+
+        Returns:
+            FileResponse: File response payload.
+        """
+
+        try:
+            attachment = api.retrieve_file(file_id)
+        except KeyError as exc:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)) from exc
+        return FileResponse(path=attachment.path, media_type=attachment.media_type)
+
+    @app.get("/Image")
+    def list_images() -> list[dict]:
+        """List stored images.
+
+        Returns:
+            list[dict]: Image attachment entries.
+        """
+
+        return [attachment.to_dict() for attachment in services.list_images()]
+
+    @app.get("/Image/{file_id}")
+    def retrieve_image(file_id: int) -> dict:
+        """Retrieve image metadata by ID.
+
+        Args:
+            file_id (int): Image record identifier.
+
+        Returns:
+            dict: Image attachment payload.
+        """
+
+        try:
+            attachment = api.retrieve_image(file_id)
+        except KeyError as exc:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)) from exc
+        return attachment.to_dict()
+
+    @app.get("/Image/{file_id}/raw")
+    def retrieve_image_raw(file_id: int) -> FileResponse:
+        """Return raw image bytes by ID.
+
+        Args:
+            file_id (int): Image record identifier.
+
+        Returns:
+            FileResponse: Image response payload.
+        """
+
+        try:
+            attachment = api.retrieve_image(file_id)
+        except KeyError as exc:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)) from exc
+        return FileResponse(path=attachment.path, media_type=attachment.media_type)

reticulum_telemetry_hub/northbound/routes_rest.py

@@ -0,0 +1,345 @@
+"""Core REST routes for the northbound API."""
+# pylint: disable=import-error
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Callable
+from typing import Optional
+
+from fastapi import Body
+from fastapi import Depends
+from fastapi import FastAPI
+from fastapi import HTTPException
+from fastapi import Query
+from fastapi import Response
+from fastapi import status
+
+from reticulum_telemetry_hub.api.service import ReticulumTelemetryHubAPI
+from reticulum_telemetry_hub.lxmf_telemetry.telemetry_controller import (
+    TelemetryController,
+)
+
+from .models import ConfigRollbackPayload
+from .models import MessagePayload
+from .services import NorthboundServices
+
+
+def register_core_routes(
+    app: FastAPI,
+    *,
+    services: NorthboundServices,
+    api: ReticulumTelemetryHubAPI,
+    telemetry_controller: TelemetryController,
+    require_protected: Callable[[], None],
+    resolve_openapi_spec: Callable[[], Optional[Path]],
+) -> None:
+    """Register core REST routes on the FastAPI app.
+
+    Args:
+        app (FastAPI): FastAPI application instance.
+        services (NorthboundServices): Aggregated services.
+        api (ReticulumTelemetryHubAPI): API service instance.
+        telemetry_controller (TelemetryController): Telemetry controller instance.
+        require_protected (Callable[[], None]): Dependency for protected routes.
+        resolve_openapi_spec (Callable[[], Optional[Path]]): OpenAPI spec resolver.
+
+    Returns:
+        None: Routes are registered on the application.
+    """
+
+    @app.get("/openapi.yaml", include_in_schema=False)
+    def openapi_yaml() -> Response:
+        """Return the OpenAPI YAML file if available.
+
+        Returns:
+            Response: YAML content response.
+        """
+
+        spec_path = resolve_openapi_spec()
+        if not spec_path:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="OpenAPI spec not found",
+            )
+        return Response(spec_path.read_text(encoding="utf-8"), media_type="application/yaml")
+
+    @app.get("/Help")
+    def get_help_text() -> Response:
+        """Return the list of supported commands.
+
+        Returns:
+            Response: Plain text command list.
+        """
+
+        return Response(services.help_text(), media_type="text/plain")
+
+    @app.get("/Examples")
+    def get_examples_text() -> Response:
+        """Return command payload examples.
+
+        Returns:
+            Response: Plain text examples.
+        """
+
+        return Response(services.examples_text(), media_type="text/plain")
+
+    @app.get("/Status", dependencies=[Depends(require_protected)])
+    def get_status() -> dict:
+        """Return dashboard status metrics.
+
+        Returns:
+            dict: Status payload.
+        """
+
+        return services.status_snapshot()
+
+    @app.get("/Events", dependencies=[Depends(require_protected)])
+    def get_events() -> list[dict]:
+        """Return recent events.
+
+        Returns:
+            list[dict]: Event entries.
+        """
+
+        return services.list_events()
+
+    @app.get("/Telemetry")
+    def get_telemetry(
+        since: int = Query(alias="since"),
+        topic_id: Optional[str] = Query(default=None, alias="topic_id"),
+    ) -> dict:
+        """Return telemetry entries since a timestamp.
+
+        Args:
+            since (int): Unix timestamp (seconds) for the earliest entries.
+            topic_id (Optional[str]): Optional topic filter.
+
+        Returns:
+            dict: Telemetry response payload.
+        """
+
+        try:
+            entries = services.telemetry_entries(since=since, topic_id=topic_id)
+        except KeyError as exc:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)) from exc
+        except ValueError as exc:
+            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc)) from exc
+        return {"entries": entries}
+
+    @app.get("/Config", dependencies=[Depends(require_protected)])
+    def get_config() -> Response:
+        """Return the config.ini payload.
+
+        Returns:
+            Response: Plain text configuration payload.
+        """
+
+        return Response(api.get_config_text(), media_type="text/plain")
+
+    @app.put("/Config", dependencies=[Depends(require_protected)])
+    def apply_config(config_text: str = Body(media_type="text/plain")) -> dict:
+        """Apply a new config.ini payload.
+
+        Args:
+            config_text (str): Raw config.ini payload.
+
+        Returns:
+            dict: Apply result payload.
+        """
+
+        try:
+            result = api.apply_config_text(config_text)
+        except ValueError as exc:
+            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc)) from exc
+        services.record_event("config_applied", "Configuration applied")
+        return result
+
+    @app.post("/Config/Validate", dependencies=[Depends(require_protected)])
+    def validate_config(config_text: str = Body(media_type="text/plain")) -> dict:
+        """Validate a config.ini payload.
+
+        Args:
+            config_text (str): Raw config.ini payload.
+
+        Returns:
+            dict: Validation result payload.
+        """
+
+        return api.validate_config_text(config_text)
+
+    @app.post("/Config/Rollback", dependencies=[Depends(require_protected)])
+    def rollback_config(payload: Optional[ConfigRollbackPayload] = Body(default=None)) -> dict:
+        """Rollback config.ini using a backup path.
+
+        Args:
+            payload (Optional[ConfigRollbackPayload]): Rollback payload.
+
+        Returns:
+            dict: Rollback result payload.
+        """
+
+        backup_path = payload.backup_path if payload else None
+        result = api.rollback_config_text(backup_path=backup_path)
+        services.record_event("config_rolled_back", "Configuration rolled back")
+        return result
+
+    @app.post("/Command/FlushTelemetry", dependencies=[Depends(require_protected)])
+    def flush_telemetry() -> dict:
+        """Flush stored telemetry entries.
+
+        Returns:
+            dict: Flush result payload.
+        """
+
+        deleted = telemetry_controller.clear_telemetry()
+        services.record_event("telemetry_flushed", f"Telemetry flushed ({deleted} rows)")
+        return {"deleted": deleted}
+
+    @app.post("/Command/ReloadConfig", dependencies=[Depends(require_protected)])
+    def reload_config() -> dict:
+        """Reload config.ini from disk.
+
+        Returns:
+            dict: Reloaded configuration payload.
+        """
+
+        info = services.reload_config()
+        services.record_event("config_reloaded", "Configuration reloaded")
+        return info.to_dict()
+
+    @app.post("/Message", dependencies=[Depends(require_protected)])
+    def send_message(payload: MessagePayload) -> dict:
+        """Send a message into the Reticulum Telemetry Hub."""
+
+        try:
+            services.send_message(
+                payload.content,
+                topic_id=payload.topic_id,
+                destination=payload.destination,
+            )
+        except RuntimeError as exc:
+            raise HTTPException(
+                status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+                detail=str(exc),
+            ) from exc
+        services.record_event(
+            "message_sent",
+            "Northbound message dispatched",
+            metadata={
+                "topic_id": payload.topic_id,
+                "destination": payload.destination,
+            },
+        )
+        return {"sent": True}
+
+    @app.get("/Command/DumpRouting", dependencies=[Depends(require_protected)])
+    def dump_routing() -> dict:
+        """Return connected destination hashes.
+
+        Returns:
+            dict: Routing summary payload.
+        """
+
+        return services.dump_routing()
+
+    @app.get("/Identities", dependencies=[Depends(require_protected)])
+    def list_identities() -> list[dict]:
+        """Return identity moderation status entries.
+
+        Returns:
+            list[dict]: Identity status entries.
+        """
+
+        return [status_entry.to_dict() for status_entry in services.list_identity_statuses()]
+
+    @app.post("/Client/{identity}/Ban", dependencies=[Depends(require_protected)])
+    def ban_identity(identity: str) -> dict:
+        """Ban an identity.
+
+        Args:
+            identity (str): Identity to ban.
+
+        Returns:
+            dict: Updated identity status.
+        """
+
+        status_entry = api.ban_identity(identity)
+        services.record_event("identity_banned", f"Identity banned: {identity}")
+        return status_entry.to_dict()
+
+    @app.post("/Client/{identity}/Unban", dependencies=[Depends(require_protected)])
+    def unban_identity(identity: str) -> dict:
+        """Unban an identity.
+
+        Args:
+            identity (str): Identity to unban.
+
+        Returns:
+            dict: Updated identity status.
+        """
+
+        status_entry = api.unban_identity(identity)
+        services.record_event("identity_unbanned", f"Identity unbanned: {identity}")
+        return status_entry.to_dict()
+
+    @app.post("/Client/{identity}/Blackhole", dependencies=[Depends(require_protected)])
+    def blackhole_identity(identity: str) -> dict:
+        """Blackhole an identity.
+
+        Args:
+            identity (str): Identity to blackhole.
+
+        Returns:
+            dict: Updated identity status.
+        """
+
+        status_entry = api.blackhole_identity(identity)
+        services.record_event("identity_blackholed", f"Identity blackholed: {identity}")
+        return status_entry.to_dict()
+
+    @app.post("/RTH")
+    def rth_join(identity: str = Query(alias="identity")) -> bool:
+        """Join the Reticulum Telemetry Hub.
+
+        Args:
+            identity (str): Identity to register.
+
+        Returns:
+            bool: ``True`` when the identity is recorded.
+        """
+
+        return api.join(identity)
+
+    @app.put("/RTH")
+    def rth_leave(identity: str = Query(alias="identity")) -> bool:
+        """Leave the Reticulum Telemetry Hub.
+
+        Args:
+            identity (str): Identity to remove.
+
+        Returns:
+            bool: ``True`` when the identity is removed.
+        """
+
+        return api.leave(identity)
+
+    @app.get("/Client", dependencies=[Depends(require_protected)])
+    def list_clients() -> list[dict]:
+        """List clients.
+
+        Returns:
+            list[dict]: Client entries.
+        """
+
+        return [client.to_dict() for client in services.list_clients()]
+
+    @app.get("/api/v1/app/info")
+    def app_info() -> dict:
+        """Return application metadata.
+
+        Returns:
+            dict: Application info payload.
+        """
+
+        return services.app_info().to_dict()

reticulum_telemetry_hub/northbound/routes_subscribers.py

@@ -0,0 +1,150 @@
+"""Subscriber routes for the northbound API."""
+# pylint: disable=import-error
+
+from __future__ import annotations
+
+from typing import Callable
+
+from fastapi import Depends
+from fastapi import FastAPI
+from fastapi import HTTPException
+from fastapi import Query
+from fastapi import status
+
+from reticulum_telemetry_hub.api.service import ReticulumTelemetryHubAPI
+
+from .models import SubscriberPayload
+from .serializers import build_subscriber
+from .serializers import serialize_subscriber
+from .services import NorthboundServices
+
+
+def register_subscriber_routes(
+    app: FastAPI,
+    *,
+    services: NorthboundServices,
+    api: ReticulumTelemetryHubAPI,
+    require_protected: Callable[[], None],
+) -> None:
+    """Register subscriber routes on the FastAPI app.
+
+    Args:
+        app (FastAPI): FastAPI application instance.
+        services (NorthboundServices): Aggregated services.
+        api (ReticulumTelemetryHubAPI): API service instance.
+        require_protected (Callable[[], None]): Dependency for protected routes.
+
+    Returns:
+        None: Routes are registered on the application.
+    """
+
+    @app.get("/Subscriber/{subscriber_id}", dependencies=[Depends(require_protected)])
+    def retrieve_subscriber(subscriber_id: str) -> dict:
+        """Retrieve a subscriber by ID.
+
+        Args:
+            subscriber_id (str): Subscriber identifier.
+
+        Returns:
+            dict: Subscriber payload.
+        """
+
+        try:
+            subscriber = api.retrieve_subscriber(subscriber_id)
+        except KeyError as exc:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)) from exc
+        return serialize_subscriber(subscriber)
+
+    @app.post("/Subscriber/Add", dependencies=[Depends(require_protected)])
+    def add_subscriber(payload: SubscriberPayload) -> dict:
+        """Add a subscriber mapping.
+
+        Args:
+            payload (SubscriberPayload): Subscriber payload.
+
+        Returns:
+            dict: Subscriber payload.
+        """
+
+        subscriber = build_subscriber(payload)
+        try:
+            created = api.add_subscriber(subscriber)
+        except ValueError as exc:
+            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc)) from exc
+        services.record_event("subscriber_added", f"Subscriber added: {created.subscriber_id}")
+        return serialize_subscriber(created)
+
+    @app.post("/Subscriber", dependencies=[Depends(require_protected)])
+    def create_subscriber(payload: SubscriberPayload) -> dict:
+        """Create a subscriber.
+
+        Args:
+            payload (SubscriberPayload): Subscriber payload.
+
+        Returns:
+            dict: Subscriber payload.
+        """
+
+        subscriber = build_subscriber(payload)
+        try:
+            created = api.create_subscriber(subscriber)
+        except ValueError as exc:
+            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc)) from exc
+        services.record_event("subscriber_created", f"Subscriber created: {created.subscriber_id}")
+        return serialize_subscriber(created)
+
+    @app.delete("/Subscriber", dependencies=[Depends(require_protected)])
+    def delete_subscriber(subscriber_id: str = Query(alias="id")) -> dict:
+        """Delete a subscriber.
+
+        Args:
+            subscriber_id (str): Subscriber identifier.
+
+        Returns:
+            dict: Deleted subscriber payload.
+        """
+
+        try:
+            subscriber = api.delete_subscriber(subscriber_id)
+        except KeyError as exc:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)) from exc
+        services.record_event("subscriber_deleted", f"Subscriber deleted: {subscriber.subscriber_id}")
+        return serialize_subscriber(subscriber)
+
+    @app.get("/Subscriber", dependencies=[Depends(require_protected)])
+    def list_subscribers() -> list[dict]:
+        """List subscribers.
+
+        Returns:
+            list[dict]: Subscriber entries.
+        """
+
+        return [serialize_subscriber(subscriber) for subscriber in services.list_subscribers()]
+
+    @app.patch("/Subscriber", dependencies=[Depends(require_protected)])
+    def patch_subscriber(payload: SubscriberPayload) -> dict:
+        """Update a subscriber.
+
+        Args:
+            payload (SubscriberPayload): Subscriber update payload.
+
+        Returns:
+            dict: Updated subscriber payload.
+        """
+
+        if not payload.subscriber_id:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="SubscriberID is required",
+            )
+        try:
+            subscriber = api.patch_subscriber(
+                payload.subscriber_id,
+                **payload.model_dump(by_alias=True, exclude_unset=True),
+            )
+        except ValueError as exc:
+            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc)) from exc
+        except KeyError as exc:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)) from exc
+        services.record_event("subscriber_updated", f"Subscriber updated: {subscriber.subscriber_id}")
+        return serialize_subscriber(subscriber)