lifx-emulator 4.0.0__py3-none-any.whl → 4.2.0__py3-none-any.whl

lifx_emulator_app/api/services/event_bridge.py

@@ -0,0 +1,234 @@
+"""Event bridge for connecting core library callbacks to WebSocket broadcasts.
+
+This module provides functions to wire up synchronous device lifecycle callbacks
+to asynchronous WebSocket broadcasts, bridging the gap between the core library
+(which has no async dependencies) and the FastAPI application layer.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import TYPE_CHECKING
+
+from lifx_emulator.devices import PacketEvent
+
+if TYPE_CHECKING:
+    from lifx_emulator.devices import (
+        ActivityLogger,
+        ActivityObserver,
+        EmulatedLifxDevice,
+        IDeviceManager,
+    )
+    from lifx_emulator.server import EmulatedLifxServer
+
+    from lifx_emulator_app.api.services.websocket_manager import WebSocketManager
+
+logger = logging.getLogger(__name__)
+
+
+def _schedule_async(coro) -> None:
+    """Schedule an async coroutine from a sync context.
+
+    Args:
+        coro: The coroutine to schedule
+    """
+    try:
+        loop = asyncio.get_running_loop()
+        loop.create_task(coro)
+    except RuntimeError:
+        logger.warning("No running event loop to schedule async task")
+
+
+def wire_device_events(
+    device_manager: IDeviceManager, ws_manager: WebSocketManager
+) -> None:
+    """Wire device lifecycle callbacks to WebSocket broadcasts.
+
+    This sets up the DeviceManager callbacks to broadcast events to
+    connected WebSocket clients when devices are added or removed.
+
+    Args:
+        device_manager: The DeviceManager to wire callbacks to (must be
+            a DeviceManager instance that supports callbacks)
+        ws_manager: The WebSocketManager to broadcast events through
+    """
+    from lifx_emulator.devices import DeviceManager
+
+    from lifx_emulator_app.api.mappers.device_mapper import DeviceMapper
+
+    # Only DeviceManager (not all IDeviceManager implementations) supports callbacks
+    if not isinstance(device_manager, DeviceManager):
+        logger.warning(
+            "Device manager is not a DeviceManager instance, skipping event wiring"
+        )
+        return
+
+    def on_device_added(device: EmulatedLifxDevice) -> None:
+        """Callback invoked when a device is added."""
+        device_info = DeviceMapper.to_device_info(device)
+        _schedule_async(ws_manager.broadcast_device_added(device_info.model_dump()))
+        logger.debug("Scheduled device_added broadcast for %s", device.state.serial)
+
+    def on_device_removed(serial: str) -> None:
+        """Callback invoked when a device is removed."""
+        _schedule_async(ws_manager.broadcast_device_removed(serial))
+        logger.debug("Scheduled device_removed broadcast for %s", serial)
+
+    device_manager.on_device_added = on_device_added
+    device_manager.on_device_removed = on_device_removed
+
+    logger.info("Device event callbacks wired to WebSocket manager")
+
+
+class WebSocketActivityObserver:
+    """ActivityObserver implementation that broadcasts events via WebSocket.
+
+    This observer bridges the synchronous ActivityObserver protocol to
+    asynchronous WebSocket broadcasts, allowing real-time activity updates
+    to connected clients.
+
+    Also wraps an optional inner observer (typically ActivityLogger) to
+    maintain the activity log while adding WebSocket broadcasting.
+    """
+
+    def __init__(
+        self,
+        ws_manager: WebSocketManager,
+        inner_observer: ActivityObserver | None = None,
+    ) -> None:
+        """Initialize the WebSocket activity observer.
+
+        Args:
+            ws_manager: The WebSocketManager to broadcast events through
+            inner_observer: Optional inner observer to delegate to (for logging).
+                If it has get_recent_activity(), that will be used.
+        """
+        from lifx_emulator.devices import ActivityLogger
+
+        self._ws_manager = ws_manager
+        # Use provided observer or create a new ActivityLogger
+        self._inner: ActivityLogger | ActivityObserver = (
+            inner_observer
+            if inner_observer is not None
+            else ActivityLogger(max_events=100)
+        )
+
+    def on_packet_received(self, event: PacketEvent) -> None:
+        """Handle packet received event.
+
+        Args:
+            event: The packet event with direction='rx'
+        """
+        # Delegate to inner observer for logging
+        self._inner.on_packet_received(event)
+
+        # Broadcast to WebSocket clients
+        _schedule_async(
+            self._ws_manager.broadcast_activity(
+                {
+                    "timestamp": event.timestamp,
+                    "direction": "rx",
+                    "packet_type": event.packet_type,
+                    "packet_name": event.packet_name,
+                    "target": event.target,
+                    "addr": event.addr,
+                }
+            )
+        )
+
+    def on_packet_sent(self, event: PacketEvent) -> None:
+        """Handle packet sent event.
+
+        Args:
+            event: The packet event with direction='tx'
+        """
+        # Delegate to inner observer for logging
+        self._inner.on_packet_sent(event)
+
+        # Broadcast to WebSocket clients
+        _schedule_async(
+            self._ws_manager.broadcast_activity(
+                {
+                    "timestamp": event.timestamp,
+                    "direction": "tx",
+                    "packet_type": event.packet_type,
+                    "packet_name": event.packet_name,
+                    "device": event.device,
+                    "addr": event.addr,
+                }
+            )
+        )
+
+    def get_recent_activity(self) -> list[dict]:
+        """Get recent activity from the inner logger.
+
+        Returns:
+            List of recent activity events, or empty list if inner observer
+            doesn't support activity tracking
+        """
+        get_activity = getattr(self._inner, "get_recent_activity", None)
+        if get_activity is not None:
+            return get_activity()
+        return []
+
+
+class StatsBroadcaster:
+    """Background task that broadcasts server stats periodically.
+
+    Broadcasts stats to WebSocket clients at a configurable interval
+    (default 1 second).
+    """
+
+    def __init__(
+        self,
+        server: EmulatedLifxServer,
+        ws_manager: WebSocketManager,
+        interval: float = 1.0,
+    ) -> None:
+        """Initialize the stats broadcaster.
+
+        Args:
+            server: The LIFX emulator server to get stats from
+            ws_manager: The WebSocketManager to broadcast through
+            interval: Broadcast interval in seconds (default 1.0)
+        """
+        self._server = server
+        self._ws_manager = ws_manager
+        self._interval = interval
+        self._task: asyncio.Task | None = None
+        self._running = False
+
+    async def _broadcast_loop(self) -> None:
+        """Background loop that broadcasts stats at regular intervals."""
+        while self._running:
+            try:
+                stats = self._server.get_stats()
+                await self._ws_manager.broadcast_stats(stats)
+            except Exception:
+                logger.exception("Error broadcasting stats")
+
+            await asyncio.sleep(self._interval)
+
+    def start(self) -> None:
+        """Start the stats broadcast background task."""
+        if self._task is not None:
+            return
+
+        self._running = True
+        self._task = asyncio.create_task(self._broadcast_loop())
+        logger.info("Stats broadcaster started (interval=%.1fs)", self._interval)
+
+    async def stop(self) -> None:
+        """Stop the stats broadcast background task."""
+        if self._task is None:
+            return
+
+        self._running = False
+        self._task.cancel()
+        try:
+            await self._task
+        except asyncio.CancelledError:
+            pass
+        self._task = None
+        logger.info("Stats broadcaster stopped")

lifx_emulator_app/api/services/scenario_service.py

@@ -0,0 +1,153 @@
+"""Scenario management business logic service.
+
+Separates API handlers from server operations, providing a clean service layer
+for scenario CRUD operations across all scope levels (global, device, type,
+location, group).
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Literal
+
+if TYPE_CHECKING:
+    from lifx_emulator.scenarios import ScenarioConfig
+    from lifx_emulator.server import EmulatedLifxServer
+
+    from lifx_emulator_app.api.services.websocket_manager import WebSocketManager
+
+logger = logging.getLogger(__name__)
+
+Scope = Literal["device", "type", "location", "group"]
+
+_SCOPE_METHODS: dict[Scope, tuple[str, str, str]] = {
+    "device": ("get_device_scenario", "set_device_scenario", "delete_device_scenario"),
+    "type": ("get_type_scenario", "set_type_scenario", "delete_type_scenario"),
+    "location": (
+        "get_location_scenario",
+        "set_location_scenario",
+        "delete_location_scenario",
+    ),
+    "group": ("get_group_scenario", "set_group_scenario", "delete_group_scenario"),
+}
+
+
+class ScenarioNotFoundError(Exception):
+    """Raised when a scenario is not set for the given scope and identifier."""
+
+    def __init__(self, scope: str, identifier: str):
+        super().__init__(f"No scenario set for {scope} {identifier}")
+        self.scope = scope
+        self.identifier = identifier
+
+
+class InvalidDeviceSerialError(Exception):
+    """Raised when a device serial is not a valid 12-character hex string."""
+
+    def __init__(self, serial: str):
+        super().__init__(f"Invalid device serial format: {serial}.")
+        self.serial = serial
+
+
+class ScenarioService:
+    """Service for managing scenario configurations across all scope levels.
+
+    Wraps the HierarchicalScenarioManager and handles cache invalidation,
+    persistence, and WebSocket broadcasts after each mutation.
+    """
+
+    def __init__(
+        self, server: EmulatedLifxServer, ws_manager: WebSocketManager | None = None
+    ):
+        self.server = server
+        self._ws_manager = ws_manager
+
+    async def _persist(self) -> None:
+        """Invalidate device scenario caches and persist to storage."""
+        self.server.invalidate_all_scenario_caches()
+        if self.server.scenario_persistence:
+            await self.server.scenario_persistence.save(self.server.scenario_manager)
+
+    async def _broadcast_change(
+        self, scope: str, identifier: str | None, config: ScenarioConfig | None
+    ) -> None:
+        """Broadcast scenario change event via WebSocket.
+
+        Args:
+            scope: The scope level (global, device, type, location, group)
+            identifier: The scope identifier (serial, type, etc.) or None for global
+            config: The new scenario config, or None if deleted
+        """
+        if self._ws_manager is None:
+            return
+
+        config_dict = config.model_dump() if config is not None else None
+        await self._ws_manager.broadcast_scenario_changed(
+            scope, identifier, config_dict
+        )
+
+    def get_global_scenario(self) -> ScenarioConfig:
+        """Return the global scenario configuration."""
+        return self.server.scenario_manager.get_global_scenario()
+
+    async def set_global_scenario(self, config: ScenarioConfig) -> None:
+        """Set the global scenario and persist."""
+        self.server.scenario_manager.set_global_scenario(config)
+        await self._persist()
+        await self._broadcast_change("global", None, config)
+        logger.info("Set global scenario")
+
+    async def clear_global_scenario(self) -> None:
+        """Clear the global scenario and persist."""
+        self.server.scenario_manager.clear_global_scenario()
+        await self._persist()
+        await self._broadcast_change("global", None, None)
+        logger.info("Cleared global scenario")
+
+    def get_scope_scenario(self, scope: Scope, identifier: str) -> ScenarioConfig:
+        """Return the scenario for a given scope and identifier.
+
+        Raises:
+            ScenarioNotFoundError: If no scenario is set.
+        """
+        getter, _, _ = _SCOPE_METHODS[scope]
+        config = getattr(self.server.scenario_manager, getter)(identifier)
+        if config is None:
+            raise ScenarioNotFoundError(scope, identifier)
+        return config
+
+    async def set_scope_scenario(
+        self, scope: Scope, identifier: str, config: ScenarioConfig
+    ) -> None:
+        """Set a scenario for a given scope and identifier, then persist.
+
+        Raises:
+            InvalidDeviceSerialError: If scope is "device" and the serial
+                is not a valid 12-character hex string.
+        """
+        if scope == "device" and not self._is_valid_serial(identifier):
+            raise InvalidDeviceSerialError(identifier)
+
+        _, setter, _ = _SCOPE_METHODS[scope]
+        getattr(self.server.scenario_manager, setter)(identifier, config)
+        await self._persist()
+        await self._broadcast_change(scope, identifier, config)
+        logger.info("Set %s scenario for %s", scope, identifier)
+
+    async def delete_scope_scenario(self, scope: Scope, identifier: str) -> None:
+        """Delete a scenario for a given scope and identifier, then persist.
+
+        Raises:
+            ScenarioNotFoundError: If no scenario is set.
+        """
+        _, _, deleter = _SCOPE_METHODS[scope]
+        if not getattr(self.server.scenario_manager, deleter)(identifier):
+            raise ScenarioNotFoundError(scope, identifier)
+        await self._persist()
+        await self._broadcast_change(scope, identifier, None)
+        logger.info("Deleted %s scenario for %s", scope, identifier)
+
+    @staticmethod
+    def _is_valid_serial(serial: str) -> bool:
+        """Check that serial is a 12-character hex string."""
+        return len(serial) == 12 and all(c in "0123456789abcdefABCDEF" for c in serial)