lifx-emulator 1.0.2__py3-none-any.whl → 2.0.0__py3-none-any.whl

lifx_emulator/repositories/storage_backend.py

@@ -0,0 +1,107 @@
+"""Storage backend interfaces for device and scenario persistence.
+
+Provides abstraction for persistent storage operations,
+following the Repository Pattern and Dependency Inversion Principle.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from lifx_emulator.scenarios import HierarchicalScenarioManager
+
+
+@runtime_checkable
+class IDeviceStorageBackend(Protocol):
+    """Interface for device state persistence operations.
+
+    This protocol defines the contract for loading and saving device state.
+    Concrete implementations can use async file I/O, databases,
+    or other storage backends.
+    """
+
+    async def save_device_state(self, device_state: Any) -> None:
+        """Save device state to persistent storage (async).
+
+        Args:
+            device_state: DeviceState instance to persist
+        """
+        raise NotImplementedError
+
+    def load_device_state(self, serial: str) -> dict | None:
+        """Load device state from persistent storage (sync).
+
+        Args:
+            serial: Device serial number (12-character hex string)
+
+        Returns:
+            Dictionary with device state data, or None if not found
+        """
+        raise NotImplementedError
+
+    def delete_device_state(self, serial: str) -> bool:
+        """Delete device state from persistent storage.
+
+        Args:
+            serial: Device serial number
+
+        Returns:
+            True if state was deleted, False if not found
+        """
+        raise NotImplementedError
+
+    def list_devices(self) -> list[str]:
+        """List all device serials with saved state.
+
+        Returns:
+            List of serial numbers
+        """
+        raise NotImplementedError
+
+    def delete_all_device_states(self) -> int:
+        """Delete all device states from persistent storage.
+
+        Returns:
+            Number of device states deleted
+        """
+        raise NotImplementedError
+
+    async def shutdown(self) -> None:
+        """Gracefully shutdown storage backend, flushing pending writes."""
+        raise NotImplementedError
+
+
+@runtime_checkable
+class IScenarioStorageBackend(Protocol):
+    """Interface for scenario configuration persistence operations.
+
+    This protocol defines the contract for loading and saving scenario configurations.
+    Concrete implementations can use async file I/O, databases,
+    or other storage backends.
+    """
+
+    async def load(self) -> HierarchicalScenarioManager:
+        """Load scenario configuration from persistent storage (async).
+
+        Returns:
+            Scenario manager with loaded configuration, or default manager
+            if no saved data
+        """
+        raise NotImplementedError
+
+    async def save(self, manager: HierarchicalScenarioManager) -> None:
+        """Save scenario configuration to persistent storage (async).
+
+        Args:
+            manager: Scenario manager whose configuration should be saved
+        """
+        raise NotImplementedError
+
+    async def delete(self) -> bool:
+        """Delete scenario configuration from persistent storage (async).
+
+        Returns:
+            True if configuration was deleted, False if it didn't exist
+        """
+        raise NotImplementedError

lifx_emulator/scenarios/__init__.py

@@ -0,0 +1,22 @@
+"""Scenario management module for LIFX emulator.
+
+This module contains all scenario-related functionality including:
+- Scenario manager (HierarchicalScenarioManager)
+- Scenario models (ScenarioConfig)
+- Scenario persistence (async file storage)
+- Device type classification (get_device_type)
+"""
+
+from lifx_emulator.scenarios.manager import (
+    HierarchicalScenarioManager,
+    get_device_type,
+)
+from lifx_emulator.scenarios.models import ScenarioConfig
+from lifx_emulator.scenarios.persistence import ScenarioPersistenceAsyncFile
+
+__all__ = [
+    "HierarchicalScenarioManager",
+    "ScenarioConfig",
+    "ScenarioPersistenceAsyncFile",
+    "get_device_type",
+]

lifx_emulator/{scenario_manager.py → scenarios/manager.py}

@@ -5,96 +5,12 @@ test scenarios at multiple scopes with precedence-based resolution.
 """
 
 import random
-from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
 
-if TYPE_CHECKING:
-    from lifx_emulator.device import EmulatedLifxDevice
-
-
-@dataclass
-class ScenarioConfig:
-    """Individual scenario configuration.
-
-    Scenarios define testing behaviors for the emulator, such as:
-    - Dropping specific packet types (no response)
-    - Adding response delays
-    - Sending malformed/corrupted responses
-    - Overriding firmware version
-    """
-
-    drop_packets: dict[int, float] = field(default_factory=dict)
-    """Packet types to drop with drop rates (0.1-1.0).
-
-    Maps packet type to drop rate where:
-    - 1.0 = always drop (100%)
-    - 0.5 = drop 50% of packets
-    - 0.1 = drop 10% of packets
-    Examples: {101: 1.0} (always drop), {102: 0.6} (drop 60% of packets)
-    """
+from lifx_emulator.scenarios.models import ScenarioConfig
 
-    response_delays: dict[int, float] = field(default_factory=dict)
-    """Response delays in seconds by packet type"""
-
-    malformed_packets: list[int] = field(default_factory=list)
-    """Packet types to send truncated/corrupted"""
-
-    invalid_field_values: list[int] = field(default_factory=list)
-    """Packet types to send with all 0xFF bytes"""
-
-    firmware_version: tuple[int, int] | None = None
-    """Override firmware version (major, minor)"""
-
-    partial_responses: list[int] = field(default_factory=list)
-    """Packet types to send incomplete multizone/tile data"""
-
-    send_unhandled: bool = False
-    """Send StateUnhandled for unknown packet types"""
-
-    def to_dict(self) -> dict[str, Any]:
-        """Convert to dictionary for API serialization."""
-        return {
-            "drop_packets": {str(k): v for k, v in self.drop_packets.items()},
-            "response_delays": {str(k): v for k, v in self.response_delays.items()},
-            "malformed_packets": self.malformed_packets,
-            "invalid_field_values": self.invalid_field_values,
-            "firmware_version": self.firmware_version,
-            "partial_responses": self.partial_responses,
-            "send_unhandled": self.send_unhandled,
-        }
-
-    @classmethod
-    def from_dict(cls, data: dict[str, Any]) -> "ScenarioConfig":
-        """Create from dictionary (API input)."""
-        firmware = data.get("firmware_version")
-        if firmware and not isinstance(firmware, tuple):
-            firmware = tuple(firmware)
-
-        # Convert drop_packets keys from string to int
-        drop_packets_input = data.get("drop_packets", {})
-        drop_packets = (
-            {int(k): v for k, v in drop_packets_input.items()}
-            if isinstance(drop_packets_input, dict)
-            else {}
-        )
-
-        # Convert response_delays keys from string to int
-        response_delays_input = data.get("response_delays", {})
-        response_delays = (
-            {int(k): v for k, v in response_delays_input.items()}
-            if isinstance(response_delays_input, dict)
-            else {}
-        )
-
-        return cls(
-            drop_packets=drop_packets,
-            response_delays=response_delays,
-            malformed_packets=data.get("malformed_packets", []),
-            invalid_field_values=data.get("invalid_field_values", []),
-            firmware_version=firmware,
-            partial_responses=data.get("partial_responses", []),
-            send_unhandled=data.get("send_unhandled", False),
-        )
+if TYPE_CHECKING:
+    from lifx_emulator.devices import EmulatedLifxDevice
 
 
 def get_device_type(device: "EmulatedLifxDevice") -> str:
@@ -144,7 +60,9 @@ class HierarchicalScenarioManager:
         self.type_scenarios: dict[str, ScenarioConfig] = {}  # type → config
         self.location_scenarios: dict[str, ScenarioConfig] = {}  # location → config
         self.group_scenarios: dict[str, ScenarioConfig] = {}  # group → config
-        self.global_scenario: ScenarioConfig = ScenarioConfig()
+        self.global_scenario: ScenarioConfig = ScenarioConfig(
+            firmware_version=None, send_unhandled=False
+        )
 
     def set_device_scenario(self, serial: str, config: ScenarioConfig):
         """Set scenario for specific device by serial."""
@@ -184,7 +102,9 @@ class HierarchicalScenarioManager:
 
     def clear_global_scenario(self):
         """Clear global scenario (reset to empty)."""
-        self.global_scenario = ScenarioConfig()
+        self.global_scenario = ScenarioConfig(
+            firmware_version=None, send_unhandled=False
+        )
 
     def get_global_scenario(self) -> ScenarioConfig:
         """Get global scenario configuration."""
@@ -265,7 +185,7 @@ class HierarchicalScenarioManager:
             Merged ScenarioConfig
         """
         # Start with empty config
-        merged = ScenarioConfig()
+        merged = ScenarioConfig(firmware_version=None, send_unhandled=False)
 
         # Layer in each scope (general to specific)
         # Later scopes override or merge with earlier ones

lifx_emulator/scenarios/models.py

@@ -0,0 +1,112 @@
+"""Shared domain models for LIFX emulator.
+
+This module contains Pydantic models that are used across multiple layers
+of the application (domain, API, persistence, etc.).
+"""
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class ScenarioConfig(BaseModel):
+    """Scenario configuration for testing LIFX protocol behavior.
+
+    Scenarios define testing behaviors for the emulator:
+    - Dropping specific packet types (no response)
+    - Adding response delays
+    - Sending malformed/corrupted responses
+    - Overriding firmware version
+    - Sending incomplete data
+
+    This is used by:
+    - HierarchicalScenarioManager (domain layer)
+    - API endpoints (API layer)
+    - ScenarioPersistence (persistence layer)
+    """
+
+    drop_packets: dict[int, float] = Field(
+        default_factory=dict,
+        description="Map of packet types to drop rates (0.0-1.0). "
+        "1.0 = always drop, 0.5 = drop 50%, 0.1 = drop 10%. "
+        "Example: {101: 1.0, 102: 0.6}",
+    )
+    response_delays: dict[int, float] = Field(
+        default_factory=dict,
+        description="Map of packet types to delay in seconds before responding",
+    )
+    malformed_packets: list[int] = Field(
+        default_factory=list,
+        description="List of packet types to send with truncated/corrupted payloads",
+    )
+    invalid_field_values: list[int] = Field(
+        default_factory=list,
+        description="List of packet types to send with all 0xFF bytes in fields",
+    )
+    firmware_version: tuple[int, int] | None = Field(
+        None, description="Override firmware version (major, minor). Example: [3, 70]"
+    )
+    partial_responses: list[int] = Field(
+        default_factory=list,
+        description="List of packet types to send with incomplete data",
+    )
+    send_unhandled: bool = Field(
+        False, description="Send unhandled message responses for unknown packet types"
+    )
+
+    @field_validator("drop_packets", mode="before")
+    @classmethod
+    def convert_drop_packets_keys(cls, v):
+        """Convert string keys to integers for drop_packets.
+
+        This allows JSON serialization where keys must be strings,
+        but internally we use integer packet types.
+        """
+        if isinstance(v, dict):
+            return {int(k): float(val) for k, val in v.items()}
+        return v
+
+    @field_validator("response_delays", mode="before")
+    @classmethod
+    def convert_response_delays_keys(cls, v):
+        """Convert string keys to integers for response_delays.
+
+        This allows JSON serialization where keys must be strings,
+        but internally we use integer packet types.
+        """
+        if isinstance(v, dict):
+            return {int(k): float(val) for k, val in v.items()}
+        return v
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "ScenarioConfig":
+        """Create from dictionary (backward compatibility wrapper).
+
+        Note: This wraps Pydantic's .model_validate() for backward compatibility.
+        The field_validators automatically handle string-to-int key conversion.
+
+        Args:
+            data: Dictionary with scenario configuration
+
+        Returns:
+            ScenarioConfig instance
+        """
+        return cls.model_validate(data)
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary for JSON serialization.
+
+        Note: Pydantic models have .model_dump() which does this,
+        but we keep this method for backward compatibility with
+        existing code that expects string keys for packet types.
+
+        Returns:
+            Dictionary with string keys for drop_packets and response_delays
+        """
+        return {
+            "drop_packets": {str(k): v for k, v in self.drop_packets.items()},
+            "response_delays": {str(k): v for k, v in self.response_delays.items()},
+            "malformed_packets": self.malformed_packets,
+            "invalid_field_values": self.invalid_field_values,
+            "firmware_version": self.firmware_version,
+            "partial_responses": self.partial_responses,
+            "send_unhandled": self.send_unhandled,
+        }

lifx_emulator/{scenario_persistence.py → scenarios/persistence.py}

@@ -1,46 +1,75 @@
-"""Persistence layer for scenario configurations.
+"""Async persistent storage for scenario configurations.
 
-This module provides JSON serialization and deserialization for scenarios,
-allowing them to persist across emulator restarts.
+This module provides async JSON serialization and deserialization for scenarios,
+allowing them to persist across emulator restarts without blocking the 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.scenario_manager import HierarchicalScenarioManager, ScenarioConfig
+from lifx_emulator.scenarios.manager import HierarchicalScenarioManager, ScenarioConfig
 
 logger = logging.getLogger(__name__)
 
+DEFAULT_STORAGE_DIR = Path.home() / ".lifx-emulator"
+
 
-class ScenarioPersistence:
-    """Handles scenario persistence to disk.
+class ScenarioPersistenceAsyncFile:
+    """Async persistent storage for scenario configurations.
 
+    Non-blocking asynchronous I/O for scenario persistence.
     Scenarios are stored in JSON format at ~/.lifx-emulator/scenarios.json
     with separate sections for each scope level.
+
+    Features:
+    - Async I/O operations (no event loop blocking)
+    - Executor-based I/O for file operations
+    - Atomic writes (write to temp file, then rename)
+    - Graceful error handling and recovery
     """
 
-    def __init__(self, storage_path: Path | None = None):
-        """Initialize scenario persistence.
+    def __init__(self, storage_path: Path | str | None = None):
+        """Initialize async scenario persistence.
 
         Args:
             storage_path: Directory to store scenarios.json
                          Defaults to ~/.lifx-emulator
         """
         if storage_path is None:
-            storage_path = Path.home() / ".lifx-emulator"
+            storage_path = DEFAULT_STORAGE_DIR
 
         self.storage_path = Path(storage_path)
         self.scenario_file = self.storage_path / "scenarios.json"
 
-    def load(self) -> HierarchicalScenarioManager:
-        """Load scenarios from disk.
+        # Single-thread executor for serialized I/O operations
+        self.executor = ThreadPoolExecutor(
+            max_workers=1, thread_name_prefix="scenario-io"
+        )
+
+        logger.debug("Async scenario storage initialized at %s", self.storage_path)
+
+    async def load(self) -> HierarchicalScenarioManager:
+        """Load scenarios from disk (async).
 
         Returns:
             HierarchicalScenarioManager with loaded scenarios.
             If file doesn't exist, returns empty manager.
         """
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(self.executor, self._sync_load)
+
+    def _sync_load(self) -> HierarchicalScenarioManager:
+        """Synchronous load operation (runs in executor).
+
+        Returns:
+            HierarchicalScenarioManager with loaded scenarios
+        """
         manager = HierarchicalScenarioManager()
 
         if not self.scenario_file.exists():
@@ -53,12 +82,14 @@ class ScenarioPersistence:
 
             # Load global scenario
             if "global" in data and data["global"]:
-                manager.global_scenario = ScenarioConfig.from_dict(data["global"])
+                manager.global_scenario = ScenarioConfig.model_validate(data["global"])
                 logger.debug("Loaded global scenario")
 
             # Load device-specific scenarios
             for serial, config_data in data.get("devices", {}).items():
-                manager.device_scenarios[serial] = ScenarioConfig.from_dict(config_data)
+                manager.device_scenarios[serial] = ScenarioConfig.model_validate(
+                    config_data
+                )
             if manager.device_scenarios:
                 logger.debug(
                     "Loaded %s device scenario(s)", len(manager.device_scenarios)
@@ -66,7 +97,7 @@ class ScenarioPersistence:
 
             # Load type-specific scenarios
             for device_type, config_data in data.get("types", {}).items():
-                manager.type_scenarios[device_type] = ScenarioConfig.from_dict(
+                manager.type_scenarios[device_type] = ScenarioConfig.model_validate(
                     config_data
                 )
             if manager.type_scenarios:
@@ -74,7 +105,7 @@ class ScenarioPersistence:
 
             # Load location-specific scenarios
             for location, config_data in data.get("locations", {}).items():
-                manager.location_scenarios[location] = ScenarioConfig.from_dict(
+                manager.location_scenarios[location] = ScenarioConfig.model_validate(
                     config_data
                 )
             if manager.location_scenarios:
@@ -84,7 +115,9 @@ class ScenarioPersistence:
 
             # Load group-specific scenarios
             for group, config_data in data.get("groups", {}).items():
-                manager.group_scenarios[group] = ScenarioConfig.from_dict(config_data)
+                manager.group_scenarios[group] = ScenarioConfig.model_validate(
+                    config_data
+                )
             if manager.group_scenarios:
                 logger.debug(
                     "Loaded %s group scenario(s)", len(manager.group_scenarios)
@@ -100,8 +133,17 @@ class ScenarioPersistence:
             logger.error("Failed to load scenarios from %s: %s", self.scenario_file, e)
             return manager
 
-    def save(self, manager: HierarchicalScenarioManager) -> None:
-        """Save scenarios to disk.
+    async def save(self, manager: HierarchicalScenarioManager) -> None:
+        """Save scenarios to disk (async).
+
+        Args:
+            manager: HierarchicalScenarioManager to save
+        """
+        loop = asyncio.get_running_loop()
+        await loop.run_in_executor(self.executor, self._sync_save, manager)
+
+    def _sync_save(self, manager: HierarchicalScenarioManager) -> None:
+        """Synchronous save operation (runs in executor).
 
         Args:
             manager: HierarchicalScenarioManager to save
@@ -156,8 +198,17 @@ class ScenarioPersistence:
             logger.error("Failed to save scenarios to %s: %s", self.scenario_file, e)
             raise
 
-    def delete(self) -> bool:
-        """Delete the scenario file.
+    async def delete(self) -> bool:
+        """Delete the scenario file (async).
+
+        Returns:
+            True if file was deleted, False if it didn't exist
+        """
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(self.executor, self._sync_delete)
+
+    def _sync_delete(self) -> bool:
+        """Synchronous delete operation (runs in executor).
 
         Returns:
             True if file was deleted, False if it didn't exist
@@ -172,35 +223,19 @@ class ScenarioPersistence:
                 raise
         return False
 
+    async def shutdown(self) -> None:
+        """Gracefully shutdown executor.
 
-def _deserialize_response_delays(data: dict[str, Any]) -> dict[int, float]:
-    """Convert string keys back to integers for response_delays.
-
-    JSON only supports string keys, so we convert them back to ints.
-
-    Args:
-        data: Dictionary with string keys
-
-    Returns:
-        Dictionary with integer keys
-    """
-    if not data:
-        return {}
-    return {int(k): v for k, v in data.items()}
-
-
-# Monkey-patch ScenarioConfig.from_dict to handle string keys
-_original_from_dict = ScenarioConfig.from_dict
+        This should be called before the application exits.
+        """
+        logger.info("Shutting down async scenario storage...")
 
+        # Shutdown executor (non-blocking to avoid hanging on Windows)
+        loop = asyncio.get_running_loop()
+        await loop.run_in_executor(None, self.executor.shutdown, True)
 
-@classmethod
-def _from_dict_with_conversion(cls, data: dict[str, Any]) -> ScenarioConfig:
-    """Create from dictionary with int key conversion."""
-    # Convert response_delays string keys to ints
-    if "response_delays" in data and data["response_delays"]:
-        data = data.copy()
-        data["response_delays"] = _deserialize_response_delays(data["response_delays"])
-    return _original_from_dict(data)
+        logger.info("Async scenario storage shutdown complete")
 
 
-ScenarioConfig.from_dict = _from_dict_with_conversion  # type: ignore
+# Note: Pydantic's field_validators in ScenarioConfig handle string-to-int
+# key conversion automatically, so no additional deserialization logic is needed.