refactor: Give capture the same per-generation adapter as restore

export_bulk_config keeps the export envelope and the per-device loop; how one generation's component configs are captured (Gen2 GetConfig/GetCode/Schedule.List vs the Gen1 mapped-config copy plus raw /settings fetch) moves unchanged into ComponentCaptureStrategy implementations under use_cases/capture_strategies.

LEGACY_SETTINGS_KEY moves to the device_backup entity: it names part of the snapshot format, which capture and restore now both consume from the same home.

Author: jfmlima

packages/core/src/core/domain/entities/device_backup.py

@@ -5,6 +5,11 @@
 
 from core.utils.validation import normalize_mac
 
+# The raw Gen1 /settings entry captured alongside the mapped components in a
+# snapshot. It is the data source a Gen1 restore replays, never a restore
+# target itself.
+LEGACY_SETTINGS_KEY = "legacy_settings"
+
 
 @dataclass
 class DeviceBackup:

packages/core/src/core/use_cases/bulk_operations.py

@@ -7,6 +7,9 @@
 from ..domain.value_objects.action_result import ActionResult
 from ..domain.value_objects.generation import Generation
 from ..gateways.device import DeviceGateway
+from .capture_strategies import ComponentCaptureStrategy
+from .capture_strategies.gen1 import Gen1CaptureStrategy
+from .capture_strategies.gen2 import Gen2CaptureStrategy
 
 logger = logging.getLogger(__name__)
 
@@ -18,6 +21,8 @@ def __init__(
         device_gateway: DeviceGateway,
     ):
         self._device_gateway = device_gateway
+        self._gen1_capture = Gen1CaptureStrategy(device_gateway)
+        self._gen2_capture = Gen2CaptureStrategy(device_gateway)
 
     async def execute_bulk_update(
         self, device_ips: list[str], channel: str = "stable"
@@ -136,6 +141,7 @@ async def export_bulk_config(
             if not device_status:
                 continue
 
+            strategy = self._capture_strategy(device_status)
             device_data: dict[str, Any] = {
                 "device_info": {
                     "device_name": device_status.device_name,
@@ -144,120 +150,19 @@ async def export_bulk_config(
                     "mac_address": device_status.mac_address,
                     "app_name": device_status.app_name,
                 },
-                "components": {},
+                "components": await strategy.capture_components(
+                    device_ip, device_status, component_types
+                ),
             }
 
-            # Gen1 has no /rpc: GetConfig and Schedule.List 404, so capture from
-            # the configs already mapped onto the DeviceStatus instead.
-            if Generation.from_device_gen(device_status.gen) is Generation.GEN1:
-                await self._export_gen1_config(
-                    device_ip, device_status, component_types, device_data
-                )
-                result["devices"][device_ip] = device_data
-                continue
-
-            for component in device_status.components:
-                if component.component_type in component_types:
-
-                    config_result = await self._device_gateway.execute_component_action(
-                        device_ip, component.key, "GetConfig", {}
-                    )
-
-                    component_export = {
-                        "type": component.component_type,
-                        "success": config_result.success,
-                        "config": config_result.data if config_result.success else None,
-                        "error": (
-                            config_result.error if not config_result.success else None
-                        ),
-                    }
-
-                    if component.component_type == "script" and config_result.success:
-                        code_data = await self._fetch_script_code(
-                            device_ip, component.key
-                        )
-                        if code_data is not None:
-                            component_export["code"] = code_data
-
-                    device_data["components"][component.key] = component_export
-
-            if "schedules" in component_types:
-                schedules = await self._fetch_schedules(device_ip)
-                device_data["components"].update(schedules)
-
             result["devices"][device_ip] = device_data
 
         return result
 
-    async def _export_gen1_config(
-        self,
-        device_ip: str,
-        device_status: DeviceStatus,
-        component_types: list[str],
-        device_data: dict[str, Any],
-    ) -> None:
-        """Capture Gen1 component configs plus the raw ``/settings``.
-
-        The ``legacy_settings`` entry is the source of truth a Gen1 restore
-        replays; it is omitted when the raw fetch fails, and the mapped configs
-        alone still make the backup valid.
-        """
-        for component in device_status.components:
-            if component.component_type in component_types:
-                device_data["components"][component.key] = {
-                    "type": component.component_type,
-                    "success": True,
-                    "config": component.config,
-                    "error": None,
-                }
-
-        legacy_settings = await self._device_gateway.get_legacy_settings(device_ip)
-        if legacy_settings is not None:
-            device_data["components"]["legacy_settings"] = {
-                "type": "legacy_settings",
-                "success": True,
-                "config": legacy_settings,
-                "error": None,
-            }
-
-    async def _fetch_script_code(
-        self, device_ip: str, component_key: str
-    ) -> dict[str, Any] | None:
-        try:
-            script_id = int(component_key.split(":")[1])
-            code_result = await self._device_gateway.execute_component_action(
-                device_ip, component_key, "GetCode", {"id": script_id}
-            )
-            if code_result.success and code_result.data:
-                return code_result.data
-        except (ValueError, IndexError, AttributeError):
-            pass
-
-        return None
-
-    async def _fetch_schedules(self, device_ip: str) -> dict[str, Any]:
-        schedule_export = {}
-
-        list_result = await self._device_gateway.execute_component_action(
-            device_ip, "schedule", "List", {}
-        )
-        schedule_data = list_result.data
-        if list_result.success and schedule_data:
-            schedule_export["schedules"] = {
-                "type": "schedule",
-                "success": True,
-                "config": schedule_data,
-                "error": None,
-            }
-        elif not list_result.success:
-            schedule_export["schedules"] = {
-                "type": "schedule",
-                "success": False,
-                "config": None,
-                "error": list_result.error,
-            }
-
-        return schedule_export
+    def _capture_strategy(self, status: DeviceStatus) -> ComponentCaptureStrategy:
+        if Generation.from_device_gen(status.gen) is Generation.GEN1:
+            return self._gen1_capture
+        return self._gen2_capture
 
     async def apply_bulk_config(
         self,

packages/core/src/core/use_cases/capture_strategies/__init__.py

@@ -0,0 +1,23 @@
+"""Per-generation capture strategies.
+
+The capture mirror of :mod:`core.use_cases.restore_strategies`:
+``BulkOperationsUseCase.export_bulk_config`` owns the export envelope and the
+per-device loop; how one generation's component configs are captured lives
+behind ``ComponentCaptureStrategy``.
+"""
+
+from typing import Any, Protocol
+
+from core.domain.entities.device_status import DeviceStatus
+
+
+class ComponentCaptureStrategy(Protocol):
+    """One device generation's side of a config capture."""
+
+    async def capture_components(
+        self, device_ip: str, status: DeviceStatus, component_types: list[str]
+    ) -> dict[str, Any]:
+        """Captured component entries keyed by component key, in the snapshot
+        shape (``{"type", "success", "config", "error"}`` plus per-type
+        extras)."""
+        ...

packages/core/src/core/use_cases/capture_strategies/gen1.py

@@ -0,0 +1,46 @@
+"""Capture strategy for Gen1 (legacy HTTP) devices."""
+
+from typing import Any
+
+from core.domain.entities.device_backup import LEGACY_SETTINGS_KEY
+from core.domain.entities.device_status import DeviceStatus
+from core.gateways.device import DeviceGateway
+
+
+class Gen1CaptureStrategy:
+    """Capture Gen1 component configs plus the raw ``/settings``.
+
+    Gen1 has no /rpc: GetConfig and Schedule.List 404, so the mapped configs
+    already on the ``DeviceStatus`` are captured instead. The
+    ``legacy_settings`` entry is the source of truth a Gen1 restore replays;
+    it is omitted when the raw fetch fails, and the mapped configs alone still
+    make the backup valid.
+    """
+
+    def __init__(self, device_gateway: DeviceGateway):
+        self._device_gateway = device_gateway
+
+    async def capture_components(
+        self, device_ip: str, status: DeviceStatus, component_types: list[str]
+    ) -> dict[str, Any]:
+        components: dict[str, Any] = {}
+
+        for component in status.components:
+            if component.component_type in component_types:
+                components[component.key] = {
+                    "type": component.component_type,
+                    "success": True,
+                    "config": component.config,
+                    "error": None,
+                }
+
+        legacy_settings = await self._device_gateway.get_legacy_settings(device_ip)
+        if legacy_settings is not None:
+            components[LEGACY_SETTINGS_KEY] = {
+                "type": LEGACY_SETTINGS_KEY,
+                "success": True,
+                "config": legacy_settings,
+                "error": None,
+            }
+
+        return components

packages/core/src/core/use_cases/capture_strategies/gen2.py

@@ -0,0 +1,86 @@
+"""Capture strategy for Gen2+ (RPC) devices."""
+
+from typing import Any
+
+from core.domain.entities.device_status import DeviceStatus
+from core.gateways.device import DeviceGateway
+
+
+class Gen2CaptureStrategy:
+    """Capture component configs over the Gen2+ RPC surface."""
+
+    def __init__(self, device_gateway: DeviceGateway):
+        self._device_gateway = device_gateway
+
+    async def capture_components(
+        self, device_ip: str, status: DeviceStatus, component_types: list[str]
+    ) -> dict[str, Any]:
+        components: dict[str, Any] = {}
+
+        for component in status.components:
+            if component.component_type in component_types:
+
+                config_result = await self._device_gateway.execute_component_action(
+                    device_ip, component.key, "GetConfig", {}
+                )
+
+                component_export = {
+                    "type": component.component_type,
+                    "success": config_result.success,
+                    "config": config_result.data if config_result.success else None,
+                    "error": (
+                        config_result.error if not config_result.success else None
+                    ),
+                }
+
+                if component.component_type == "script" and config_result.success:
+                    code_data = await self._fetch_script_code(device_ip, component.key)
+                    if code_data is not None:
+                        component_export["code"] = code_data
+
+                components[component.key] = component_export
+
+        if "schedules" in component_types:
+            schedules = await self._fetch_schedules(device_ip)
+            components.update(schedules)
+
+        return components
+
+    async def _fetch_script_code(
+        self, device_ip: str, component_key: str
+    ) -> dict[str, Any] | None:
+        try:
+            script_id = int(component_key.split(":")[1])
+            code_result = await self._device_gateway.execute_component_action(
+                device_ip, component_key, "GetCode", {"id": script_id}
+            )
+            if code_result.success and code_result.data:
+                return code_result.data
+        except (ValueError, IndexError, AttributeError):
+            pass
+
+        return None
+
+    async def _fetch_schedules(self, device_ip: str) -> dict[str, Any]:
+        schedule_export = {}
+
+        list_result = await self._device_gateway.execute_component_action(
+            device_ip, "schedule", "List", {}
+        )
+        schedule_data = list_result.data
+        if list_result.success and schedule_data:
+            schedule_export["schedules"] = {
+                "type": "schedule",
+                "success": True,
+                "config": schedule_data,
+                "error": None,
+            }
+        elif not list_result.success:
+            schedule_export["schedules"] = {
+                "type": "schedule",
+                "success": False,
+                "config": None,
+                "error": list_result.error,
+            }
+
+        return schedule_export

packages/core/src/core/use_cases/restore_device_config.py

@@ -5,7 +5,7 @@
 from contextlib import AbstractAsyncContextManager
 from typing import Any
 
-from core.domain.entities.device_backup import DeviceBackup
+from core.domain.entities.device_backup import LEGACY_SETTINGS_KEY, DeviceBackup
 from core.domain.entities.exceptions import DeviceNotFoundError
 from core.domain.value_objects.generation import Generation
 from core.domain.value_objects.restore_result import (
@@ -15,10 +15,7 @@
 from core.gateways.device import DeviceGateway
 from core.repositories.backup_repository import BackupRepository
 from core.use_cases.backup_device_config import BackupNotFoundError
-from core.use_cases.restore_strategies import (
-    LEGACY_SETTINGS_KEY,
-    ComponentRestoreStrategy,
-)
+from core.use_cases.restore_strategies import ComponentRestoreStrategy
 from core.use_cases.restore_strategies.gen1 import Gen1RestoreStrategy
 from core.use_cases.restore_strategies.gen2 import Gen2RestoreStrategy
 from core.utils.validation import normalize_mac

packages/core/src/core/use_cases/restore_strategies/__init__.py

@@ -12,10 +12,6 @@
 from core.domain.entities.device_status import DeviceStatus
 from core.domain.value_objects.restore_result import ComponentRestoreResult
 
-# The raw Gen1 /settings entry captured alongside the mapped components. It is the
-# data source a Gen1 restore replays, never a restore target itself.
-LEGACY_SETTINGS_KEY = "legacy_settings"
-
 
 @dataclass
 class PrepareOutcome:

packages/core/src/core/use_cases/restore_strategies/gen1.py

@@ -9,15 +9,15 @@
 import asyncio
 from typing import Any
 
-from core.domain.entities.device_backup import DeviceBackup
+from core.domain.entities.device_backup import LEGACY_SETTINGS_KEY, DeviceBackup
 from core.domain.entities.device_status import DeviceStatus
 from core.domain.services.gen1_settings_translation import (
     restorable_params,
     wifi_subresources,
 )
 from core.domain.value_objects.restore_result import ComponentRestoreResult
 from core.gateways.device import DeviceGateway
-from core.use_cases.restore_strategies import LEGACY_SETTINGS_KEY, PrepareOutcome
+from core.use_cases.restore_strategies import PrepareOutcome
 
 
 class Gen1RestoreStrategy: