Self-hosted homelab infrastructure visualizer — interactive network diagram with live status monitoring
TypeScript diagramhomelabhomelab-infrastructure-observabilitynetworkproxmox-veself-hostedzigbeezwavezwave-js
fix(zigbee): stop canvas imports dying on a proxy read timeout
Pouzor0acfe3acc374
diff --git a/.env.example b/.env.exampleindex 0eb0a5f..ced130a 100644--- a/.env.example+++ b/.env.example@@ -89,6 +89,10 @@ MCP_SERVICE_KEY=svc_changeme# ZIGBEE_BASE_TOPIC=zigbee2mqtt# ZIGBEE_MQTT_TLS=false # true for TLS brokers (typically port 8883)# ZIGBEE_MQTT_TLS_INSECURE=false # skip cert verify (self-signed only; requires TLS)+# Seconds to wait for the Z2M bridge to answer a networkmap request. Applies to+# manual imports too. Raise it on a large mesh (200+ devices can take minutes)+# if an import fails with "Timed out waiting for networkmap response".+# ZIGBEE_NETWORKMAP_TIMEOUT=300# Z-Wave JS UI (zwavejs2mqtt) auto-sync — same MQTT secret/env rules as Zigbee.# ZWAVE_MQTT_HOST=192.168.1.20@@ -99,3 +103,6 @@ MCP_SERVICE_KEY=svc_changeme# ZWAVE_GATEWAY_NAME=zwavejs2mqtt# ZWAVE_MQTT_TLS=false # true for TLS brokers (typically port 8883)# ZWAVE_MQTT_TLS_INSECURE=false # skip cert verify (self-signed only; requires TLS)+# Seconds to wait for the gateway to answer an MQTT request. Same rationale as+# ZIGBEE_NETWORKMAP_TIMEOUT above.+# MQTT_RESPONSE_TIMEOUT=300diff --git a/backend/app/api/routes/zigbee.py b/backend/app/api/routes/zigbee.pyindex 37cdf13..b2dd02b 100644--- a/backend/app/api/routes/zigbee.py+++ b/backend/app/api/routes/zigbee.py@@ -19,6 +19,8 @@ from app.schemas.zigbee import (ZigbeeConfig,ZigbeeCoordinatorOut,ZigbeeEdgeOut,+ ZigbeeImportJob,+ ZigbeeImportJobResult,ZigbeeImportPendingResponse,ZigbeeImportRequest,ZigbeeImportResponse,@@ -27,6 +29,7 @@ from app.schemas.zigbee import (ZigbeeTestConnectionRequest,ZigbeeTestConnectionResponse,)+from app.services.import_jobs import create_job, fail_job, finish_job, get_jobfrom app.services.node_dedupe import dedupe_nodes_by_devicefrom app.services.zigbee_service import (build_zigbee_properties,@@ -48,18 +51,70 @@ async def _is_drawn(db: AsyncSession, device_id: str) -> bool:router = APIRouter()[email protected]("/import", response_model=ZigbeeImportResponse)+def _import_error(exc: BaseException) -> tuple[int, str]:+ """Map a fetch_networkmap failure to the (status, detail) the API reports."""+ if isinstance(exc, ImportError):+ return 500, str(exc)+ if isinstance(exc, ConnectionError):+ return 502, str(exc)+ if isinstance(exc, TimeoutError):+ return 504, str(exc)+ if isinstance(exc, ValueError):+ return 422, str(exc)+ logger.exception("Unexpected error during Zigbee import", exc_info=exc)+ return 500, "Unexpected error during Zigbee import"++[email protected]("/import", response_model=ZigbeeImportJob, status_code=202)async def import_zigbee_network(payload: ZigbeeImportRequest,+ background_tasks: BackgroundTasks,_: str = Depends(get_current_user),-) -> ZigbeeImportResponse:- """Fetch the Zigbee2MQTT network map and return nodes + edges ready for canvas drop.+) -> ZigbeeImportJob:+ """Start a canvas import and return a job id to poll.Connects to the specified MQTT broker, publishes a networkmap request to- ``<base_topic>/bridge/request/networkmap``, and waits up to 60 s for the- response (large meshes can take 30 s+). The devices are returned as typed homelable nodes with a- coordinator → router → end-device hierarchy.+ ``<base_topic>/bridge/request/networkmap`` and waits up to+ ``ZIGBEE_NETWORKMAP_TIMEOUT`` seconds (default 300) for the response.++ The fetch runs in the background and the result is collected from+ ``GET /zigbee/import/{job_id}``: a 200+ device mesh takes minutes to answer,+ which outlives the read timeout of any reverse proxy sitting in front of the+ API. Polling keeps each request short.+ """+ job = create_job()+ background_tasks.add_task(_background_canvas_import, job.id, payload)+ return ZigbeeImportJob(job_id=job.id, status=job.status)++[email protected]("/import/{job_id}", response_model=ZigbeeImportJobResult)+async def get_zigbee_import_job(+ job_id: str,+ _: str = Depends(get_current_user),+) -> ZigbeeImportJobResult:+ """Poll a canvas import started by ``POST /zigbee/import``.++ While running, returns ``status="running"`` with no payload. On success the+ nodes and edges are carried in ``result``. A failed fetch is reported as the+ status code the synchronous route used to raise, so the client keeps+ distinguishing a bad broker (502) from a slow mesh (504)."""+ job = get_job(job_id)+ if job is None:+ raise HTTPException(status_code=404, detail="Import job not found or expired")+ if job.status == "error":+ raise HTTPException(+ status_code=job.error_status or 500,+ detail=job.error or "Zigbee import failed",+ )+ result = None+ if job.status == "done" and job.result is not None:+ result = ZigbeeImportResponse(**job.result)+ return ZigbeeImportJobResult(job_id=job.id, status=job.status, result=result)+++async def _background_canvas_import(job_id: str, payload: ZigbeeImportRequest) -> None:+ """Fetch the network map and park the canvas-ready payload on the job."""try:nodes_raw, edges_raw = await fetch_networkmap(mqtt_host=payload.mqtt_host,@@ -70,21 +125,19 @@ async def import_zigbee_network(tls=payload.mqtt_tls,tls_insecure=payload.mqtt_tls_insecure,)- except ImportError as exc:- raise HTTPException(status_code=500, detail=str(exc)) from exc- except ConnectionError as exc:- raise HTTPException(status_code=502, detail=str(exc)) from exc- except TimeoutError as exc:- raise HTTPException(status_code=504, detail=str(exc)) from exc- except ValueError as exc:- raise HTTPException(status_code=422, detail=str(exc)) from excexcept Exception as exc:- logger.exception("Unexpected error during Zigbee import")- raise HTTPException(status_code=500, detail="Unexpected error during Zigbee import") from exc+ status, detail = _import_error(exc)+ fail_job(job_id, detail, status)+ returnnodes = [ZigbeeNodeOut(**n) for n in nodes_raw]edges = [ZigbeeEdgeOut(**e) for e in edges_raw]- return ZigbeeImportResponse(nodes=nodes, edges=edges, device_count=len(nodes))+ finish_job(+ job_id,+ ZigbeeImportResponse(+ nodes=nodes, edges=edges, device_count=len(nodes)+ ).model_dump(),+ )@router.post("/import-pending", response_model=ScanRunResponse)diff --git a/backend/app/core/config.py b/backend/app/core/config.pyindex 652ff72..a66280c 100644--- a/backend/app/core/config.py+++ b/backend/app/core/config.py@@ -179,6 +179,10 @@ class Settings(BaseSettings):zigbee_mqtt_tls_insecure: bool = Falsezigbee_sync_enabled: bool = Falsezigbee_sync_interval: int = 3600 # seconds (floor 300 enforced on write)+ # Seconds to wait for the Z2M bridge to answer a networkmap request. A mesh+ # of 200+ devices can take several minutes to build the map, so raise this+ # if imports fail with "Timed out waiting for networkmap response".+ zigbee_networkmap_timeout: int = 300# Z-Wave JS UI (zwavejs2mqtt) auto-sync import. Same secret/env rules.zwave_mqtt_host: str = ""@@ -192,6 +196,10 @@ class Settings(BaseSettings):zwave_sync_enabled: bool = Falsezwave_sync_interval: int = 3600 # seconds (floor 300 enforced on write)+ # Seconds to wait for any MQTT gateway request/response round-trip+ # (the Z-Wave node dump today). Same rationale as the Zigbee twin above.+ mqtt_response_timeout: int = 300+def _override_path(self) -> Path:return Path(self.sqlite_path).parent / "scan_config.json"diff --git a/backend/app/schemas/zigbee.py b/backend/app/schemas/zigbee.pyindex 9ff4f38..2edc84e 100644--- a/backend/app/schemas/zigbee.py+++ b/backend/app/schemas/zigbee.py@@ -73,6 +73,21 @@ class ZigbeeImportResponse(BaseModel):device_count: int+class ZigbeeImportJob(BaseModel):+ """Handle returned when a canvas import is queued."""++ job_id: str+ status: str # running | done | error+++class ZigbeeImportJobResult(BaseModel):+ """Poll response for a canvas import. ``result`` is set once done."""++ job_id: str+ status: str # running | done+ result: ZigbeeImportResponse | None = None++class ZigbeeTestConnectionResponse(BaseModel):connected: boolmessage: strdiff --git a/backend/app/services/import_jobs.py b/backend/app/services/import_jobs.pynew file mode 100644index 0000000..33c1301--- /dev/null+++ b/backend/app/services/import_jobs.py@@ -0,0 +1,92 @@+"""In-process registry for long-running import jobs that return a payload.++Pending imports already run in the background and report through ``scan_runs``.+Canvas imports are different: the caller wants the fetched map *back* so it can+drop it on the canvas, which kept the request open for the whole MQTT+round-trip. On a large mesh that outlives any reverse proxy's read timeout+(Cloudflare cuts at 100 s and returns a 524), so the browser never sees the+result even though the fetch succeeded server-side.++The fix is to hand the client a job id immediately and let it poll. Results are+transient — a canvas import is meaningless once the user has closed the modal —+so they live in memory rather than the DB, and expire on a TTL. The backend runs+a single uvicorn worker, the same assumption the scheduler and ``BackgroundTasks``+already make.+"""++from __future__ import annotations++import time+import uuid+from dataclasses import dataclass, field+from typing import Any, Literal++JobStatus = Literal["running", "done", "error"]++# How long a finished job stays readable. Long enough for a client that polls+# slowly or reloads mid-import, short enough that a forgotten map is not held+# for the life of the process.+JOB_TTL_SECONDS = 900.0+++@dataclass+class ImportJob:+ id: str+ status: JobStatus = "running"+ result: dict[str, Any] | None = None+ error: str | None = None+ # HTTP status the synchronous route would have raised, so the client can+ # keep reacting to failures the way it always has.+ error_status: int | None = None+ created_at: float = field(default_factory=time.monotonic)+ finished_at: float | None = None+++_jobs: dict[str, ImportJob] = {}+++def _purge_expired(now: float) -> None:+ for job_id, job in list(_jobs.items()):+ if job.finished_at is not None and now - job.finished_at > JOB_TTL_SECONDS:+ del _jobs[job_id]+++def create_job() -> ImportJob:+ """Register a new running job and return it."""+ now = time.monotonic()+ _purge_expired(now)+ job = ImportJob(id=str(uuid.uuid4()))+ _jobs[job.id] = job+ return job+++def get_job(job_id: str) -> ImportJob | None:+ """Return a job, or None if it never existed or has expired."""+ _purge_expired(time.monotonic())+ return _jobs.get(job_id)+++def finish_job(job_id: str, result: dict[str, Any]) -> None:+ """Mark a job done and attach its payload. No-op if it expired."""+ job = _jobs.get(job_id)+ if job is None:+ return+ job.status = "done"+ job.result = result+ job.finished_at = time.monotonic()+++def fail_job(job_id: str, error: str, status: int) -> None:+ """Mark a job failed with a client-safe message. No-op if it expired."""+ job = _jobs.get(job_id)+ if job is None:+ return+ job.status = "error"+ job.error = error+ job.error_status = status+ job.finished_at = time.monotonic()+++def reset_jobs() -> None:+ """Drop every job. For tests."""+ _jobs.clear()diff --git a/backend/app/services/mqtt_common.py b/backend/app/services/mqtt_common.pyindex f9e915c..c4fc534 100644--- a/backend/app/services/mqtt_common.py+++ b/backend/app/services/mqtt_common.py@@ -13,6 +13,8 @@ import loggingimport sslfrom typing import Any+from app.core.config import settings+logger = logging.getLogger(__name__)try:@@ -21,7 +23,10 @@ except ImportError: # pragma: no coveraiomqtt = None # type: ignore[assignment]_CONNECTION_TIMEOUT = 5.0 # seconds to verify broker reachability-_RESPONSE_TIMEOUT = 300.0 # seconds to wait for a gateway response (large meshes are slow)+# Fallback wait for a gateway response. The effective value comes from+# ``settings.mqtt_response_timeout`` (env MQTT_RESPONSE_TIMEOUT), read at call+# time so an operator with a large mesh can raise it without a code change.+_RESPONSE_TIMEOUT = 300.0def _sanitize_mqtt_error(exc: BaseException) -> str:@@ -71,11 +76,14 @@ async def request_response(password: str | None = None,tls: bool = False,tls_insecure: bool = False,- response_timeout: float = _RESPONSE_TIMEOUT,+ response_timeout: float | None = None,) -> dict[str, Any]:"""Publish ``request_payload`` to ``request_topic`` and return the firstJSON message received on ``response_topic`` as a dict.+ ``response_timeout`` defaults to ``settings.mqtt_response_timeout``+ (env ``MQTT_RESPONSE_TIMEOUT``, 300 s) — a large mesh can take minutes.+Raises:ImportError: if aiomqtt is not installed.TimeoutError: if no response arrives in time.@@ -88,6 +96,14 @@ async def request_response("Install it with: pip install aiomqtt")+ timeout = (+ float(settings.mqtt_response_timeout)+ if response_timeout is None+ else response_timeout+ )+ if timeout <= 0:+ timeout = _RESPONSE_TIMEOUT+response_payload: dict[str, Any] = {}tls_context = _build_tls_context(tls_insecure) if tls else None@@ -122,12 +138,15 @@ async def request_response(raise ValueError(f"Malformed MQTT response: {exc}") from excreturn- await asyncio.wait_for(_wait_for_response(), timeout=response_timeout)+ await asyncio.wait_for(_wait_for_response(), timeout=timeout)except aiomqtt.MqttError as exc:raise ConnectionError(_sanitize_mqtt_error(exc)) from excexcept asyncio.TimeoutError as exc:- raise TimeoutError("Timed out waiting for MQTT response") from exc+ raise TimeoutError(+ f"Timed out waiting for MQTT response after {timeout:g}s — "+ "raise MQTT_RESPONSE_TIMEOUT if your mesh is large"+ ) from excif not response_payload:raise ValueError("Empty MQTT response received")diff --git a/backend/app/services/zigbee_service.py b/backend/app/services/zigbee_service.pyindex 93b1bdb..085ee2b 100644--- a/backend/app/services/zigbee_service.py+++ b/backend/app/services/zigbee_service.py@@ -7,6 +7,7 @@ import jsonimport loggingfrom typing import Any+from app.core.config import settingsfrom app.services.mqtt_common import _build_tls_context, _sanitize_mqtt_errorlogger = logging.getLogger(__name__)@@ -19,7 +20,10 @@ except ImportError: # pragma: no cover_NETWORKMAP_REQUEST_TOPIC = "{base_topic}/bridge/request/networkmap"_NETWORKMAP_RESPONSE_TOPIC = "{base_topic}/bridge/response/networkmap"_CONNECTION_TIMEOUT = 5.0 # seconds to verify broker reachability-_NETWORKMAP_TIMEOUT = 300.0 # seconds to wait for the networkmap response (large meshes can be slow)+# Fallback wait for the networkmap response. The effective value comes from+# ``settings.zigbee_networkmap_timeout`` (env ZIGBEE_NETWORKMAP_TIMEOUT), read at+# call time so an operator with a large mesh can raise it without a code change.+_NETWORKMAP_TIMEOUT = 300.0# Re-exported for backwards compatibility — these now live in mqtt_common.__all__ = ["_build_tls_context", "_sanitize_mqtt_error"]@@ -238,9 +242,14 @@ async def fetch_networkmap(password: str | None = None,tls: bool = False,tls_insecure: bool = False,+ response_timeout: float | None = None,) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:"""Connect to the MQTT broker, request the Z2M networkmap, and return (nodes, edges).+ ``response_timeout`` defaults to ``settings.zigbee_networkmap_timeout``+ (env ``ZIGBEE_NETWORKMAP_TIMEOUT``, 300 s) — a 200+ device mesh can take+ minutes to answer.+Raises:TimeoutError: if the broker does not respond in time.ConnectionError: if the broker cannot be reached.@@ -252,6 +261,14 @@ async def fetch_networkmap("Install it with: pip install aiomqtt")+ timeout = (+ float(settings.zigbee_networkmap_timeout)+ if response_timeout is None+ else response_timeout+ )+ if timeout <= 0:+ timeout = _NETWORKMAP_TIMEOUT+request_topic = _NETWORKMAP_REQUEST_TOPIC.format(base_topic=base_topic)response_topic = _NETWORKMAP_RESPONSE_TOPIC.format(base_topic=base_topic)@@ -295,12 +312,15 @@ async def fetch_networkmap() from excreturn- await asyncio.wait_for(_wait_for_response(), timeout=_NETWORKMAP_TIMEOUT)+ await asyncio.wait_for(_wait_for_response(), timeout=timeout)except aiomqtt.MqttError as exc:raise ConnectionError(_sanitize_mqtt_error(exc)) from excexcept asyncio.TimeoutError as exc:- raise TimeoutError("Timed out waiting for networkmap response") from exc+ raise TimeoutError(+ f"Timed out waiting for networkmap response after {timeout:g}s — "+ "raise ZIGBEE_NETWORKMAP_TIMEOUT if your mesh is large"+ ) from excif not response_payload:raise ValueError("Empty networkmap response received")diff --git a/backend/tests/test_import_jobs.py b/backend/tests/test_import_jobs.pynew file mode 100644index 0000000..169111c--- /dev/null+++ b/backend/tests/test_import_jobs.py@@ -0,0 +1,90 @@+"""Unit tests for the in-process canvas-import job registry."""++from __future__ import annotations++import pytest++from app.services import import_jobs+from app.services.import_jobs import (+ create_job,+ fail_job,+ finish_job,+ get_job,+ reset_jobs,+)++[email protected](autouse=True)+def _clean() -> None:+ reset_jobs()+++def test_create_job_starts_running_with_unique_id() -> None:+ a = create_job()+ b = create_job()+ assert a.id != b.id+ assert a.status == "running"+ assert a.result is None+ assert a.error is None+++def test_get_job_returns_the_registered_job() -> None:+ job = create_job()+ assert get_job(job.id) is job+++def test_get_unknown_job_returns_none() -> None:+ assert get_job("nope") is None+++def test_finish_job_records_the_payload() -> None:+ job = create_job()+ finish_job(job.id, {"device_count": 3})+ stored = get_job(job.id)+ assert stored is not None+ assert stored.status == "done"+ assert stored.result == {"device_count": 3}+ assert stored.finished_at is not None+++def test_fail_job_records_message_and_status() -> None:+ job = create_job()+ fail_job(job.id, "broker unreachable", 502)+ stored = get_job(job.id)+ assert stored is not None+ assert stored.status == "error"+ assert stored.error == "broker unreachable"+ assert stored.error_status == 502+++def test_finish_and_fail_are_noops_for_unknown_ids() -> None:+ finish_job("gone", {"device_count": 0})+ fail_job("gone", "boom", 500)+ assert get_job("gone") is None+++def test_finished_jobs_expire_after_the_ttl(monkeypatch) -> None:+ clock = {"now": 0.0}+ monkeypatch.setattr(import_jobs.time, "monotonic", lambda: clock["now"])++ job = create_job()+ finish_job(job.id, {"device_count": 1})++ clock["now"] = import_jobs.JOB_TTL_SECONDS + 1+ assert get_job(job.id) is None+++def test_running_jobs_never_expire(monkeypatch) -> None:+ """A slow mesh must not have its job purged out from under it."""+ clock = {"now": 0.0}+ monkeypatch.setattr(import_jobs.time, "monotonic", lambda: clock["now"])++ job = create_job()+ clock["now"] = import_jobs.JOB_TTL_SECONDS * 10+ assert get_job(job.id) is not None+++def test_reset_jobs_clears_everything() -> None:+ job = create_job()+ reset_jobs()+ assert get_job(job.id) is Nonediff --git a/backend/tests/test_mqtt_common.py b/backend/tests/test_mqtt_common.pyindex cd18675..a0c16fc 100644--- a/backend/tests/test_mqtt_common.py+++ b/backend/tests/test_mqtt_common.py@@ -2,13 +2,16 @@from __future__ import annotations+import asyncioimport jsonimport sslfrom unittest.mock import patchimport pytest+from app.core.config import settingsfrom app.services.mqtt_common import (+ _RESPONSE_TIMEOUT,_build_tls_context,_sanitize_mqtt_error,request_response,@@ -181,3 +184,100 @@ async def test_test_connection_failure() -> None:mock_aiomqtt.MqttError = Exceptionwith pytest.raises(ConnectionError):await _test_connection("bad", 1883)+++# ---------------------------------------------------------------------------+# Response timeout — configurable via MQTT_RESPONSE_TIMEOUT (issue #380)+# ---------------------------------------------------------------------------+++class _SilentClient:+ """An MQTT client that connects but never delivers the response message."""++ async def __aenter__(self):+ return self++ async def __aexit__(self, *_):+ pass++ async def subscribe(self, *_a, **_kw) -> None:+ pass++ async def publish(self, *_a, **_kw) -> None:+ pass++ @property+ def messages(self):+ async def _never():+ await asyncio.Event().wait()+ yield # pragma: no cover++ return _never()+++class _NeverMqttError(Exception):+ """Stand-in for aiomqtt.MqttError that no test path actually raises."""+++async def _round_trip(**kwargs):+ return await request_response(+ mqtt_host="host",+ mqtt_port=1883,+ request_topic="req",+ response_topic="res",+ request_payload={},+ **kwargs,+ )+++async def test_request_response_uses_settings_timeout(monkeypatch) -> None:+ monkeypatch.setattr(settings, "mqtt_response_timeout", 0.01)++ with patch("app.services.mqtt_common.aiomqtt") as mock_aiomqtt:+ mock_aiomqtt.Client.return_value = _SilentClient()+ mock_aiomqtt.MqttError = _NeverMqttError++ with pytest.raises(TimeoutError) as ei:+ await _round_trip()++ msg = str(ei.value)+ assert "0.01s" in msg+ assert "MQTT_RESPONSE_TIMEOUT" in msg+++async def test_request_response_explicit_timeout_overrides_settings(monkeypatch) -> None:+ monkeypatch.setattr(settings, "mqtt_response_timeout", 999)++ with patch("app.services.mqtt_common.aiomqtt") as mock_aiomqtt:+ mock_aiomqtt.Client.return_value = _SilentClient()+ mock_aiomqtt.MqttError = _NeverMqttError++ with pytest.raises(TimeoutError) as ei:+ await _round_trip(response_timeout=0.01)++ assert "0.01s" in str(ei.value)+++async def test_request_response_non_positive_setting_falls_back(monkeypatch) -> None:+ """A misconfigured 0 must not mean 'give up immediately'."""+ monkeypatch.setattr(settings, "mqtt_response_timeout", 0)+ captured: dict[str, float] = {}++ async def _fake_wait_for(awaitable, timeout):+ captured["timeout"] = timeout+ awaitable.close()+ raise asyncio.TimeoutError++ with patch("app.services.mqtt_common.aiomqtt") as mock_aiomqtt:+ mock_aiomqtt.Client.return_value = _SilentClient()+ mock_aiomqtt.MqttError = _NeverMqttError+ with (+ patch("app.services.mqtt_common.asyncio.wait_for", _fake_wait_for),+ pytest.raises(TimeoutError),+ ):+ await _round_trip()++ assert captured["timeout"] == _RESPONSE_TIMEOUTdiff --git a/backend/tests/test_zigbee_router.py b/backend/tests/test_zigbee_router.pyindex a439896..79408cb 100644--- a/backend/tests/test_zigbee_router.py+++ b/backend/tests/test_zigbee_router.py@@ -7,10 +7,34 @@ from unittest.mock import AsyncMock, patchimport pytestfrom httpx import AsyncClient+from app.services.import_jobs import reset_jobs+# ---------------------------------------------------------------------------# Fixtures# ---------------------------------------------------------------------------+[email protected](autouse=True)+def _clear_import_jobs() -> None:+ """The canvas-import job registry is process-global; isolate each test."""+ reset_jobs()+++async def _start_canvas_import(+ client: AsyncClient, headers: dict, body: dict+) -> str:+ """POST /zigbee/import and return the job id.++ The route is fire-and-poll: it answers 202 immediately and the fetch runs as+ a Starlette background task, which the ASGI transport completes before this+ await returns — so the job is already settled by the time we poll.+ """+ res = await client.post("/api/v1/zigbee/import", json=body, headers=headers)+ assert res.status_code == 202, res.text+ job_id: str = res.json()["job_id"]+ assert res.json()["status"] == "running"+ return job_id+# ---------------------------------------------------------------------------# /api/v1/zigbee/test-connection# ---------------------------------------------------------------------------@@ -104,18 +128,18 @@ _SAMPLE_EDGES = [async def test_import_success(client: AsyncClient, headers: dict) -> None:with patch("app.api.routes.zigbee.fetch_networkmap") as mock_fetch:mock_fetch.return_value = (_SAMPLE_NODES, _SAMPLE_EDGES)- res = await client.post(- "/api/v1/zigbee/import",- json={- "mqtt_host": "localhost",- "mqtt_port": 1883,- "base_topic": "zigbee2mqtt",- },- headers=headers,+ job_id = await _start_canvas_import(+ client,+ headers,+ {"mqtt_host": "localhost", "mqtt_port": 1883, "base_topic": "zigbee2mqtt"},)+ res = await client.get(f"/api/v1/zigbee/import/{job_id}", headers=headers)assert res.status_code == 200- data = res.json()+ body = res.json()+ assert body["status"] == "done"+ assert body["job_id"] == job_id+ data = body["result"]assert data["device_count"] == 2assert len(data["nodes"]) == 2assert len(data["edges"]) == 1@@ -124,21 +148,56 @@ async def test_import_success(client: AsyncClient, headers: dict) -> None:@pytest.mark.asyncio-async def test_import_with_credentials(client: AsyncClient, headers: dict) -> None:+async def test_import_post_does_not_block_on_the_fetch(+ client: AsyncClient, headers: dict+) -> None:+ """The POST answers 202 without a payload — that is what keeps a slow mesh+ from outliving a reverse proxy's read timeout (issue #380)."""with patch("app.api.routes.zigbee.fetch_networkmap") as mock_fetch:- mock_fetch.return_value = ([], [])+ mock_fetch.return_value = (_SAMPLE_NODES, _SAMPLE_EDGES)res = await client.post("/api/v1/zigbee/import",- json={+ json={"mqtt_host": "localhost", "mqtt_port": 1883},+ headers=headers,+ )+ assert res.status_code == 202+ assert set(res.json()) == {"job_id", "status"}+++async def test_import_job_unknown_id_returns_404(+ client: AsyncClient, headers: dict+) -> None:+ res = await client.get("/api/v1/zigbee/import/no-such-job", headers=headers)+ assert res.status_code == 404+++async def test_import_job_requires_auth(client: AsyncClient, headers: dict) -> None:+ with patch("app.api.routes.zigbee.fetch_networkmap") as mock_fetch:+ mock_fetch.return_value = ([], [])+ job_id = await _start_canvas_import(+ client, headers, {"mqtt_host": "localhost", "mqtt_port": 1883}+ )+ res = await client.get(f"/api/v1/zigbee/import/{job_id}")+ assert res.status_code == 401+++async def test_import_with_credentials(client: AsyncClient, headers: dict) -> None:+ with patch("app.api.routes.zigbee.fetch_networkmap") as mock_fetch:+ mock_fetch.return_value = ([], [])+ await _start_canvas_import(+ client,+ headers,+ {"mqtt_host": "localhost","mqtt_port": 1883,"mqtt_username": "admin","mqtt_password": "secret","base_topic": "z2m",},- headers=headers,)- assert res.status_code == 200mock_fetch.assert_called_once_with(mqtt_host="localhost",mqtt_port=1883,@@ -154,11 +213,10 @@ async def test_import_with_credentials(client: AsyncClient, headers: dict) -> Noasync def test_import_connection_error_returns_502(client: AsyncClient, headers: dict) -> None:with patch("app.api.routes.zigbee.fetch_networkmap") as mock_fetch:mock_fetch.side_effect = ConnectionError("broker unreachable")- res = await client.post(- "/api/v1/zigbee/import",- json={"mqtt_host": "bad-host", "mqtt_port": 1883},- headers=headers,+ job_id = await _start_canvas_import(+ client, headers, {"mqtt_host": "bad-host", "mqtt_port": 1883})+ res = await client.get(f"/api/v1/zigbee/import/{job_id}", headers=headers)assert res.status_code == 502assert "broker unreachable" in res.json()["detail"]@@ -167,23 +225,22 @@ async def test_import_connection_error_returns_502(client: AsyncClient, headers:async def test_import_timeout_returns_504(client: AsyncClient, headers: dict) -> None:with patch("app.api.routes.zigbee.fetch_networkmap") as mock_fetch:mock_fetch.side_effect = TimeoutError("timed out")- res = await client.post(- "/api/v1/zigbee/import",- json={"mqtt_host": "localhost", "mqtt_port": 1883},- headers=headers,+ job_id = await _start_canvas_import(+ client, headers, {"mqtt_host": "localhost", "mqtt_port": 1883})+ res = await client.get(f"/api/v1/zigbee/import/{job_id}", headers=headers)assert res.status_code == 504+ assert "timed out" in res.json()["detail"]@pytest.mark.asyncioasync def test_import_malformed_payload_returns_422(client: AsyncClient, headers: dict) -> None:with patch("app.api.routes.zigbee.fetch_networkmap") as mock_fetch:mock_fetch.side_effect = ValueError("malformed response")- res = await client.post(- "/api/v1/zigbee/import",- json={"mqtt_host": "localhost", "mqtt_port": 1883},- headers=headers,+ job_id = await _start_canvas_import(+ client, headers, {"mqtt_host": "localhost", "mqtt_port": 1883})+ res = await client.get(f"/api/v1/zigbee/import/{job_id}", headers=headers)assert res.status_code == 422@@ -201,13 +258,12 @@ async def test_import_empty_network(client: AsyncClient, headers: dict) -> None:"""An empty Zigbee network (coordinator only) is a valid response."""with patch("app.api.routes.zigbee.fetch_networkmap") as mock_fetch:mock_fetch.return_value = ([], [])- res = await client.post(- "/api/v1/zigbee/import",- json={"mqtt_host": "localhost", "mqtt_port": 1883},- headers=headers,+ job_id = await _start_canvas_import(+ client, headers, {"mqtt_host": "localhost", "mqtt_port": 1883})+ res = await client.get(f"/api/v1/zigbee/import/{job_id}", headers=headers)assert res.status_code == 200- data = res.json()+ data = res.json()["result"]assert data["device_count"] == 0assert data["nodes"] == []assert data["edges"] == []@@ -227,16 +283,11 @@ async def test_import_missing_mqtt_host(client: AsyncClient, headers: dict) -> Nasync def test_import_with_tls_passes_flags(client: AsyncClient, headers: dict) -> None:with patch("app.api.routes.zigbee.fetch_networkmap") as mock_fetch:mock_fetch.return_value = ([], [])- res = await client.post(- "/api/v1/zigbee/import",- json={- "mqtt_host": "broker.example.com",- "mqtt_port": 8883,- "mqtt_tls": True,- },- headers=headers,+ await _start_canvas_import(+ client,+ headers,+ {"mqtt_host": "broker.example.com", "mqtt_port": 8883, "mqtt_tls": True},)- assert res.status_code == 200kwargs = mock_fetch.call_args.kwargsassert kwargs["tls"] is Trueassert kwargs["tls_insecure"] is Falsediff --git a/backend/tests/test_zigbee_service.py b/backend/tests/test_zigbee_service.pyindex 39ee260..1702379 100644--- a/backend/tests/test_zigbee_service.py+++ b/backend/tests/test_zigbee_service.py@@ -2,6 +2,7 @@from __future__ import annotations+import asyncioimport jsonfrom typing import Anyfrom unittest.mock import patch@@ -9,7 +10,9 @@ from unittest.mock import patchimport aiomqtt # noqa: F401import pytest+from app.core.config import settingsfrom app.services.zigbee_service import (+ _NETWORKMAP_TIMEOUT,_find_parent_router,_z2m_type_to_homelable,fetch_networkmap,@@ -433,6 +436,10 @@ async def test_test_mqtt_connection_failure() -> None:await _test_mqtt_connection("bad-host", 1883)+class _NeverMqttError(Exception):+ """Stand-in for aiomqtt.MqttError that no test path actually raises."""++# ---------------------------------------------------------------------------# TLS context# ---------------------------------------------------------------------------@@ -571,3 +578,95 @@ async def test_fetch_networkmap_does_not_leak_creds_in_connection_error() -> Nonassert "hunter2" not in msgassert "admin" not in msgassert msg == "Authentication failed"+++# ---------------------------------------------------------------------------+# Networkmap response timeout — configurable via ZIGBEE_NETWORKMAP_TIMEOUT+# (issue #380: a 200+ device mesh needs longer than the hard-coded 300 s)+# ---------------------------------------------------------------------------+++class _SilentClient:+ """An MQTT client that connects but never delivers the response message."""++ async def __aenter__(self):+ return self++ async def __aexit__(self, *_):+ pass++ async def subscribe(self, *_a, **_kw) -> None:+ pass++ async def publish(self, *_a, **_kw) -> None:+ pass++ @property+ def messages(self):+ async def _never():+ await asyncio.Event().wait()+ yield # pragma: no cover++ return _never()+++async def test_fetch_networkmap_uses_settings_timeout(monkeypatch) -> None:+ monkeypatch.setattr(settings, "zigbee_networkmap_timeout", 0.01)++ with patch("app.services.zigbee_service.aiomqtt") as mock_aiomqtt:+ mock_aiomqtt.Client.return_value = _SilentClient()+ mock_aiomqtt.MqttError = _NeverMqttError++ with pytest.raises(TimeoutError) as ei:+ await fetch_networkmap(+ mqtt_host="host", mqtt_port=1883, base_topic="zigbee2mqtt"+ )++ msg = str(ei.value)+ assert "0.01s" in msg+ assert "ZIGBEE_NETWORKMAP_TIMEOUT" in msg+++async def test_fetch_networkmap_explicit_timeout_overrides_settings(monkeypatch) -> None:+ monkeypatch.setattr(settings, "zigbee_networkmap_timeout", 999)++ with patch("app.services.zigbee_service.aiomqtt") as mock_aiomqtt:+ mock_aiomqtt.Client.return_value = _SilentClient()+ mock_aiomqtt.MqttError = _NeverMqttError++ with pytest.raises(TimeoutError) as ei:+ await fetch_networkmap(+ mqtt_host="host",+ mqtt_port=1883,+ base_topic="zigbee2mqtt",+ response_timeout=0.01,+ )++ assert "0.01s" in str(ei.value)+++async def test_fetch_networkmap_non_positive_setting_falls_back(monkeypatch) -> None:+ """A misconfigured 0 must not mean 'give up immediately'."""+ monkeypatch.setattr(settings, "zigbee_networkmap_timeout", 0)+ captured: dict[str, float] = {}++ async def _fake_wait_for(awaitable, timeout):+ captured["timeout"] = timeout+ awaitable.close()+ raise asyncio.TimeoutError++ with patch("app.services.zigbee_service.aiomqtt") as mock_aiomqtt:+ mock_aiomqtt.Client.return_value = _SilentClient()+ mock_aiomqtt.MqttError = _NeverMqttError+ with (+ patch("app.services.zigbee_service.asyncio.wait_for", _fake_wait_for),+ pytest.raises(TimeoutError),+ ):+ await fetch_networkmap(+ mqtt_host="host", mqtt_port=1883, base_topic="zigbee2mqtt"+ )++ assert captured["timeout"] == _NETWORKMAP_TIMEOUTdiff --git a/docs/zigbee-import.md b/docs/zigbee-import.mdindex 1de33ee..e55a6d7 100644--- a/docs/zigbee-import.md+++ b/docs/zigbee-import.md@@ -55,9 +55,25 @@ Click **Fetch Devices**. Homelable will:1. Connect to the broker2. Subscribe to the response topic3. Publish `{"type": "raw", "routes": false}` to the request topic-4. Wait up to 60 seconds for the network map response (large meshes can take 30 s+)+4. Wait up to `ZIGBEE_NETWORKMAP_TIMEOUT` seconds (default 300) for the network map response5. Parse and group devices by type+The fetch runs server-side and the browser polls for the result, so a mesh that+takes minutes to answer cannot be cut short by a reverse proxy's read timeout.++### Large meshes and timeouts++A network of 200+ devices can take several minutes to build its map. Two knobs:++| Variable | Default | What it bounds |+|---|---|---|+| `ZIGBEE_NETWORKMAP_TIMEOUT` | `300` | Seconds to wait for the Z2M bridge to answer a networkmap request. Raise it if an import fails with *Timed out waiting for networkmap response*. |+| `MQTT_RESPONSE_TIMEOUT` | `300` | The same bound for the Z-Wave MQTT round-trip. |++Both apply to manual imports and to auto-sync. If you reverse-proxy the API,+these are the only timeouts that matter — the import request itself returns+immediately.+### 5. Select and add to canvasDevices are grouped by type (Coordinator / Router / End Device).diff --git a/frontend/src/api/__tests__/client.test.ts b/frontend/src/api/__tests__/client.test.tsindex 3cda64d..98f462c 100644--- a/frontend/src/api/__tests__/client.test.ts+++ b/frontend/src/api/__tests__/client.test.ts@@ -242,6 +242,11 @@ describe('api/client', () => {expect(api.post).toHaveBeenCalledWith('/zigbee/import-pending', cfg)})+ it('zigbeeApi.getImportJob polls the job by id', () => {+ mod.zigbeeApi.getImportJob('job-1')+ expect(api.get).toHaveBeenCalledWith('/zigbee/import/job-1')+ })+it('zwaveApi.testConnection/importNetwork/importToPending', () => {const cfg = { mqtt_host: 'h', mqtt_port: 1883, prefix: 'zwave', gateway_name: 'zwavejs2mqtt' }mod.zwaveApi.testConnection(cfg)diff --git a/frontend/src/api/client.ts b/frontend/src/api/client.tsindex 392c755..d3bbb22 100644--- a/frontend/src/api/client.ts+++ b/frontend/src/api/client.ts@@ -305,6 +305,8 @@ export const racksApi = {}),}+export type ZigbeeImportJobStatus = 'running' | 'done' | 'error'+export interface ZigbeeConfigData {mqtt_host: stringmqtt_port: number@@ -358,11 +360,20 @@ export const zigbeeApi = {mqtt_tls?: booleanmqtt_tls_insecure?: boolean}) =>- api.post<{- nodes: import('@/components/zigbee/types').ZigbeeNode[]- edges: import('@/components/zigbee/types').ZigbeeEdge[]- device_count: number- }>('/zigbee/import', data),+ api.post<{ job_id: string; status: ZigbeeImportJobStatus }>('/zigbee/import', data),++ // Poll a canvas import started by importNetwork. The fetch runs server-side+ // so a slow mesh cannot outlive a reverse proxy's read timeout.+ getImportJob: (jobId: string) =>+ api.get<{+ job_id: string+ status: ZigbeeImportJobStatus+ result: {+ nodes: import('@/components/zigbee/types').ZigbeeNode[]+ edges: import('@/components/zigbee/types').ZigbeeEdge[]+ device_count: number+ } | null+ }>(`/zigbee/import/${jobId}`),importToPending: (data: {mqtt_host: stringdiff --git a/frontend/src/components/zigbee/ZigbeeImportModal.tsx b/frontend/src/components/zigbee/ZigbeeImportModal.tsxindex 6172581..f18f551 100644--- a/frontend/src/components/zigbee/ZigbeeImportModal.tsx+++ b/frontend/src/components/zigbee/ZigbeeImportModal.tsx@@ -1,10 +1,11 @@-import { useState } from 'react'+import { useEffect, useRef, useState } from 'react'import { Network, Router, Cpu, CheckCircle2, XCircle, Loader2, Plus } from 'lucide-react'import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogFooter } from '@/components/ui/dialog'import { Button } from '@/components/ui/button'import { Input } from '@/components/ui/input'import { Label } from '@/components/ui/label'import { zigbeeApi } from '@/api/client'+import { pollImportJob, PollAbortedError } from '@/utils/importJobPoll'import { toast } from 'sonner'import type { ZigbeeNode, ZigbeeEdge } from './types'@@ -68,6 +69,10 @@ export function ZigbeeImportModal({ open, onClose, onAddToCanvas, onInventoryImpconst [edges, setEdges] = useState<ZigbeeEdge[]>([])const [checked, setChecked] = useState<Set<string>>(new Set())const [importMode, setImportMode] = useState<ImportMode>('pending')+ // Aborts the canvas-import poll loop when the modal closes or unmounts.+ const pollAbort = useRef<AbortController | null>(null)++ useEffect(() => () => pollAbort.current?.abort(), [])const updateField = (field: keyof ConnectionForm, value: string) =>setForm((f) => ({@@ -143,17 +148,27 @@ export function ZigbeeImportModal({ open, onClose, onAddToCanvas, onInventoryImponInventoryImported?.(null)handleClose()} else {- const res = await zigbeeApi.importNetwork(buildPayload())- setDevices(res.data.nodes)- setEdges(res.data.edges)- setChecked(new Set(res.data.nodes.map((n) => n.id)))- if (res.data.device_count === 0) {+ // The backend fetches the network map in the background and we poll for+ // it — a large mesh takes minutes, which no reverse proxy will hold open.+ pollAbort.current?.abort()+ const controller = new AbortController()+ pollAbort.current = controller+ const start = await zigbeeApi.importNetwork(buildPayload())+ const result = await pollImportJob(+ async () => (await zigbeeApi.getImportJob(start.data.job_id)).data,+ { signal: controller.signal },+ )+ setDevices(result.nodes)+ setEdges(result.edges)+ setChecked(new Set(result.nodes.map((n) => n.id)))+ if (result.device_count === 0) {toast.info('No Zigbee devices found in the network map')} else {- toast.success(`Found ${res.data.device_count} device${res.data.device_count !== 1 ? 's' : ''}`)+ toast.success(`Found ${result.device_count} device${result.device_count !== 1 ? 's' : ''}`)}}} catch (err: unknown) {+ if (err instanceof PollAbortedError) returntoast.error(extractError(err) ?? 'Failed to fetch Zigbee devices')} finally {setLoading(false)@@ -181,6 +196,8 @@ export function ZigbeeImportModal({ open, onClose, onAddToCanvas, onInventoryImp}const handleClose = () => {+ pollAbort.current?.abort()+ pollAbort.current = nullsetDevices([])setEdges([])setChecked(new Set())diff --git a/frontend/src/components/zigbee/__tests__/ZigbeeImportModal.test.tsx b/frontend/src/components/zigbee/__tests__/ZigbeeImportModal.test.tsxindex 3e8f960..f5cea9e 100644--- a/frontend/src/components/zigbee/__tests__/ZigbeeImportModal.test.tsx+++ b/frontend/src/components/zigbee/__tests__/ZigbeeImportModal.test.tsx@@ -1,11 +1,12 @@import { describe, it, expect, vi, beforeEach } from 'vitest'-import { render, screen, fireEvent, waitFor } from '@testing-library/react'+import { render, screen, fireEvent, waitFor, act } from '@testing-library/react'import { ZigbeeImportModal } from '../ZigbeeImportModal'vi.mock('@/api/client', () => ({zigbeeApi: {testConnection: vi.fn(),importNetwork: vi.fn(),+ getImportJob: vi.fn(),importToPending: vi.fn(),},}))@@ -51,6 +52,7 @@ describe('ZigbeeImportModal', () => {beforeEach(() => {vi.mocked(zigbeeApi.testConnection).mockReset()vi.mocked(zigbeeApi.importNetwork).mockReset()+ vi.mocked(zigbeeApi.getImportJob).mockReset()vi.mocked(zigbeeApi.importToPending).mockReset()vi.mocked(toast.success).mockReset()vi.mocked(toast.error).mockReset()@@ -115,16 +117,33 @@ describe('ZigbeeImportModal', () => {fireEvent.click(screen.getByRole('radio', { name: /canvas directly/i }))}- it('fetches devices and renders them grouped by type', async () => {+ /** A canvas import now answers with a job id; the payload arrives from a poll. */+ const mockCanvasImport = (result: {+ nodes: typeof sampleNodes+ edges: { source: string; target: string }[]+ device_count: number+ }) => {vi.mocked(zigbeeApi.importNetwork).mockResolvedValue({- data: { nodes: sampleNodes, edges: [], device_count: 2 },+ data: { job_id: 'job-1', status: 'running' },+ } as never)+ vi.mocked(zigbeeApi.getImportJob).mockResolvedValue({+ data: { job_id: 'job-1', status: 'done', result },} as never)+ }+ const startCanvasFetch = () => {render(<ZigbeeImportModal {...defaultProps} />)selectCanvasMode()- const hostInput = screen.getByPlaceholderText('192.168.1.x or mqtt.local')- fireEvent.change(hostInput, { target: { value: '192.168.1.100' } })+ fireEvent.change(screen.getByPlaceholderText('192.168.1.x or mqtt.local'), {+ target: { value: '192.168.1.100' },+ })fireEvent.click(screen.getByRole('button', { name: /fetch devices/i }))+ }++ it('fetches devices and renders them grouped by type', async () => {+ mockCanvasImport({ nodes: sampleNodes, edges: [], device_count: 2 })++ startCanvasFetch()await waitFor(() => {expect(screen.getByText('Coordinator')).toBeDefined()@@ -134,15 +153,9 @@ describe('ZigbeeImportModal', () => {})it('shows info toast when no devices found', async () => {- vi.mocked(zigbeeApi.importNetwork).mockResolvedValue({- data: { nodes: [], edges: [], device_count: 0 },- } as never)+ mockCanvasImport({ nodes: [], edges: [], device_count: 0 })- render(<ZigbeeImportModal {...defaultProps} />)- selectCanvasMode()- const hostInput = screen.getByPlaceholderText('192.168.1.x or mqtt.local')- fireEvent.change(hostInput, { target: { value: '192.168.1.100' } })- fireEvent.click(screen.getByRole('button', { name: /fetch devices/i }))+ startCanvasFetch()await waitFor(() => {expect(toast.info).toHaveBeenCalledWith('No Zigbee devices found in the network map')@@ -150,15 +163,13 @@ describe('ZigbeeImportModal', () => {})it('calls onAddToCanvas with selected devices and closes modal', async () => {- vi.mocked(zigbeeApi.importNetwork).mockResolvedValue({- data: { nodes: sampleNodes, edges: [{ source: '0x0000', target: '0x0001' }], device_count: 2 },- } as never)+ mockCanvasImport({+ nodes: sampleNodes,+ edges: [{ source: '0x0000', target: '0x0001' }],+ device_count: 2,+ })- render(<ZigbeeImportModal {...defaultProps} />)- selectCanvasMode()- const hostInput = screen.getByPlaceholderText('192.168.1.x or mqtt.local')- fireEvent.change(hostInput, { target: { value: '192.168.1.100' } })- fireEvent.click(screen.getByRole('button', { name: /fetch devices/i }))+ startCanvasFetch()await waitFor(() => screen.getByText('Coordinator'))@@ -207,17 +218,81 @@ describe('ZigbeeImportModal', () => {})it('switching to canvas mode calls importNetwork and not importToPending', async () => {+ mockCanvasImport({ nodes: sampleNodes, edges: [], device_count: 2 })++ startCanvasFetch()++ await waitFor(() => expect(zigbeeApi.importNetwork).toHaveBeenCalled())+ expect(zigbeeApi.importToPending).not.toHaveBeenCalled()+ })++ it('keeps polling the job until the map is ready (issue #380)', async () => {+ vi.useFakeTimers({ shouldAdvanceTime: true })+ try {+ vi.mocked(zigbeeApi.importNetwork).mockResolvedValue({+ data: { job_id: 'job-1', status: 'running' },+ } as never)+ vi.mocked(zigbeeApi.getImportJob)+ .mockResolvedValueOnce({+ data: { job_id: 'job-1', status: 'running', result: null },+ } as never)+ .mockResolvedValueOnce({+ data: {+ job_id: 'job-1',+ status: 'done',+ result: { nodes: sampleNodes, edges: [], device_count: 2 },+ },+ } as never)++ startCanvasFetch()++ await waitFor(() => expect(zigbeeApi.getImportJob).toHaveBeenCalledTimes(1))+ await act(async () => {+ await vi.advanceTimersByTimeAsync(2000)+ })+ await waitFor(() => expect(screen.getByText('router_1')).toBeDefined())+ expect(zigbeeApi.getImportJob).toHaveBeenCalledWith('job-1')+ } finally {+ vi.useRealTimers()+ }+ })++ it('surfaces the backend detail when the job fails', async () => {vi.mocked(zigbeeApi.importNetwork).mockResolvedValue({- data: { nodes: sampleNodes, edges: [], device_count: 2 },+ data: { job_id: 'job-1', status: 'running' },} as never)+ vi.mocked(zigbeeApi.getImportJob).mockRejectedValue({+ response: { status: 504, data: { detail: 'Timed out waiting for networkmap response' } },+ })- render(<ZigbeeImportModal {...defaultProps} />)- fireEvent.click(screen.getByRole('radio', { name: /canvas directly/i }))- const hostInput = screen.getByPlaceholderText('192.168.1.x or mqtt.local')- fireEvent.change(hostInput, { target: { value: '192.168.1.100' } })+ startCanvasFetch()++ await waitFor(() => {+ expect(toast.error).toHaveBeenCalledWith('Timed out waiting for networkmap response')+ })+ })++ it('stops polling and stays quiet when the modal is closed mid-import', async () => {+ vi.mocked(zigbeeApi.importNetwork).mockResolvedValue({+ data: { job_id: 'job-1', status: 'running' },+ } as never)+ vi.mocked(zigbeeApi.getImportJob).mockResolvedValue({+ data: { job_id: 'job-1', status: 'running', result: null },+ } as never)++ const { unmount } = render(<ZigbeeImportModal {...defaultProps} />)+ selectCanvasMode()+ fireEvent.change(screen.getByPlaceholderText('192.168.1.x or mqtt.local'), {+ target: { value: '192.168.1.100' },+ })fireEvent.click(screen.getByRole('button', { name: /fetch devices/i }))- await waitFor(() => expect(zigbeeApi.importNetwork).toHaveBeenCalled())- expect(zigbeeApi.importToPending).not.toHaveBeenCalled()+ await waitFor(() => expect(zigbeeApi.getImportJob).toHaveBeenCalled())+ unmount()++ const callsAtUnmount = vi.mocked(zigbeeApi.getImportJob).mock.calls.length+ await new Promise((r) => setTimeout(r, 50))+ expect(vi.mocked(zigbeeApi.getImportJob).mock.calls.length).toBe(callsAtUnmount)+ expect(toast.error).not.toHaveBeenCalled()})})diff --git a/frontend/src/utils/__tests__/importJobPoll.test.ts b/frontend/src/utils/__tests__/importJobPoll.test.tsnew file mode 100644index 0000000..8cbe175--- /dev/null+++ b/frontend/src/utils/__tests__/importJobPoll.test.ts@@ -0,0 +1,102 @@+import { describe, it, expect, vi } from 'vitest'+import { pollImportJob, PollAbortedError, type ImportJobState } from '../importJobPoll'++interface Payload { device_count: number }++const done = (device_count: number): ImportJobState<Payload> => ({+ status: 'done',+ result: { device_count },+})+const running: ImportJobState<Payload> = { status: 'running', result: null }++/** Resolves instantly so no test waits on a real timer. */+const noSleep = () => Promise.resolve()++describe('pollImportJob', () => {+ it('returns the result when the first poll is already done', async () => {+ const fetchJob = vi.fn().mockResolvedValue(done(2))+ await expect(pollImportJob(fetchJob, { sleep: noSleep })).resolves.toEqual({ device_count: 2 })+ expect(fetchJob).toHaveBeenCalledTimes(1)+ })++ it('keeps polling while the job is running', async () => {+ const fetchJob = vi+ .fn()+ .mockResolvedValueOnce(running)+ .mockResolvedValueOnce(running)+ .mockResolvedValueOnce(done(7))++ await expect(pollImportJob(fetchJob, { sleep: noSleep })).resolves.toEqual({ device_count: 7 })+ expect(fetchJob).toHaveBeenCalledTimes(3)+ })++ it('waits the configured interval between polls', async () => {+ const sleep = vi.fn().mockResolvedValue(undefined)+ const fetchJob = vi.fn().mockResolvedValueOnce(running).mockResolvedValueOnce(done(1))++ await pollImportJob(fetchJob, { intervalMs: 1234, sleep })+ expect(sleep).toHaveBeenCalledTimes(1)+ expect(sleep.mock.calls[0][0]).toBe(1234)+ })++ it('propagates a rejected poll so the caller sees the backend status', async () => {+ const err = Object.assign(new Error('boom'), {+ response: { status: 504, data: { detail: 'Timed out' } },+ })+ const fetchJob = vi.fn().mockResolvedValueOnce(running).mockRejectedValueOnce(err)++ await expect(pollImportJob(fetchJob, { sleep: noSleep })).rejects.toBe(err)+ })++ it('rejects with PollAbortedError when aborted before the first poll', async () => {+ const controller = new AbortController()+ controller.abort()+ const fetchJob = vi.fn().mockResolvedValue(done(1))++ await expect(+ pollImportJob(fetchJob, { signal: controller.signal, sleep: noSleep }),+ ).rejects.toBeInstanceOf(PollAbortedError)+ expect(fetchJob).not.toHaveBeenCalled()+ })++ it('rejects with PollAbortedError when aborted while a poll is in flight', async () => {+ const controller = new AbortController()+ const fetchJob = vi.fn().mockImplementation(async () => {+ controller.abort()+ return running+ })++ await expect(+ pollImportJob(fetchJob, { signal: controller.signal, sleep: noSleep }),+ ).rejects.toBeInstanceOf(PollAbortedError)+ expect(fetchJob).toHaveBeenCalledTimes(1)+ })++ it('rejects when the job reports done with no payload', async () => {+ const fetchJob = vi.fn().mockResolvedValue({ status: 'done', result: null })+ await expect(pollImportJob(fetchJob, { sleep: noSleep })).rejects.toThrow(+ 'Import finished without a result',+ )+ })++ it('default sleep resolves after the interval and rejects on abort', async () => {+ vi.useFakeTimers()+ try {+ const fetchJob = vi.fn().mockResolvedValueOnce(running).mockResolvedValueOnce(done(1))+ const promise = pollImportJob(fetchJob, { intervalMs: 50 })+ await vi.advanceTimersByTimeAsync(60)+ await expect(promise).resolves.toEqual({ device_count: 1 })++ const controller = new AbortController()+ const aborting = pollImportJob(+ vi.fn().mockResolvedValue(running),+ { intervalMs: 50, signal: controller.signal },+ )+ await vi.advanceTimersByTimeAsync(1)+ controller.abort()+ await expect(aborting).rejects.toBeInstanceOf(PollAbortedError)+ } finally {+ vi.useRealTimers()+ }+ })+})diff --git a/frontend/src/utils/importJobPoll.ts b/frontend/src/utils/importJobPoll.tsnew file mode 100644index 0000000..df139b0--- /dev/null+++ b/frontend/src/utils/importJobPoll.ts@@ -0,0 +1,73 @@+/**+ * Polling helper for backend import jobs that answer immediately and finish later.+ *+ * A Zigbee canvas import has to fetch a Z2M networkmap, which on a large mesh+ * takes minutes — longer than the read timeout of any reverse proxy in front of+ * the API. The backend therefore returns a job id and does the work in the+ * background; the client polls short requests until the payload is ready.+ */++export class PollAbortedError extends Error {+ constructor() {+ super('Import polling aborted')+ this.name = 'PollAbortedError'+ }+}++export interface ImportJobState<T> {+ status: string+ result: T | null+}++export interface PollImportJobOptions {+ /** Delay between polls, in ms. */+ intervalMs?: number+ /** Abort the loop (modal closed, component unmounted). */+ signal?: AbortSignal+ /** Injected in tests so no timer actually runs. */+ sleep?: (ms: number, signal?: AbortSignal) => Promise<void>+}++const defaultSleep = (ms: number, signal?: AbortSignal) =>+ new Promise<void>((resolve, reject) => {+ const timer = setTimeout(() => {+ signal?.removeEventListener('abort', onAbort)+ resolve()+ }, ms)+ const onAbort = () => {+ clearTimeout(timer)+ reject(new PollAbortedError())+ }+ if (signal?.aborted) {+ onAbort()+ return+ }+ signal?.addEventListener('abort', onAbort, { once: true })+ })++/**+ * Poll `fetchJob` until it reports a terminal status, then resolve its result.+ *+ * A failed job surfaces as a rejected `fetchJob` call (the backend replays the+ * original status code), so errors propagate untouched to the caller. Rejects+ * with `PollAbortedError` if the signal fires, and with a plain Error if the+ * job reports done without a payload.+ */+export async function pollImportJob<T>(+ fetchJob: () => Promise<ImportJobState<T>>,+ { intervalMs = 2000, signal, sleep = defaultSleep }: PollImportJobOptions = {},+): Promise<T> {+ for (;;) {+ if (signal?.aborted) throw new PollAbortedError()++ const job = await fetchJob()+ if (signal?.aborted) throw new PollAbortedError()++ if (job.status !== 'running') {+ if (job.result == null) throw new Error('Import finished without a result')+ return job.result+ }++ await sleep(intervalMs, signal)+ }+}