span-panel-api 3.0.0b6__tar.gz → 3.0.0b8__tar.gz

{span_panel_api-3.0.0b6 → span_panel_api-3.0.0b8}/CHANGELOG.md

@@ -4,6 +4,28 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.0.0b8]
+
+### Fixed
+
+- **A panel answering `502` while it reboots no longer costs the automatic reload.** When a panel upgrades its firmware it drops MQTT, comes back, and serves HTTP a little later — and a booting device brings its network stack and reverse proxy up before
+  the application behind them, so the schema fetch is answered with `502` rather than refused. The retry that exists for exactly this handled "cannot reach" and "timed out" but not "answered, with 502", so the first attempt raised straight out of the loop,
+  out of the fire-and-forget task that called it, and the parser was never swapped. Caught on two Home Assistant instances watching one panel through the same live upgrade: both logged `Task exception was never retrieved`, both stayed on the old parser,
+  and neither recovered without a manual reload. `get_homie_schema` now raises `SpanPanelServerError` for any 5xx — "not ready yet", distinct from a 4xx that will not fix itself — and the retry treats it as retryable.
+- **The wait is now the length of a real reboot.** Five attempts backing off to 8s gave up after about 23 seconds. The observed upgrade took four minutes from MQTT dropping to the broker returning, with HTTP still answering 502 at that point. Twelve
+  attempts backing off to 30s covers it.
+- **Nothing escapes the redispatch task any more.** An unexpected failure there used to surface as a bare `Task exception was never retrieved` while the parser silently stayed on the old generation — the failure the redispatch exists to prevent, reached by
+  another route. It is now logged at ERROR naming the consequence and the remedy, because a reload is the user's only move and nothing else was going to tell them.
+
+## [3.0.0b7]
+
+### Changed
+
+- **`SpanMqttClient` accepts an `httpx_client`, and so does `create_span_client`.** Four config-flow-facing entry points already took an injected client; the runtime path was the one that did not, so every schema read built a throwaway — including the
+  retry loop that runs during a firmware upgrade, which built one per attempt at exactly the moment the panel was mid-reboot. Optional and defaulted, so nothing outside Home Assistant changes. The ownership rule is the one the existing entry points already
+  state: a client handed in is never closed here, and its timeouts, limits and headers are the caller's, which is why the per-call `timeout` defaults are ignored when one is given. Home Assistant's shared client carries httpx's default timeout rather than
+  this library's 10 s, and that is the caller exercising the policy it owns rather than a setting being lost.
+
 ## [3.0.0b6]
 
 ### Added

{span_panel_api-3.0.0b6 → span_panel_api-3.0.0b8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: span-panel-api
-Version: 3.0.0b6
+Version: 3.0.0b8
 Summary: A client library for SPAN Panel API
 Project-URL: Homepage, https://github.com/SpanPanel/span-panel-api
 Project-URL: Issues, https://github.com/SpanPanel/span-panel-api/issues

{span_panel_api-3.0.0b6 → span_panel_api-3.0.0b8}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "span-panel-api"
-version = "3.0.0b6"
+version = "3.0.0b8"
 description = "A client library for SPAN Panel API"
 authors = [
     {name = "SpanPanel"}

{span_panel_api-3.0.0b6 → span_panel_api-3.0.0b8}/src/span_panel_api/auth.py

@@ -15,7 +15,13 @@ import uuid
 import httpx
 
 from ._http import _build_url, _get_client
-from .exceptions import SpanPanelAPIError, SpanPanelAuthError, SpanPanelConnectionError, SpanPanelTimeoutError
+from .exceptions import (
+    SpanPanelAPIError,
+    SpanPanelAuthError,
+    SpanPanelConnectionError,
+    SpanPanelServerError,
+    SpanPanelTimeoutError,
+)
 from .models import HomieSchemaTypes, V2AuthResponse, V2HomieSchema, V2StatusInfo
 
 
@@ -187,8 +193,22 @@ async def get_homie_schema(
     except httpx.TimeoutException as exc:
         raise SpanPanelTimeoutError(f"Timed out connecting to {host}") from exc
 
+    if response.status_code >= 500:
+        # A rebooting panel answers 502 from its front end while the application
+        # behind it is still starting. That is "not ready yet", not "wrong" --
+        # and it is the ordinary shape of a firmware upgrade, because a device
+        # brings its network stack and proxy up before its application. Raised as
+        # a distinct class so a caller can retry it and fail fast on a 4xx, which
+        # will not fix itself.
+        raise SpanPanelServerError(
+            f"Panel not ready: HTTP {response.status_code} fetching the Homie schema",
+            status_code=response.status_code,
+        )
     if response.status_code != 200:
-        raise SpanPanelAPIError(f"Failed to fetch Homie schema: HTTP {response.status_code}")
+        raise SpanPanelAPIError(
+            f"Failed to fetch Homie schema: HTTP {response.status_code}",
+            status_code=response.status_code,
+        )
 
     data: dict[str, object] = response.json()
 

{span_panel_api-3.0.0b6 → span_panel_api-3.0.0b8}/src/span_panel_api/factory.py

@@ -8,6 +8,7 @@ from __future__ import annotations
 
 import asyncio
 import logging
+from typing import TYPE_CHECKING
 
 from .adapters import resolve_adapter
 from .auth import get_homie_schema, register_v2
@@ -17,6 +18,9 @@ from .exceptions import SpanPanelAuthError
 from .mqtt.client import SpanMqttClient
 from .mqtt.models import MqttClientConfig
 
+if TYPE_CHECKING:
+    import httpx
+
 _LOGGER = logging.getLogger(__name__)
 
 _V2_CLIENT_NAME = "span-panel-api"
@@ -28,6 +32,7 @@ async def create_span_client(
     mqtt_config: MqttClientConfig | None = None,
     serial_number: str | None = None,
     port: int = 80,
+    httpx_client: httpx.AsyncClient | None = None,
 ) -> SpanMqttClient:
     """Create a SPAN Panel MQTT client.
 
@@ -37,6 +42,10 @@ async def create_span_client(
         mqtt_config: Pre-built MQTT broker configuration.
         serial_number: Panel serial number (extracted from detection/registration if omitted).
         port: HTTP port of the panel bootstrap API used for registration and detection.
+        httpx_client: Optional shared ``httpx.AsyncClient``, used for every request this
+            makes and handed to the client it builds. Not closed here; its timeouts and
+            limits are the caller's, which is why the per-call ``timeout`` defaults are
+            ignored when one is given.
 
     Returns:
         A connected-ready SpanMqttClient instance.
@@ -54,7 +63,7 @@ async def create_span_client(
     if mqtt_config is None:
         if passphrase is None:
             raise SpanPanelAuthError("Neither mqtt_config nor passphrase provided")
-        auth_response = await register_v2(host, _V2_CLIENT_NAME, passphrase, port=port)
+        auth_response = await register_v2(host, _V2_CLIENT_NAME, passphrase, port=port, httpx_client=httpx_client)
         mqtt_config = MqttClientConfig(
             broker_host=auth_response.ebus_broker_host,
             username=auth_response.ebus_broker_username,
@@ -68,7 +77,7 @@ async def create_span_client(
 
     if serial_number is None:
         # Try to detect from panel status
-        result = await detect_api_version(host, port=port)
+        result = await detect_api_version(host, port=port, httpx_client=httpx_client)
         if result.status_info is not None:
             serial_number = result.status_info.serial_number
 
@@ -80,7 +89,7 @@ async def create_span_client(
     # flat-versus-parent/child signal, mirroring MQTT's `info/data-model-version`
     # — so the parser is chosen before a single message is consumed, rather than
     # a wrong parser being discovered by its output.
-    schema = await get_homie_schema(host, port=port)
+    schema = await get_homie_schema(host, port=port, httpx_client=httpx_client)
     adapter_key, dispatch_reason = select_adapter_key(schema.data_model_version)
     # In a thread: resolution reads distribution metadata and imports the adapter
     # package, and this is the first call in the process to do either. See
@@ -96,6 +105,7 @@ async def create_span_client(
         data_model_version=schema.data_model_version,
         schema_dispatch_reason=dispatch_reason,
         schema=schema,
+        httpx_client=httpx_client,
     )
     await client.connect()
     return client

{span_panel_api-3.0.0b6 → span_panel_api-3.0.0b8}/src/span_panel_api/mqtt/client.py

@@ -13,6 +13,7 @@ import contextlib
 from importlib.metadata import version
 import logging
 import time
+from typing import TYPE_CHECKING
 
 from span_panel_api.schema_drift import log_schema_drift
 
@@ -34,6 +35,9 @@ from .connection import AsyncMqttBridge
 from .const import MQTT_READY_TIMEOUT_S
 from .models import MqttClientConfig
 
+if TYPE_CHECKING:
+    import httpx
+
 _LOGGER = logging.getLogger(__name__)
 
 # How long to wait for circuit name properties after device ready.
@@ -74,6 +78,7 @@ class SpanMqttClient:
         data_model_version: str | None = None,
         schema_dispatch_reason: str | None = None,
         schema: V2HomieSchema | None = None,
+        httpx_client: httpx.AsyncClient | None = None,
     ) -> None:
         self._host = host
         self._serial_number = serial_number
@@ -81,6 +86,12 @@ class SpanMqttClient:
         self._snapshot_interval = snapshot_interval
         self._panel_http_port = panel_http_port
         self._adapter_factory = adapter_factory
+        # Shared by the caller, owned by the caller: never closed here, and its
+        # policy -- timeouts, limits, headers -- is whatever the caller set. That
+        # is the same rule the four config-flow entry points already state, and
+        # the reason this exists at all is that the runtime path was the one place
+        # left without it. See `_get_client`.
+        self._httpx_client = httpx_client
 
         self._bridge: AsyncMqttBridge | None = None
         self._adapter: SchemaAdapter | None = None
@@ -287,7 +298,11 @@ class SpanMqttClient:
         # would be a second call to the same unauthenticated endpoint for a
         # value that cannot have changed. A directly-constructed client has no
         # schema yet, so it fetches here and dispatches in _build_adapter.
-        schema = self._schema if self._schema is not None else await get_homie_schema(self._host, port=self._panel_http_port)
+        schema = (
+            self._schema
+            if self._schema is not None
+            else await get_homie_schema(self._host, port=self._panel_http_port, httpx_client=self._httpx_client)
+        )
         self._schema = schema
         await self._preload_adapter(schema)
         adapter = self._build_adapter(schema)
@@ -807,8 +822,21 @@ class SpanMqttClient:
         last: Exception | None = None
         for _ in range(_REDISPATCH_RETRY_ATTEMPTS):
             try:
-                return await get_homie_schema(self._host, port=self._panel_http_port)
-            except (SpanPanelConnectionError, SpanPanelTimeoutError) as exc:
+                return await get_homie_schema(self._host, port=self._panel_http_port, httpx_client=self._httpx_client)
+            except (
+                SpanPanelConnectionError,
+                SpanPanelTimeoutError,
+                # The third way HTTP lags the broker, and the one a real upgrade
+                # actually produced: the panel answers, with 502. Its front end is
+                # up while the application behind it is still starting, which is
+                # the ordinary order for a booting device. Omitting this meant the
+                # first attempt raised straight out of this loop, out of the
+                # fire-and-forget task that called it, and the parser was never
+                # swapped -- observed on two Home Assistant instances watching one
+                # panel through the same upgrade, neither of which recovered
+                # without a manual reload.
+                SpanPanelServerError,
+            ) as exc:
                 last = exc
                 await asyncio.sleep(delay)
                 delay = min(delay * 2, _REDISPATCH_RETRY_MAX_S)
@@ -847,6 +875,23 @@ class SpanMqttClient:
         """
         try:
             await self._redispatch_once()
+        except Exception:  # pylint: disable=broad-exception-caught
+            # Nothing may escape here. This runs as a fire-and-forget task, so an
+            # escaping exception becomes "Task exception was never retrieved" in
+            # the log and the parser silently stays on the old generation --
+            # which is the failure this whole method exists to prevent, arrived at
+            # by a different route. That is not hypothetical: a 502 from a
+            # rebooting panel did exactly this on two live installs.
+            #
+            # Logged at ERROR with the consequence spelled out, because the user's
+            # remedy is a reload and nothing else will tell them so.
+            _LOGGER.error(
+                "Could not follow the panel's schema-generation change; the %r parser is "
+                "unchanged and its data will read as missing. Reload the integration once "
+                "the panel is fully back up.",
+                self._data_model_version,
+                exc_info=True,
+            )
         finally:
             # Released only when the swap is finished, not when the fetch is.
             # Clearing it after the fetch left a window that the slowest step in

{span_panel_api-3.0.0b6 → span_panel_api-3.0.0b8}/tests/test_auth_and_homie_helpers.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import json
-from unittest.mock import AsyncMock, patch
+from unittest.mock import AsyncMock, MagicMock, patch
 
 import httpx
 import pytest
@@ -11,7 +11,12 @@ import pytest
 from span_panel_api_schema_0.accumulator import HomiePropertyAccumulator
 from span_panel_api_schema_0.consumer import HomieDeviceConsumer, _parse_int
 from span_panel_api.auth import _int, download_ca_cert, get_homie_schema
-from span_panel_api.exceptions import SpanPanelConnectionError, SpanPanelTimeoutError
+from span_panel_api.exceptions import (
+    SpanPanelAPIError,
+    SpanPanelConnectionError,
+    SpanPanelServerError,
+    SpanPanelTimeoutError,
+)
 
 # ---------------------------------------------------------------------------
 # auth._int edge cases (lines 29-31)
@@ -34,6 +39,17 @@ class TestIntHelper:
 # ---------------------------------------------------------------------------
 
 
+def _mock_response(method: str, status_code: int) -> AsyncMock:
+    """A client whose request completes and returns `status_code`."""
+    response = MagicMock()
+    response.status_code = status_code
+    mock = AsyncMock()
+    setattr(mock, method, AsyncMock(return_value=response))
+    mock.__aenter__ = AsyncMock(return_value=mock)
+    mock.__aexit__ = AsyncMock(return_value=False)
+    return mock
+
+
 def _mock_client(method: str, side_effect: Exception) -> AsyncMock:
     mock = AsyncMock()
     setattr(mock, method, AsyncMock(side_effect=side_effect))
@@ -78,6 +94,32 @@ class TestGetHomieSchemaErrors:
             with pytest.raises(SpanPanelTimeoutError):
                 await get_homie_schema("192.168.1.1")
 
+    @pytest.mark.asyncio
+    @pytest.mark.parametrize("status", [500, 502, 503, 504])
+    async def test_a_server_status_is_not_ready_rather_than_wrong(self, status: int) -> None:
+        """A rebooting panel answers from its front end while the app behind it starts.
+
+        Raised as `SpanPanelServerError` so a caller can tell "not yet" from
+        "no". The redispatch retry depends on this distinction: a live firmware
+        upgrade produced 502 here, the retry loop did not catch the general
+        `SpanPanelAPIError` it used to be, and the parser was never swapped.
+        """
+        with patch("span_panel_api._http.httpx.AsyncClient") as cls:
+            cls.return_value = _mock_response("get", status)
+            with pytest.raises(SpanPanelServerError) as caught:
+                await get_homie_schema("192.168.1.1")
+        assert caught.value.status_code == status
+
+    @pytest.mark.asyncio
+    @pytest.mark.parametrize("status", [401, 404])
+    async def test_a_client_status_is_not_retryable(self, status: int) -> None:
+        """These do not fix themselves, so they must not look like "not ready yet"."""
+        with patch("span_panel_api._http.httpx.AsyncClient") as cls:
+            cls.return_value = _mock_response("get", status)
+            with pytest.raises(SpanPanelAPIError) as caught:
+                await get_homie_schema("192.168.1.1")
+        assert not isinstance(caught.value, SpanPanelServerError)
+
 
 # ---------------------------------------------------------------------------
 # homie._parse_int failure path (lines 51-52)

{span_panel_api-3.0.0b6 → span_panel_api-3.0.0b8}/tests/test_redispatch_on_reconnect.py

@@ -30,7 +30,7 @@ from unittest.mock import patch
 
 import pytest
 
-from span_panel_api.exceptions import SpanPanelConnectionError
+from span_panel_api.exceptions import SpanPanelConnectionError, SpanPanelServerError
 from span_panel_api.mqtt.client import _REDISPATCH_RETRY_ATTEMPTS, SpanMqttClient
 from span_panel_api.mqtt.models import MqttClientConfig
 
@@ -299,3 +299,68 @@ async def test_a_raising_consumer_does_not_break_the_swap() -> None:
 
     assert client.data_model_version == "1.0", "the swap must stand"
     assert reached == ["second"], "one raising subscriber must not starve the others"
+
+
+@pytest.mark.asyncio
+async def test_a_rebooting_panel_answering_502_is_waited_for_not_abandoned() -> None:
+    """The failure that cost a live firmware upgrade its automatic reload.
+
+    A panel accepts MQTT before it serves HTTP, and the retry loop above exists
+    for that. But there are three ways HTTP lags the broker, and this loop
+    originally handled two: it caught "cannot reach" and "timed out" and not
+    "answered, with 502". A booting device brings its network stack and reverse
+    proxy up before the application behind them, so 502 is the *ordinary* shape,
+    not an exotic one.
+
+    Because `SpanPanelServerError` was not caught, the very first attempt raised
+    straight out of the loop, out of the fire-and-forget task that called it, and
+    the parser was never swapped. Observed on two Home Assistant instances
+    watching one panel through the same upgrade: both logged `Task exception was
+    never retrieved`, both stayed on the flat parser, and neither recovered
+    without a manual reload.
+    """
+    client, _ = _client(None)
+    before = client.adapter
+    attempts = 0
+
+    def _five_oh_two_then_ready(*_a: object, **_k: object) -> _Schema:
+        nonlocal attempts
+        attempts += 1
+        if attempts < 3:
+            raise SpanPanelServerError("Panel not ready: HTTP 502 fetching the Homie schema", 502)
+        return _Schema("1.0")
+
+    with (
+        patch("span_panel_api.mqtt.client.get_homie_schema", side_effect=_five_oh_two_then_ready),
+        patch("span_panel_api.mqtt.client._REDISPATCH_RETRY_INITIAL_S", 0),
+        patch("span_panel_api.mqtt.client._REDISPATCH_RETRY_MAX_S", 0),
+    ):
+        await _panel_publishes_version(client, "1.0")
+
+    assert attempts >= 3, "a 502 must be retried rather than ending the attempt"
+    assert client.adapter is not before, "the parser must swap once the panel answers"
+
+
+@pytest.mark.asyncio
+async def test_an_unexpected_failure_leaves_a_usable_message_rather_than_a_bare_traceback(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """Nothing may escape the fire-and-forget task.
+
+    An escaping exception surfaces as "Task exception was never retrieved" and
+    the parser silently stays on the old generation -- the exact failure this
+    method exists to prevent, reached by a different route. The user's remedy is
+    a reload, and nothing else is going to tell them so.
+    """
+    client, _ = _client(None)
+    before = client.adapter
+
+    with patch(
+        "span_panel_api.mqtt.client.get_homie_schema",
+        side_effect=RuntimeError("something nobody predicted"),
+    ):
+        await _panel_publishes_version(client, "1.0")
+
+    assert client.adapter is before
+    assert "Reload the integration" in caplog.text
+    assert "something nobody predicted" in caplog.text

{span_panel_api-3.0.0b6 → span_panel_api-3.0.0b8}/tests/test_schema_one_conformance.py

@@ -37,6 +37,7 @@ import ast
 import importlib
 import json
 import os
+import subprocess
 from pathlib import Path
 import re
 from typing import NoReturn
@@ -572,26 +573,64 @@ def test_nothing_is_recorded_as_unexercised_once_the_simulator_publishes_it() ->
 
 
 def test_vendored_catalogs_are_byte_identical_to_the_specification() -> None:
-    """Byte comparison against the specification at `synced_commit`.
-
-    Skipped rather than failed without a checkout: the checks above are the ones
-    that must run everywhere, and making them depend on a second repository would
-    mean they stop running.
+    """Are the bytes we vendored the bytes we claim they are?
+
+    Read out of git **at `synced_commit`** rather than from the checkout's working
+    tree, so the answer does not depend on what that clone happens to be sitting
+    on. This used to read the working tree while its own docstring claimed
+    otherwise, and `synced_commit` appeared only in the failure message. That is
+    wrong three ways, and one of them is the dangerous one:
+
+    * it **fails** when the clone has moved *ahead* of the pin, which is ordinary
+      currency drift and not a defect here -- observed the day the specification
+      went to `power-flows` 0.3;
+    * it **fails spuriously** with the clone on an unrelated branch;
+    * it **passes falsely** with a clone itself stale at the pinned commit while
+      the specification has moved on.
+
+    **Integrity, deliberately not currency.** Whether upstream has moved past our
+    pin is a separate question whose answer is normally "yes, a little", and it
+    must not fail a build. Conflating the two is what made this unreliable.
+    Currency is not checked by anything automatic here, and wants a scheduled job
+    rather than a gate.
+
+    The upstream reference producer fixed the same defect in its own copy of this
+    check (`distribution-enclosure-simulator` #47), which is where the framing
+    comes from.
     """
     spec = _checkout(
         "EBUS_SPEC_DIR",
         "a specification checkout to verify vendored bytes",
         expect="capabilities",
     )
-    differing = [
-        path.name
-        for path in sorted(_CATALOGS.glob("*.json"))
-        if (spec / "capabilities" / path.name).read_bytes() != path.read_bytes()
-    ]
+    commit = _lock()["synced_commit"]
+    differing: list[str] = []
+    for path in sorted(_CATALOGS.glob("*.json")):
+        blob = subprocess.run(
+            ["git", "-C", str(spec), "show", f"{commit}:capabilities/{path.name}"],
+            capture_output=True,
+            # Stripped, because `-C` does not beat them. Git hooks export `GIT_DIR`
+            # and `GIT_INDEX_FILE` pointing at the repository being committed to,
+            # and an exported `GIT_DIR` wins over directory discovery -- so under
+            # pre-commit this read the *consumer's* object store, could not find a
+            # specification commit there, and failed with a fetch instruction for a
+            # commit the clone already had. Caught by the hook that causes it.
+            env={k: v for k, v in os.environ.items() if not k.startswith("GIT_")},
+        )
+        if blob.returncode != 0:
+            # A clone that cannot resolve the pin fails rather than skipping: a
+            # silent skip reads exactly like a pass on the one check that proves
+            # the vendored bytes are what the lockfile says.
+            pytest.fail(
+                f"{spec} cannot resolve {commit} (needed to read capabilities/{path.name}). "
+                f"Fetch it: git -C {spec} fetch origin {commit}"
+            )
+        if blob.stdout != path.read_bytes():
+            differing.append(path.name)
 
     assert not differing, (
-        f"vendored catalogs differ from {spec} (lockfile pins {_lock()['synced_commit']}): {differing}. "
-        "Check the checkout is at synced_commit before assuming the copies are wrong."
+        f"vendored catalogs differ from the specification at {commit}: {differing}. "
+        "These are byte copies, so this is a vendoring defect rather than upstream having moved."
     )
 
 

span_panel_api-3.0.0b8/tests/test_shared_http_client.py

@@ -0,0 +1,121 @@
+"""The runtime path uses the caller's HTTP client, not one of its own.
+
+Four config-flow-facing entry points already take an injected
+`httpx.AsyncClient`; `SpanMqttClient` was the one runtime entry point without
+it, so every schema fetch built a throwaway client -- including the retry loop
+that runs during a firmware upgrade, which builds one per attempt at exactly the
+moment the panel is mid-reboot.
+
+Home Assistant is the caller that cares. It owns a shared client, closes it at
+shutdown, and the integration's own `quality_scale.yaml` claims
+`inject-websession: done` -- a claim that was true of the config flow and not of
+anything that ran afterwards.
+
+**Ownership is the whole contract.** A client handed in is never closed here, and
+its policy is the caller's: timeouts, limits and headers are whatever the caller
+configured, which is why the per-call `timeout` arguments are documented as
+ignored when a client is injected. Home Assistant's shared client carries
+httpx's default timeout rather than this library's, and that is the caller
+exercising the policy it owns rather than a setting being lost.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from span_panel_api.mqtt import MqttClientConfig
+from span_panel_api.mqtt.client import SpanMqttClient
+
+SERIAL = "sp3-242424-001"
+
+
+class _Schema:
+    def __init__(self, version: str | None) -> None:
+        self.data_model_version = version
+
+
+def _client(injected: object | None) -> SpanMqttClient:
+    return SpanMqttClient(
+        host="192.168.1.1",
+        serial_number=SERIAL,
+        broker_config=MqttClientConfig(broker_host="broker.local", username="u", password="p"),
+        httpx_client=injected,  # type: ignore[arg-type]
+    )
+
+
+@pytest.mark.asyncio
+async def test_the_connect_fetch_uses_the_injected_client() -> None:
+    """The first schema read of a session, and the one every install makes."""
+    sentinel = MagicMock(name="shared-client")
+    client = _client(sentinel)
+
+    fetch = AsyncMock(return_value=_Schema("1.0"))
+    with (
+        patch("span_panel_api.mqtt.client.get_homie_schema", fetch),
+        patch.object(client, "_preload_adapter", AsyncMock()),
+        patch.object(client, "_build_adapter", MagicMock()),
+        patch.object(client, "_connect_bridge", AsyncMock(), create=True),
+    ):
+        # Connect goes on to bring up the MQTT bridge, which has nothing to do
+        # with this assertion and no broker to reach. The fetch is what is under
+        # test, and the await-count assertion below is what keeps that from
+        # passing vacuously if it never happened at all.
+        with contextlib.suppress(Exception):
+            await client.connect()
+
+    assert fetch.await_count >= 1
+    assert fetch.await_args.kwargs["httpx_client"] is sentinel
+
+
+@pytest.mark.asyncio
+async def test_the_upgrade_refetch_uses_the_injected_client() -> None:
+    """The path that mattered most, because it builds one client per retry attempt.
+
+    A panel accepts MQTT before it serves HTTP, so this loop can run several times
+    in a row while the panel finishes booting -- each one previously a fresh
+    client, a fresh connection pool, thrown away on the next attempt.
+    """
+    sentinel = MagicMock(name="shared-client")
+    client = _client(sentinel)
+    client._loop = asyncio.get_running_loop()
+
+    fetch = AsyncMock(return_value=_Schema("1.0"))
+    with patch("span_panel_api.mqtt.client.get_homie_schema", fetch):
+        assert await client._fetch_schema_with_retry() is not None
+
+    assert fetch.await_args.kwargs["httpx_client"] is sentinel
+
+
+@pytest.mark.asyncio
+async def test_an_injected_client_is_never_closed_here() -> None:
+    """It belongs to the caller, and the caller may still be using it.
+
+    Home Assistant hands out one shared client to every integration and closes it
+    at shutdown; closing it from here would take the others down with it. HA
+    guards its own copy, but a library that relies on the caller guarding it is
+    relying on the caller.
+    """
+    sentinel = MagicMock(name="shared-client")
+    sentinel.aclose = AsyncMock()
+    client = _client(sentinel)
+
+    await client.close()
+
+    sentinel.aclose.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_no_injected_client_still_works() -> None:
+    """The default has to stay the default: this library is not Home Assistant's alone."""
+    client = _client(None)
+    client._loop = asyncio.get_running_loop()
+
+    fetch = AsyncMock(return_value=_Schema("1.0"))
+    with patch("span_panel_api.mqtt.client.get_homie_schema", fetch):
+        assert await client._fetch_schema_with_retry() is not None
+
+    assert fetch.await_args.kwargs["httpx_client"] is None