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

reticulum_telemetry_hub/northbound/routes_topics.py

@@ -0,0 +1,178 @@
+"""Topic 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 SubscribeTopicRequest
+from .models import TopicPayload
+from .serializers import build_topic
+from .serializers import serialize_subscriber
+from .serializers import serialize_topic
+from .services import NorthboundServices
+
+
+def register_topic_routes(
+    app: FastAPI,
+    *,
+    services: NorthboundServices,
+    api: ReticulumTelemetryHubAPI,
+    require_protected: Callable[[], None],
+) -> None:
+    """Register topic 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("/Topic/{topic_id}")
+    def retrieve_topic(topic_id: str) -> dict:
+        """Retrieve a topic by ID.
+
+        Args:
+            topic_id (str): Topic identifier.
+
+        Returns:
+            dict: Topic payload.
+        """
+
+        try:
+            topic = api.retrieve_topic(topic_id)
+        except KeyError as exc:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)) from exc
+        return serialize_topic(topic)
+
+    @app.post("/Topic", dependencies=[Depends(require_protected)])
+    def create_topic(payload: TopicPayload) -> dict:
+        """Create a new topic.
+
+        Args:
+            payload (TopicPayload): Topic request payload.
+
+        Returns:
+            dict: Created topic payload.
+        """
+
+        topic = build_topic(payload)
+        try:
+            created = api.create_topic(topic)
+        except ValueError as exc:
+            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc)) from exc
+        services.record_event("topic_created", f"Topic created: {created.topic_id}")
+        return serialize_topic(created)
+
+    @app.delete("/Topic", dependencies=[Depends(require_protected)])
+    def delete_topic(topic_id: str = Query(alias="id")) -> dict:
+        """Delete a topic.
+
+        Args:
+            topic_id (str): Topic identifier.
+
+        Returns:
+            dict: Deleted topic payload.
+        """
+
+        try:
+            topic = api.delete_topic(topic_id)
+        except KeyError as exc:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)) from exc
+        services.record_event("topic_deleted", f"Topic deleted: {topic.topic_id}")
+        return serialize_topic(topic)
+
+    @app.get("/Topic")
+    def list_topics() -> list[dict]:
+        """List topics.
+
+        Returns:
+            list[dict]: Topic entries.
+        """
+
+        return [serialize_topic(topic) for topic in services.list_topics()]
+
+    @app.patch("/Topic", dependencies=[Depends(require_protected)])
+    def patch_topic(payload: TopicPayload) -> dict:
+        """Update a topic.
+
+        Args:
+            payload (TopicPayload): Topic update payload.
+
+        Returns:
+            dict: Updated topic payload.
+        """
+
+        if not payload.topic_id:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="TopicID is required",
+            )
+        try:
+            topic = api.patch_topic(payload.topic_id, **payload.model_dump(by_alias=True, exclude_unset=True))
+        except KeyError as exc:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)) from exc
+        services.record_event("topic_updated", f"Topic updated: {topic.topic_id}")
+        return serialize_topic(topic)
+
+    @app.post("/Topic/Subscribe")
+    def subscribe_topic(payload: SubscribeTopicRequest) -> dict:
+        """Subscribe a destination to a topic.
+
+        Args:
+            payload (SubscribeTopicRequest): Subscription payload.
+
+        Returns:
+            dict: Subscriber payload.
+        """
+
+        if not payload.destination:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Destination is required when authentication identity is unavailable",
+            )
+        try:
+            subscriber = api.subscribe_topic(
+                payload.topic_id,
+                payload.destination,
+                reject_tests=payload.reject_tests,
+                metadata=payload.metadata,
+            )
+        except KeyError as exc:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)) from exc
+        services.record_event(
+            "topic_subscribed",
+            f"Subscriber added: {subscriber.subscriber_id}",
+            metadata={"topic_id": subscriber.topic_id},
+        )
+        return serialize_subscriber(subscriber)
+
+    @app.post("/Topic/Associate", dependencies=[Depends(require_protected)])
+    def associate_topic(payload: TopicPayload) -> dict:
+        """Return the topic association payload.
+
+        Args:
+            payload (TopicPayload): Topic association payload.
+
+        Returns:
+            dict: Topic association payload.
+        """
+
+        if not payload.topic_id:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="TopicID is required",
+            )
+        return {"TopicID": payload.topic_id}

reticulum_telemetry_hub/northbound/routes_ws.py

@@ -0,0 +1,107 @@
+"""WebSocket route registrations for the northbound API."""
+# pylint: disable=import-error
+
+from __future__ import annotations
+
+from fastapi import FastAPI
+from fastapi import WebSocket
+
+from .auth import ApiAuth
+from .services import NorthboundServices
+from .websocket import EventBroadcaster
+from .websocket import MessageBroadcaster
+from .websocket import TelemetryBroadcaster
+from .websocket import handle_message_socket
+from .websocket import handle_system_socket
+from .websocket import handle_telemetry_socket
+
+
+def register_ws_routes(
+    app: FastAPI,
+    *,
+    services: NorthboundServices,
+    auth: ApiAuth,
+    event_broadcaster: EventBroadcaster,
+    telemetry_broadcaster: TelemetryBroadcaster,
+    message_broadcaster: MessageBroadcaster,
+) -> None:
+    """Register WebSocket routes on the FastAPI app.
+
+    Args:
+        app (FastAPI): FastAPI application instance.
+        services (NorthboundServices): Aggregated services.
+        auth (ApiAuth): Auth validator.
+        event_broadcaster (EventBroadcaster): Event broadcaster.
+        telemetry_broadcaster (TelemetryBroadcaster): Telemetry broadcaster.
+        message_broadcaster (MessageBroadcaster): Message broadcaster.
+
+    Returns:
+        None: Routes are registered on the application.
+    """
+
+    @app.websocket("/events/system")
+    async def system_websocket(websocket: WebSocket) -> None:
+        """WebSocket stream for system status and events.
+
+        Args:
+            websocket (WebSocket): WebSocket connection.
+        """
+
+        def _event_list_provider(limit: int) -> list[dict]:
+            """Return recent events with the provided limit.
+
+            Args:
+                limit (int): Maximum number of events to return.
+
+            Returns:
+                list[dict]: Event entries.
+            """
+
+            return services.list_events(limit=limit)
+
+        await handle_system_socket(
+            websocket,
+            auth=auth,
+            event_broadcaster=event_broadcaster,
+            status_provider=services.status_snapshot,
+            event_list_provider=_event_list_provider,
+        )
+
+    @app.websocket("/telemetry/stream")
+    async def telemetry_websocket(websocket: WebSocket) -> None:
+        """WebSocket stream for telemetry updates.
+
+        Args:
+            websocket (WebSocket): WebSocket connection.
+        """
+
+        def _telemetry_snapshot(since: int, topic_id: str | None) -> list[dict]:
+            """Return telemetry snapshots for WebSocket clients.
+
+            Args:
+                since (int): Unix timestamp (seconds) for the earliest entries.
+                topic_id (str | None): Optional topic filter.
+
+            Returns:
+                list[dict]: Telemetry entries.
+            """
+
+            return services.telemetry_entries(since=since, topic_id=topic_id)
+
+        await handle_telemetry_socket(
+            websocket,
+            auth=auth,
+            telemetry_broadcaster=telemetry_broadcaster,
+            telemetry_snapshot=_telemetry_snapshot,
+        )
+
+    @app.websocket("/messages/stream")
+    async def message_websocket(websocket: WebSocket) -> None:
+        """WebSocket stream for inbound/outbound messages."""
+
+        await handle_message_socket(
+            websocket,
+            auth=auth,
+            message_broadcaster=message_broadcaster,
+            message_sender=services.send_message,
+        )

reticulum_telemetry_hub/northbound/serializers.py

@@ -0,0 +1,72 @@
+"""Serialization helpers for the northbound API."""
+
+from __future__ import annotations
+
+from reticulum_telemetry_hub.api.models import Subscriber
+from reticulum_telemetry_hub.api.models import Topic
+
+from .models import SubscriberPayload
+from .models import TopicPayload
+
+
+def serialize_topic(topic: Topic) -> dict:
+    """Serialize a topic for JSON output.
+
+    Args:
+        topic (Topic): Topic instance.
+
+    Returns:
+        dict: Serialized topic payload.
+    """
+
+    return topic.to_dict()
+
+
+def serialize_subscriber(subscriber: Subscriber) -> dict:
+    """Serialize a subscriber for JSON output.
+
+    Args:
+        subscriber (Subscriber): Subscriber instance.
+
+    Returns:
+        dict: Serialized subscriber payload.
+    """
+
+    return subscriber.to_dict()
+
+
+def build_topic(payload: TopicPayload) -> Topic:
+    """Build a topic model from a payload.
+
+    Args:
+        payload (TopicPayload): Topic payload.
+
+    Returns:
+        Topic: Topic instance.
+    """
+
+    return Topic(
+        topic_id=payload.topic_id,
+        topic_name=payload.topic_name or "",
+        topic_path=payload.topic_path or "",
+        topic_description=payload.topic_description or "",
+    )
+
+
+def build_subscriber(payload: SubscriberPayload) -> Subscriber:
+    """Build a subscriber model from a payload.
+
+    Args:
+        payload (SubscriberPayload): Subscriber payload.
+
+    Returns:
+        Subscriber: Subscriber instance.
+    """
+
+    return Subscriber(
+        subscriber_id=payload.subscriber_id,
+        destination=payload.destination or "",
+        topic_id=payload.topic_id,
+        reject_tests=payload.reject_tests,
+        metadata=payload.metadata or {},
+    )