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

lifx_emulator/api/routers/devices.py

@@ -0,0 +1,130 @@
+"""Device management endpoints."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from fastapi import APIRouter, HTTPException
+
+if TYPE_CHECKING:
+    from lifx_emulator.server import EmulatedLifxServer
+
+from lifx_emulator.api.models import DeviceCreateRequest, DeviceInfo
+from lifx_emulator.api.services.device_service import (
+    DeviceAlreadyExistsError,
+    DeviceCreationError,
+    DeviceNotFoundError,
+    DeviceService,
+)
+
+
+def create_devices_router(server: EmulatedLifxServer) -> APIRouter:
+    """Create devices router with server dependency.
+
+    Args:
+        server: The LIFX emulator server instance
+
+    Returns:
+        Configured APIRouter for device endpoints
+    """
+    # Create fresh router instance for this server
+    router = APIRouter(prefix="/api/devices", tags=["devices"])
+
+    # Create service layer
+    device_service = DeviceService(server)
+
+    @router.get(
+        "",
+        response_model=list[DeviceInfo],
+        summary="List all devices",
+        description=(
+            "Returns a list of all emulated devices with their current configuration."
+        ),
+    )
+    async def list_devices():
+        """List all emulated devices."""
+        return device_service.list_all_devices()
+
+    @router.get(
+        "/{serial}",
+        response_model=DeviceInfo,
+        summary="Get device information",
+        description=(
+            "Returns detailed information about a specific device by its serial number."
+        ),
+        responses={
+            404: {"description": "Device not found"},
+        },
+    )
+    async def get_device(serial: str):
+        """Get specific device information."""
+        try:
+            return device_service.get_device_info(serial)
+        except DeviceNotFoundError as e:
+            raise HTTPException(status_code=404, detail=str(e))
+
+    @router.post(
+        "",
+        response_model=DeviceInfo,
+        status_code=201,
+        summary="Create a new device",
+        description=(
+            "Creates a new emulated device by product ID. "
+            "The device will be added to the emulator immediately."
+        ),
+        responses={
+            201: {"description": "Device created successfully"},
+            400: {"description": "Invalid product ID or parameters"},
+            409: {"description": "Device with this serial already exists"},
+        },
+    )
+    async def create_device(request: DeviceCreateRequest):
+        """Create a new device."""
+        try:
+            return device_service.create_device(request)
+        except DeviceCreationError as e:
+            raise HTTPException(status_code=400, detail=str(e))
+        except DeviceAlreadyExistsError as e:
+            raise HTTPException(status_code=409, detail=str(e))
+
+    @router.delete(
+        "/{serial}",
+        status_code=204,
+        summary="Delete a device",
+        description=(
+            "Removes an emulated device from the server. "
+            "The device will stop responding to LIFX protocol packets."
+        ),
+        responses={
+            204: {"description": "Device deleted successfully"},
+            404: {"description": "Device not found"},
+        },
+    )
+    async def delete_device(serial: str):
+        """Delete a device."""
+        try:
+            device_service.delete_device(serial)
+        except DeviceNotFoundError as e:
+            raise HTTPException(status_code=404, detail=str(e))
+
+    @router.delete(
+        "",
+        status_code=200,
+        summary="Delete all devices",
+        description=(
+            "Removes all emulated devices from the server. "
+            "All devices will stop responding to LIFX protocol packets."
+        ),
+        responses={
+            200: {"description": "All devices deleted successfully"},
+        },
+    )
+    async def delete_all_devices():
+        """Delete all devices from the running server."""
+        count = device_service.clear_all_devices(delete_storage=False)
+        return {"deleted": count, "message": f"Removed {count} device(s) from server"}
+
+    # TODO: Add storage clear endpoint (was /api/storage in old API, not under /devices)
+    # This should be handled separately or at the app level
+
+    return router

lifx_emulator/api/routers/monitoring.py

@@ -0,0 +1,52 @@
+"""Monitoring endpoints for server statistics and activity."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from fastapi import APIRouter
+
+if TYPE_CHECKING:
+    from lifx_emulator.server import EmulatedLifxServer
+
+from lifx_emulator.api.models import ActivityEvent, ServerStats
+
+
+def create_monitoring_router(server: EmulatedLifxServer) -> APIRouter:
+    """Create monitoring router with server dependency.
+
+    Args:
+        server: The LIFX emulator server instance
+
+    Returns:
+        Configured APIRouter for monitoring endpoints
+    """
+    # Create fresh router instance for this server
+    router = APIRouter(prefix="/api", tags=["monitoring"])
+
+    @router.get(
+        "/stats",
+        response_model=ServerStats,
+        summary="Get server statistics",
+        description=(
+            "Returns server uptime, packet counts, error counts, and device count."
+        ),
+    )
+    async def get_stats():
+        """Get server statistics."""
+        return server.get_stats()
+
+    @router.get(
+        "/activity",
+        response_model=list[ActivityEvent],
+        summary="Get recent activity",
+        description=(
+            "Returns the last 100 packet events (TX/RX) "
+            "with timestamps and packet details."
+        ),
+    )
+    async def get_activity():
+        """Get recent activity events."""
+        return [ActivityEvent(**event) for event in server.get_recent_activity()]
+
+    return router

lifx_emulator/api/routers/scenarios.py

@@ -0,0 +1,247 @@
+"""Scenario management endpoints for testing LIFX protocol behavior."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from fastapi import APIRouter, HTTPException
+
+if TYPE_CHECKING:
+    from lifx_emulator.server import EmulatedLifxServer
+
+from lifx_emulator.api.models import ScenarioConfig, ScenarioResponse
+
+
+def _validate_device_serial(serial: str) -> bool:
+    """Validate that serial is a properly formatted 12-character hex string."""
+    return len(serial) == 12 and all(c in "0123456789abcdefABCDEF" for c in serial)
+
+
+def _add_global_endpoints(router: APIRouter, server: EmulatedLifxServer, persist_fn):
+    """Add global scenario endpoints to router."""
+
+    @router.get(
+        "/global",
+        response_model=ScenarioResponse,
+        summary="Get global scenario",
+        description=(
+            "Returns the global scenario that applies to all devices as a baseline."
+        ),
+    )
+    async def get_global_scenario():
+        config = server.scenario_manager.get_global_scenario()
+        return ScenarioResponse(scope="global", identifier=None, scenario=config)
+
+    @router.put(
+        "/global",
+        response_model=ScenarioResponse,
+        summary="Set global scenario",
+        description=(
+            "Sets the global scenario that applies to all devices as a baseline."
+        ),
+    )
+    async def set_global_scenario(scenario: ScenarioConfig):
+        server.scenario_manager.set_global_scenario(scenario)
+        await persist_fn()
+        return ScenarioResponse(scope="global", identifier=None, scenario=scenario)
+
+    @router.delete(
+        "/global",
+        status_code=204,
+        summary="Clear global scenario",
+        description="Clears the global scenario, resetting it to defaults.",
+    )
+    async def clear_global_scenario():
+        server.scenario_manager.clear_global_scenario()
+        await persist_fn()
+
+
+def _add_device_endpoints(router: APIRouter, server: EmulatedLifxServer, persist_fn):
+    """Add device-specific scenario endpoints to router."""
+
+    @router.get(
+        "/devices/{serial}",
+        response_model=ScenarioResponse,
+        summary="Get device scenario",
+        description="Returns the scenario for a specific device by serial number.",
+        responses={404: {"description": "Device scenario not set"}},
+    )
+    async def get_device_scenario(serial: str):
+        config = server.scenario_manager.get_device_scenario(serial)
+        if config is None:
+            raise HTTPException(404, f"No scenario set for device {serial}")
+        return ScenarioResponse(scope="device", identifier=serial, scenario=config)
+
+    @router.put(
+        "/devices/{serial}",
+        response_model=ScenarioResponse,
+        summary="Set device scenario",
+        description="Sets the scenario for a specific device by serial number.",
+        responses={404: {"description": "Invalid device serial format"}},
+    )
+    async def set_device_scenario(serial: str, scenario: ScenarioConfig):
+        if not _validate_device_serial(serial):
+            raise HTTPException(404, f"Invalid device serial format: {serial}.")
+        server.scenario_manager.set_device_scenario(serial, scenario)
+        await persist_fn()
+        return ScenarioResponse(scope="device", identifier=serial, scenario=scenario)
+
+    @router.delete(
+        "/devices/{serial}",
+        status_code=204,
+        summary="Clear device scenario",
+        description="Clears the scenario for a specific device.",
+        responses={404: {"description": "Device scenario not found"}},
+    )
+    async def clear_device_scenario(serial: str):
+        if not server.scenario_manager.delete_device_scenario(serial):
+            raise HTTPException(404, f"No scenario set for device {serial}")
+        await persist_fn()
+
+
+def _add_type_endpoints(router: APIRouter, server: EmulatedLifxServer, persist_fn):
+    """Add type-specific scenario endpoints to router."""
+
+    @router.get(
+        "/types/{device_type}",
+        response_model=ScenarioResponse,
+        summary="Get type scenario",
+        description="Returns the scenario for all devices of a specific type.",
+        responses={404: {"description": "Type scenario not set"}},
+    )
+    async def get_type_scenario(device_type: str):
+        config = server.scenario_manager.get_type_scenario(device_type)
+        if config is None:
+            raise HTTPException(404, f"No scenario set for type {device_type}")
+        return ScenarioResponse(scope="type", identifier=device_type, scenario=config)
+
+    @router.put(
+        "/types/{device_type}",
+        response_model=ScenarioResponse,
+        summary="Set type scenario",
+        description="Sets the scenario for all devices of a specific type.",
+    )
+    async def set_type_scenario(device_type: str, scenario: ScenarioConfig):
+        server.scenario_manager.set_type_scenario(device_type, scenario)
+        await persist_fn()
+        return ScenarioResponse(scope="type", identifier=device_type, scenario=scenario)
+
+    @router.delete(
+        "/types/{device_type}",
+        status_code=204,
+        summary="Clear type scenario",
+        description="Clears the scenario for a device type.",
+        responses={404: {"description": "Type scenario not found"}},
+    )
+    async def clear_type_scenario(device_type: str):
+        if not server.scenario_manager.delete_type_scenario(device_type):
+            raise HTTPException(404, f"No scenario set for type {device_type}")
+        await persist_fn()
+
+
+def _add_location_endpoints(router: APIRouter, server: EmulatedLifxServer, persist_fn):
+    """Add location-based scenario endpoints to router."""
+
+    @router.get(
+        "/locations/{location}",
+        response_model=ScenarioResponse,
+        summary="Get location scenario",
+        description="Returns the scenario for all devices in a location.",
+        responses={404: {"description": "Location scenario not set"}},
+    )
+    async def get_location_scenario(location: str):
+        config = server.scenario_manager.get_location_scenario(location)
+        if config is None:
+            raise HTTPException(404, f"No scenario set for location {location}")
+        return ScenarioResponse(scope="location", identifier=location, scenario=config)
+
+    @router.put(
+        "/locations/{location}",
+        response_model=ScenarioResponse,
+        summary="Set location scenario",
+        description="Sets the scenario for all devices in a location.",
+    )
+    async def set_location_scenario(location: str, scenario: ScenarioConfig):
+        server.scenario_manager.set_location_scenario(location, scenario)
+        await persist_fn()
+        return ScenarioResponse(
+            scope="location", identifier=location, scenario=scenario
+        )
+
+    @router.delete(
+        "/locations/{location}",
+        status_code=204,
+        summary="Clear location scenario",
+        description="Clears the scenario for a location.",
+        responses={404: {"description": "Location scenario not found"}},
+    )
+    async def clear_location_scenario(location: str):
+        if not server.scenario_manager.delete_location_scenario(location):
+            raise HTTPException(404, f"No scenario set for location {location}")
+        await persist_fn()
+
+
+def _add_group_endpoints(router: APIRouter, server: EmulatedLifxServer, persist_fn):
+    """Add group-based scenario endpoints to router."""
+
+    @router.get(
+        "/groups/{group}",
+        response_model=ScenarioResponse,
+        summary="Get group scenario",
+        description="Returns the scenario for all devices in a group.",
+        responses={404: {"description": "Group scenario not set"}},
+    )
+    async def get_group_scenario(group: str):
+        config = server.scenario_manager.get_group_scenario(group)
+        if config is None:
+            raise HTTPException(404, f"No scenario set for group {group}")
+        return ScenarioResponse(scope="group", identifier=group, scenario=config)
+
+    @router.put(
+        "/groups/{group}",
+        response_model=ScenarioResponse,
+        summary="Set group scenario",
+        description="Sets the scenario for all devices in a group.",
+    )
+    async def set_group_scenario(group: str, scenario: ScenarioConfig):
+        server.scenario_manager.set_group_scenario(group, scenario)
+        await persist_fn()
+        return ScenarioResponse(scope="group", identifier=group, scenario=scenario)
+
+    @router.delete(
+        "/groups/{group}",
+        status_code=204,
+        summary="Clear group scenario",
+        description="Clears the scenario for a group.",
+        responses={404: {"description": "Group scenario not found"}},
+    )
+    async def clear_group_scenario(group: str):
+        if not server.scenario_manager.delete_group_scenario(group):
+            raise HTTPException(404, f"No scenario set for group {group}")
+        await persist_fn()
+
+
+def create_scenarios_router(server: EmulatedLifxServer) -> APIRouter:
+    """Create scenarios router with server dependency.
+
+    Args:
+        server: The LIFX emulator server instance
+
+    Returns:
+        Configured APIRouter for scenario endpoints
+    """
+    router = APIRouter(prefix="/api/scenarios", tags=["scenarios"])
+
+    async def persist():
+        """Helper to invalidate device caches and persist scenarios."""
+        server.invalidate_all_scenario_caches()
+        if server.scenario_persistence:
+            await server.scenario_persistence.save(server.scenario_manager)
+
+    _add_global_endpoints(router, server, persist)
+    _add_device_endpoints(router, server, persist)
+    _add_type_endpoints(router, server, persist)
+    _add_location_endpoints(router, server, persist)
+    _add_group_endpoints(router, server, persist)
+
+    return router

lifx_emulator/api/services/__init__.py

@@ -0,0 +1,8 @@
+"""Business logic services for API endpoints."""
+
+from lifx_emulator.api.services.device_service import DeviceService
+
+# TODO: Create ScenarioService (Phase 1.1b completion)
+# from lifx_emulator.api.services.scenario_service import ScenarioService
+
+__all__ = ["DeviceService"]

lifx_emulator/api/services/device_service.py

@@ -0,0 +1,198 @@
+"""Device management business logic service.
+
+Separates API handlers from server operations, providing a clean service layer
+for device CRUD operations. Applies Single Responsibility Principle by keeping
+business logic separate from HTTP concerns.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from lifx_emulator.server import EmulatedLifxServer
+
+from lifx_emulator.api.mappers import DeviceMapper
+from lifx_emulator.api.models import DeviceCreateRequest, DeviceInfo
+from lifx_emulator.factories import create_device
+
+logger = logging.getLogger(__name__)
+
+
+class DeviceNotFoundError(Exception):
+    """Raised when a device with the specified serial is not found."""
+
+    def __init__(self, serial: str):
+        super().__init__(f"Device {serial} not found")
+        self.serial = serial
+
+
+class DeviceAlreadyExistsError(Exception):
+    """Raised when attempting to create a device with a serial that already exists."""
+
+    def __init__(self, serial: str):
+        super().__init__(f"Device with serial {serial} already exists")
+        self.serial = serial
+
+
+class DeviceCreationError(Exception):
+    """Raised when device creation fails."""
+
+    pass
+
+
+class DeviceService:
+    """Service for managing emulated LIFX devices.
+
+    Provides business logic for device operations:
+    - Listing all devices
+    - Getting individual device info
+    - Creating new devices
+    - Deleting devices
+    - Clearing all devices
+
+    **Benefits**:
+    - Separates business logic from HTTP/API concerns
+    - Testable without FastAPI dependencies
+    - Consistent error handling
+    - Single source of truth for device operations
+    """
+
+    def __init__(self, server: EmulatedLifxServer):
+        """Initialize the device service.
+
+        Args:
+            server: The LIFX emulator server instance to manage devices for
+        """
+        self.server = server
+
+    def list_all_devices(self) -> list[DeviceInfo]:
+        """Get information about all emulated devices.
+
+        Returns:
+            List of DeviceInfo objects for all devices
+
+        Example:
+            >>> service = DeviceService(server)
+            >>> devices = service.list_all_devices()
+            >>> len(devices)
+            3
+        """
+        devices = self.server.get_all_devices()
+        return DeviceMapper.to_device_info_list(devices)
+
+    def get_device_info(self, serial: str) -> DeviceInfo:
+        """Get information about a specific device.
+
+        Args:
+            serial: The device serial number (12-character hex string)
+
+        Returns:
+            DeviceInfo object for the device
+
+        Raises:
+            DeviceNotFoundError: If no device with the given serial exists
+
+        Example:
+            >>> service = DeviceService(server)
+            >>> info = service.get_device_info("d073d5000001")
+            >>> info.label
+            'LIFX Bulb'
+        """
+        device = self.server.get_device(serial)
+        if not device:
+            raise DeviceNotFoundError(serial)
+
+        return DeviceMapper.to_device_info(device)
+
+    def create_device(self, request: DeviceCreateRequest) -> DeviceInfo:
+        """Create a new emulated device.
+
+        Args:
+            request: Device creation request with product_id and optional parameters
+
+        Returns:
+            DeviceInfo object for the newly created device
+
+        Raises:
+            DeviceCreationError: If device creation fails
+            DeviceAlreadyExistsError: If a device with the serial already exists
+
+        Example:
+            >>> service = DeviceService(server)
+            >>> request = DeviceCreateRequest(product_id=27, serial="d073d5000001")
+            >>> info = service.create_device(request)
+            >>> info.product
+            27
+        """
+        # Build firmware version tuple if provided
+        firmware_version = None
+        if request.firmware_major is not None and request.firmware_minor is not None:
+            firmware_version = (request.firmware_major, request.firmware_minor)
+
+        # Create the device using the factory
+        try:
+            device = create_device(
+                product_id=request.product_id,
+                serial=request.serial,
+                zone_count=request.zone_count,
+                tile_count=request.tile_count,
+                tile_width=request.tile_width,
+                tile_height=request.tile_height,
+                firmware_version=firmware_version,
+                storage=self.server.storage,
+                scenario_manager=self.server.scenario_manager,
+            )
+        except Exception as e:
+            logger.error("Failed to create device: %s", e, exc_info=True)
+            raise DeviceCreationError(f"Failed to create device: {e}") from e
+
+        # Add device to server
+        if not self.server.add_device(device):
+            raise DeviceAlreadyExistsError(device.state.serial)
+
+        logger.info(
+            "Created device: serial=%s product=%s",
+            device.state.serial,
+            device.state.product,
+        )
+
+        return DeviceMapper.to_device_info(device)
+
+    def delete_device(self, serial: str) -> None:
+        """Delete an emulated device.
+
+        Args:
+            serial: The device serial number to delete
+
+        Raises:
+            DeviceNotFoundError: If no device with the given serial exists
+
+        Example:
+            >>> service = DeviceService(server)
+            >>> service.delete_device("d073d5000001")
+        """
+        if not self.server.remove_device(serial):
+            raise DeviceNotFoundError(serial)
+
+        logger.info("Deleted device: serial=%s", serial)
+
+    def clear_all_devices(self, delete_storage: bool = False) -> int:
+        """Remove all emulated devices from the server.
+
+        Args:
+            delete_storage: If True, also delete persistent storage for devices
+
+        Returns:
+            The number of devices removed
+
+        Example:
+            >>> service = DeviceService(server)
+            >>> count = service.clear_all_devices()
+            >>> count
+            5
+        """
+        count = self.server.remove_all_devices(delete_storage=delete_storage)
+        logger.info("Cleared %d devices (delete_storage=%s)", count, delete_storage)
+        return count