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

lifx_emulator_app/api/__init__.py

@@ -9,10 +9,6 @@ The API is built with FastAPI and organized into routers for clean separation
 of concerns.
 """
 
-# Import from new refactored structure
 from lifx_emulator_app.api.app import create_api_app, run_api_server
 
-# Note: HTML_UI remains in the old lifx_emulator/api.py file temporarily
-# TODO: Phase 1.1d - extract HTML template to separate file
-
 __all__ = ["create_api_app", "run_api_server"]

lifx_emulator_app/api/app.py

@@ -4,32 +4,40 @@ This module creates the main FastAPI application by assembling routers for:
 - Monitoring (server stats, activity)
 - Devices (CRUD operations)
 - Scenarios (test scenario management)
+- WebSocket (real-time updates)
 """
 
 from __future__ import annotations
 
 import logging
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
 from pathlib import Path
 from typing import TYPE_CHECKING
 
-from fastapi import FastAPI, Request
-from fastapi.responses import HTMLResponse
+from fastapi import FastAPI
+from fastapi.responses import FileResponse
 from fastapi.staticfiles import StaticFiles
-from fastapi.templating import Jinja2Templates
 
 if TYPE_CHECKING:
     from lifx_emulator.server import EmulatedLifxServer
 
 from lifx_emulator_app.api.routers.devices import create_devices_router
 from lifx_emulator_app.api.routers.monitoring import create_monitoring_router
+from lifx_emulator_app.api.routers.products import create_products_router
 from lifx_emulator_app.api.routers.scenarios import create_scenarios_router
+from lifx_emulator_app.api.routers.websocket import create_websocket_router
+from lifx_emulator_app.api.services.event_bridge import (
+    StatsBroadcaster,
+    WebSocketActivityObserver,
+    wire_device_events,
+)
+from lifx_emulator_app.api.services.websocket_manager import WebSocketManager
 
 logger = logging.getLogger(__name__)
 
-# Asset directories for web UI
-TEMPLATES_DIR = Path(__file__).parent / "templates"
+# Asset directory for web UI (Svelte build output)
 STATIC_DIR = Path(__file__).parent / "static"
-templates = Jinja2Templates(directory=str(TEMPLATES_DIR))
 
 
 def create_api_app(server: EmulatedLifxServer) -> FastAPI:
@@ -52,7 +60,21 @@ def create_api_app(server: EmulatedLifxServer) -> FastAPI:
         >>> app = create_api_app(server)
         >>> # Run with: uvicorn app:app --host 127.0.0.1 --port 8080
     """
+    # Create WebSocket manager early so we can reference it in lifespan
+    ws_manager = WebSocketManager(server)
+    stats_broadcaster = StatsBroadcaster(server, ws_manager)
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
+        """Manage application lifecycle - start/stop background tasks."""
+        # Startup: start the stats broadcaster
+        stats_broadcaster.start()
+        yield
+        # Shutdown: stop the stats broadcaster
+        await stats_broadcaster.stop()
+
     app = FastAPI(
+        lifespan=lifespan,
         title="LIFX Emulator API",
         description="""
 Runtime management and monitoring API for LIFX device emulator.
@@ -69,10 +91,11 @@ LIFX LAN protocol.
 - OpenAPI 3.1.0 compliant schema
 
 ## Architecture
-The API is organized into three main routers:
+The API is organized into four main routers:
 - **Monitoring**: Server stats and activity logs
 - **Devices**: Device CRUD operations
 - **Scenarios**: Test scenario configuration
+- **Products**: LIFX product registry
         """,
         version="1.0.0",
         contact={
@@ -96,29 +119,112 @@ The API is organized into three main routers:
                 "name": "scenarios",
                 "description": "Test scenario management",
             },
+            {
+                "name": "products",
+                "description": "LIFX product registry",
+            },
+            {
+                "name": "websocket",
+                "description": """Real-time updates via WebSocket.
+
+## Connection
+
+Connect to `ws://<host>:<port>/ws` to receive real-time updates.
+
+## Client Messages
+
+### Subscribe to Topics
+
+```json
+{"type": "subscribe", "topics": ["stats", "devices", "activity", "scenarios"]}
+```
+
+**Available topics:**
+- `stats` - Server statistics (pushed every second)
+- `devices` - Device add/remove/update events
+- `activity` - Packet activity events (requires `--activity` flag)
+- `scenarios` - Scenario configuration changes
+
+### Request Full State Sync
+
+```json
+{"type": "sync"}
+```
+
+Returns current state for all subscribed topics.
+
+## Server Messages
+
+All server messages follow this format:
+
+```json
+{"type": "<message_type>", "data": {...}}
+```
+
+### Message Types
+
+| Type | Description |
+|------|-------------|
+| `sync` | Full state response containing `stats`, `devices`, `activity`, `scenarios` |
+| `stats` | Server statistics update |
+| `device_added` | New device created |
+| `device_removed` | Device deleted (data: `{"serial": "..."}`) |
+| `device_updated` | Device state changed (data: `{serial, changes}`) |
+| `activity` | Packet activity event |
+| `scenario_changed` | Scenario configuration changed |
+| `error` | Error message (data: `{"message": "..."}`) |
+
+## Example Session
+
+```
+-> {"type": "subscribe", "topics": ["devices", "stats"]}
+-> {"type": "sync"}
+<- {"type": "sync", "data": {"stats": {...}, "devices": [...]}}
+<- {"type": "stats", "data": {"uptime_seconds": 123, ...}}
+<- {"type": "device_added", "data": {"serial": "d073d5000001", ...}}
+```
+""",
+            },
         ],
     )
 
-    @app.get("/", response_class=HTMLResponse, include_in_schema=False)
-    async def root(request: Request):
-        """Serve embedded web UI dashboard."""
-        return templates.TemplateResponse(request, "dashboard.html")
+    @app.get("/", include_in_schema=False)
+    async def root():
+        """Serve embedded Svelte dashboard."""
+        return FileResponse(STATIC_DIR / "index.html", media_type="text/html")
+
+    # Mount Svelte app assets at /_app (SvelteKit default)
+    app.mount("/_app", StaticFiles(directory=str(STATIC_DIR / "_app")), name="app")
 
-    # Mount static files for JS/CSS assets (cached by browsers)
+    # Mount static files for backward compatibility
     app.mount("/static", StaticFiles(directory=str(STATIC_DIR)), name="static")
 
+    # Store WebSocket manager in app state for access by event handlers
+    app.state.ws_manager = ws_manager
+
+    # Wire device lifecycle events to WebSocket broadcasts
+    wire_device_events(server._device_manager, ws_manager)
+
+    # Wrap the activity observer with WebSocket broadcasting
+    # This preserves activity logging while adding real-time WebSocket updates
+    server.activity_observer = WebSocketActivityObserver(
+        ws_manager, server.activity_observer
+    )
+
     # Include routers with server dependency injection
     monitoring_router = create_monitoring_router(server)
     devices_router = create_devices_router(server)
-    scenarios_router = create_scenarios_router(server)
+    scenarios_router = create_scenarios_router(server, ws_manager)
+    products_router = create_products_router()
+    websocket_router = create_websocket_router(ws_manager)
 
     app.include_router(monitoring_router)
     app.include_router(devices_router)
     app.include_router(scenarios_router)
+    app.include_router(products_router)
+    app.include_router(websocket_router)
 
-    logger.info(
-        "API application created with 3 routers (monitoring, devices, scenarios)"
-    )
+    logger.info("API application created with 5 routers")
 
     return app
 

lifx_emulator_app/api/models.py

@@ -21,7 +21,7 @@ class DeviceCreateRequest(BaseModel):
         None, description="Number of zones for multizone devices", ge=0, le=1000
     )
     tile_count: int | None = Field(
-        None, description="Number of tiles for matrix devices", ge=0, le=100
+        None, description="Number of tiles for matrix devices", ge=0, le=5
     )
     tile_width: int | None = Field(
         None, description="Width of each tile in zones", ge=1, le=256
@@ -118,6 +118,37 @@ class ActivityEvent(BaseModel):
     addr: str
 
 
+class TileColorUpdate(BaseModel):
+    """Color update for a specific tile in a matrix device."""
+
+    tile_index: int = Field(..., ge=0, le=4)
+    colors: list[ColorHsbk] = Field(..., min_length=1, max_length=1024)
+
+
+class DeviceStateUpdate(BaseModel):
+    """PATCH request body for updating device state — all fields optional."""
+
+    power_level: int | None = Field(None, ge=0, le=65535)
+    color: ColorHsbk | None = None
+    zone_colors: list[ColorHsbk] | None = Field(default=None, min_length=1)
+    tile_colors: list[TileColorUpdate] | None = Field(default=None, min_length=1)
+
+
+class BulkDeviceCreateRequest(BaseModel):
+    """Request to create multiple devices at once."""
+
+    devices: list[DeviceCreateRequest] = Field(..., min_length=1, max_length=100)
+
+
+class PaginatedDeviceList(BaseModel):
+    """Paginated list of devices."""
+
+    devices: list[DeviceInfo]
+    total: int
+    offset: int
+    limit: int
+
+
 class ScenarioResponse(BaseModel):
     """Response model for scenario operations."""
 

lifx_emulator_app/api/routers/__init__.py

@@ -2,10 +2,14 @@
 
 from lifx_emulator_app.api.routers.devices import create_devices_router
 from lifx_emulator_app.api.routers.monitoring import create_monitoring_router
+from lifx_emulator_app.api.routers.products import create_products_router
 from lifx_emulator_app.api.routers.scenarios import create_scenarios_router
+from lifx_emulator_app.api.routers.websocket import create_websocket_router
 
 __all__ = [
-    "create_monitoring_router",
     "create_devices_router",
+    "create_monitoring_router",
+    "create_products_router",
     "create_scenarios_router",
+    "create_websocket_router",
 ]

lifx_emulator_app/api/routers/devices.py

@@ -4,17 +4,24 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
-from fastapi import APIRouter, HTTPException
+from fastapi import APIRouter, HTTPException, Query
 
 if TYPE_CHECKING:
     from lifx_emulator.server import EmulatedLifxServer
 
-from lifx_emulator_app.api.models import DeviceCreateRequest, DeviceInfo
+from lifx_emulator_app.api.models import (
+    BulkDeviceCreateRequest,
+    DeviceCreateRequest,
+    DeviceInfo,
+    DeviceStateUpdate,
+    PaginatedDeviceList,
+)
 from lifx_emulator_app.api.services.device_service import (
     DeviceAlreadyExistsError,
     DeviceCreationError,
     DeviceNotFoundError,
     DeviceService,
+    DeviceStateUpdateError,
 )
 
 
@@ -35,15 +42,24 @@ def create_devices_router(server: EmulatedLifxServer) -> APIRouter:
 
     @router.get(
         "",
-        response_model=list[DeviceInfo],
+        response_model=PaginatedDeviceList,
         summary="List all devices",
         description=(
-            "Returns a list of all emulated devices with their current configuration."
+            "Returns a paginated list of all emulated devices "
+            "with their current configuration."
         ),
     )
-    async def list_devices():
-        """List all emulated devices."""
-        return device_service.list_all_devices()
+    async def list_devices(
+        offset: int = Query(0, ge=0, description="Number of devices to skip"),
+        limit: int = Query(
+            50, ge=1, le=1000, description="Maximum number of devices to return"
+        ),
+    ):
+        """List all emulated devices with pagination."""
+        devices, total = device_service.list_devices_paginated(offset, limit)
+        return PaginatedDeviceList(
+            devices=devices, total=total, offset=offset, limit=limit
+        )
 
     @router.get(
         "/{serial}",
@@ -63,6 +79,27 @@ def create_devices_router(server: EmulatedLifxServer) -> APIRouter:
         except DeviceNotFoundError as e:
             raise HTTPException(status_code=404, detail=str(e))
 
+    @router.post(
+        "/bulk",
+        response_model=list[DeviceInfo],
+        status_code=201,
+        summary="Create multiple devices",
+        description="Creates multiple emulated devices at once.",
+        responses={
+            201: {"description": "All devices created successfully"},
+            400: {"description": "Invalid product ID or parameters"},
+            409: {"description": "Duplicate serial in batch or existing device"},
+        },
+    )
+    async def create_devices_bulk(request: BulkDeviceCreateRequest):
+        """Create multiple devices at once."""
+        try:
+            return device_service.create_devices_bulk(request.devices)
+        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.post(
         "",
         response_model=DeviceInfo,
@@ -87,6 +124,26 @@ def create_devices_router(server: EmulatedLifxServer) -> APIRouter:
         except DeviceAlreadyExistsError as e:
             raise HTTPException(status_code=409, detail=str(e))
 
+    @router.patch(
+        "/{serial}/state",
+        response_model=DeviceInfo,
+        summary="Update device state",
+        description="Updates the state of an existing device. All fields are optional.",
+        responses={
+            200: {"description": "Device state updated successfully"},
+            400: {"description": "Invalid state update for device capabilities"},
+            404: {"description": "Device not found"},
+        },
+    )
+    async def update_device_state(serial: str, update: DeviceStateUpdate):
+        """Update device state."""
+        try:
+            return device_service.update_device_state(serial, update)
+        except DeviceNotFoundError as e:
+            raise HTTPException(status_code=404, detail=str(e))
+        except DeviceStateUpdateError as e:
+            raise HTTPException(status_code=400, detail=str(e))
+
     @router.delete(
         "/{serial}",
         status_code=204,
@@ -124,7 +181,4 @@ def create_devices_router(server: EmulatedLifxServer) -> APIRouter:
         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_app/api/routers/products.py

@@ -0,0 +1,42 @@
+"""Product registry endpoints."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter
+from lifx_emulator.products.registry import PRODUCTS
+
+
+def create_products_router() -> APIRouter:
+    """Create products router.
+
+    Returns:
+        Configured APIRouter for product endpoints
+    """
+    router = APIRouter(prefix="/api/products", tags=["products"])
+
+    @router.get(
+        "",
+        status_code=200,
+        summary="List all known products",
+        description="Returns a list of all LIFX products from the product registry.",
+    )
+    async def list_products():
+        """List all products from the registry."""
+        return [
+            {
+                "pid": info.pid,
+                "name": info.name,
+                "vendor": info.vendor,
+                "has_color": info.has_color,
+                "has_infrared": info.has_infrared,
+                "has_multizone": info.has_multizone,
+                "has_chain": info.has_chain,
+                "has_matrix": info.has_matrix,
+                "has_relays": info.has_relays,
+                "has_buttons": info.has_buttons,
+                "has_hev": info.has_hev,
+            }
+            for info in sorted(PRODUCTS.values(), key=lambda p: p.pid)
+        ]
+
+    return router