lifx-emulator 2.4.0__py3-none-any.whl → 3.0.1__py3-none-any.whl

lifx_emulator/devices/observers.py

@@ -1,139 +0,0 @@
-"""Observer pattern for activity tracking and event notification.
-
-This module implements the Observer pattern to decouple activity tracking
-from the server core, following the Open/Closed Principle.
-"""
-
-from __future__ import annotations
-
-from collections import deque
-from dataclasses import dataclass
-from typing import Any, Protocol
-
-
-@dataclass
-class PacketEvent:
-    """Represents a packet transmission or reception event.
-
-    Attributes:
-        timestamp: Unix timestamp of the event
-        direction: 'rx' for received, 'tx' for transmitted
-        packet_type: Numeric packet type identifier
-        packet_name: Human-readable packet name
-        addr: Network address string (host:port)
-        device: Device serial (for tx events) or None
-        target: Target identifier (for rx events) or None
-    """
-
-    timestamp: float
-    direction: str  # 'rx' or 'tx'
-    packet_type: int
-    packet_name: str
-    addr: str
-    device: str | None = None  # Device serial for tx events
-    target: str | None = None  # Target for rx events
-
-
-class ActivityObserver(Protocol):
-    """Protocol for observers that track packet activity.
-
-    Observers implementing this protocol can be attached to the server
-    to receive notifications of packet events.
-    """
-
-    def on_packet_received(self, event: PacketEvent) -> None:
-        """Called when a packet is received.
-
-        Args:
-            event: PacketEvent with direction='rx'
-        """
-        ...
-
-    def on_packet_sent(self, event: PacketEvent) -> None:
-        """Called when a packet is sent.
-
-        Args:
-            event: PacketEvent with direction='tx'
-        """
-        ...
-
-
-class ActivityLogger:
-    """Observer that logs recent packet activity.
-
-    Maintains a rolling buffer of recent packet events for monitoring
-    and debugging purposes.
-    """
-
-    def __init__(self, max_events: int = 100):
-        """Initialize activity logger.
-
-        Args:
-            max_events: Maximum number of events to retain
-        """
-        self.recent_activity: deque[dict[str, Any]] = deque(maxlen=max_events)
-
-    def on_packet_received(self, event: PacketEvent) -> None:
-        """Record a received packet event.
-
-        Args:
-            event: PacketEvent with direction='rx'
-        """
-        self.recent_activity.append(
-            {
-                "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:
-        """Record a sent packet event.
-
-        Args:
-            event: PacketEvent with direction='tx'
-        """
-        self.recent_activity.append(
-            {
-                "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[str, Any]]:
-        """Get list of recent activity events.
-
-        Returns:
-            List of activity event dictionaries
-        """
-        return list(self.recent_activity)
-
-
-class NullObserver:
-    """No-op observer for when activity tracking is disabled.
-
-    Allows code to unconditionally call notify without checking for None.
-    """
-
-    def on_packet_received(self, event: PacketEvent) -> None:
-        """No-op packet received handler.
-
-        Args:
-            event: PacketEvent (ignored)
-        """
-        pass
-
-    def on_packet_sent(self, event: PacketEvent) -> None:
-        """No-op packet sent handler.
-
-        Args:
-            event: PacketEvent (ignored)
-        """
-        pass

lifx_emulator/devices/persistence.py

@@ -1,308 +0,0 @@
-"""Async persistent storage with debouncing to avoid blocking event loop."""
-
-from __future__ import annotations
-
-import asyncio
-import json
-import logging
-from concurrent.futures import ThreadPoolExecutor
-from pathlib import Path
-from typing import Any
-
-from lifx_emulator.devices.state_serializer import (
-    deserialize_device_state,
-    serialize_device_state,
-)
-
-logger = logging.getLogger(__name__)
-
-DEFAULT_STORAGE_DIR = Path.home() / ".lifx-emulator"
-
-
-class DevicePersistenceAsyncFile:
-    """High-performance async storage with smart debouncing.
-
-    Non-blocking asynchronous I/O for device state persistence.
-    Recommended for production use.
-
-    Features:
-    - Per-device debouncing (coalesces rapid changes to same device)
-    - Batch writes (groups multiple devices in single flush)
-    - Executor-based I/O (no event loop blocking)
-    - Adaptive flush (flushes early if queue size threshold met)
-    - Task lifecycle management (prevents GC of background tasks)
-    """
-
-    def __init__(
-        self,
-        storage_dir: Path | str = DEFAULT_STORAGE_DIR,
-        debounce_ms: int = 100,
-        batch_size_threshold: int = 50,
-    ):
-        """Initialize async storage.
-
-        Args:
-            storage_dir: Directory to store device state files
-            debounce_ms: Milliseconds to wait before flushing (default: 100ms)
-            batch_size_threshold: Flush early if queue exceeds this size (default: 50)
-        """
-        self.storage_dir = Path(storage_dir)
-        self.storage_dir.mkdir(parents=True, exist_ok=True)
-
-        self.debounce_ms = debounce_ms
-        self.batch_size_threshold = batch_size_threshold
-
-        # Per-device pending writes (coalescence)
-        self.pending: dict[str, dict] = {}
-
-        # Single-thread executor (serialized writes)
-        self.executor = ThreadPoolExecutor(max_workers=1, thread_name_prefix="storage")
-
-        # Flush task management
-        self.flush_task: asyncio.Task | None = None
-        self.lock = asyncio.Lock()
-
-        # Background task tracking (prevents GC)
-        self.background_tasks: set[asyncio.Task] = set()
-
-        # Metrics
-        self.writes_queued = 0
-        self.writes_executed = 0
-        self.flushes = 0
-
-        logger.debug("Async storage initialized at %s", self.storage_dir)
-
-    async def save_device_state(self, device_state: Any) -> None:
-        """Queue device state for saving (non-blocking).
-
-        Args:
-            device_state: DeviceState instance to persist
-        """
-        async with self.lock:
-            serial = device_state.serial
-
-            # Coalesce: Latest state wins
-            self.pending[serial] = serialize_device_state(device_state)
-            self.writes_queued += 1
-
-            # Adaptive flush: If queue large, flush early
-            if len(self.pending) >= self.batch_size_threshold:
-                if self.flush_task and not self.flush_task.done():
-                    self.flush_task.cancel()
-
-                # Create flush task and track it
-                task = asyncio.create_task(self._flush())
-                self._track_task(task)
-                self.flush_task = task
-
-            # Otherwise, debounce normally
-            elif not self.flush_task or self.flush_task.done():
-                # Create flush task and track it
-                task = asyncio.create_task(self._flush_after_delay())
-                self._track_task(task)
-                self.flush_task = task
-
-    def _track_task(self, task: asyncio.Task) -> None:
-        """Track background task to prevent garbage collection.
-
-        Args:
-            task: Task to track
-        """
-        self.background_tasks.add(task)
-        task.add_done_callback(self.background_tasks.discard)
-
-    async def _flush_after_delay(self) -> None:
-        """Wait for debounce period, then flush."""
-        try:
-            await asyncio.sleep(self.debounce_ms / 1000.0)
-            await self._flush()
-        except asyncio.CancelledError:
-            # Cancelled by adaptive flush - this is normal
-            logger.debug("Flush cancelled by adaptive flush")
-
-    async def _flush(self) -> None:
-        """Flush all pending writes to disk."""
-        async with self.lock:
-            if not self.pending:
-                return
-
-            writes = list(self.pending.items())
-            self.pending.clear()
-            self.flushes += 1
-
-        # Execute batch write in background thread
-        loop = asyncio.get_running_loop()
-        try:
-            await loop.run_in_executor(self.executor, self._batch_write, writes)
-            self.writes_executed += len(writes)
-            logger.debug("Flushed %s device states to disk", len(writes))
-        except Exception as e:
-            logger.error("Error flushing device states: %s", e, exc_info=True)
-
-    def _batch_write(self, writes: list[tuple[str, dict]]) -> None:
-        """Synchronous batch write (runs in executor).
-
-        Args:
-            writes: List of (serial, state_dict) tuples to write
-        """
-        for serial, state_dict in writes:
-            path = self.storage_dir / f"{serial}.json"
-
-            # Atomic write: write to temp, then rename
-            temp_path = path.with_suffix(".json.tmp")
-            try:
-                with open(temp_path, "w") as f:
-                    json.dump(state_dict, f, indent=2)
-                temp_path.replace(path)  # Atomic on POSIX
-            except Exception as e:
-                logger.error("Failed to write state for device %s: %s", serial, e)
-                if temp_path.exists():
-                    temp_path.unlink()
-
-    def load_device_state(self, serial: str) -> dict[str, Any] | None:
-        """Load device state from disk (synchronous).
-
-        Loading only happens at startup, so blocking is acceptable here.
-        This method can be called from both sync and async contexts.
-
-        Args:
-            serial: Device serial
-
-        Returns:
-            Dictionary with device state, or None if not found
-        """
-        return self._sync_load(serial)
-
-    def _sync_load(self, serial: str) -> dict[str, Any] | None:
-        """Synchronous load (runs in executor)."""
-        device_path = self.storage_dir / f"{serial}.json"
-
-        if not device_path.exists():
-            logger.debug("No saved state found for device %s", serial)
-            return None
-
-        try:
-            with open(device_path) as f:
-                state_dict = json.load(f)
-
-            state_dict = deserialize_device_state(state_dict)
-            logger.info("Loaded saved state for device %s", serial)
-            return state_dict
-
-        except Exception as e:
-            logger.error("Failed to load state for device %s: %s", serial, e)
-            return None
-
-    def delete_device_state(self, serial: str) -> None:
-        """Delete device state from disk (synchronous).
-
-        Deletion is rare and blocking is acceptable.
-
-        Args:
-            serial: Device serial
-        """
-        self._sync_delete(serial)
-
-    def _sync_delete(self, serial: str) -> None:
-        """Synchronous delete (runs in executor).
-
-        Args:
-            serial: Device serial
-        """
-        device_path = self.storage_dir / f"{serial}.json"
-
-        if device_path.exists():
-            try:
-                device_path.unlink()
-                logger.info("Deleted saved state for device %s", serial)
-            except Exception as e:
-                logger.error("Failed to delete state for device %s: %s", serial, e)
-
-    def list_devices(self) -> list[str]:
-        """List all devices with saved state (synchronous, safe to call anytime).
-
-        Returns:
-            List of device serials
-        """
-        serials = []
-        for path in self.storage_dir.glob("*.json"):
-            # Skip temp files
-            if path.suffix == ".tmp":
-                continue
-            serials.append(path.stem)
-        return sorted(serials)
-
-    def delete_all_device_states(self) -> int:
-        """Delete all device states from disk (synchronous).
-
-        Returns:
-            Number of devices deleted
-        """
-        deleted_count = 0
-        for path in self.storage_dir.glob("*.json"):
-            # Skip temp files
-            if path.suffix == ".tmp":
-                continue
-            try:
-                path.unlink()
-                deleted_count += 1
-                logger.info("Deleted saved state for device %s", path.stem)
-            except Exception as e:
-                logger.error("Failed to delete state for device %s: %s", path.stem, e)
-
-        logger.info("Deleted %s device state(s) from persistent storage", deleted_count)
-        return deleted_count
-
-    async def shutdown(self) -> None:
-        """Flush pending writes and shutdown executor.
-
-        This should be called before the application exits to ensure
-        all pending writes are persisted to disk.
-        """
-        logger.info("Shutting down async storage...")
-
-        # Cancel pending flush task
-        if self.flush_task and not self.flush_task.done():
-            self.flush_task.cancel()
-            try:
-                await self.flush_task
-            except asyncio.CancelledError:
-                pass
-
-        # Flush any remaining pending writes
-        await self._flush()
-
-        # Wait for all background tasks to complete
-        if self.background_tasks:
-            logger.debug(
-                f"Waiting for {len(self.background_tasks)} background tasks..."
-            )
-            await asyncio.gather(*self.background_tasks, return_exceptions=True)
-
-        # Shutdown executor (non-blocking to avoid hanging on Windows)
-        loop = asyncio.get_running_loop()
-        await loop.run_in_executor(None, self.executor.shutdown, True)
-
-        logger.info("Async storage shutdown complete")
-
-    def get_stats(self) -> dict[str, Any]:
-        """Get storage performance statistics.
-
-        Returns:
-            Dictionary with performance metrics
-        """
-        coalesce_ratio = (
-            (1 - (self.writes_executed / self.writes_queued))
-            if self.writes_queued > 0
-            else 0
-        )
-
-        return {
-            "writes_queued": self.writes_queued,
-            "writes_executed": self.writes_executed,
-            "pending_writes": len(self.pending),
-            "flushes": self.flushes,
-            "coalesce_ratio": coalesce_ratio,
-            "background_tasks": len(self.background_tasks),
-            "debounce_ms": self.debounce_ms,
-        }

lifx_emulator/devices/state_restorer.py

@@ -1,259 +0,0 @@
-"""State restoration for devices with persistent storage.
-
-This module provides centralized state restoration logic, eliminating
-duplication between factories and device initialization.
-"""
-
-from __future__ import annotations
-
-import logging
-from typing import Any
-
-from lifx_emulator.devices.device import DeviceState
-
-logger = logging.getLogger(__name__)
-
-
-class StateRestorer:
-    """Handles restoration of device state from persistent storage.
-
-    Consolidates state restoration logic that was previously duplicated
-    between factories and device initialization.
-    """
-
-    def __init__(self, storage: Any):
-        """Initialize state restorer.
-
-        Args:
-            storage: Storage instance (DeviceStorage or DevicePersistenceAsyncFile)
-        """
-        self.storage = storage
-
-    def restore_if_available(self, state: DeviceState) -> DeviceState:
-        """Restore saved state if available and compatible.
-
-        Args:
-            state: DeviceState to restore into
-
-        Returns:
-            The same DeviceState instance with restored values
-        """
-        if not self.storage:
-            return state
-
-        saved_state = self.storage.load_device_state(state.serial)
-        if not saved_state:
-            logger.debug("No saved state found for device %s", state.serial)
-            return state
-
-        # Only restore if product matches
-        if saved_state.get("product") != state.product:
-            logger.warning(
-                "Saved state for %s has different product (%s vs %s), skipping restore",
-                state.serial,
-                saved_state.get("product"),
-                state.product,
-            )
-            return state
-
-        logger.info("Restoring saved state for device %s", state.serial)
-
-        # Restore core state
-        self._restore_core_state(state, saved_state)
-
-        # Restore location and group
-        self._restore_location_and_group(state, saved_state)
-
-        # Restore capability-specific state
-        self._restore_capability_state(state, saved_state)
-
-        return state
-
-    def _restore_core_state(
-        self, state: DeviceState, saved_state: dict[str, Any]
-    ) -> None:
-        """Restore core device state fields.
-
-        Args:
-            state: DeviceState to restore into
-            saved_state: Dictionary with saved state values
-        """
-        if "label" in saved_state:
-            state.core.label = saved_state["label"]
-        if "power_level" in saved_state:
-            state.core.power_level = saved_state["power_level"]
-        if "color" in saved_state:
-            state.core.color = saved_state["color"]
-
-    def _restore_location_and_group(
-        self, state: DeviceState, saved_state: dict[str, Any]
-    ) -> None:
-        """Restore location and group metadata.
-
-        Args:
-            state: DeviceState to restore into
-            saved_state: Dictionary with saved state values
-        """
-        # Location
-        if "location_id" in saved_state:
-            state.location.location_id = saved_state["location_id"]
-        if "location_label" in saved_state:
-            state.location.location_label = saved_state["location_label"]
-        if "location_updated_at" in saved_state:
-            state.location.location_updated_at = saved_state["location_updated_at"]
-
-        # Group
-        if "group_id" in saved_state:
-            state.group.group_id = saved_state["group_id"]
-        if "group_label" in saved_state:
-            state.group.group_label = saved_state["group_label"]
-        if "group_updated_at" in saved_state:
-            state.group.group_updated_at = saved_state["group_updated_at"]
-
-    def _restore_capability_state(
-        self, state: DeviceState, saved_state: dict[str, Any]
-    ) -> None:
-        """Restore capability-specific state.
-
-        Args:
-            state: DeviceState to restore into
-            saved_state: Dictionary with saved state values
-        """
-        # Infrared
-        if (
-            state.has_infrared
-            and state.infrared
-            and "infrared_brightness" in saved_state
-        ):
-            state.infrared.infrared_brightness = saved_state["infrared_brightness"]
-
-        # HEV
-        if state.has_hev and state.hev:
-            if "hev_cycle_duration_s" in saved_state:
-                state.hev.hev_cycle_duration_s = saved_state["hev_cycle_duration_s"]
-            if "hev_cycle_remaining_s" in saved_state:
-                state.hev.hev_cycle_remaining_s = saved_state["hev_cycle_remaining_s"]
-            if "hev_cycle_last_power" in saved_state:
-                state.hev.hev_cycle_last_power = saved_state["hev_cycle_last_power"]
-            if "hev_indication" in saved_state:
-                state.hev.hev_indication = saved_state["hev_indication"]
-            if "hev_last_result" in saved_state:
-                state.hev.hev_last_result = saved_state["hev_last_result"]
-
-        # Multizone
-        if state.has_multizone and state.multizone:
-            self._restore_multizone_state(state, saved_state)
-
-        # Matrix (Tile)
-        if state.has_matrix and state.matrix:
-            self._restore_matrix_state(state, saved_state)
-
-    def _restore_multizone_state(
-        self, state: DeviceState, saved_state: dict[str, Any]
-    ) -> None:
-        """Restore multizone-specific state.
-
-        Args:
-            state: DeviceState to restore into
-            saved_state: Dictionary with saved state values
-        """
-        if state.multizone is None:
-            return
-
-        # First restore zone_count from saved state
-        # This ensures the device matches what was previously saved
-        if "zone_count" in saved_state:
-            state.multizone.zone_count = saved_state["zone_count"]
-            logger.debug("Restored zone_count: %s", state.multizone.zone_count)
-
-        # Now restore zone colors if available
-        if "zone_colors" in saved_state:
-            # Verify zone count matches (should match now that we restored it)
-            if len(saved_state["zone_colors"]) == state.multizone.zone_count:
-                state.multizone.zone_colors = saved_state["zone_colors"]
-                logger.debug("Restored %s zone colors", len(saved_state["zone_colors"]))
-            else:
-                logger.warning(
-                    "Zone count mismatch: saved has %s zones, current has %s zones",
-                    len(saved_state["zone_colors"]),
-                    state.multizone.zone_count,
-                )
-
-        if "multizone_effect_type" in saved_state:
-            state.multizone.effect_type = saved_state["multizone_effect_type"]
-        if "multizone_effect_speed" in saved_state:
-            state.multizone.effect_speed = saved_state["multizone_effect_speed"]
-
-    def _restore_matrix_state(
-        self, state: DeviceState, saved_state: dict[str, Any]
-    ) -> None:
-        """Restore matrix (tile) specific state.
-
-        Args:
-            state: DeviceState to restore into
-            saved_state: Dictionary with saved state values
-        """
-        if state.matrix is None:
-            return
-
-        # First restore tile configuration (count, width, height) from saved state
-        # This ensures the device matches what was previously saved
-        if "tile_count" in saved_state:
-            state.matrix.tile_count = saved_state["tile_count"]
-            logger.debug("Restored tile_count: %s", state.matrix.tile_count)
-        if "tile_width" in saved_state:
-            state.matrix.tile_width = saved_state["tile_width"]
-            logger.debug("Restored tile_width: %s", state.matrix.tile_width)
-        if "tile_height" in saved_state:
-            state.matrix.tile_height = saved_state["tile_height"]
-            logger.debug("Restored tile_height: %s", state.matrix.tile_height)
-
-        # Now restore tile devices if available
-        if "tile_devices" in saved_state:
-            saved_tiles = saved_state["tile_devices"]
-            # Verify tile count matches (should match now that we restored it)
-            if len(saved_tiles) == state.matrix.tile_count:
-                # Verify all tiles have matching dimensions
-                if all(
-                    t["width"] == state.matrix.tile_width
-                    and t["height"] == state.matrix.tile_height
-                    for t in saved_tiles
-                ):
-                    state.matrix.tile_devices = saved_tiles
-                    logger.debug("Restored %s tile devices", len(saved_tiles))
-                else:
-                    logger.warning(
-                        "Tile dimensions mismatch, skipping tile restoration"
-                    )
-            else:
-                logger.warning(
-                    f"Tile count mismatch: saved has {len(saved_tiles)} tiles, "
-                    f"current has {state.matrix.tile_count} tiles"
-                )
-
-        if "tile_effect_type" in saved_state:
-            state.matrix.effect_type = saved_state["tile_effect_type"]
-        if "tile_effect_speed" in saved_state:
-            state.matrix.effect_speed = saved_state["tile_effect_speed"]
-        if "tile_effect_palette_count" in saved_state:
-            state.matrix.effect_palette_count = saved_state["tile_effect_palette_count"]
-        if "tile_effect_palette" in saved_state:
-            state.matrix.effect_palette = saved_state["tile_effect_palette"]
-
-
-class NullStateRestorer:
-    """No-op state restorer for devices without persistence.
-
-    Allows code to unconditionally call restore without checking for None.
-    """
-
-    def restore_if_available(self, state: DeviceState) -> DeviceState:
-        """No-op restoration.
-
-        Args:
-            state: DeviceState (returned unchanged)
-
-        Returns:
-            The same DeviceState instance
-        """
-        return state