span-panel-api 2.3.0__tar.gz → 2.3.2__tar.gz

{span_panel_api-2.3.0 → span_panel_api-2.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: span-panel-api
-Version: 2.3.0
+Version: 2.3.2
 Summary: A client library for SPAN Panel API
 License-File: LICENSE
 Author: SpanPanel

{span_panel_api-2.3.0 → span_panel_api-2.3.2}/pyproject.toml

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

{span_panel_api-2.3.0 → span_panel_api-2.3.2}/src/span_panel_api/__init__.py

@@ -4,7 +4,15 @@ A modern, type-safe Python client library for the SPAN Panel API,
 supporting MQTT/Homie (v2) transport.
 """
 
-from .auth import download_ca_cert, get_homie_schema, regenerate_passphrase, register_v2
+from .auth import (
+    delete_fqdn,
+    download_ca_cert,
+    get_fqdn,
+    get_homie_schema,
+    regenerate_passphrase,
+    register_fqdn,
+    register_v2,
+)
 from .detection import DetectionResult, detect_api_version
 from .exceptions import (
     SpanPanelAPIError,
@@ -44,7 +52,7 @@ from .protocol import (
     StreamingCapableProtocol,
 )
 
-__version__ = "2.3.0"
+__version__ = "2.3.2"
 # fmt: off
 __all__ = [  # noqa: RUF022
     # Protocols
@@ -70,8 +78,11 @@ __all__ = [  # noqa: RUF022
     "V2AuthResponse",
     "V2HomieSchema",
     "V2StatusInfo",
+    "delete_fqdn",
     "download_ca_cert",
+    "get_fqdn",
     "get_homie_schema",
+    "register_fqdn",
     "regenerate_passphrase",
     "register_v2",
     # Transport

{span_panel_api-2.3.0 → span_panel_api-2.3.2}/src/span_panel_api/auth.py

@@ -241,6 +241,123 @@ async def regenerate_passphrase(host: str, token: str, timeout: float = 10.0, po
     return _str(data["ebusBrokerPassword"])
 
 
+async def register_fqdn(host: str, token: str, fqdn: str, timeout: float = 10.0, port: int = 80) -> None:
+    """Register an FQDN with the SPAN Panel for TLS certificate SAN inclusion.
+
+    The panel regenerates its TLS server certificate to include the
+    provided FQDN in the Subject Alternative Names, allowing MQTTS
+    clients connecting via the FQDN to pass hostname verification.
+
+    Args:
+        host: IP address or hostname of the SPAN Panel
+        token: Valid JWT access token from register_v2
+        fqdn: Fully qualified domain name to register
+        timeout: Request timeout in seconds
+        port: HTTP port of the panel bootstrap API
+
+    Raises:
+        SpanPanelAuthError: Token invalid or expired
+        SpanPanelConnectionError: Cannot reach panel
+        SpanPanelTimeoutError: Request timed out
+        SpanPanelAPIError: Unexpected response (including 404 if unsupported)
+    """
+    url = _build_url(host, port, "/api/v2/dns/fqdn")
+    headers = {"Authorization": f"Bearer {token}"}
+    payload = {"ebusTlsFqdn": fqdn}
+
+    try:
+        async with httpx.AsyncClient(timeout=timeout, verify=False) as client:  # nosec B501
+            response = await client.post(url, json=payload, headers=headers)
+    except httpx.ConnectError as exc:
+        raise SpanPanelConnectionError(f"Cannot reach panel at {host}") from exc
+    except httpx.TimeoutException as exc:
+        raise SpanPanelTimeoutError(f"Timed out connecting to {host}") from exc
+
+    if response.status_code in (401, 403):
+        raise SpanPanelAuthError(f"Authentication failed (HTTP {response.status_code})")
+
+    if response.status_code not in (200, 201, 204):
+        raise SpanPanelAPIError(f"Failed to register FQDN: HTTP {response.status_code}")
+
+
+async def get_fqdn(host: str, token: str, timeout: float = 10.0, port: int = 80) -> str:
+    """Retrieve the currently registered FQDN from the SPAN Panel.
+
+    Args:
+        host: IP address or hostname of the SPAN Panel
+        token: Valid JWT access token from register_v2
+        timeout: Request timeout in seconds
+        port: HTTP port of the panel bootstrap API
+
+    Returns:
+        The registered FQDN, or empty string if none is configured
+
+    Raises:
+        SpanPanelAuthError: Token invalid or expired
+        SpanPanelConnectionError: Cannot reach panel
+        SpanPanelTimeoutError: Request timed out
+        SpanPanelAPIError: Unexpected response
+    """
+    url = _build_url(host, port, "/api/v2/dns/fqdn")
+    headers = {"Authorization": f"Bearer {token}"}
+
+    try:
+        async with httpx.AsyncClient(timeout=timeout, verify=False) as client:  # nosec B501
+            response = await client.get(url, headers=headers)
+    except httpx.ConnectError as exc:
+        raise SpanPanelConnectionError(f"Cannot reach panel at {host}") from exc
+    except httpx.TimeoutException as exc:
+        raise SpanPanelTimeoutError(f"Timed out connecting to {host}") from exc
+
+    if response.status_code in (401, 403):
+        raise SpanPanelAuthError(f"Authentication failed (HTTP {response.status_code})")
+
+    if response.status_code == 404:
+        return ""
+
+    if response.status_code != 200:
+        raise SpanPanelAPIError(f"Failed to get FQDN: HTTP {response.status_code}")
+
+    data: dict[str, object] = response.json()
+    return _str(data.get("ebusTlsFqdn"))
+
+
+async def delete_fqdn(host: str, token: str, timeout: float = 10.0, port: int = 80) -> None:
+    """Remove the registered FQDN from the SPAN Panel.
+
+    The panel regenerates its TLS certificate without the FQDN in
+    the SAN list.
+
+    Args:
+        host: IP address or hostname of the SPAN Panel
+        token: Valid JWT access token from register_v2
+        timeout: Request timeout in seconds
+        port: HTTP port of the panel bootstrap API
+
+    Raises:
+        SpanPanelAuthError: Token invalid or expired
+        SpanPanelConnectionError: Cannot reach panel
+        SpanPanelTimeoutError: Request timed out
+        SpanPanelAPIError: Unexpected response
+    """
+    url = _build_url(host, port, "/api/v2/dns/fqdn")
+    headers = {"Authorization": f"Bearer {token}"}
+
+    try:
+        async with httpx.AsyncClient(timeout=timeout, verify=False) as client:  # nosec B501
+            response = await client.delete(url, headers=headers)
+    except httpx.ConnectError as exc:
+        raise SpanPanelConnectionError(f"Cannot reach panel at {host}") from exc
+    except httpx.TimeoutException as exc:
+        raise SpanPanelTimeoutError(f"Timed out connecting to {host}") from exc
+
+    if response.status_code in (401, 403):
+        raise SpanPanelAuthError(f"Authentication failed (HTTP {response.status_code})")
+
+    if response.status_code not in (200, 204):
+        raise SpanPanelAPIError(f"Failed to delete FQDN: HTTP {response.status_code}")
+
+
 async def get_v2_status(host: str, timeout: float = 5.0, port: int = 80) -> V2StatusInfo:
     """Lightweight v2 status probe (unauthenticated).
 

{span_panel_api-2.3.0 → span_panel_api-2.3.2}/src/span_panel_api/mqtt/connection.py

@@ -175,7 +175,12 @@ class AsyncMqttBridge:
                 self._client.on_socket_open = self._on_socket_open_sync
                 self._client.on_socket_register_write = self._on_socket_register_write_sync
                 _LOGGER.debug("BRIDGE: Running TLS+connect in executor to %s:%s", self._host, self._port)
-                await self._loop.run_in_executor(None, _blocking_tls_and_connect)
+                try:
+                    await self._loop.run_in_executor(None, _blocking_tls_and_connect)
+                except OSError as exc:
+                    raise SpanPanelConnectionError(
+                        f"Cannot connect to MQTT broker at {self._host}:{self._port}: {exc}"
+                    ) from exc
                 _LOGGER.debug("BRIDGE: Executor connect returned, waiting for CONNACK...")
             finally:
                 # Switch to async-only socket callbacks now that we are