lifx-emulator 1.0.1__tar.gz → 2.0.0__tar.gz

{lifx_emulator-1.0.1 → lifx_emulator-2.0.0}/.github/workflows/ci.yml

@@ -36,7 +36,7 @@ jobs:
     - name: Run Ruff format check
       run: uv run ruff format --check .
 
-    - name: Run Ruff linter
+    - name: Run Ruff linter (with complexity checks)
       run: uv run ruff check .
 
     - name: Run Pyright type checker
@@ -74,8 +74,8 @@ jobs:
     - name: Install dependencies
       run: uv sync --frozen
 
-    - name: Run unit tests
-      run: uv run --frozen pytest
+    - name: Run unit tests with coverage threshold
+      run: uv run --frozen pytest --cov-fail-under=80
 
     - name: Upload coverage to Codecov
       if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.11'

{lifx_emulator-1.0.1 → lifx_emulator-2.0.0}/.pre-commit-config.yaml

@@ -50,7 +50,7 @@ repos:
   - id: ruff-format
     types_or: [python, pyi]
 
-      # Run the linter
+      # Run the linter with complexity checks (configured in pyproject.toml)
   - id: ruff
     types_or: [python, pyi]
     args: [--fix, --exit-non-zero-on-fix]

{lifx_emulator-1.0.1 → lifx_emulator-2.0.0}/CLAUDE.md

@@ -106,7 +106,7 @@ lifx-emulator --help
     - `brightness only`: Fixed color temperature, brightness control only
     - `switch`: Relay-based switches (not lights)
     - `multizone`: Linear light strips
-    - `extended-multizone`: Extended multizone (>16 zones)
+    - `extended-multizone`: Extended multizone packet support
     - `matrix`: 2D tile/candle arrangements
     - `infrared`: Night vision capability
     - `HEV`: Germicidal UV-C capability
@@ -219,9 +219,12 @@ curl -X POST http://localhost:8080/api/devices \
 curl -X DELETE http://localhost:8080/api/devices/d073d5000001
 ```
 
-**API Module** (`src/lifx_emulator/api.py`):
-- `create_api_app(server)`: Create FastAPI application with OpenAPI 3.1.0 schema
-- `run_api_server(server, host, port)`: Run the API server
+**API Module** (`src/lifx_emulator/api/`):
+- `create_api_app(server)`: Create FastAPI application with OpenAPI 3.1.0 schema (in `api/app.py`)
+- `run_api_server(server, host, port)`: Run the API server (in `api/app.py`)
+- Modular architecture with separate routers for monitoring, devices, and scenarios (in `api/routers/`)
+- Pydantic models for validation (in `api/models.py`)
+- Service layer for business logic (in `api/services/`)
 - Automatic OpenAPI schema generation with full Pydantic validation
 - Interactive API documentation via Swagger UI and ReDoc
 
@@ -258,14 +261,14 @@ lifx-emulator --persistent
 **Programmatic API:**
 ```python
 import asyncio
-from lifx_emulator.async_storage import AsyncDeviceStorage
+from lifx_emulator.devices import DevicePersistenceAsyncFile
 from lifx_emulator.factories import create_color_light
 
 async def main():
     # Create storage
-    storage = AsyncDeviceStorage()  # Uses ~/.lifx-emulator by default
+    storage = DevicePersistenceAsyncFile()  # Uses ~/.lifx-emulator by default
     # Or specify custom path:
-    # storage = AsyncDeviceStorage("/path/to/storage")
+    # storage = DevicePersistenceAsyncFile("/path/to/storage")
 
     # Create device with persistence
     device = create_color_light(serial="d073d5123456", storage=storage)
@@ -281,8 +284,8 @@ async def main():
 asyncio.run(main())
 ```
 
-**Storage Module** (`src/lifx_emulator/async_storage.py`):
-- `AsyncDeviceStorage`: High-performance async persistent storage with debouncing
+**Storage Module** (`src/lifx_emulator/devices/persistence.py`):
+- `DevicePersistenceAsyncFile`: High-performance async persistent storage with debouncing
 - `async save_device_state(device_state)`: Queue state for async save (non-blocking)
 - `load_device_state(serial)`: Load saved state from disk (synchronous)
 - `delete_device_state(serial)`: Remove saved state (synchronous)
@@ -439,7 +442,7 @@ lifx-emulator --api --persistent --persistent-scenarios
 
 **Programmatic API:**
 ```python
-from lifx_emulator.scenario_manager import HierarchicalScenarioManager, ScenarioConfig
+from lifx_emulator.scenarios import HierarchicalScenarioManager, ScenarioConfig
 
 # Create manager
 manager = HierarchicalScenarioManager()
@@ -475,17 +478,18 @@ should_respond = manager.should_respond(101, merged)  # False (dropped)
 delay = manager.get_response_delay(502, merged)  # 1.0s
 ```
 
-**Scenario Manager** (`src/lifx_emulator/scenario_manager.py`):
+**Scenario Manager** (`src/lifx_emulator/scenarios/manager.py`):
 - `ScenarioConfig`: Dataclass representing a scenario configuration
 - `HierarchicalScenarioManager`: Manages scenarios across 5 scope levels
 - `get_device_type()`: Classify device by capability for type-based scoping
 - Methods: `set_*_scenario()`, `delete_*_scenario()`, `get_scenario_for_device()`, `should_respond()`, etc.
 
-**Persistence Module** (`src/lifx_emulator/scenario_persistence.py`):
-- `ScenarioPersistence`: Handles JSON serialization of scenario configurations
+**Persistence Module** (`src/lifx_emulator/scenarios/persistence.py`):
+- `ScenarioPersistenceAsyncFile`: Handles async JSON serialization of scenario configurations
 - Automatic save after API updates
 - Atomic file operations (temp file + rename) for consistency
 - Error recovery on corrupted scenario files
+- All operations are async for non-blocking I/O
 
 ## Architecture
 
@@ -493,17 +497,29 @@ delay = manager.get_response_delay(502, merged)  # 1.0s
 
 **EmulatedLifxServer** (`src/lifx_emulator/server.py`):
 - UDP server using asyncio DatagramProtocol
-- Routes incoming packets to appropriate devices based on target serial (encoded in header target field)
-- Handles broadcast packets (tagged=True or target=00000000) by forwarding to all devices
-- Supports configurable response delays per packet type for testing
-
-**EmulatedLifxDevice** (`src/lifx_emulator/device.py`):
+- **Single Responsibility**: Network transport only (UDP protocol handling)
+- Delegates device management to `DeviceManager`
+- Delegates scenario management to `HierarchicalScenarioManager`
+- Uses dependency injection for testability and flexibility
+- **Constructor signature**: `EmulatedLifxServer(devices, device_manager, bind_address, port, ...)`
+
+**DeviceManager** (`src/lifx_emulator/devices/manager.py`):
+- **Domain logic layer** for device lifecycle and packet routing
+- Separates device management concerns from network I/O
+- Key responsibilities:
+  - Device lifecycle operations (add, remove, get, count)
+  - Packet routing logic (target resolution, broadcast handling)
+  - Scenario cache invalidation across all devices
+- Uses `IDeviceRepository` for storage abstraction
+- Protocol interface `IDeviceManager` for testability
+
+**EmulatedLifxDevice** (`src/lifx_emulator/devices/device.py`):
 - Represents a single virtual LIFX device with stateful behavior
 - `process_packet()`: Main entry point that handles packet type routing and acknowledgments
 - `_handle_packet_type()`: Dispatcher that routes to specific handlers (e.g., `_handle_light_set_color()`)
 - Supports testing scenarios: packet dropping, malformed responses, invalid field values, partial responses
 
-**DeviceState** (`src/lifx_emulator/device.py`):
+**DeviceState** (`src/lifx_emulator/devices/states.py`):
 - Dataclass holding all device state (color, power, zones, tiles, firmware version, etc.)
 - Capability flags: `has_color`, `has_infrared`, `has_multizone`, `has_matrix`, `has_hev`
 - Initialized differently per device type via factory functions
@@ -536,9 +552,10 @@ delay = manager.get_response_delay(502, merged)  # 1.0s
 - `create_infrared_light()`: Night vision capable (product=29)
 - `create_hev_light()`: LIFX Clean with HEV (product=90)
 - `create_multizone_light(zone_count=None, extended_multizone=False)`: Multizone strip/beam
-  - `extended_multizone=False`: LIFX Z strip (product=32, up to 16 zones)
-  - `extended_multizone=True`: LIFX Beam (product=38, up to 82 zones)
-  - Extended multizone devices are backwards compatible with non-extended packets
+  - `extended_multizone=False`: LIFX Z strip (product=32)
+  - `extended_multizone=True`: LIFX Beam (product=38)
+  - Extended multizone devices are backwards compatible and support GetMultiZone and StateMultiZone packets
+  - Multizone devices with more than 82 zones will return multiple StateExtendedMultiZone packets
   - Zone count uses product defaults from specs if not specified
 - `create_tile_device(tile_count=None)`: Tile chain (product=55)
   - Tile count and dimensions use product defaults from specs if not specified
@@ -553,12 +570,176 @@ All factory functions now use the specs system to load product-specific defaults
 - Tile dimensions (e.g., 8x8 for Tiles, 5x6 for Candles)
 - Users can override these defaults by passing explicit parameters
 
+### Repository Pattern & Domain Architecture
+
+**IMPORTANT**: The emulator uses a layered architecture with clear separation between network I/O, domain logic, and persistence. All code that creates `EmulatedLifxServer` instances must provide `DeviceManager` and repository dependencies.
+
+**Architecture Layers**:
+1. **Network Layer** (`EmulatedLifxServer`): UDP protocol handling
+2. **Domain Layer** (`DeviceManager`, `HierarchicalScenarioManager`): Business logic
+3. **Repository Layer** (`IDeviceRepository`, `IDeviceStorageBackend`): Storage abstraction
+4. **Persistence Layer** (`DevicePersistenceAsyncFile`, `ScenarioPersistenceAsyncFile`): File I/O
+
+**Repository Interfaces** (`src/lifx_emulator/repositories/`):
+- `IDeviceRepository`: Protocol interface for device collection storage
+  - Methods: `add()`, `remove()`, `get()`, `get_all()`, `clear()`, `count()`
+  - Implementation: `DeviceRepository` (in-memory dictionary)
+- `IDeviceStorageBackend`: Protocol interface for device state persistence
+  - Methods: `async save_device_state()`, `load_device_state()`, `delete_device_state()`
+  - Implementation: `DevicePersistenceAsyncFile` (JSON files with debouncing)
+- `IScenarioStorageBackend`: Protocol interface for scenario persistence
+  - Methods: `async save()`, `async load()`, `async delete()`
+  - Implementation: `ScenarioPersistenceAsyncFile` (atomic JSON writes)
+
+**Usage Example**:
+```python
+from lifx_emulator.repositories import DeviceRepository
+from lifx_emulator.devices import DeviceManager
+from lifx_emulator.server import EmulatedLifxServer
+from lifx_emulator.factories import create_color_light
+
+# Create devices
+devices = [create_color_light("d073d5000001")]
+
+# Create repository and manager
+device_repository = DeviceRepository()
+device_manager = DeviceManager(device_repository)
+
+# Create server (DeviceManager is REQUIRED as second argument)
+server = EmulatedLifxServer(
+    devices,
+    device_manager,  # REQUIRED
+    "127.0.0.1",
+    56700
+)
+
+# With device state persistence
+from lifx_emulator.devices import DevicePersistenceAsyncFile
+
+storage = DevicePersistenceAsyncFile()
+devices_with_storage = [create_color_light("d073d5000001", storage=storage)]
+server = EmulatedLifxServer(
+    devices_with_storage,
+    device_manager,
+    "127.0.0.1",
+    56700
+)
+```
+
+**Architectural Benefits**:
+- **Single Responsibility**: Each layer has one clear purpose
+- **Testability**: Easy to inject mock managers/repositories for testing
+- **Flexibility**: Can swap storage backends without changing domain logic
+- **Separation of Concerns**: Network, domain, and persistence are independent
+- **Dependency Inversion**: All layers depend on Protocol interfaces, not concrete implementations
+
+### Module Organization
+
+The codebase follows a modular structure with clear separation of concerns:
+
+**Device Module** (`src/lifx_emulator/devices/`):
+- `device.py`: Core `EmulatedLifxDevice` class with packet processing
+- `manager.py`: `DeviceManager` for lifecycle and routing operations
+- `states.py`: All state dataclasses (`DeviceState`, `CoreDeviceState`, etc.)
+- `persistence.py`: `DevicePersistenceAsyncFile` for async device state storage
+- `state_restorer.py`: State restoration from persistent storage
+- `state_serializer.py`: State serialization for persistence
+- `observers.py`: Device state observation patterns
+- `__init__.py`: Public API exports
+
+**Scenario Module** (`src/lifx_emulator/scenarios/`):
+- `manager.py`: `HierarchicalScenarioManager` for multi-scope scenario management
+- `models.py`: `ScenarioConfig` dataclass and related models
+- `persistence.py`: `ScenarioPersistenceAsyncFile` for scenario storage
+- `__init__.py`: Public API exports
+
+**API Module** (`src/lifx_emulator/api/`):
+- `app.py`: FastAPI application creation and server startup
+- `models.py`: Pydantic request/response models with validation
+- `routers/`: Modular endpoint handlers (monitoring, devices, scenarios)
+- `services/`: Business logic layer for API operations
+- `__init__.py`: Public API exports
+
+**Repositories Module** (`src/lifx_emulator/repositories/`):
+- `device_repository.py`: In-memory device collection storage
+- `storage_backend.py`: Protocol interfaces for persistence layers
+- `__init__.py`: Public API exports
+
+**Import Guidelines**:
+```python
+# Device-related imports
+from lifx_emulator.devices import (
+    EmulatedLifxDevice,
+    DeviceState,
+    DeviceManager,
+    DevicePersistenceAsyncFile,
+)
+
+# Scenario-related imports
+from lifx_emulator.scenarios import (
+    HierarchicalScenarioManager,
+    ScenarioConfig,
+    ScenarioPersistenceAsyncFile,
+)
+
+# Repository imports
+from lifx_emulator.repositories import DeviceRepository
+
+# API imports
+from lifx_emulator.api import create_api_app, run_api_server
+```
+
+### Product Registry
+
+**Product Registry** (`src/lifx_emulator/products/registry.py`):
+- Auto-generated from official LIFX products.json (https://github.com/LIFX/products)
+- Contains 137+ product definitions with capabilities, temperature ranges, and firmware requirements
+- Pre-built `ProductInfo` instances for efficient runtime lookups
+- Capability flags: `COLOR`, `INFRARED`, `MULTIZONE`, `CHAIN`, `MATRIX`, `RELAYS`, `BUTTONS`, `HEV`, `EXTENDED_MULTIZONE`
+- Never edit this file manually - regenerate using the generator
+
+**Product Registry Generator** (`src/lifx_emulator/products/generator.py`):
+- Downloads latest products.json from LIFX GitHub repository
+- Generates optimized Python code with pre-built product definitions
+- Handles extended multizone capability detection:
+  - **Native support**: Products with `extended_multizone: true` in features (no firmware requirement)
+    - Examples: LIFX Z US (PID 117), LIFX Beam US (PID 119), LIFX Neon, LIFX Permanent Outdoor
+  - **Firmware upgrade**: Products with `extended_multizone` in upgrades section (requires minimum firmware)
+    - Examples: LIFX Z (PID 32, requires firmware 2.77+), LIFX Beam (PID 38, requires firmware 2.77+)
+- Updates specs.yml with templates for new multizone/matrix products
+- Run with: `python -m lifx_emulator.products.generator`
+
+**Product Specs** (`src/lifx_emulator/products/specs.yml`):
+- Product-specific configuration not available in upstream products.json
+- Default zone counts, tile configurations, and device-specific defaults
+- Used by factory functions to create realistic device configurations
+- Manually maintained for accurate product specifications
+
+**ProductInfo API:**
+```python
+from lifx_emulator.products.registry import get_product
+
+product = get_product(117)  # LIFX Z US
+product.has_extended_multizone  # True
+product.min_ext_mz_firmware     # None (native support)
+product.supports_extended_multizone()  # True
+
+product = get_product(32)  # LIFX Z (older model)
+product.has_extended_multizone  # True
+product.min_ext_mz_firmware     # 131149 (firmware 2.77)
+product.supports_extended_multizone(131149)  # True (meets requirement)
+product.supports_extended_multizone(131148)  # False (below requirement)
+```
+
 ## Key Implementation Details
 
 ### MultiZone Handling
-- Standard multizone: Returns multiple `StateMultiZone` packets (type 506), each containing up to 8 zones
-- Extended multizone: Returns one or more `ExtendedStateMultiZone` packet (type 512) with with up to 82 zones
+- Standard multizone: Returns multiple `StateMultiZone` packets (type 506), each containing 8 zones
+- Extended multizone: Returns one or more `ExtendedStateMultiZone` packet (type 512), each containing 82 zones
 - Zone colors stored in `DeviceState.zone_colors` list indexed by zone number
+- The minimum number of zones for a multizone device is 8
+- There is no maximum number of zones for a multizone device
+- There is no correlation between number of zones and the extended multizone capability
 
 ### Tile Handling
 - Matrix devices support up to 5 tiles in a chain, but most only have 1.
@@ -601,3 +782,143 @@ Configure via ScenarioConfig in HierarchicalScenarioManager:
 - Key dependencies: `pyyaml` for config, asyncio for networking
 - Dev dependencies: `pytest`, `pytest-asyncio`, `ruff`, `pyright`, `hatchling`
 - Never use the term or phrase "wide tile device". Use "large matrix device" or "chained matrix device" instead
+
+## Recent Refactoring (Phases 1-5 - In Progress)
+
+The codebase has completed Phases 1-4 and is currently in Phase 5 of a comprehensive refactoring plan.
+
+**Overall Progress**: 40% complete (20/50 tasks)
+- Phase 1 (Critical Infrastructure): ✅ 100% Complete
+- Phase 2 (Code Quality & DRY): ✅ 100% Complete
+- Phase 3 (Performance & Scalability): ✅ 100% Complete
+- Phase 4 (Automated Tooling & Security): ✅ 100% Complete
+- Phase 5 (Testing & Documentation): 🔄 33% Complete (3/9 tasks)
+
+### Key Architectural Changes
+
+**DeviceManager Pattern (Phase 2.3 - COMPLETE)**:
+- Extracted device management domain logic from `EmulatedLifxServer`
+- Created `DeviceManager` class with `IDeviceManager` Protocol interface
+- Server is now **just** the network layer (UDP protocol handling)
+- Clean separation: Network → Domain → Repository → Persistence
+
+**Breaking Changes**:
+- `EmulatedLifxServer` constructor now **requires** `device_manager` as the second parameter (was `device_repository`)
+- Example: `EmulatedLifxServer(devices, device_manager, bind_address, port)`
+- All device management methods delegated to `DeviceManager`
+
+**Repository Pattern (Phase 2.2 - COMPLETE)**:
+- Created repository abstractions (`IDeviceRepository`, `IDeviceStorageBackend`, `IScenarioStorageBackend` protocols)
+- Implemented concrete repositories (`DeviceRepository`)
+- Renamed storage backends for clarity:
+  - `AsyncDeviceStorage` → `DevicePersistenceAsyncFile`
+  - `ScenarioPersistence` → `ScenarioPersistenceAsyncFile`
+- Applied Dependency Inversion Principle throughout stack
+
+**Performance Optimizations (Phase 3 - COMPLETE)**:
+- Cached packed packet payloads to avoid double packing (CPU efficiency)
+- Optimized zone initialization with list comprehensions (20-30% faster)
+- Verified optimal async/await usage and storage debouncing (100ms)
+
+**Code Quality & Security (Phase 4 - COMPLETE)**:
+- Configured Ruff with McCabe complexity limits (max-complexity=10)
+- Enhanced CI/CD with quality gates (80%+ coverage required)
+- Added comprehensive Pydantic validation to API models:
+  - Product ID: 0-10000 range validation
+  - Serial: 12 hex chars with automatic lowercase normalization
+  - Zone/tile counts: sensible limits (0-1000, 0-100)
+  - HSBK colors: proper ranges (hue/sat/bright: 0-65535, kelvin: 1500-9000)
+- Verified atomic file writes for persistence (already correct)
+
+**Enhanced Testing (Phase 5.1 - COMPLETE)**:
+- Created comprehensive test suites:
+  - `tests/test_device_manager.py`: 13 tests for DeviceManager operations
+  - `tests/test_api_validation.py`: 38 tests for Pydantic validation
+- Coverage improvements:
+  - DeviceManager: 71% → 78%
+  - API models: 88% → 92%
+  - Overall project: 84% → 95%
+- Total tests: 608 → 653 (+45 tests)
+- All tests passing with 100% pass rate
+
+### Migration Guide
+
+**If you're upgrading from older versions**, update your code as follows:
+
+```python
+# OLD (before Phase 2.3):
+from lifx_emulator.repositories import DeviceRepository
+server = EmulatedLifxServer(devices, DeviceRepository(), "127.0.0.1", 56700)
+
+# NEW (current):
+from lifx_emulator.repositories import DeviceRepository
+from lifx_emulator.devices import DeviceManager
+
+device_repository = DeviceRepository()
+device_manager = DeviceManager(device_repository)
+server = EmulatedLifxServer(devices, device_manager, "127.0.0.1", 56700)
+```
+
+**Storage backend changes**:
+```python
+# OLD:
+from lifx_emulator.async_storage import AsyncDeviceStorage
+storage = AsyncDeviceStorage()
+
+# NEW:
+from lifx_emulator.devices import DevicePersistenceAsyncFile
+storage = DevicePersistenceAsyncFile()
+```
+
+### Quality Metrics
+
+**Current Status** (as of Phase 5.1):
+- Test Coverage: 95% (up from 84%)
+- Total Tests: 653 (100% pass rate)
+- Code Complexity: All functions ≤10 (enforced by Ruff)
+- API Input Validation: 100% (Pydantic validators on all endpoints)
+- Pre-commit Hooks: Format, lint, type-check, security scan, complexity check
+- CI/CD Gates: All checks + 80% coverage threshold
+
+**Files Modified**:
+- `src/lifx_emulator/server.py` - Network layer only, delegates to DeviceManager
+- `src/lifx_emulator/devices/manager.py` - Domain logic layer (NEW)
+- `src/lifx_emulator/__main__.py` - Updated CLI to create managers
+- `src/lifx_emulator/repositories/` - Repository abstractions (NEW)
+- `src/lifx_emulator/devices/` - Device module (NEW - organized device-related code)
+- `src/lifx_emulator/scenarios/` - Scenario module (NEW - organized scenario-related code)
+- `src/lifx_emulator/api/models.py` - Pydantic validators added
+- `pyproject.toml` - Ruff complexity limits
+- `.pre-commit-config.yaml` - Quality gates enabled
+- `.github/workflows/ci.yml` - CI quality gates
+- `src/lifx_emulator/api/routers/` - Fixed router fixture isolation (3 files)
+- `tests/*.py` - All test fixtures updated to pass repositories (60+ call sites)
+
+**Migration Guide**:
+```python
+# OLD (no longer works):
+server = EmulatedLifxServer(devices, "127.0.0.1", 56700)
+
+# NEW (required):
+from lifx_emulator.repositories import DeviceRepository
+
+server = EmulatedLifxServer(devices, DeviceRepository(), "127.0.0.1", 56700)
+```
+
+### Previous Refactorings (Phase 1 & 2.1 - COMPLETE)
+
+**Phase 1 - Critical Infrastructure** (9/9 tasks complete):
+1. **API Module** (1.1): Broke apart 751-line monolith into modular routers with service layer
+2. **Device Factory** (1.2): Reduced create_device() from 218 to 33 lines (85% reduction) using Builder pattern
+3. **DeviceState** (1.3): Eliminated 203 lines of property boilerplate using `__getattr__`/`__setattr__`
+
+**Phase 2.1 - Code Quality & DRY** (5/5 tasks complete):
+1. Consolidated ScenarioConfig model (~160 lines eliminated)
+2. Moved label encoding to protocol layer (82 lines eliminated)
+3. Extracted scenario cache invalidation (27 lines eliminated)
+4. Verified response builder pattern already implemented
+5. Verified handler registry pattern already implemented
+
+**Total Lines Improved**: ~1,707 lines refactored or eliminated
+
+**Testing Status**: All 94 core tests passing (100% pass rate)

{lifx_emulator-1.0.1 → lifx_emulator-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lifx-emulator
-Version: 1.0.1
+Version: 2.0.0
 Summary: LIFX Emulator for testing LIFX LAN protocol libraries
 Author-email: Avi Miller <me@dje.li>
 Maintainer-email: Avi Miller <me@dje.li>

lifx_emulator-2.0.0/docs/advanced/index.md

@@ -0,0 +1,145 @@
+# Advanced Features
+
+Power-user features for sophisticated testing scenarios.
+
+## Overview
+
+This section covers advanced emulator features for complex testing needs. These features are optional but powerful for:
+
+- Maintaining device state across test runs
+- Runtime device management
+- Comprehensive error simulation
+- Complex multi-scenario testing
+
+## Prerequisites
+
+Before exploring advanced features, you should:
+
+- Be comfortable with basic emulator usage
+- Have completed at least the first 2-3 tutorials
+- Understand your testing requirements
+- Be familiar with REST APIs (for API features)
+
+## Learning Path
+
+Read these guides in order from simple to complex:
+
+1. **[Persistent Storage](storage.md)** - Save device state across restarts
+2. **[Device Management API](device-management-api.md)** - Add/remove devices at runtime
+3. **[Scenarios](scenarios.md)** - Comprehensive error simulation concepts
+4. **[Scenario API](scenario-api.md)** - REST API for managing test scenarios
+
+## Quick Concepts
+
+### Persistent Storage
+
+Save device state (colors, labels, power) across emulator restarts:
+
+```bash
+lifx-emulator --persistent
+```
+
+Device states are saved to `~/.lifx-emulator/` and automatically restored.
+
+👉 **[Storage Guide](storage.md)**
+
+### Device Management API
+
+Enable the HTTP API to manage devices at runtime:
+
+```bash
+lifx-emulator --api
+```
+
+Access the web dashboard at `http://localhost:8080` or use the REST API to add/remove devices dynamically.
+
+👉 **[Device Management Guide](device-management-api.md)**
+
+### Testing Scenarios
+
+Configure error conditions for comprehensive testing:
+
+- Packet loss (test retries)
+- Response delays (test timeouts)
+- Malformed data (test error handling)
+- Firmware version overrides
+
+👉 **[Scenarios Guide](scenarios.md)**
+
+### Scenario API
+
+Manage scenarios via REST API with hierarchical scoping:
+
+```bash
+# Drop 100% of GetColor packets for all color devices
+curl -X PUT http://localhost:8080/api/scenarios/types/color \
+  -H "Content-Type: application/json" \
+  -d '{"drop_packets": {"101": 1.0}}'
+```
+
+Supports device-specific, type-based, location-based, group-based, and global scenarios.
+
+👉 **[Scenario API Reference](scenario-api.md)**
+
+## Feature Comparison
+
+| Feature | Basic | Advanced |
+|---------|-------|----------|
+| Create devices | ✅ | ✅ |
+| Device discovery | ✅ | ✅ |
+| Control devices | ✅ | ✅ |
+| State persistence | ❌ | ✅ |
+| Runtime management | ❌ | ✅ |
+| Error simulation | Basic | Comprehensive |
+| Web UI | ❌ | ✅ |
+| REST API | ❌ | ✅ |
+
+## When to Use Advanced Features
+
+### Use Persistent Storage When:
+
+- Running long test suites where state matters
+- Testing state restoration after failures
+- Developing iteratively and want to preserve state
+- Simulating real-world device persistence
+
+### Use Device Management API When:
+
+- Tests need dynamic device creation/removal
+- Running multi-stage test scenarios
+- Need visual monitoring during development
+- Integrating with external test orchestration
+
+### Use Scenarios When:
+
+- Testing retry logic and error handling
+- Simulating network issues (packet loss, delays)
+- Testing edge cases (malformed data, timeouts)
+- Validating firmware version compatibility
+- Testing client resilience
+
+## Combined Example
+
+Use multiple advanced features together:
+
+```bash
+# Start with persistence, API, and scenarios
+lifx-emulator --persistent --api --color 2
+
+# Configure global scenario for packet loss
+curl -X PUT http://localhost:8080/api/scenarios/global \
+  -H "Content-Type: application/json" \
+  -d '{"drop_packets": {"101": 0.3}}'  # 30% packet loss
+
+# Add device at runtime
+curl -X POST http://localhost:8080/api/devices \
+  -H "Content-Type: application/json" \
+  -d '{"product_id": 32, "zone_count": 16}'
+
+# Run your tests...
+# State persists across restarts
+```
+
+## Next Steps
+
+Choose a topic based on your needs, or read through all guides in order for comprehensive understanding.

{lifx_emulator-1.0.1 → lifx_emulator-2.0.0}/docs/advanced/scenarios.md

@@ -22,7 +22,7 @@ Configure a simple scenario via Python API:
 
 ```python
 from lifx_emulator import create_color_light
-from lifx_emulator.scenario_manager import ScenarioConfig
+from lifx_emulator.scenarios.manager import ScenarioConfig
 
 device = create_color_light("d073d5000001")
 
@@ -56,7 +56,7 @@ curl -X PUT http://localhost:8080/api/scenarios/global \
 Simulate packet loss by dropping incoming packets:
 
 ```python
-from lifx_emulator.scenario_manager import ScenarioConfig
+from lifx_emulator.scenarios.manager import ScenarioConfig
 
 # Drop 100% of GetColor packets
 config = ScenarioConfig(drop_packets={"101": 1.0})
@@ -133,7 +133,7 @@ config = ScenarioConfig(firmware_version=(3, 90))
 Apply to all devices:
 
 ```python
-from lifx_emulator.scenario_manager import HierarchicalScenarioManager
+from lifx_emulator.scenarios.manager import HierarchicalScenarioManager
 
 manager = HierarchicalScenarioManager()
 

{lifx_emulator-1.0.1 → lifx_emulator-2.0.0}/docs/advanced/storage.md

@@ -211,7 +211,7 @@ Combine persistent storage with test scenarios:
 ```python
 from lifx_emulator import create_color_light
 from lifx_emulator.async_storage import AsyncDeviceStorage
-from lifx_emulator.scenario_manager import ScenarioConfig
+from lifx_emulator.scenarios.manager import ScenarioConfig
 
 storage = AsyncDeviceStorage()
 device = create_color_light("d073d5000001", storage=storage)