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

reticulum_telemetry_hub/northbound/internal_adapter.py

@@ -0,0 +1,302 @@
+"""Internal API adapter routes for the northbound gateway."""
+# pylint: disable=import-error
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from dataclasses import dataclass
+from datetime import datetime
+from datetime import timezone
+from typing import Optional
+from uuid import uuid4
+
+from fastapi import APIRouter
+from fastapi import FastAPI
+from fastapi import HTTPException
+from fastapi import Query
+from fastapi import WebSocket
+from fastapi import WebSocketDisconnect
+from fastapi import status
+from pydantic import BaseModel
+from pydantic import ConfigDict
+
+from reticulum_telemetry_hub.internal_api import InProcessCommandBus
+from reticulum_telemetry_hub.internal_api import InProcessEventBus
+from reticulum_telemetry_hub.internal_api import InProcessQueryBus
+from reticulum_telemetry_hub.internal_api import InternalApiCore
+from reticulum_telemetry_hub.internal_api.bus import CommandBus
+from reticulum_telemetry_hub.internal_api.bus import EventBus
+from reticulum_telemetry_hub.internal_api.bus import QueryBus
+from reticulum_telemetry_hub.internal_api.v1.enums import CommandStatus
+from reticulum_telemetry_hub.internal_api.v1.enums import CommandType
+from reticulum_telemetry_hub.internal_api.v1.enums import ErrorCode
+from reticulum_telemetry_hub.internal_api.v1.enums import IssuerType
+from reticulum_telemetry_hub.internal_api.v1.enums import MessageType
+from reticulum_telemetry_hub.internal_api.v1.enums import Qos
+from reticulum_telemetry_hub.internal_api.v1.enums import QueryType
+from reticulum_telemetry_hub.internal_api.v1.schemas import CommandEnvelope
+from reticulum_telemetry_hub.internal_api.v1.schemas import CommandResult
+from reticulum_telemetry_hub.internal_api.v1.schemas import QueryEnvelope
+from reticulum_telemetry_hub.internal_api.v1.schemas import QueryResult
+from reticulum_telemetry_hub.internal_api.versioning import select_api_version
+
+
+_ISSUER_ID = "internal-adapter"
+_LOGGER = logging.getLogger(__name__)
+
+
+class InternalMessageRequest(BaseModel):
+    """Request payload for sending a text message."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    destination: str
+    text: str
+
+
+@dataclass
+class InternalAdapter:
+    """Container for internal API adapter dependencies."""
+
+    command_bus: CommandBus
+    query_bus: QueryBus
+    event_bus: EventBus
+    core: InternalApiCore
+
+    async def start(self) -> None:
+        """Start in-process buses."""
+
+        await self.event_bus.start()
+        await self.command_bus.start()
+        await self.query_bus.start()
+
+    async def stop(self) -> None:
+        """Stop in-process buses."""
+
+        await self.command_bus.stop()
+        await self.query_bus.stop()
+        await self.event_bus.stop()
+
+
+def build_internal_adapter() -> InternalAdapter:
+    """Build an internal adapter backed by in-process buses."""
+
+    event_bus = InProcessEventBus()
+    core = InternalApiCore(event_bus)
+    command_bus = InProcessCommandBus()
+    query_bus = InProcessQueryBus()
+    command_bus.register_handler(core.handle_command)
+    query_bus.register_handler(core.handle_query)
+    return InternalAdapter(
+        command_bus=command_bus,
+        query_bus=query_bus,
+        event_bus=event_bus,
+        core=core,
+    )
+
+
+def register_internal_adapter(app: FastAPI, *, adapter: InternalAdapter) -> None:
+    """Register internal adapter routes on the FastAPI app."""
+
+    router = APIRouter(prefix="/internal")
+
+    @app.on_event("startup")
+    async def _start_internal_buses() -> None:
+        await adapter.start()
+
+    @app.on_event("shutdown")
+    async def _stop_internal_buses() -> None:
+        await adapter.stop()
+
+    @router.get("/topics")
+    async def list_topics(prefix: Optional[str] = Query(default=None)) -> list[str]:
+        """Return topic identifiers using the internal query API."""
+
+        query = _build_query(QueryType.GET_TOPICS, {"prefix": prefix} if prefix else {})
+        result = await adapter.query_bus.execute(query)
+        data = _unwrap_query(result)
+        return [topic["topic_id"] for topic in data.get("topics", [])]
+
+    @router.get("/topics/{topic_id}/subscribers")
+    async def list_subscribers(topic_id: str) -> list[str]:
+        """Return subscriber node IDs for a topic."""
+
+        query = _build_query(QueryType.GET_SUBSCRIBERS, {"topic_path": topic_id})
+        result = await adapter.query_bus.execute(query)
+        data = _unwrap_query(result)
+        return [entry["node_id"] for entry in data.get("subscribers", [])]
+
+    @router.get("/nodes/{node_id}")
+    async def get_node_status(node_id: str) -> dict:
+        """Return collapsed node status details."""
+
+        query = _build_query(QueryType.GET_NODE_STATUS, {"node_id": node_id})
+        result = await adapter.query_bus.execute(query)
+        data = _unwrap_query(result)
+        status_value = data.get("status")
+        return {
+            "node_id": data.get("node_id", node_id),
+            "online": status_value == "online",
+            "topics": data.get("topics", []),
+        }
+
+    @router.post("/message")
+    async def post_message(payload: InternalMessageRequest) -> dict:
+        """Publish a text message using the internal command API."""
+
+        command = _build_command(
+            CommandType.PUBLISH_MESSAGE,
+            {
+                "topic_path": payload.destination,
+                "message_type": MessageType.TEXT,
+                "content": {
+                    "message_type": MessageType.TEXT,
+                    "text": payload.text,
+                    "encoding": "utf-8",
+                },
+                "qos": Qos.BEST_EFFORT,
+            },
+        )
+        result = await adapter.command_bus.send(command)
+        _raise_for_command(result)
+        return {"accepted": True}
+
+    @router.websocket("/events/stream")
+    async def stream_events(websocket: WebSocket) -> None:
+        """Stream internal API events over WebSocket."""
+
+        await websocket.accept()
+        queue: asyncio.Queue[dict] = asyncio.Queue(maxsize=32)
+
+        async def _handler(event) -> None:
+            await queue.put(event.model_dump(mode="json"))
+
+        unsubscribe = adapter.event_bus.subscribe(_handler)
+        try:
+            while True:
+                message = await queue.get()
+                await websocket.send_json(message)
+        except WebSocketDisconnect:
+            return
+        finally:
+            unsubscribe()
+
+    app.include_router(router)
+    app.state.internal_adapter = adapter
+
+
+def _build_command(command_type: CommandType, payload: dict) -> CommandEnvelope:
+    """Build a command envelope with API issuer metadata."""
+
+    command = CommandEnvelope.model_validate(
+        {
+            "api_version": select_api_version(),
+            "command_id": uuid4(),
+            "command_type": command_type,
+            "issued_at": _utc_now(),
+            "issuer": {"type": IssuerType.API, "id": _ISSUER_ID},
+            "payload": payload,
+        }
+    )
+    _LOGGER.debug(
+        "Internal adapter command built",
+        extra={
+            "command_id": str(command.command_id),
+            "command_type": command.command_type.value,
+            "correlation_id": str(command.command_id),
+        },
+    )
+    return command
+
+
+def _build_query(query_type: QueryType, payload: dict) -> QueryEnvelope:
+    """Build a query envelope."""
+
+    query = QueryEnvelope.model_validate(
+        {
+            "api_version": select_api_version(),
+            "query_id": uuid4(),
+            "query_type": query_type,
+            "issued_at": _utc_now(),
+            "payload": payload,
+        }
+    )
+    _LOGGER.debug(
+        "Internal adapter query built",
+        extra={
+            "query_id": str(query.query_id),
+            "query_type": query.query_type.value,
+            "correlation_id": str(query.query_id),
+        },
+    )
+    return query
+
+
+def _unwrap_query(result: QueryResult) -> dict:
+    """Return query data or raise an HTTP error."""
+
+    if result.ok and result.result is not None:
+        return result.result.data
+    error = result.error
+    if error is None:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Query failed without an error payload",
+        )
+    status_code = _map_query_error(error.code)
+    raise HTTPException(
+        status_code=status_code,
+        detail={"code": error.code.value, "message": error.message},
+    )
+
+
+def _raise_for_command(result: CommandResult) -> None:
+    """Raise HTTP errors for rejected commands."""
+
+    if result.status == CommandStatus.ACCEPTED:
+        return
+    if result.reason:
+        status_code = _map_command_error(result.reason)
+        raise HTTPException(
+            status_code=status_code,
+            detail={"code": result.reason, "message": "Command rejected"},
+        )
+    raise HTTPException(
+        status_code=status.HTTP_400_BAD_REQUEST,
+        detail={"code": "COMMAND_REJECTED", "message": "Command rejected"},
+    )
+
+
+def _map_query_error(error_code: ErrorCode) -> int:
+    """Map query error codes to HTTP status codes."""
+
+    if error_code == ErrorCode.TOPIC_NOT_FOUND:
+        return status.HTTP_404_NOT_FOUND
+    if error_code == ErrorCode.INVALID_QUERY:
+        return status.HTTP_400_BAD_REQUEST
+    if error_code == ErrorCode.UNAUTHORIZED:
+        return status.HTTP_403_FORBIDDEN
+    if error_code == ErrorCode.INTERNAL_ERROR:
+        return status.HTTP_500_INTERNAL_SERVER_ERROR
+    return status.HTTP_500_INTERNAL_SERVER_ERROR
+
+
+def _map_command_error(reason: str) -> int:
+    """Map command rejection reasons to HTTP status codes."""
+
+    try:
+        error_code = ErrorCode(reason)
+    except ValueError:
+        return status.HTTP_400_BAD_REQUEST
+    if error_code == ErrorCode.TOPIC_NOT_FOUND:
+        return status.HTTP_404_NOT_FOUND
+    if error_code == ErrorCode.UNAUTHORIZED_COMMAND:
+        return status.HTTP_403_FORBIDDEN
+    return status.HTTP_400_BAD_REQUEST
+
+
+def _utc_now() -> datetime:
+    """Return the current UTC timestamp."""
+
+    return datetime.now(timezone.utc)

reticulum_telemetry_hub/northbound/models.py

@@ -0,0 +1,213 @@
+"""Pydantic models for the northbound API."""
+# pylint: disable=import-error
+
+from __future__ import annotations
+
+from typing import Any
+from typing import Dict
+from typing import Optional
+
+from pydantic import AliasChoices
+from pydantic import BaseModel
+from pydantic import ConfigDict
+from pydantic import Field
+from pydantic import model_validator
+
+
+def _normalize_aliases(values: object, alias_map: dict[str, tuple[str, ...]]) -> object:
+    """Normalize payload keys using alias hints.
+
+    Args:
+        values (object): Raw payload input.
+        alias_map (dict[str, tuple[str, ...]]): Map of canonical keys to alias keys.
+
+    Returns:
+        object: Normalized payload values.
+    """
+
+    if not isinstance(values, dict):
+        return values
+
+    normalized = dict(values)
+    for field_name, aliases in alias_map.items():
+        if field_name in normalized:
+            continue
+        for alias in aliases:
+            if alias in normalized:
+                normalized[field_name] = normalized[alias]
+                break
+    return normalized
+
+
+class TopicPayload(BaseModel):
+    """Topic payload for create/update requests."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    topic_id: Optional[str] = Field(
+        default=None,
+        validation_alias=AliasChoices("TopicID", "topic_id", "topicId", "id"),
+        serialization_alias="TopicID",
+    )
+    topic_name: Optional[str] = Field(
+        default=None,
+        validation_alias=AliasChoices("TopicName", "topic_name", "topicName", "name"),
+        serialization_alias="TopicName",
+    )
+    topic_path: Optional[str] = Field(
+        default=None,
+        validation_alias=AliasChoices("TopicPath", "topic_path", "topicPath", "path"),
+        serialization_alias="TopicPath",
+    )
+    topic_description: Optional[str] = Field(
+        default=None,
+        validation_alias=AliasChoices("TopicDescription", "topic_description", "topicDescription", "description"),
+        serialization_alias="TopicDescription",
+    )
+
+
+class SubscriberPayload(BaseModel):
+    """Subscriber payload for create/update requests."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    subscriber_id: Optional[str] = Field(
+        default=None,
+        validation_alias=AliasChoices("SubscriberID", "subscriber_id", "subscriberId", "id"),
+        serialization_alias="SubscriberID",
+    )
+    destination: Optional[str] = Field(
+        default=None,
+        validation_alias=AliasChoices("Destination", "destination"),
+        serialization_alias="Destination",
+    )
+    topic_id: Optional[str] = Field(
+        default=None,
+        validation_alias=AliasChoices("TopicID", "topic_id", "topicId"),
+        serialization_alias="TopicID",
+    )
+    reject_tests: Optional[int] = Field(
+        default=None,
+        validation_alias=AliasChoices("RejectTests", "reject_tests", "rejectTests"),
+        serialization_alias="RejectTests",
+    )
+    metadata: Optional[Dict[str, Any]] = Field(
+        default=None,
+        validation_alias=AliasChoices("Metadata", "metadata"),
+        serialization_alias="Metadata",
+    )
+
+
+class SubscribeTopicRequest(BaseModel):
+    """Payload for topic subscription requests."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    topic_id: str = Field(
+        validation_alias=AliasChoices("TopicID", "topic_id", "topicId", "id"),
+        serialization_alias="TopicID",
+    )
+    destination: Optional[str] = Field(
+        default=None,
+        validation_alias=AliasChoices("Destination", "destination"),
+        serialization_alias="Destination",
+    )
+    reject_tests: Optional[int] = Field(
+        default=None,
+        validation_alias=AliasChoices("RejectTests", "reject_tests", "rejectTests"),
+        serialization_alias="RejectTests",
+    )
+    metadata: Optional[Dict[str, Any]] = Field(
+        default=None,
+        validation_alias=AliasChoices("Metadata", "metadata"),
+        serialization_alias="Metadata",
+    )
+
+
+class ConfigRollbackPayload(BaseModel):
+    """Payload for configuration rollbacks."""
+
+    backup_path: Optional[str] = None
+
+
+class MessagePayload(BaseModel):
+    """Payload for sending chat messages into the hub."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    content: str
+    topic_id: Optional[str] = None
+    destination: Optional[str] = None
+
+    @model_validator(mode="before")
+    @classmethod
+    def _normalize_payload(cls, values: object) -> object:
+        """Normalize payload aliases to field names.
+
+        Args:
+            values (object): Raw payload input.
+
+        Returns:
+            object: Normalized payload values.
+        """
+
+        return _normalize_aliases(
+            values,
+            {
+                "content": ("Content",),
+                "topic_id": ("TopicID", "topicId"),
+                "destination": ("Destination",),
+            },
+        )
+
+
+class ChatSendPayload(BaseModel):
+    """Payload for sending chat messages with optional attachments."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    content: Optional[str] = None
+    scope: str
+    topic_id: Optional[str] = None
+    destination: Optional[str] = None
+    file_ids: list[int] = Field(default_factory=list)
+    image_ids: list[int] = Field(default_factory=list)
+
+    @model_validator(mode="before")
+    @classmethod
+    def _normalize_payload(cls, values: object) -> object:
+        """Normalize payload aliases to field names.
+
+        Args:
+            values (object): Raw payload input.
+
+        Returns:
+            object: Normalized payload values.
+        """
+
+        return _normalize_aliases(
+            values,
+            {
+                "content": ("Content",),
+                "scope": ("Scope",),
+                "topic_id": ("TopicID", "topicId"),
+                "destination": ("Destination",),
+                "file_ids": ("FileIDs", "fileIds"),
+                "image_ids": ("ImageIDs", "imageIds"),
+            },
+        )
+
+    @model_validator(mode="after")
+    def _validate_payload(self) -> "ChatSendPayload":
+        """Validate scope-specific requirements."""
+
+        scope = self.scope.lower().strip()
+        if scope not in {"dm", "topic", "broadcast"}:
+            raise ValueError("Scope must be dm, topic, or broadcast")
+        if scope == "dm" and not self.destination:
+            raise ValueError("Destination is required for DM scope")
+        if scope == "topic" and not self.topic_id:
+            raise ValueError("TopicID is required for topic scope")
+        if not (self.content and self.content.strip()) and not (self.file_ids or self.image_ids):
+            raise ValueError("Content or attachments are required")
+        return self

reticulum_telemetry_hub/northbound/routes_chat.py

@@ -0,0 +1,123 @@
+"""Chat routes for the northbound API."""
+# pylint: disable=import-error
+
+from __future__ import annotations
+
+import hashlib
+from typing import Optional
+
+from fastapi import Depends
+from fastapi import FastAPI
+from fastapi import File
+from fastapi import Form
+from fastapi import HTTPException
+from fastapi import Query
+from fastapi import UploadFile
+from fastapi import status
+
+from .models import ChatSendPayload
+from .services import NorthboundServices
+
+
+MAX_ATTACHMENT_BYTES = 8 * 1024 * 1024
+
+
+def register_chat_routes(
+    app: FastAPI,
+    *,
+    services: NorthboundServices,
+    require_protected,
+) -> None:
+    """Register chat routes on the FastAPI app."""
+
+    @app.get("/Chat/Messages", dependencies=[Depends(require_protected)])
+    def list_chat_messages(
+        limit: int = Query(default=200),
+        direction: Optional[str] = Query(default=None),
+        topic_id: Optional[str] = Query(default=None, alias="topic_id"),
+        destination: Optional[str] = Query(default=None),
+        source: Optional[str] = Query(default=None),
+    ) -> list[dict]:
+        """Return persisted chat messages."""
+
+        messages = services.list_chat_messages(
+            limit=limit,
+            direction=direction,
+            topic_id=topic_id,
+            destination=destination,
+            source=source,
+        )
+        return [message.to_dict() for message in messages]
+
+    @app.post("/Chat/Message", dependencies=[Depends(require_protected)])
+    def send_chat_message(payload: ChatSendPayload) -> dict:
+        """Send a chat message with optional attachments."""
+
+        try:
+            attachments = services.resolve_attachments(
+                file_ids=payload.file_ids, image_ids=payload.image_ids
+            )
+        except KeyError as exc:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)) from exc
+        try:
+            message = services.send_chat_message(
+                content=payload.content or "",
+                scope=payload.scope,
+                topic_id=payload.topic_id,
+                destination=payload.destination,
+                attachments=attachments,
+            )
+        except RuntimeError as exc:
+            raise HTTPException(
+                status_code=status.HTTP_503_SERVICE_UNAVAILABLE, detail=str(exc)
+            ) from exc
+        return message.to_dict()
+
+    @app.post("/Chat/Attachment", dependencies=[Depends(require_protected)])
+    async def upload_chat_attachment(
+        category: str = Form(...),
+        file: UploadFile = File(...),
+        sha256: Optional[str] = Form(default=None),
+        topic_id: Optional[str] = Form(default=None),
+    ) -> dict:
+        """Upload a chat attachment to the hub."""
+
+        normalized = category.lower().strip()
+        if normalized not in {"file", "image"}:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Attachment category must be file or image",
+            )
+        content = await file.read()
+        if not content:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Attachment content is empty",
+            )
+        if len(content) > MAX_ATTACHMENT_BYTES:
+            raise HTTPException(
+                status_code=status.HTTP_413_REQUEST_ENTITY_TOO_LARGE,
+                detail="Attachment exceeds size limit",
+            )
+        if normalized == "image":
+            media_type = file.content_type or ""
+            if not media_type.startswith("image/"):
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail="Image attachments must use an image content type",
+                )
+        if sha256:
+            digest = hashlib.sha256(content).hexdigest()
+            if digest.lower() != sha256.lower():
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail="Attachment hash mismatch",
+                )
+        attachment = services.store_uploaded_attachment(
+            content=content,
+            filename=file.filename or "upload.bin",
+            media_type=file.content_type,
+            category=normalized,
+            topic_id=topic_id,
+        )
+        return attachment.to_dict()