sofapython 0.0.1rc1__py3-none-any.whl

sofapython/discovery.py

@@ -0,0 +1,315 @@
+# discovery.py — LAN discovery of physical Sofabaton hubs via mDNS.
+#
+# Library-owned counterpart to the Home Assistant integration's zeroconf
+# config flow: browses the hub service types, decodes TXT records,
+# classifies the hub variant and (by default) filters out advertisements
+# published by our own proxies (marked with PROXY_TXT_KEY).
+#
+# ``zeroconf`` is imported lazily so the package stays importable in
+# environments that only use the parsing layers (mirrors x1_proxy's
+# advertising path).
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import Any, Callable, Iterable, Optional
+
+from .hub_versions import (
+    MDNS_SERVICE_TYPES,
+    classify_hub_version,
+    is_proxy_advertisement,
+)
+
+log = logging.getLogger(__name__)
+
+DEFAULT_DISCOVERY_TIMEOUT = 5.0
+# How long to wait for a ServiceInfo resolution per advertisement.
+_INFO_REQUEST_TIMEOUT_MS = 3000
+
+
+@dataclass(frozen=True)
+class DiscoveredHub:
+    """One mDNS advertisement, normalized.
+
+    ``hub_version`` is ``None`` when the advertisement carries no
+    recognisable ``HVER`` TXT record (unknown firmware lineage); the
+    raw ``txt`` dict is always preserved so callers can apply their own
+    policy, mirroring how the HA config flow re-evaluates later.
+    """
+
+    host: str
+    port: int
+    name: str
+    mac: Optional[str]
+    txt: dict[str, str] = field(compare=False)
+    hub_version: Optional[str]
+    is_proxy: bool
+    service_type: str
+    instance_name: str = field(compare=False, default="")
+
+    @property
+    def key(self) -> tuple[str, str]:
+        """Stable identity of the advertisement within a browse session."""
+
+        return (self.service_type, self.instance_name)
+
+
+def decode_txt_properties(properties: Any) -> dict[str, str]:
+    """Decode a zeroconf properties mapping into plain str->str.
+
+    zeroconf hands back ``dict[bytes, bytes | None]``; HA hands the
+    config flow already-decoded strings. Accept both, drop value-less
+    keys' values to empty strings, and ignore undecodable garbage.
+    """
+
+    props: dict[str, str] = {}
+    if not properties:
+        return props
+    for key, value in dict(properties).items():
+        if isinstance(key, bytes):
+            try:
+                key = key.decode("utf-8")
+            except UnicodeDecodeError:
+                continue
+        if isinstance(value, bytes):
+            try:
+                value = value.decode("utf-8")
+            except UnicodeDecodeError:
+                continue
+        props[str(key)] = "" if value is None else str(value)
+    return props
+
+
+def normalize_advertisement(
+    service_type: str,
+    instance_name: str,
+    *,
+    host: Optional[str],
+    port: Optional[int],
+    properties: Any,
+) -> Optional[DiscoveredHub]:
+    """Build a :class:`DiscoveredHub` from raw advertisement details.
+
+    Returns ``None`` when the advertisement is unusable (no address) or
+    the service type is not a known hub type. Classification failures do
+    NOT reject the hub — ``hub_version`` is simply ``None``.
+    """
+
+    if service_type not in MDNS_SERVICE_TYPES:
+        return None
+    if not host:
+        return None
+
+    txt = decode_txt_properties(properties)
+    label = instance_name.split(".")[0]
+    name = txt.get("NAME") or label
+    mac = txt.get("MAC") or None
+    try:
+        hub_version: Optional[str] = classify_hub_version(txt)
+    except ValueError:
+        hub_version = None
+
+    return DiscoveredHub(
+        host=host,
+        port=int(port) if port else 0,
+        name=name,
+        mac=mac,
+        txt=txt,
+        hub_version=hub_version,
+        is_proxy=is_proxy_advertisement(txt),
+        service_type=service_type,
+        instance_name=instance_name,
+    )
+
+
+HubCallback = Callable[[DiscoveredHub], None]
+
+
+class HubBrowser:
+    """Continuous mDNS browse for Sofabaton hubs.
+
+    Callbacks fire on the zeroconf engine thread; keep them quick and
+    hand off to your own executor/loop for real work. ``include_proxies``
+    keeps proxy advertisements (marked via PROXY_TXT_KEY) out of the
+    result set by default so applications discover *physical* hubs.
+    """
+
+    def __init__(
+        self,
+        *,
+        zc: Any = None,
+        include_proxies: bool = False,
+        service_types: Iterable[str] = MDNS_SERVICE_TYPES,
+        on_added: Optional[HubCallback] = None,
+        on_updated: Optional[HubCallback] = None,
+        on_removed: Optional[HubCallback] = None,
+    ) -> None:
+        self._zc = zc
+        self._zc_owned = False
+        self._include_proxies = bool(include_proxies)
+        self._service_types = list(service_types)
+        self._on_added = on_added
+        self._on_updated = on_updated
+        self._on_removed = on_removed
+        self._browser: Any = None
+        self._lock = threading.Lock()
+        self._hubs: dict[tuple[str, str], DiscoveredHub] = {}
+
+    # -- zeroconf plumbing (overridable for tests) ----------------------
+
+    def _create_zeroconf(self) -> Any:
+        from zeroconf import IPVersion, Zeroconf
+
+        return Zeroconf(ip_version=IPVersion.V4Only)
+
+    def _create_browser(self, zc: Any) -> Any:
+        from zeroconf import ServiceBrowser
+
+        return ServiceBrowser(
+            zc, self._service_types, handlers=[self._on_service_state_change]
+        )
+
+    # -- lifecycle -------------------------------------------------------
+
+    def start(self) -> "HubBrowser":
+        if self._browser is not None:
+            return self
+        if self._zc is None:
+            self._zc = self._create_zeroconf()
+            self._zc_owned = True
+        self._browser = self._create_browser(self._zc)
+        return self
+
+    def stop(self) -> None:
+        browser, self._browser = self._browser, None
+        if browser is not None:
+            try:
+                browser.cancel()
+            except Exception:  # pragma: no cover - engine teardown races
+                log.debug("HubBrowser: browser cancel failed", exc_info=True)
+        if self._zc_owned and self._zc is not None:
+            try:
+                self._zc.close()
+            except Exception:  # pragma: no cover - engine teardown races
+                log.debug("HubBrowser: zeroconf close failed", exc_info=True)
+            self._zc = None
+            self._zc_owned = False
+
+    def __enter__(self) -> "HubBrowser":
+        return self.start()
+
+    def __exit__(self, *exc_info: Any) -> None:
+        self.stop()
+
+    # -- results ----------------------------------------------------------
+
+    @property
+    def hubs(self) -> list[DiscoveredHub]:
+        """Snapshot of currently-visible hubs, stable order."""
+
+        with self._lock:
+            return sorted(
+                self._hubs.values(), key=lambda hub: (hub.host, hub.instance_name)
+            )
+
+    # -- engine callbacks --------------------------------------------------
+
+    def _on_service_state_change(
+        self, zeroconf: Any, service_type: str, name: str, state_change: Any
+    ) -> None:
+        # Compare by enum name so fake engines in tests don't need the
+        # real zeroconf ServiceStateChange type.
+        change = getattr(state_change, "name", str(state_change))
+        if change == "Removed":
+            self._handle_removed(service_type, name)
+            return
+        if change not in ("Added", "Updated"):
+            return
+
+        info = None
+        try:
+            info = zeroconf.get_service_info(
+                service_type, name, timeout=_INFO_REQUEST_TIMEOUT_MS
+            )
+        except Exception:  # pragma: no cover - engine-side failures
+            log.debug("HubBrowser: get_service_info(%s) failed", name, exc_info=True)
+        if info is None:
+            return
+        self._handle_info(service_type, name, info, is_update=(change == "Updated"))
+
+    def _handle_info(
+        self, service_type: str, name: str, info: Any, *, is_update: bool
+    ) -> None:
+        host = self._first_ipv4(info)
+        hub = normalize_advertisement(
+            service_type,
+            name,
+            host=host,
+            port=getattr(info, "port", None),
+            properties=getattr(info, "properties", None),
+        )
+        if hub is None:
+            return
+        if hub.is_proxy and not self._include_proxies:
+            return
+
+        with self._lock:
+            previous = self._hubs.get(hub.key)
+            self._hubs[hub.key] = hub
+        if previous is None:
+            self._emit(self._on_added, hub)
+        elif previous != hub or is_update:
+            self._emit(self._on_updated, hub)
+
+    def _handle_removed(self, service_type: str, name: str) -> None:
+        with self._lock:
+            hub = self._hubs.pop((service_type, name), None)
+        if hub is not None:
+            self._emit(self._on_removed, hub)
+
+    @staticmethod
+    def _first_ipv4(info: Any) -> Optional[str]:
+        parsed = getattr(info, "parsed_addresses", None)
+        if callable(parsed):
+            try:
+                addresses = parsed()
+            except TypeError:  # pragma: no cover - exotic fakes
+                addresses = []
+            for address in addresses or []:
+                if ":" not in address:
+                    return address
+        return getattr(info, "host", None)
+
+    @staticmethod
+    def _emit(callback: Optional[HubCallback], hub: DiscoveredHub) -> None:
+        if callback is None:
+            return
+        try:
+            callback(hub)
+        except Exception:
+            log.exception("HubBrowser: callback failed for %s", hub.instance_name)
+
+
+def discover_hubs(
+    timeout: float = DEFAULT_DISCOVERY_TIMEOUT,
+    *,
+    zc: Any = None,
+    include_proxies: bool = False,
+) -> list[DiscoveredHub]:
+    """One-shot blocking scan for Sofabaton hubs on the local network.
+
+    Browses both hub service types for ``timeout`` seconds and returns
+    the normalized advertisements seen. Pass an existing ``Zeroconf``
+    instance via ``zc`` to share an engine; otherwise one is created and
+    torn down for the scan.
+    """
+
+    browser = HubBrowser(zc=zc, include_proxies=include_proxies)
+    browser.start()
+    try:
+        time.sleep(max(0.0, float(timeout)))
+        return browser.hubs
+    finally:
+        browser.stop()

sofapython/frame_handlers.py

@@ -0,0 +1,131 @@
+"""Utilities for decoding framed hub traffic.
+
+This module centralizes the registration of opcode-specific frame handlers so
+``X1Proxy._log_frames`` can simply route frames to the appropriate handler. To
+add support for a new opcode simply:
+
+1. Subclass :class:`BaseFrameHandler` (or implement the :class:`FrameHandler`
+   protocol) and override :meth:`BaseFrameHandler.handle`.
+2. Decorate the handler with :func:`register_handler`, specifying one or more
+   opcodes and (optionally) the directions that should trigger it.
+3. Access the :class:`FrameContext` passed to ``handle`` to introspect the frame
+   payload and mutate the :class:`~.x1_proxy.X1Proxy` state.
+
+Because handlers are registered via decorators, ``_log_frames`` never needs to
+change when new opcodes are implemented. Direction-specific handling is achieved
+by passing ``directions=("A→H",)`` (or ``("H→A",)``) to ``register_handler``.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol, Sequence, Iterator, Optional, runtime_checkable, TYPE_CHECKING
+
+from .protocol_const import opcode_family
+
+if TYPE_CHECKING:
+    from .x1_proxy import X1Proxy
+
+
+@dataclass(slots=True)
+class FrameContext:
+    """State passed to each handler invocation."""
+
+    proxy: "X1Proxy"
+    opcode: int
+    direction: str
+    payload: bytes
+    raw: bytes
+    name: str
+
+
+@runtime_checkable
+class FrameHandler(Protocol):
+    """Interface implemented by opcode handlers."""
+
+    def matches(self, opcode: int, direction: str) -> bool:  # pragma: no cover - protocol
+        """Return ``True`` when this handler should process the frame."""
+
+    def handle(self, frame: FrameContext) -> None:  # pragma: no cover - protocol
+        """Decode the frame and mutate ``frame.proxy`` as needed."""
+
+
+class BaseFrameHandler(FrameHandler):
+    """Convenience base class implementing ``matches`` via attributes."""
+
+    opcodes: tuple[int, ...] | None = None
+    opcode_families_low: tuple[int, ...] | None = None
+    directions: tuple[str, ...] | None = None
+
+    def matches(self, opcode: int, direction: str) -> bool:
+        if self.opcodes is None and self.opcode_families_low is None:
+            opcode_match = True
+        else:
+            opcode_match = False
+            if self.opcodes is not None and opcode in self.opcodes:
+                opcode_match = True
+            if (
+                not opcode_match
+                and self.opcode_families_low is not None
+                and opcode_family(opcode) in self.opcode_families_low
+            ):
+                opcode_match = True
+        direction_match = True if self.directions is None else direction in self.directions
+        return opcode_match and direction_match
+
+
+class FrameHandlerRegistry:
+    """Collection of registered handlers."""
+
+    def __init__(self) -> None:
+        self._handlers: list[FrameHandler] = []
+
+    def register(self, handler: FrameHandler) -> FrameHandler:
+        self._handlers.append(handler)
+        return handler
+
+    def iter_for(self, opcode: int, direction: str) -> Iterator[FrameHandler]:
+        for handler in self._handlers:
+            try:
+                if handler.matches(opcode, direction):
+                    yield handler
+            except Exception:
+                continue
+
+
+frame_handler_registry = FrameHandlerRegistry()
+
+
+def register_handler(
+    handler: Optional[type[BaseFrameHandler] | FrameHandler] = None,
+    *,
+    opcodes: Sequence[int] | None = None,
+    opcode_families_low: Sequence[int] | None = None,
+    directions: Sequence[str] | None = None,
+    registry: FrameHandlerRegistry = frame_handler_registry,
+):
+    """Decorator used to register ``FrameHandler`` implementations."""
+
+    def _decorator(obj):
+        instance = obj() if isinstance(obj, type) else obj
+        if opcodes is not None:
+            instance.opcodes = tuple(opcodes)  # type: ignore[attr-defined]
+        if opcode_families_low is not None:
+            instance.opcode_families_low = tuple(opcode_families_low)  # type: ignore[attr-defined]
+        if directions is not None:
+            instance.directions = tuple(directions)  # type: ignore[attr-defined]
+        registry.register(instance)
+        return obj
+
+    if handler is not None:
+        return _decorator(handler)
+    return _decorator
+
+
+__all__ = [
+    "BaseFrameHandler",
+    "FrameContext",
+    "FrameHandler",
+    "FrameHandlerRegistry",
+    "frame_handler_registry",
+    "register_handler",
+]

sofapython/hub_listener.py

@@ -0,0 +1,242 @@
+"""Process-wide TCP listener that dispatches accepted hub sockets to
+the right :class:`TransportBridge` by peer IP.
+
+Before this module, each ``TransportBridge`` opened its own listening
+socket on a unique port (8200, 8201, 8202, ...) and the hub dialled
+back to that per-instance port. With multiple hubs on one host that
+fanned the firewall surface and the bookkeeping out unnecessarily —
+every hub on the LAN has a unique IP, so peer IP is already a clean
+dispatch key.
+
+This singleton mirrors the existing :mod:`notify_demuxer` pattern:
+each ``TransportBridge`` registers ``(real_hub_ip, on_socket_cb)``;
+the listener accepts on one port and routes the socket to the
+matching bridge. Registrations also carry the hub's expected MAC
+(from the mDNS advertisement) for a sanity-check log if the peer IP
+maps to a different MAC than we expected.
+"""
+
+from __future__ import annotations
+
+import logging
+import socket
+import threading
+from dataclasses import dataclass
+from typing import Callable, Dict, Optional, Tuple
+
+from .hub_logging import get_hub_logger
+
+log = logging.getLogger("x1proxy.listener")
+
+# Default TCP port for the shared hub-side listener. Matches the
+# original ``hub_listen_base`` default; user-configured values still
+# work — the first registration's port wins (subsequent differing
+# values log a warning, mirroring NotifyDemuxer).
+DEFAULT_HUB_LISTEN_PORT = 8200
+
+
+OnSocketCallback = Callable[[socket.socket, Tuple[str, int]], None]
+
+
+@dataclass(frozen=True)
+class HubRegistration:
+    proxy_id: str
+    real_hub_ip: str
+    expected_mac_bytes: bytes  # 6 bytes; all-zero if unknown
+    on_socket: OnSocketCallback
+
+
+class HubListener:
+    """Accept TCP connections on one port; dispatch by peer IP."""
+
+    def __init__(self, listen_port: int = DEFAULT_HUB_LISTEN_PORT) -> None:
+        self.listen_port = int(listen_port)
+        self._sock: Optional[socket.socket] = None
+        self._thr: Optional[threading.Thread] = None
+        self._stop_event = threading.Event()
+        self._lock = threading.Lock()
+        # Keyed by real_hub_ip so dispatch is O(1) on accept.
+        self._by_ip: Dict[str, HubRegistration] = {}
+        self._by_proxy: Dict[str, HubRegistration] = {}
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+    def register_hub(
+        self,
+        *,
+        proxy_id: str,
+        real_hub_ip: str,
+        on_socket: OnSocketCallback,
+        expected_mac_bytes: bytes = b"\x00" * 6,
+    ) -> int:
+        """Register one bridge; return the listen port to advertise."""
+
+        reg = HubRegistration(
+            proxy_id=proxy_id,
+            real_hub_ip=real_hub_ip,
+            expected_mac_bytes=bytes(expected_mac_bytes[:6]).ljust(6, b"\x00"),
+            on_socket=on_socket,
+        )
+        with self._lock:
+            existing = self._by_ip.get(real_hub_ip)
+            if existing is not None and existing.proxy_id != proxy_id:
+                get_hub_logger(log, proxy_id).warning(
+                    "[LISTEN] replacing existing registration for %s "
+                    "(was proxy=%s)",
+                    real_hub_ip,
+                    existing.proxy_id,
+                )
+                self._by_proxy.pop(existing.proxy_id, None)
+            self._by_ip[real_hub_ip] = reg
+            self._by_proxy[proxy_id] = reg
+            self._ensure_running_locked()
+            get_hub_logger(log, proxy_id).info(
+                "[LISTEN] registered hub %s on shared port %d",
+                real_hub_ip,
+                self.listen_port,
+            )
+            return self.listen_port
+
+    def unregister_hub(self, proxy_id: str) -> None:
+        with self._lock:
+            reg = self._by_proxy.pop(proxy_id, None)
+            if reg is not None:
+                if self._by_ip.get(reg.real_hub_ip) is reg:
+                    self._by_ip.pop(reg.real_hub_ip, None)
+                get_hub_logger(log, proxy_id).info(
+                    "[LISTEN] unregistered hub %s", reg.real_hub_ip
+                )
+            self._stop_if_idle_locked()
+
+    def shutdown(self) -> None:
+        with self._lock:
+            self._by_ip.clear()
+            self._by_proxy.clear()
+            self._stop_thread_locked()
+
+    # ------------------------------------------------------------------
+    # Internals
+    # ------------------------------------------------------------------
+    def _ensure_running_locked(self) -> None:
+        if self._thr is not None and self._thr.is_alive():
+            return
+        self._stop_event = threading.Event()
+        self._sock = self._open_socket()
+        self._thr = threading.Thread(
+            target=self._accept_loop,
+            name="x1proxy-hub-listen",
+            daemon=True,
+        )
+        self._thr.start()
+
+    def _stop_if_idle_locked(self) -> None:
+        if self._by_proxy:
+            return
+        self._stop_thread_locked()
+
+    def _stop_thread_locked(self) -> None:
+        self._stop_event.set()
+        if self._sock is not None:
+            try:
+                self._sock.close()
+            except Exception:
+                pass
+            self._sock = None
+        if self._thr is not None:
+            self._thr.join(timeout=1.0)
+            self._thr = None
+
+    def _open_socket(self) -> socket.socket:
+        s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        s.bind(("0.0.0.0", self.listen_port))
+        s.listen(8)
+        s.settimeout(1.0)
+        log.info("[LISTEN] accepting hubs on *:%d", self.listen_port)
+        return s
+
+    def _accept_loop(self) -> None:
+        sock = self._sock
+        if sock is None:
+            return
+        while not self._stop_event.is_set():
+            try:
+                client, addr = sock.accept()
+            except socket.timeout:
+                continue
+            except OSError:
+                break
+            peer_ip, peer_port = addr[0], addr[1]
+
+            with self._lock:
+                reg = self._by_ip.get(peer_ip)
+
+            if reg is None:
+                log.warning(
+                    "[LISTEN] dropping unrecognised hub connection from %s:%d",
+                    peer_ip,
+                    peer_port,
+                )
+                try:
+                    client.shutdown(socket.SHUT_RDWR)
+                except Exception:
+                    pass
+                try:
+                    client.close()
+                except Exception:
+                    pass
+                continue
+
+            get_hub_logger(log, reg.proxy_id).info(
+                "[LISTEN] accepted hub %s:%d", peer_ip, peer_port
+            )
+            try:
+                reg.on_socket(client, (peer_ip, peer_port))
+            except Exception:
+                get_hub_logger(log, reg.proxy_id).exception(
+                    "[LISTEN] on_socket callback raised; closing"
+                )
+                try:
+                    client.shutdown(socket.SHUT_RDWR)
+                except Exception:
+                    pass
+                try:
+                    client.close()
+                except Exception:
+                    pass
+
+
+_GLOBAL_LISTENER: Optional[HubListener] = None
+_GLOBAL_LOCK = threading.Lock()
+
+
+def get_hub_listener(listen_port: Optional[int] = None) -> HubListener:
+    """Return the process-wide :class:`HubListener` singleton.
+
+    The first caller fixes the listen port. Later callers requesting a
+    different port get a warning and the existing instance — matching
+    the lifecycle behaviour of :func:`get_notify_demuxer`.
+    """
+
+    global _GLOBAL_LISTENER
+    with _GLOBAL_LOCK:
+        if _GLOBAL_LISTENER is None:
+            _GLOBAL_LISTENER = HubListener(listen_port or DEFAULT_HUB_LISTEN_PORT)
+        elif listen_port is not None and listen_port != _GLOBAL_LISTENER.listen_port:
+            log.warning(
+                "[LISTEN] existing listener on %d (ignoring requested %d)",
+                _GLOBAL_LISTENER.listen_port,
+                listen_port,
+            )
+        return _GLOBAL_LISTENER
+
+
+def reset_hub_listener_for_tests() -> None:
+    """Test helper: drop the global singleton."""
+
+    global _GLOBAL_LISTENER
+    with _GLOBAL_LOCK:
+        if _GLOBAL_LISTENER is not None:
+            _GLOBAL_LISTENER.shutdown()
+            _GLOBAL_LISTENER = None