topicgate 1.1.0__py3-none-any.whl

topicgate/core/interfaces/topic_message_store.py

@@ -0,0 +1,13 @@
+from abc import ABC, abstractmethod
+from uuid import UUID
+
+from topicgate.core.models.topic_message import TopicMessage
+
+
+class TopicMessageStore(ABC):
+    """Read and persist the latest observed state for broker topics."""
+
+    @abstractmethod
+    def get_latest_messages(self, broker_id: UUID) -> tuple[TopicMessage, ...]:
+        """Return the latest stored state for each topic owned by a broker."""
+

topicgate/core/models/broker_profile.py

@@ -0,0 +1,15 @@
+from dataclasses import dataclass
+from uuid import UUID
+
+from topicgate.core.config.mqtt_config import MqttConfig
+from topicgate.core.models.observer_workspace import ObserverWorkspace
+
+
+@dataclass
+class BrokerProfile:
+    id: UUID
+    name: str
+    config: MqttConfig
+
+    workspace_id: UUID
+    workspace: ObserverWorkspace

topicgate/core/models/broker_profile_identity.py

@@ -0,0 +1,14 @@
+from dataclasses import dataclass
+from uuid import UUID
+
+
+@dataclass(frozen=True)
+class BrokerProfileIdentity:
+    """Persisted identity and display metadata for a broker profile."""
+
+    id: UUID
+    name: str
+    position: int
+    is_active: bool
+    workspace_id: UUID
+

topicgate/core/models/broker_summary.py

@@ -0,0 +1,14 @@
+from dataclasses import dataclass
+from uuid import UUID
+
+from topicgate.core.config.mqtt_config import MqttConfig
+
+
+@dataclass(frozen=True)
+class BrokerSummary:
+    """Broker settings safe to expose outside the application runtime."""
+
+    id: UUID
+    name: str
+    config: MqttConfig
+    password_configured: bool

topicgate/core/models/connection_status.py

@@ -0,0 +1,9 @@
+
+from enum import StrEnum
+
+
+class ConnectionStatus(StrEnum):
+    CONNECTING = "connecting"
+    CONNECTED = "connected"
+    RECONNECTING = "reconnecting"
+    DISCONNECTED = "disconnected"

topicgate/core/models/message_filter.py

@@ -0,0 +1,9 @@
+from dataclasses import dataclass, field
+from datetime import datetime
+
+
+@dataclass(frozen=True)
+class MessageFilter:
+    after: datetime | None = None
+    before: datetime | None = None
+    topics: tuple[str, ...] = field(default_factory=tuple)

topicgate/core/models/mqtt_message.py

@@ -0,0 +1,13 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class MqttMessage:
+    topic: str
+    payload: bytes
+    qos: int
+    retain: bool
+    payload_size: int | None = None
+
+    def __post_init__(self) -> None:
+        self.payload_size = max(self.payload_size or 0, len(self.payload))

topicgate/core/models/mqtt_observation.py

@@ -0,0 +1,36 @@
+from dataclasses import dataclass
+from datetime import datetime
+from enum import StrEnum
+from uuid import UUID
+
+
+class ObservationSource(StrEnum):
+    """How an observation entered the current application process."""
+
+    STORED = "stored"
+    LIVE = "live"
+
+
+@dataclass
+class MqttObservation:
+    """The latest MQTT value observed for one topic."""
+
+    name: str
+    topic: str
+    payload: bytes
+    qos: int
+    retain: bool
+    recieved_at: datetime
+    message_count: int = 1
+    payload_size: int | None = None
+    source: ObservationSource = ObservationSource.LIVE
+    observation_id: UUID | None = None
+    connection_id: UUID | None = None
+
+    def __post_init__(self) -> None:
+        self.payload_size = max(self.payload_size or 0, len(self.payload))
+
+    @property
+    def received_at(self) -> datetime:
+        """Return the receive time with its correctly spelled public name."""
+        return self.recieved_at

topicgate/core/models/mqtt_state.py

@@ -0,0 +1,5 @@
+from abc import ABC
+
+
+class MqttState(ABC):
+    """Marker base class for MQTT-backed state models."""

topicgate/core/models/observation_cache_administration.py

@@ -0,0 +1,135 @@
+from dataclasses import dataclass
+from datetime import datetime
+from enum import StrEnum
+from uuid import UUID
+
+from topicgate.core.models.observation_deletion_preview import (
+    ObservationDeletionEntry,
+    ObservationDeletionPreview,
+)
+from topicgate.core.models.observation_retention_policy import (
+    ObservationRetentionPolicy,
+)
+
+
+class RetentionRemovalReason(StrEnum):
+    EXPIRED = "expired"
+    PER_BROKER_ENTRY_LIMIT = "per_broker_entry_limit"
+    PER_BROKER_BYTE_LIMIT = "per_broker_byte_limit"
+    GLOBAL_ENTRY_LIMIT = "global_entry_limit"
+    GLOBAL_BYTE_LIMIT = "global_byte_limit"
+    UNSUBSCRIBED = "unsubscribed"
+
+
+@dataclass(frozen=True)
+class BrokerCacheUsage:
+    broker_id: UUID
+    entry_count: int
+    stored_payload_bytes: int
+    oldest_received_at: datetime | None
+    newest_received_at: datetime | None
+
+
+@dataclass(frozen=True)
+class CacheUsageSummary:
+    brokers: tuple[BrokerCacheUsage, ...]
+
+    @property
+    def entry_count(self) -> int:
+        return sum(item.entry_count for item in self.brokers)
+
+    @property
+    def stored_payload_bytes(self) -> int:
+        return sum(item.stored_payload_bytes for item in self.brokers)
+
+    @property
+    def oldest_received_at(self) -> datetime | None:
+        return min(
+            (
+                item.oldest_received_at
+                for item in self.brokers
+                if item.oldest_received_at is not None
+            ),
+            default=None,
+        )
+
+    @property
+    def newest_received_at(self) -> datetime | None:
+        return max(
+            (
+                item.newest_received_at
+                for item in self.brokers
+                if item.newest_received_at is not None
+            ),
+            default=None,
+        )
+
+
+@dataclass(frozen=True)
+class PersistedTopicSummary:
+    broker_id: UUID
+    topic: str
+    observation_id: UUID
+    stored_payload_bytes: int
+    received_at: datetime
+    is_subscribed: bool
+
+
+@dataclass(frozen=True)
+class RetentionImpactGroup:
+    broker_id: UUID
+    reason: RetentionRemovalReason
+    entries: tuple[ObservationDeletionEntry, ...]
+
+    @property
+    def stored_payload_bytes(self) -> int:
+        return sum(item.stored_payload_bytes for item in self.entries)
+
+
+@dataclass(frozen=True)
+class RetentionPolicyPreview:
+    previous_policy: ObservationRetentionPolicy
+    proposed_policy: ObservationRetentionPolicy
+    deletion: ObservationDeletionPreview
+    groups: tuple[RetentionImpactGroup, ...]
+
+    @property
+    def has_deletions(self) -> bool:
+        return bool(self.deletion.entries)
+
+
+@dataclass(frozen=True)
+class ObservationDeletionResult:
+    previewed_entries: tuple[ObservationDeletionEntry, ...]
+    deleted_entries: tuple[ObservationDeletionEntry, ...]
+    skipped_entries: tuple[ObservationDeletionEntry, ...]
+
+    @property
+    def previewed_count(self) -> int:
+        return len(self.previewed_entries)
+
+    @property
+    def deleted_count(self) -> int:
+        return len(self.deleted_entries)
+
+    @property
+    def skipped_count(self) -> int:
+        return len(self.skipped_entries)
+
+    @property
+    def deleted_bytes(self) -> int:
+        return sum(item.stored_payload_bytes for item in self.deleted_entries)
+
+    @property
+    def skipped_bytes(self) -> int:
+        return sum(item.stored_payload_bytes for item in self.skipped_entries)
+
+    @property
+    def is_partial(self) -> bool:
+        return bool(self.skipped_entries)
+
+
+@dataclass(frozen=True)
+class RetentionPolicyApplicationResult:
+    policy: ObservationRetentionPolicy
+    enforcement: ObservationDeletionResult

topicgate/core/models/observation_deletion_preview.py

@@ -0,0 +1,39 @@
+from dataclasses import dataclass
+from datetime import datetime
+from uuid import UUID
+
+
+@dataclass(frozen=True)
+class ObservationDeletionEntry:
+    broker_id: UUID
+    topic: str
+    observation_id: UUID
+    received_at: datetime
+    stored_payload_bytes: int
+
+
+@dataclass(frozen=True)
+class ObservationDeletionPreview:
+    broker_id: UUID | None
+    entries: tuple[ObservationDeletionEntry, ...]
+    scope: str = "broker"
+
+    @property
+    def broker_ids(self) -> tuple[UUID, ...]:
+        return tuple(sorted({entry.broker_id for entry in self.entries}, key=str))
+
+    @property
+    def total_entries(self) -> int:
+        return len(self.entries)
+
+    @property
+    def stored_payload_bytes(self) -> int:
+        return sum(entry.stored_payload_bytes for entry in self.entries)
+
+    @property
+    def oldest_received_at(self) -> datetime | None:
+        return min((entry.received_at for entry in self.entries), default=None)
+
+    @property
+    def newest_received_at(self) -> datetime | None:
+        return max((entry.received_at for entry in self.entries), default=None)

topicgate/core/models/observation_retention_policy.py

@@ -0,0 +1,65 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ObservationRetentionPolicy:
+    """Application-wide limits for persisted MQTT observations."""
+
+    max_entries_per_broker: int = 1_000
+    max_entries_total: int = 10_000
+    warning_threshold: float = 0.80
+    max_payload_bytes_per_topic: int = 64 * 1024
+    max_payload_bytes_per_broker: int = 8 * 1024 * 1024
+    max_persisted_payload_database_bytes_total: int = 256 * 1024 * 1024
+    max_age_seconds: int | None = None
+    auto_remove_expired: bool = True
+    auto_remove_excess: bool = True
+    auto_remove_unsubscribed: bool = False
+
+    def __post_init__(self) -> None:
+        positive_limits = {
+            "max_entries_per_broker": self.max_entries_per_broker,
+            "max_entries_total": self.max_entries_total,
+            "max_payload_bytes_per_topic": self.max_payload_bytes_per_topic,
+            "max_payload_bytes_per_broker": self.max_payload_bytes_per_broker,
+            "max_persisted_payload_database_bytes_total": (
+                self.max_persisted_payload_database_bytes_total
+            ),
+        }
+        for name, value in positive_limits.items():
+            if type(value) is not int or value <= 0:
+                raise ValueError(f"{name} must be a positive integer.")
+        if (
+            not isinstance(self.warning_threshold, (int, float))
+            or isinstance(self.warning_threshold, bool)
+            or not 0 < self.warning_threshold <= 1
+        ):
+            raise ValueError("warning_threshold must be greater than 0 and at most 1.")
+        if self.max_age_seconds is not None and (
+            type(self.max_age_seconds) is not int or self.max_age_seconds <= 0
+        ):
+            raise ValueError("max_age_seconds must be a positive integer or None.")
+        for name in (
+            "auto_remove_expired",
+            "auto_remove_excess",
+            "auto_remove_unsubscribed",
+        ):
+            if type(getattr(self, name)) is not bool:
+                raise ValueError(f"{name} must be a boolean.")
+        if self.max_entries_per_broker > self.max_entries_total:
+            raise ValueError(
+                "max_entries_per_broker cannot exceed max_entries_total."
+            )
+        if self.max_payload_bytes_per_topic > self.max_payload_bytes_per_broker:
+            raise ValueError(
+                "max_payload_bytes_per_topic cannot exceed "
+                "max_payload_bytes_per_broker."
+            )
+        if (
+            self.max_payload_bytes_per_broker
+            > self.max_persisted_payload_database_bytes_total
+        ):
+            raise ValueError(
+                "max_payload_bytes_per_broker cannot exceed "
+                "max_persisted_payload_database_bytes_total."
+            )

topicgate/core/models/observer_model.py

@@ -0,0 +1,22 @@
+from dataclasses import dataclass, field
+
+from topicgate.core.models.mqtt_observation import MqttObservation
+from topicgate.core.models.mqtt_state import MqttState
+
+
+# Check compatibility for callers migrating from the former presentation name.
+TopicState = MqttObservation
+
+
+@dataclass
+class TopicNode:
+    segment: str
+    state: MqttObservation | None = None
+    children: dict[str, "TopicNode"] = field(default_factory=dict)
+
+
+@dataclass
+class ObserverModel(MqttState):
+    root_stats: list[TopicNode]
+    topic_states: dict[str, MqttObservation] = field(default_factory=dict)
+    configured_topics: set[str] = field(default_factory=set)

topicgate/core/models/observer_workspace.py

@@ -0,0 +1,13 @@
+from dataclasses import dataclass
+from uuid import UUID
+
+from topicgate.core.models.observer_model import ObserverModel
+from topicgate.core.models.subscription import Subscription
+
+
+@dataclass
+class ObserverWorkspace:
+    id: UUID
+    profile_id: UUID
+    model: ObserverModel
+    subscriptions: tuple[Subscription, ...] = ()

topicgate/core/models/subscription.py

@@ -0,0 +1,29 @@
+from dataclasses import dataclass
+
+from topicgate.core.mqtt_topics import validate_topic_size_and_depth
+
+
+@dataclass(frozen=True)
+class Subscription:
+    """Editable MQTT subscription options."""
+
+    topic_filter: str
+    qos: int = 1
+    retain_as_published: bool = False
+    retain_handling: int = 0
+    id: int | None = None
+
+    def __post_init__(self) -> None:
+        segments = validate_topic_size_and_depth(
+            self.topic_filter, "topic filter"
+        )
+        if any("#" in segment and segment != "#" for segment in segments):
+            raise ValueError("# must occupy an entire topic level.")
+        if "#" in segments and segments[-1] != "#":
+            raise ValueError("# is only valid in the final topic level.")
+        if any("+" in segment and segment != "+" for segment in segments):
+            raise ValueError("+ must occupy an entire topic level.")
+        if self.qos not in (0, 1, 2):
+            raise ValueError("QoS must be 0, 1, or 2.")
+        if self.retain_handling not in (0, 1, 2):
+            raise ValueError("Retain handling must be 0, 1, or 2.")

topicgate/core/models/topic_message.py

@@ -0,0 +1,16 @@
+from dataclasses import dataclass
+from datetime import datetime
+from uuid import UUID
+
+
+@dataclass(frozen=True)
+class TopicMessage:
+    broker_id: UUID
+    topic: str
+    payload: bytes
+    qos: int
+    retain: bool
+    received_at: datetime
+    payload_size: int
+    message_count: int
+    observation_id: UUID

topicgate/core/mqtt_topics.py

@@ -0,0 +1,46 @@
+MAX_MQTT_TOPIC_BYTES = 65_535
+MAX_MQTT_TOPIC_LEVELS = 128
+
+
+def validate_topic_size_and_depth(topic: str, kind: str) -> list[str]:
+    if not topic:
+        raise ValueError(f"A {kind} is required.")
+    if "\0" in topic:
+        raise ValueError(f"A {kind} cannot contain a null character.")
+    if len(topic.encode("utf-8")) > MAX_MQTT_TOPIC_BYTES:
+        raise ValueError(
+            f"A {kind} cannot exceed {MAX_MQTT_TOPIC_BYTES:,} UTF-8 bytes."
+        )
+
+    segments = topic.split("/")
+    if len(segments) > MAX_MQTT_TOPIC_LEVELS:
+        raise ValueError(
+            f"A {kind} cannot exceed {MAX_MQTT_TOPIC_LEVELS} levels."
+        )
+    return segments
+
+
+def validate_topic_name(topic: str) -> list[str]:
+    segments = validate_topic_size_and_depth(topic, "topic name")
+    if "+" in topic or "#" in topic:
+        raise ValueError("A topic name cannot contain wildcard characters.")
+    return segments
+
+
+def mqtt_filter_matches(topic_filter: str, topic: str) -> bool:
+    """Return whether an MQTT topic matches a valid wildcard filter."""
+    filter_segments = topic_filter.split("/")
+    topic_segments = topic.split("/")
+
+    if topic.startswith("$") and not topic_filter.startswith("$"):
+        return False
+
+    for index, filter_segment in enumerate(filter_segments):
+        if filter_segment == "#":
+            return index == len(filter_segments) - 1
+        if index >= len(topic_segments):
+            return False
+        if filter_segment != "+" and filter_segment != topic_segments[index]:
+            return False
+
+    return len(filter_segments) == len(topic_segments)

topicgate/core/observer_limits.py

@@ -0,0 +1,8 @@
+MAX_OBSERVED_TOPICS = 1_000
+MAX_OBSERVER_NODES = 10_000
+MAX_RETAINED_PAYLOAD_BYTES = 8 * 1024 * 1024
+TOPIC_TREE_REFRESH_INTERVAL_SECONDS = 0.1
+
+
+class ObserverModelCapacityError(ValueError):
+    pass

topicgate/core/payload_limits.py

@@ -0,0 +1,6 @@
+MAX_STORED_PAYLOAD_BYTES = 64 * 1024
+MAX_RENDERED_PAYLOAD_BYTES = 16 * 1024
+MAX_FORMATTED_JSON_CHARACTERS = 16 * 1024
+MAX_PENDING_MESSAGE_NOTIFICATIONS = 100
+MAX_PENDING_INGRESS_MESSAGES = 100
+MAX_MESSAGE_CALLBACK_BATCH = 25

topicgate/gui/app.py

@@ -0,0 +1,97 @@
+
+
+import asyncio
+import ctypes
+import sys
+
+from PySide6.QtCore import QCoreApplication
+from PySide6.QtGui import QGuiApplication, QIcon
+from PySide6.QtWidgets import QApplication
+from qasync import QEventLoop
+
+from topicgate.app.app_dependencies import AppDependencies
+from topicgate.app.services.service_container import ServiceContainer
+from topicgate.gui.main_window import MainWindow
+from topicgate.gui.main_view_model import MainViewModel
+from topicgate.gui.theme import apply_light_theme
+from topicgate.paths import asset_path
+
+
+class App:
+    def __init__(self, qt_application: QApplication):
+        self._qt_application = qt_application
+        self._dependencies = AppDependencies(control_owner="desktop")
+        self._services = ServiceContainer(self._dependencies)
+        self._view_model = MainViewModel(
+            runtime=self._dependencies.runtime,
+            snapshot_service=self._dependencies.snapshot_service,
+            mcp_setup_service=self._dependencies.mcp_setup,
+        )
+        self._window = MainWindow(self._view_model)
+
+
+    async def run(self) -> int:
+        stopped = asyncio.get_running_loop().create_future()
+
+        def request_shutdown() -> None:
+            if not stopped.done():
+                stopped.set_result(None)
+
+        self._qt_application.lastWindowClosed.connect(request_shutdown)
+        try:
+            try:
+                await self._services.start_services()
+            except ConnectionError as error:
+                self._view_model.log_message.emit(
+                    f"Initial MQTT connection failed: {error}"
+                )
+            await self._view_model.start()
+            self._window.show()
+            await stopped
+            return 0
+        finally:
+            try:
+                try:
+                    cancel_operations = getattr(
+                        self._window,
+                        "cancel_pending_operations",
+                        None,
+                    )
+                    if cancel_operations is not None:
+                        await cancel_operations()
+                finally:
+                    await self._view_model.stop()
+            finally:
+                await self._services.stop_services()
+
+
+def configure_windows_identity() -> None:
+    if sys.platform == "win32":
+        ctypes.windll.shell32.SetCurrentProcessExplicitAppUserModelID(
+            "Dumdart.TopicGate"
+        )
+
+
+def configure_application_identity() -> None:
+    QCoreApplication.setOrganizationName("Dumdart")
+    QCoreApplication.setApplicationName("TopicGate")
+    QGuiApplication.setApplicationDisplayName("TopicGate Desktop")
+
+
+def run() -> int:
+    configure_windows_identity()
+    configure_application_identity()
+
+    qt_application = QApplication(sys.argv)
+    icon = QIcon(asset_path("icon.png"))
+    qt_application.setWindowIcon(icon)
+
+    apply_light_theme(qt_application)
+
+    event_loop = QEventLoop(qt_application)
+    asyncio.set_event_loop(event_loop)
+
+    app = App(qt_application)
+
+    with event_loop:
+        return event_loop.run_until_complete(app.run())

topicgate/gui/broker_state_reader.py

@@ -0,0 +1,29 @@
+from typing import Protocol
+from uuid import UUID
+
+from topicgate.core.config.mqtt_config import MqttConfig
+from topicgate.core.models.broker_profile import BrokerProfile
+
+
+class BrokerStateReader(Protocol):
+    """Provides settings for the active broker profile to the UI."""
+
+    def get_mqtt(self) -> MqttConfig: ...
+
+    def update_mqtt(self, mqtt: MqttConfig) -> None: ...
+
+    def get_profile(self, profile_id: UUID | None = None) -> BrokerProfile: ...
+
+    def get_all_profiles(self) -> tuple[BrokerProfile, ...]: ...
+
+    def create_profile(self, name: str, config: MqttConfig) -> BrokerProfile: ...
+
+    def update_profile(self, profile: BrokerProfile) -> None: ...
+
+    def delete_profile(self, profile_id: UUID) -> BrokerProfile: ...
+
+    def activate_profile(
+        self,
+        profile_id: UUID,
+        mqtt: MqttConfig | None = None,
+    ) -> None: ...