topicgate 1.1.0__py3-none-any.whl

topicgate/__main__.py

@@ -0,0 +1,5 @@
+from topicgate.mcp.server import run
+
+
+if __name__ == "__main__":
+    raise SystemExit(run())

topicgate/app/app_dependencies.py

@@ -0,0 +1,148 @@
+from pathlib import Path
+from uuid import UUID
+
+from topicgate.app.services.service_item import ServiceItem
+from topicgate.app.services.persistence_lifecycle import PersistenceLifecycle
+from topicgate.app.services.broker_profile_service import BrokerProfileService
+from topicgate.app.services.observation_cache_service import ObservationCacheService
+from topicgate.app.services.observation_retention_policy_service import (
+    ObservationRetentionPolicyService,
+)
+from topicgate.app.services.broker_snapshot_service import BrokerSnapshotService
+from topicgate.app.services.control_operation_service import ControlOperationService
+from topicgate.app.services.mcp_setup_service import McpSetupService
+from topicgate.app.broker_runtime_state import BrokerRuntimeState
+from topicgate.app.topicgate_runtime import TopicGateRuntime
+from topicgate.core.interfaces.observer_repository import ObserverRepository
+from topicgate.core.models.broker_profile import BrokerProfile
+from topicgate.core.models.mqtt_observation import MqttObservation
+from topicgate.core.models.topic_message import TopicMessage
+from topicgate.infrastructure.database.database_context import DatabaseContext
+from topicgate.infrastructure.credentials.credential_store import CredentialStore
+from topicgate.infrastructure.credentials.os_credential_store import OSCredentialStore
+from topicgate.infrastructure.repository.observer_mqtt_repository import (
+    ObserverMqttRepository,
+)
+from topicgate.infrastructure.repository.topic_message_repository import (
+    TopicMessageRepository,
+)
+from topicgate.infrastructure.repository.observation_retention_policy_repository import (
+    ObservationRetentionPolicyRepository,
+)
+from topicgate.paths import prepare_database_path, sqlite_url
+
+
+class AppDependencies:
+    """Build application components and expose their lifecycle order."""
+
+    def __init__(
+        self,
+        data_dir: Path | None = None,
+        credential_store: CredentialStore | None = None,
+        *,
+        control_owner: str = "application",
+    ) -> None:
+
+        database_path = prepare_database_path(data_dir)
+        self._db_context = DatabaseContext(sqlite_url(database_path))
+        self.database_path = database_path
+        self.credential_store = (
+            OSCredentialStore() if credential_store is None else credential_store
+        )
+
+        self.broker_runtime_state = BrokerRuntimeState()
+        self.observation_retention_policy = ObservationRetentionPolicyRepository(
+            self._db_context
+        )
+        self.retention_policy = ObservationRetentionPolicyService(
+            self.observation_retention_policy
+        )
+        self.topic_messages = TopicMessageRepository(
+            self._db_context,
+            policy_provider=self.retention_policy.get,
+        )
+        self.observation_cache = ObservationCacheService(
+            self.topic_messages,
+            self.retention_policy,
+        )
+        self.control_operations = ControlOperationService(
+            self._db_context,
+            control_owner,
+        )
+        self.persistence = PersistenceLifecycle(
+            self.topic_messages,
+            self._db_context,
+        )
+        self.broker_profiles = BrokerProfileService(
+            self._db_context,
+            credential_store=self.credential_store,
+            runtime_state=self.broker_runtime_state,
+            topic_messages=self.topic_messages,
+        )
+        profile = self.broker_profiles.get_profile()
+
+        self.broker_runtime_state.repositories.update(
+            {
+                item.id: self._create_observer_repository(item)
+                for item in self.broker_profiles.get_all_profiles()
+            }
+        )
+
+        self.runtime = TopicGateRuntime(
+            self.broker_profiles,
+             self.broker_runtime_state.repositories,
+            profile.id,
+            self._create_observer_repository,
+            self.observation_cache,
+            self.control_operations,
+        )
+        self.snapshot_service = BrokerSnapshotService(self.runtime)
+        self.mcp_setup = McpSetupService(
+            self.runtime,
+            self.snapshot_service,
+            self._db_context,
+            self.credential_store,
+            database_path.parent,
+            database_path,
+        )
+
+        self.service_items: tuple[ServiceItem, ...] = (
+            self.persistence,
+            self.runtime,
+        )
+
+    def _create_observer_repository(
+        self,
+        profile: BrokerProfile,
+    ) -> ObserverRepository:
+        return ObserverMqttRepository(
+            profile.config,
+            list(profile.workspace.subscriptions),
+            profile.workspace.model,
+            retention_policy=self.retention_policy.get,
+            observation_sink=lambda observation: self._persist_observation(
+                profile.id,
+                observation,
+            ),
+        )
+
+    def _persist_observation(
+        self,
+        broker_id: UUID,
+        observation: MqttObservation,
+    ) -> None:
+        if observation.observation_id is None:
+            raise ValueError("A live observation requires an observation ID.")
+        self.topic_messages.update_message(
+            TopicMessage(
+                broker_id=broker_id,
+                topic=observation.topic,
+                payload=observation.payload,
+                qos=observation.qos,
+                retain=observation.retain,
+                received_at=observation.received_at,
+                payload_size=observation.payload_size or len(observation.payload),
+                message_count=observation.message_count,
+                observation_id=observation.observation_id,
+            )
+        )

topicgate/app/broker_runtime_state.py

@@ -0,0 +1,43 @@
+from uuid import UUID
+
+from topicgate.core.interfaces.observer_repository import ObserverRepository
+from topicgate.core.models.observer_model import ObserverModel
+from topicgate.core.models.broker_profile import BrokerProfile
+
+
+class BrokerRuntimeState:
+    """In-memory observer models and repositories, keyed by broker identity."""
+
+    def __init__(self) -> None:
+        self._models: dict[UUID, ObserverModel] = {}
+        self._repositories: dict[UUID, ObserverRepository] = {}
+        self._profile_handles: dict[UUID, BrokerProfile] = {}
+        self._config_ids: dict[UUID, int | None] = {}
+
+    def get_model(self, broker_id: UUID) -> ObserverModel | None:
+        return self._models.get(broker_id)
+
+    def set_model(self, broker_id: UUID, model: ObserverModel) -> None:
+        self._models[broker_id] = model
+
+    def remove(self, broker_id: UUID) -> None:
+        self._models.pop(broker_id, None)
+        self._repositories.pop(broker_id, None)
+        self._profile_handles.pop(broker_id, None)
+        self._config_ids.pop(broker_id, None)
+
+    def get_config_id(self, broker_id: UUID, persisted_id: int | None) -> int | None:
+        return self._config_ids.get(broker_id, persisted_id)
+
+    def set_config_id(self, broker_id: UUID, config_id: int | None) -> None:
+        self._config_ids[broker_id] = config_id
+
+    def get_profile_handle(self, broker_id: UUID) -> BrokerProfile | None:
+        return self._profile_handles.get(broker_id)
+
+    def set_profile_handle(self, profile: BrokerProfile) -> None:
+        self._profile_handles[profile.id] = profile
+
+    @property
+    def repositories(self) -> dict[UUID, ObserverRepository]:
+        return self._repositories

topicgate/app/models/__init__.py

@@ -0,0 +1 @@
+"""Application-level read models."""

topicgate/app/models/broker_snapshot.py

@@ -0,0 +1,107 @@
+from dataclasses import dataclass
+from datetime import datetime
+from enum import StrEnum
+from uuid import UUID
+
+from topicgate.core.models.mqtt_observation import ObservationSource
+
+
+class SnapshotPayloadEncoding(StrEnum):
+    UTF8 = "utf-8"
+    BASE64 = "base64"
+
+
+class SnapshotTopicStatus(StrEnum):
+    LIVE = "live"
+    CACHED = "cached"
+    STALE = "stale"
+
+
+class SnapshotLimitation(StrEnum):
+    CURRENT_STATE_ONLY = "current_state_only"
+    RETAINED_DELIVERY_UNCONFIRMED = "retained_delivery_unconfirmed"
+    BROKER_DISCONNECTED = "broker_disconnected"
+    OBSERVATION_NOT_STARTED = "observation_not_started"
+    STORED_STATE_PREDATES_OBSERVATION = "stored_state_predates_observation"
+    DROPPED_MESSAGES = "dropped_messages"
+    STALE_STATES_OMITTED = "stale_states_omitted"
+    RESULT_LIMIT_REACHED = "result_limit_reached"
+    PAYLOAD_TRUNCATED = "payload_truncated"
+
+
+@dataclass(frozen=True)
+class SnapshotBrokerIdentity:
+    id: UUID
+    name: str
+
+
+@dataclass(frozen=True)
+class SnapshotPayload:
+    encoding: SnapshotPayloadEncoding
+    value: str
+    original_size: int
+    available_size: int
+    rendered_size: int
+    ingestion_truncated: bool
+    rendering_truncated: bool
+    truncated: bool
+
+
+@dataclass(frozen=True)
+class SnapshotTopicState:
+    topic: str
+    payload: SnapshotPayload
+    qos: int
+    retain: bool
+    received_at: datetime
+    age_seconds: float
+    message_count: int
+    source: ObservationSource
+    status: SnapshotTopicStatus
+
+
+@dataclass(frozen=True)
+class SnapshotFreshness:
+    max_age_seconds: float | None
+    stale_count: int
+
+
+@dataclass(frozen=True)
+class SnapshotResultLimit:
+    limit: int
+    total: int
+    returned: int
+    omitted: int
+    omitted_as_stale: int
+    omitted_by_limit: int
+    truncated: bool
+
+
+@dataclass(frozen=True)
+class SnapshotSettling:
+    requested_seconds: float
+    maximum_seconds: float
+    actual_seconds: float
+
+
+@dataclass(frozen=True)
+class SnapshotCompleteness:
+    is_complete: bool
+    limitations: tuple[SnapshotLimitation, ...]
+
+
+@dataclass(frozen=True)
+class BrokerSnapshot:
+    broker: SnapshotBrokerIdentity
+    connection_status: str
+    captured_at: datetime
+    connected_at: datetime | None
+    observation_started_at: datetime | None
+    observed_for_seconds: float | None
+    topic_filter: str
+    topics: tuple[SnapshotTopicState, ...]
+    dropped_message_count: int
+    freshness: SnapshotFreshness
+    results: SnapshotResultLimit
+    settling: SnapshotSettling
+    completeness: SnapshotCompleteness

topicgate/app/models/mcp_setup.py

@@ -0,0 +1,20 @@
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class McpPreflightCheck:
+    name: str
+    status: str
+    detail: str
+
+
+@dataclass(frozen=True)
+class McpSetupInformation:
+    version: str
+    executable_path: Path
+    data_path: Path
+    database_path: Path
+    command: str
+    command_prefix_arguments: tuple[str, ...]
+

topicgate/app/services/broker_profile_service.py

@@ -0,0 +1,245 @@
+from dataclasses import replace
+from uuid import UUID
+
+from topicgate.app.broker_runtime_state import BrokerRuntimeState
+from topicgate.core.config.app_config import AppConfig
+from topicgate.core.config.mqtt_config import MqttConfig
+from topicgate.core.models.broker_profile import BrokerProfile
+from topicgate.core.models.observer_model import ObserverModel
+from topicgate.core.models.mqtt_observation import (
+    MqttObservation,
+    ObservationSource,
+)
+from topicgate.core.interfaces.topic_message_store import TopicMessageStore
+from topicgate.core.models.observer_workspace import ObserverWorkspace
+from topicgate.infrastructure.credentials.credential_store import CredentialStore
+from topicgate.infrastructure.database.database_context import DatabaseContext
+from topicgate.infrastructure.repository.broker_config_repository import (
+    BrokerConfigRepository,
+)
+from topicgate.infrastructure.repository.broker_repository import BrokerRepository
+from topicgate.infrastructure.repository.subscription_repository import (
+    SubscriptionRepository,
+)
+from topicgate.processors.observer_model_processor import ObserverModelProcessor
+
+
+class BrokerProfileService:
+    """Compose broker identity, persisted config, credentials, and runtime state."""
+
+    def __init__(
+        self,
+        settings: AppConfig | DatabaseContext | None = None,
+        db: DatabaseContext | AppConfig | None = None,
+        *,
+        credential_store: CredentialStore,
+        runtime_state: BrokerRuntimeState | None = None,
+        topic_messages: TopicMessageStore | None = None,
+    ) -> None:
+        if isinstance(settings, DatabaseContext):
+            self._db = settings
+            supplied_settings = db if isinstance(db, AppConfig) else None
+        else:
+            self._db = db if isinstance(db, DatabaseContext) else DatabaseContext(
+                "sqlite:///:memory:"
+            )
+            supplied_settings = settings
+        self._credentials = credential_store
+        self._runtime_state = runtime_state or BrokerRuntimeState()
+        self.brokers = BrokerRepository(self._db)
+        self.configs = BrokerConfigRepository(self._db)
+        self.subscriptions = SubscriptionRepository(self._db)
+        self._topic_messages = topic_messages
+        self._settings_id = supplied_settings.id if supplied_settings else None
+
+        identities = self.brokers.list_profiles()
+        if not identities:
+            initial = supplied_settings.mqtt if supplied_settings else MqttConfig(
+                "localhost", 1883, "", ""
+            )
+            self._create_seed_profile("Default", initial, is_active=True)
+            self._create_seed_profile(
+                "Local MQTT", MqttConfig("localhost", 1883, "", "")
+            )
+        elif supplied_settings is not None:
+            active_id = self.brokers.get_profile().id
+            if self._credentials.get_password(active_id) is None:
+                self._store_password(active_id, supplied_settings.mqtt.password)
+
+        self._settings = (
+            supplied_settings
+            if supplied_settings is not None and not identities
+            else AppConfig(self.get_profile().config, id=self._settings_id)
+        )
+
+    def get_profile(self, profile_id: UUID | None = None) -> BrokerProfile:
+        identity = self.brokers.get_profile(profile_id)
+        config = self.configs.get(identity.id)
+        config = replace(
+            config,
+            password=self._credentials.get_password(identity.id) or "",
+            id=self._runtime_state.get_config_id(identity.id, config.id),
+        )
+        subscriptions = self.subscriptions.list_for_workspace(identity.workspace_id)
+        model = self._runtime_state.get_model(identity.id)
+        if model is None:
+            model = self._hydrate_observer_model(identity.id, subscriptions)
+        workspace = ObserverWorkspace(
+            id=identity.workspace_id,
+            profile_id=identity.id,
+            model=model,
+            subscriptions=subscriptions,
+        )
+        return BrokerProfile(
+            id=identity.id,
+            name=identity.name,
+            config=config,
+            workspace_id=identity.workspace_id,
+            workspace=workspace,
+        )
+
+    def get_all_profiles(self) -> tuple[BrokerProfile, ...]:
+        return tuple(self.get_profile(item.id) for item in self.brokers.list_profiles())
+
+    def create_profile(self, name: str, config: MqttConfig) -> BrokerProfile:
+        name = self.brokers.validate_profile_name(name)
+        with self._db.transaction() as session:
+            config_id = self.configs.create(config, session=session)
+            identity = self.brokers.create_profile(
+                name, config_id, session=session
+            )
+        self._store_password(identity.id, config.password)
+        self._runtime_state.set_config_id(identity.id, config.id)
+        profile = self.get_profile(identity.id)
+        self._runtime_state.set_profile_handle(profile)
+        self.save()
+        return profile
+
+    def update_profile(self, profile: BrokerProfile) -> None:
+        identity = self.brokers.get_profile(profile.id)
+        if (
+            profile.workspace.profile_id != profile.id
+            or profile.workspace_id != identity.workspace_id
+            or profile.workspace.id != identity.workspace_id
+        ):
+            raise ValueError("The workspace must belong to the broker profile.")
+        self.brokers.update_profile_name(profile.id, profile.name)
+        self.configs.update(profile.id, profile.config)
+        self.subscriptions.replace_all(
+            identity.workspace_id, profile.workspace.subscriptions
+        )
+        self._store_password(profile.id, profile.config.password)
+        self._runtime_state.set_config_id(profile.id, profile.config.id)
+        self._runtime_state.set_profile_handle(profile)
+        if identity.is_active:
+            self._settings = AppConfig(profile.config, id=self._settings_id)
+        self.save()
+
+    def delete_profile(self, profile_id: UUID) -> BrokerProfile:
+        profile = self._runtime_state.get_profile_handle(profile_id) or self.get_profile(
+            profile_id
+        )
+        self.brokers.delete_profile(profile_id)
+        self._delete_password(profile_id)
+        self._runtime_state.remove(profile_id)
+        self.save()
+        return profile
+
+    def select_active_profile(self, profile_id: UUID) -> None:
+        self.brokers.select_active_profile(profile_id)
+        self._settings = AppConfig(self.get_profile().config, id=self._settings_id)
+
+    def activate_profile(
+        self, profile_id: UUID, config: MqttConfig | None = None
+    ) -> None:
+        if config is not None:
+            self.configs.update(profile_id, config)
+            self._store_password(profile_id, config.password)
+            self._runtime_state.set_config_id(profile_id, config.id)
+        self.select_active_profile(profile_id)
+
+    def replace_subscriptions(self, workspace_id: UUID, subscriptions) -> None:
+        self.subscriptions.replace_all(workspace_id, tuple(subscriptions))
+
+    def update_observer_workspace(self, workspace: ObserverWorkspace) -> None:
+        self.replace_subscriptions(workspace.id, workspace.subscriptions)
+
+    def update_observer_model(self, model: ObserverModel) -> None:
+        self._runtime_state.set_model(self.brokers.get_profile().id, model)
+        self.save()
+
+    def get_observer_model(self) -> ObserverModel:
+        return self.get_profile().workspace.model
+
+    def get_observer_workspace(self) -> ObserverWorkspace:
+        return self.get_profile().workspace
+
+    def get_mqtt(self) -> MqttConfig:
+        return self.get_profile().config
+
+    def update_mqtt(self, config: MqttConfig) -> None:
+        profile_id = self.brokers.get_profile().id
+        self.configs.update(profile_id, config)
+        self._store_password(profile_id, config.password)
+        self._runtime_state.set_config_id(profile_id, config.id)
+        self._settings = AppConfig(config, id=self._settings_id)
+        self.save()
+
+    def get(self) -> AppConfig:
+        current = self.get_mqtt()
+        if self._settings.mqtt != current:
+            self._settings = AppConfig(current, id=self._settings_id)
+        return self._settings
+
+    def update(self, settings: AppConfig) -> None:
+        self.update_mqtt(settings.mqtt)
+        self._settings = settings
+
+    def save(self) -> None:
+        """Compatibility hook; repositories commit each mutation."""
+
+    def _create_seed_profile(
+        self, name: str, config: MqttConfig, *, is_active: bool = False
+    ) -> None:
+        with self._db.transaction() as session:
+            config_id = self.configs.create(config, session=session)
+            identity = self.brokers.create_profile(
+                name, config_id, is_active=is_active, session=session
+            )
+        self._store_password(identity.id, config.password)
+        self._runtime_state.set_config_id(identity.id, config.id)
+
+    def _hydrate_observer_model(self, broker_id: UUID, subscriptions) -> ObserverModel:
+        model = ObserverModelProcessor.add_topics(
+            ObserverModel(root_stats=[]),
+            (item.topic_filter for item in subscriptions),
+        )
+        if self._topic_messages is None:
+            return model
+        for message in self._topic_messages.get_latest_messages(broker_id):
+            node = ObserverModelProcessor.find_or_create_node(model, message.topic)
+            state = MqttObservation(
+                name=node.segment,
+                topic=message.topic,
+                payload=message.payload,
+                qos=message.qos,
+                retain=message.retain,
+                recieved_at=message.received_at,
+                payload_size=message.payload_size,
+                message_count=message.message_count,
+                source=ObservationSource.STORED,
+                observation_id=message.observation_id,
+            )
+            node.state = state
+            model.topic_states[message.topic] = state
+        return model
+
+    def _store_password(self, profile_id: UUID, password: str) -> None:
+        if password:
+            self._credentials.set_password(profile_id, password)
+        else:
+            self._delete_password(profile_id)
+
+    def _delete_password(self, profile_id: UUID) -> None:
+        if self._credentials.get_password(profile_id) is not None:
+            self._credentials.delete_password(profile_id)

topicgate/app/services/broker_resolver.py

@@ -0,0 +1,58 @@
+from uuid import UUID
+
+from topicgate.app.topicgate_runtime import TopicGateRuntime
+from topicgate.core.models.broker_summary import BrokerSummary
+
+
+class BrokerNotFoundError(LookupError):
+    """Raised when a broker selector does not match a configured broker."""
+
+
+class AmbiguousBrokerError(ValueError):
+    """Raised when a broker name matches more than one configured broker."""
+
+
+class BrokerResolver:
+    """Resolve broker summaries by UUID or case-insensitive profile name."""
+
+    def __init__(self, runtime: TopicGateRuntime) -> None:
+        self._runtime = runtime
+
+    def resolve(self, selector: UUID | str) -> BrokerSummary:
+        brokers = self._runtime.list_brokers()
+        broker_id = self._parse_uuid(selector)
+        if broker_id is not None:
+            match = next((item for item in brokers if item.id == broker_id), None)
+            if match is None:
+                raise BrokerNotFoundError(f"Unknown broker UUID: {broker_id}")
+            return match
+
+        name = str(selector).strip()
+        matches = tuple(
+            item for item in brokers if item.name.casefold() == name.casefold()
+        )
+        if not matches:
+            raise BrokerNotFoundError(f"Unknown broker name: {name!r}")
+        if len(matches) > 1:
+            matching_ids = ", ".join(str(item.id) for item in matches)
+            raise AmbiguousBrokerError(
+                f"Broker name {name!r} is ambiguous; matching UUIDs: {matching_ids}"
+            )
+        return matches[0]
+
+    def resolve_or_active(
+        self,
+        selector: UUID | str | None,
+    ) -> BrokerSummary:
+        if selector is None:
+            return self._runtime.active_broker
+        return self.resolve(selector)
+
+    @staticmethod
+    def _parse_uuid(selector: UUID | str) -> UUID | None:
+        if isinstance(selector, UUID):
+            return selector
+        try:
+            return UUID(selector.strip())
+        except (AttributeError, ValueError):
+            return None