topicgate 1.1.0__py3-none-any.whl

topicgate/app/services/mcp_setup_service.py

@@ -0,0 +1,192 @@
+import importlib.util
+from importlib.metadata import PackageNotFoundError, version
+import json
+from pathlib import Path
+import shutil
+import sys
+
+from sqlalchemy import text
+
+from topicgate.app.models.mcp_setup import McpPreflightCheck, McpSetupInformation
+from topicgate.app.services.broker_snapshot_service import BrokerSnapshotService
+from topicgate.app.topicgate_runtime import TopicGateRuntime
+from topicgate.infrastructure.credentials.credential_store import CredentialStore
+from topicgate.infrastructure.database.database_context import DatabaseContext
+from topicgate.infrastructure.database.migrations import EXPECTED_SCHEMA_REVISION
+
+
+class McpSetupService:
+    """Provide desktop MCP configuration and non-mutating diagnostics."""
+
+    def __init__(
+        self,
+        runtime: TopicGateRuntime,
+        snapshot_service: BrokerSnapshotService,
+        database: DatabaseContext,
+        credential_store: CredentialStore,
+        data_path: Path,
+        database_path: Path,
+    ) -> None:
+        self._runtime = runtime
+        self._snapshots = snapshot_service
+        self._database = database
+        self._credential_store = credential_store
+        executable = shutil.which("topicgate")
+        if executable:
+            command = str(Path(executable).resolve())
+            prefix: tuple[str, ...] = ()
+        else:
+            command = str(Path(sys.executable).resolve())
+            prefix = ("-m", "topicgate")
+        try:
+            installed_version = version("topicgate")
+        except PackageNotFoundError:
+            installed_version = "development"
+        self.information = McpSetupInformation(
+            version=installed_version,
+            executable_path=Path(command),
+            data_path=data_path.resolve(),
+            database_path=database_path.resolve(),
+            command=command,
+            command_prefix_arguments=prefix,
+        )
+
+    def configuration(self, mode: str = "read-only") -> str:
+        if mode not in {"read-only", "control"}:
+            raise ValueError("MCP mode must be read-only or control.")
+        server = {
+            "type": "stdio",
+            "command": self.information.command,
+            "args": [
+                *self.information.command_prefix_arguments,
+                "--mode",
+                mode,
+            ],
+            "env": {"TOPICGATE_DATA_DIR": str(self.information.data_path)},
+        }
+        rendered = json.dumps({"mcpServers": {"topicgate": server}}, indent=2)
+        return rendered.replace(
+            f'        "--mode",\n        "{mode}"',
+            f'        "--mode", "{mode}"',
+        )
+
+    def preflight(self) -> tuple[McpPreflightCheck, ...]:
+        checks = [self._database_check(), self._migration_check()]
+        checks.append(self._credential_check())
+        brokers = self._runtime.list_brokers()
+        checks.append(
+            McpPreflightCheck(
+                "Broker profiles",
+                "pass" if brokers else "fail",
+                f"{len(brokers)} configured profile(s)."
+                if brokers
+                else "Create a broker profile in TopicGate Desktop.",
+            )
+        )
+        usable = sum(
+            len(self._runtime.list_subscriptions(broker.id)) for broker in brokers
+        )
+        checks.append(
+            McpPreflightCheck(
+                "Subscriptions",
+                "pass" if usable else "fail",
+                f"{usable} usable subscription(s)."
+                if usable
+                else "Add at least one subscription in TopicGate Desktop.",
+            )
+        )
+        try:
+            self._snapshots.build_current(self._runtime.active_broker.id)
+        except Exception as error:
+            checks.append(
+                McpPreflightCheck(
+                    "Snapshot service",
+                    "fail",
+                    f"Snapshot unavailable: {error}",
+                )
+            )
+        else:
+            checks.append(
+                McpPreflightCheck(
+                    "Snapshot service",
+                    "pass",
+                    "A local broker snapshot can be built while disconnected.",
+                )
+            )
+        dashboard_available = all(
+            importlib.util.find_spec(module) is not None
+            for module in ("fastmcp", "prefab_ui")
+        )
+        checks.append(
+            McpPreflightCheck(
+                "Dashboard dependencies",
+                "pass" if dashboard_available else "warning",
+                "Optional dashboard dependencies are available."
+                if dashboard_available
+                else "Optional only: install TopicGate with the 'apps' extra for dashboards.",
+            )
+        )
+        return tuple(checks)
+
+    def _database_check(self) -> McpPreflightCheck:
+        try:
+            with self._database.session() as session:
+                session.execute(text("SELECT 1")).scalar_one()
+                journal_mode = session.execute(
+                    text("PRAGMA journal_mode")
+                ).scalar_one()
+                busy_timeout = session.execute(
+                    text("PRAGMA busy_timeout")
+                ).scalar_one()
+        except Exception as error:
+            return McpPreflightCheck(
+                "Database accessibility",
+                "fail",
+                f"Cannot open the TopicGate database: {error}",
+            )
+        if str(journal_mode).lower() != "wal" or int(busy_timeout) < 5000:
+            return McpPreflightCheck(
+                "Database accessibility",
+                "fail",
+                "SQLite coordination is incomplete; restart TopicGate to enable WAL and busy timeout.",
+            )
+        return McpPreflightCheck(
+            "Database accessibility",
+            "pass",
+            "SQLite is accessible with WAL and a 5-second busy timeout.",
+        )
+
+    def _migration_check(self) -> McpPreflightCheck:
+        try:
+            with self._database.session() as session:
+                revision = session.execute(
+                    text("SELECT version_num FROM alembic_version")
+                ).scalar_one()
+        except Exception as error:
+            return McpPreflightCheck(
+                "Database migrations",
+                "fail",
+                f"Migration state cannot be read: {error}",
+            )
+        if revision != EXPECTED_SCHEMA_REVISION:
+            return McpPreflightCheck(
+                "Database migrations",
+                "fail",
+                f"Expected schema {EXPECTED_SCHEMA_REVISION}, found {revision}; restart TopicGate to migrate.",
+            )
+        return McpPreflightCheck(
+            "Database migrations",
+            "pass",
+            f"Schema {revision} is current.",
+        )
+
+    def _credential_check(self) -> McpPreflightCheck:
+        required = ("get_password", "set_password", "delete_password")
+        available = all(callable(getattr(self._credential_store, name, None)) for name in required)
+        return McpPreflightCheck(
+            "Credential store",
+            "pass" if available else "fail",
+            "Operating-system credential store interface is available."
+            if available
+            else "Configure a supported keyring backend before storing broker credentials.",
+        )

topicgate/app/services/observation_cache_service.py

@@ -0,0 +1,256 @@
+from collections.abc import Collection
+from collections import defaultdict
+from datetime import datetime, timedelta, timezone
+from uuid import UUID
+
+from topicgate.core.models.observation_cache_administration import (
+    CacheUsageSummary,
+    ObservationDeletionResult,
+    PersistedTopicSummary,
+    RetentionImpactGroup,
+    RetentionPolicyApplicationResult,
+    RetentionPolicyPreview,
+    RetentionRemovalReason,
+)
+from topicgate.core.models.observation_deletion_preview import (
+    ObservationDeletionEntry,
+)
+from topicgate.core.models.observation_deletion_preview import (
+    ObservationDeletionPreview,
+)
+from topicgate.core.models.observation_retention_policy import (
+    ObservationRetentionPolicy,
+)
+from topicgate.core.models.subscription import Subscription
+from topicgate.core.mqtt_topics import mqtt_filter_matches
+from topicgate.app.services.observation_retention_policy_service import (
+    ObservationRetentionPolicyService,
+)
+from topicgate.infrastructure.repository.topic_message_repository import (
+    TopicMessageRepository,
+)
+
+
+class ObservationCacheService:
+    """Coordinate retention settings and confirmed cache deletion."""
+
+    def __init__(
+        self,
+        messages: TopicMessageRepository,
+        policies: ObservationRetentionPolicyService,
+    ) -> None:
+        self._messages = messages
+        self._policies = policies
+
+    def get_retention_policy(self) -> ObservationRetentionPolicy:
+        return self._policies.get()
+
+    def update_retention_policy(
+        self,
+        policy: ObservationRetentionPolicy,
+    ) -> ObservationRetentionPolicy:
+        persisted = self._policies.update(policy)
+        self._messages.enforce_retention()
+        return persisted
+
+    def preview_clear_cache(
+        self,
+        broker_id: UUID,
+        topics: Collection[str] | None = None,
+    ) -> ObservationDeletionPreview:
+        return self._messages.preview_deletion(broker_id, topics)
+
+    def preview_unsubscribed(
+        self,
+        broker_id: UUID,
+        subscriptions: Collection[Subscription],
+    ) -> ObservationDeletionPreview:
+        preview = self._messages.preview_deletion(broker_id)
+        entries = tuple(
+            entry
+            for entry in preview.entries
+            if not any(
+                mqtt_filter_matches(subscription.topic_filter, entry.topic)
+                for subscription in subscriptions
+            )
+        )
+        return ObservationDeletionPreview(broker_id, entries)
+
+    def get_cache_usage(self) -> CacheUsageSummary:
+        return self._messages.cache_usage()
+
+    def get_persisted_topics(
+        self,
+        broker_id: UUID,
+        subscriptions: Collection[Subscription],
+    ) -> tuple[PersistedTopicSummary, ...]:
+        preview = self._messages.preview_deletion(broker_id)
+        return tuple(
+            PersistedTopicSummary(
+                broker_id=entry.broker_id,
+                topic=entry.topic,
+                observation_id=entry.observation_id,
+                stored_payload_bytes=entry.stored_payload_bytes,
+                received_at=entry.received_at,
+                is_subscribed=any(
+                    mqtt_filter_matches(item.topic_filter, entry.topic)
+                    for item in subscriptions
+                ),
+            )
+            for entry in preview.entries
+        )
+
+    def preview_all(self) -> ObservationDeletionPreview:
+        return self._messages.preview_all_deletion()
+
+    def confirm_deletion_detailed(
+        self,
+        preview: ObservationDeletionPreview,
+    ) -> ObservationDeletionResult:
+        return self._messages.delete_previewed_detailed(preview)
+
+    def preview_retention_policy(
+        self,
+        policy: ObservationRetentionPolicy,
+        subscriptions: dict[UUID, Collection[Subscription]],
+        *,
+        now: datetime | None = None,
+    ) -> RetentionPolicyPreview:
+        current = self._policies.get()
+        all_entries = self._messages.preview_all_deletion().entries
+        grouped = self._retention_impact(
+            all_entries,
+            policy,
+            subscriptions,
+            now=now or datetime.now(timezone.utc),
+        )
+        entries = tuple(
+            entry
+            for group in grouped
+            for entry in group.entries
+        )
+        return RetentionPolicyPreview(
+            current,
+            policy,
+            ObservationDeletionPreview(None, entries, "policy_enforcement"),
+            grouped,
+        )
+
+    def confirm_retention_policy(
+        self,
+        preview: RetentionPolicyPreview,
+        subscriptions: dict[UUID, Collection[Subscription]],
+    ) -> RetentionPolicyApplicationResult:
+        if self._policies.get() != preview.previous_policy:
+            raise ValueError("The retention policy changed after preview.")
+        current = self.preview_retention_policy(
+            preview.proposed_policy,
+            subscriptions,
+        )
+        if current.deletion.entries != preview.deletion.entries:
+            raise ValueError(
+                "Persisted observations changed after preview; preview again."
+            )
+        enforcement = self.confirm_deletion_detailed(preview.deletion)
+        persisted = self._policies.update(preview.proposed_policy)
+        return RetentionPolicyApplicationResult(persisted, enforcement)
+
+    def confirm_deletion(self, preview: ObservationDeletionPreview) -> int:
+        return self.confirm_deletion_detailed(preview).deleted_count
+
+    def flush_pending_writes(self) -> None:
+        self._messages.flush()
+
+    @classmethod
+    def _retention_impact(
+        cls,
+        entries: tuple[ObservationDeletionEntry, ...],
+        policy: ObservationRetentionPolicy,
+        subscriptions: dict[UUID, Collection[Subscription]],
+        *,
+        now: datetime,
+    ) -> tuple[RetentionImpactGroup, ...]:
+        ordered = sorted(
+            entries,
+            key=lambda item: (
+                cls._utc(item.received_at),
+                str(item.broker_id),
+                item.topic,
+                str(item.observation_id),
+            ),
+        )
+        reasons: dict[UUID, RetentionRemovalReason] = {}
+        if policy.auto_remove_expired and policy.max_age_seconds is not None:
+            cutoff = cls._utc(now) - timedelta(seconds=policy.max_age_seconds)
+            for entry in ordered:
+                if cls._utc(entry.received_at) < cutoff:
+                    reasons[entry.observation_id] = RetentionRemovalReason.EXPIRED
+
+        if policy.auto_remove_unsubscribed:
+            for entry in ordered:
+                if entry.observation_id in reasons:
+                    continue
+                if not any(
+                    mqtt_filter_matches(item.topic_filter, entry.topic)
+                    for item in subscriptions.get(entry.broker_id, ())
+                ):
+                    reasons[entry.observation_id] = (
+                        RetentionRemovalReason.UNSUBSCRIBED
+                    )
+
+        if policy.auto_remove_excess:
+            by_broker: dict[UUID, list[ObservationDeletionEntry]] = defaultdict(list)
+            for entry in ordered:
+                if entry.observation_id not in reasons:
+                    by_broker[entry.broker_id].append(entry)
+            for broker_entries in by_broker.values():
+                stored_bytes = sum(item.stored_payload_bytes for item in broker_entries)
+                while (
+                    len(broker_entries) > policy.max_entries_per_broker
+                    or stored_bytes > policy.max_payload_bytes_per_broker
+                ):
+                    reason = (
+                        RetentionRemovalReason.PER_BROKER_ENTRY_LIMIT
+                        if len(broker_entries) > policy.max_entries_per_broker
+                        else RetentionRemovalReason.PER_BROKER_BYTE_LIMIT
+                    )
+                    removed = broker_entries.pop(0)
+                    stored_bytes -= removed.stored_payload_bytes
+                    reasons[removed.observation_id] = reason
+
+            remaining = [
+                entry for entry in ordered if entry.observation_id not in reasons
+            ]
+            stored_bytes = sum(item.stored_payload_bytes for item in remaining)
+            while (
+                len(remaining) > policy.max_entries_total
+                or stored_bytes
+                > policy.max_persisted_payload_database_bytes_total
+            ):
+                reason = (
+                    RetentionRemovalReason.GLOBAL_ENTRY_LIMIT
+                    if len(remaining) > policy.max_entries_total
+                    else RetentionRemovalReason.GLOBAL_BYTE_LIMIT
+                )
+                removed = remaining.pop(0)
+                stored_bytes -= removed.stored_payload_bytes
+                reasons[removed.observation_id] = reason
+
+        groups: dict[
+            tuple[UUID, RetentionRemovalReason],
+            list[ObservationDeletionEntry],
+        ] = defaultdict(list)
+        for entry in ordered:
+            reason = reasons.get(entry.observation_id)
+            if reason is not None:
+                groups[(entry.broker_id, reason)].append(entry)
+        return tuple(
+            RetentionImpactGroup(broker_id, reason, tuple(items))
+            for (broker_id, reason), items in sorted(
+                groups.items(), key=lambda item: (str(item[0][0]), item[0][1].value)
+            )
+        )
+
+    @staticmethod
+    def _utc(value: datetime) -> datetime:
+        return value.replace(tzinfo=timezone.utc) if value.tzinfo is None else value

topicgate/app/services/observation_retention_policy_service.py

@@ -0,0 +1,33 @@
+from threading import Lock
+
+from topicgate.core.models.observation_retention_policy import (
+    ObservationRetentionPolicy,
+)
+from topicgate.infrastructure.repository.observation_retention_policy_repository import (
+    ObservationRetentionPolicyRepository,
+)
+
+
+class ObservationRetentionPolicyService:
+    """Keep the persisted retention policy available without callback I/O."""
+
+    def __init__(
+        self,
+        repository: ObservationRetentionPolicyRepository,
+    ) -> None:
+        self._repository = repository
+        self._lock = Lock()
+        self._policy = repository.get()
+
+    def get(self) -> ObservationRetentionPolicy:
+        with self._lock:
+            return self._policy
+
+    def update(
+        self,
+        policy: ObservationRetentionPolicy,
+    ) -> ObservationRetentionPolicy:
+        persisted = self._repository.update(policy)
+        with self._lock:
+            self._policy = persisted
+        return persisted

topicgate/app/services/persistence_lifecycle.py

@@ -0,0 +1,25 @@
+from topicgate.app.services.service_item import ServiceItem
+from topicgate.infrastructure.database.database_context import DatabaseContext
+from topicgate.infrastructure.repository.topic_message_repository import (
+    TopicMessageRepository,
+)
+
+
+class PersistenceLifecycle(ServiceItem):
+    """Close application-owned persistence resources after runtime shutdown."""
+
+    def __init__(
+        self,
+        topic_messages: TopicMessageRepository,
+        database: DatabaseContext,
+    ) -> None:
+        self._topic_messages = topic_messages
+        self._database = database
+
+    async def start(self) -> None:
+        """Persistence resources are ready immediately after construction."""
+
+    async def stop(self) -> None:
+        """Drain queued messages before disposing database connections."""
+        self._topic_messages.close()
+        self._database.dispose()

topicgate/app/services/service_container.py

@@ -0,0 +1,20 @@
+from topicgate.app.app_dependencies import AppDependencies
+from topicgate.app.services.service_item import ServiceItem
+
+
+class ServiceContainer:
+    """Starts registered services in order and stops them in reverse order."""
+
+    def __init__(self, dependencies: AppDependencies) -> None:
+        self._service_items: tuple[ServiceItem, ...] = dependencies.service_items
+        self._started_items: list[ServiceItem] = []
+
+    async def start_services(self) -> None:
+        for service_item in self._service_items:
+            await service_item.start()
+            self._started_items.append(service_item)
+
+    async def stop_services(self) -> None:
+        while self._started_items:
+            service_item = self._started_items.pop()
+            await service_item.stop()

topicgate/app/services/service_item.py

@@ -0,0 +1,13 @@
+from abc import ABC, abstractmethod
+
+
+class ServiceItem(ABC):
+    """A component whose lifetime is managed by the application."""
+
+    @abstractmethod
+    async def start(self) -> None:
+        """Start the service."""
+
+    @abstractmethod
+    async def stop(self) -> None:
+        """Stop the service."""