sofapython 0.0.1rc1__py3-none-any.whl

sofapython/hub_logging.py

@@ -0,0 +1,152 @@
+# hub_logging.py — per-hub log prefixing and canonical subsystem tags.
+# Library-side source of truth; the Home Assistant integration's
+# logging_utils.py re-exports these names. Nothing here may import
+# outside the library package.
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any
+
+_HUB_LOG_PREFIX_PATTERN = re.compile(r"^\[(?P<entry_id>[^\[\]]+)\]\s+")
+
+
+class LogTag:
+    """Canonical subsystem tags for log-message prefixes.
+
+    Single source of truth for the ``[TAG]`` token that follows the per-hub
+    ``[entry_id]`` prefix added by :class:`HubLogger`. Every value is an
+    UPPERCASE, bracket-wrapped string so call sites can write the prefix
+    directly, e.g. ``log.debug("%s connected", LogTag.TRANSPORT)`` or
+    ``log.debug(f"{LogTag.FRAME} ...")``.
+
+    Tags are deliberately UPPERCASE: :func:`extract_hub_log_entry_id` rejects
+    an all-caps leading bracket, so a tag is never mistaken for a hub entry id
+    when a line carries no ``[entry_id]`` prefix (such lines are treated as
+    globally relevant and shown in every hub's view).
+    """
+
+    # Transport / wire
+    TRANSPORT = "[TRANSPORT]"   # socket bridge connect/disconnect/io (TCP/UDP)
+    SEND = "[SEND]"             # outbound frame dispatch to the hub
+    WIRE = "[WIRE]"             # full hex frame dumps (gated by the hex-logging switch)
+    FRAME = "[FRAME]"           # decoded inbound/outbound frame summaries (family/role/paging)
+    PARSE = "[PARSE]"           # frame-decode errors
+
+    # Lifecycle / identity
+    PROXY = "[PROXY]"           # proxy lifecycle: enable/disable/stop/hex toggle
+    MDNS = "[MDNS]"             # mDNS discovery / advertisement
+    HUB = "[HUB]"               # hub identity / name
+    BANNER = "[BANNER]"         # connect banner parsing
+    STATE = "[STATE]"           # current-activity / connection state changes
+
+    # Command dispatch & acks
+    CMD = "[CMD]"               # command queue / dispatch
+    ACK = "[ACK]"               # ack waiters / STATUS_ACK classification
+
+    # Catalog read paths
+    CATALOG = "[CATALOG]"       # device/activity/button/command catalog requests & parsing
+    MACRO = "[MACRO]"           # macro page decode
+    REMOTE = "[REMOTE]"         # remote sync/find, idle/device-control queries
+
+    # Write / mutation flows
+    CREATE = "[CREATE]"         # device/activity create flow
+    RESTORE = "[RESTORE]"       # restore flow
+    BACKUP = "[BACKUP]"         # backup serialization / erase
+    WIFI = "[WIFI]"             # wifi / virtual-ip device flow & per-step acks
+    IR = "[IR]"                 # IR blob play / persist
+    ACTIVITY = "[ACTIVITY]"     # activity-assign, favorites, keymap-write ops
+
+    # Subsystems
+    DEMUX = "[DEMUX]"           # CALL_ME notify demuxer
+    ROKU = "[ROKU]"             # Roku ECP listener
+    HINT = "[HINT]"             # diagnostic hints
+
+    @classmethod
+    def all(cls) -> tuple[str, ...]:
+        """Return every registered tag value."""
+
+        return tuple(
+            value
+            for name, value in vars(cls).items()
+            if not name.startswith("_") and isinstance(value, str)
+        )
+
+
+def extract_hub_log_entry_id(message: str) -> str | None:
+    """Return the canonical hub entry id from the start of a log message."""
+
+    match = _HUB_LOG_PREFIX_PATTERN.match(str(message or ""))
+    if not match:
+        return None
+    candidate = str(match.group("entry_id") or "").strip()
+    if re.fullmatch(r"[A-Z_]+", candidate):
+        return None
+    return candidate or None
+
+
+def format_hub_log_message(entry_id: str, message: str) -> str:
+    """Prepend the canonical hub prefix unless it is already present."""
+
+    text = str(message or "")
+    normalized_entry_id = str(entry_id or "").strip()
+    if not normalized_entry_id:
+        return text
+
+    existing_entry_id = extract_hub_log_entry_id(text)
+    if existing_entry_id == normalized_entry_id:
+        return text
+
+    return f"[{normalized_entry_id}] {text}"
+
+
+class HubLogger:
+    """Prefix log lines with the canonical hub entry id."""
+
+    def __init__(self, logger: logging.Logger, entry_id: str) -> None:
+        self._logger = logger
+        self._entry_id = str(entry_id or "").strip()
+
+    def isEnabledFor(self, level: int) -> bool:
+        return self._logger.isEnabledFor(level)
+
+    def log(self, level: int, message: str, *args: Any, **kwargs: Any) -> None:
+        normalized_message = str(message or "")
+        normalized_args = args
+
+        # Preserve existing call sites that still use "[%s] ..." with the
+        # entry id as the first formatting argument.
+        if (
+            normalized_message.startswith("[%s] ")
+            and normalized_args
+            and str(normalized_args[0] or "").strip() == self._entry_id
+        ):
+            normalized_message = normalized_message[5:]
+            normalized_args = normalized_args[1:]
+
+        self._logger.log(
+            level,
+            format_hub_log_message(self._entry_id, normalized_message),
+            *normalized_args,
+            **kwargs,
+        )
+
+    def debug(self, message: str, *args: Any, **kwargs: Any) -> None:
+        self.log(logging.DEBUG, message, *args, **kwargs)
+
+    def info(self, message: str, *args: Any, **kwargs: Any) -> None:
+        self.log(logging.INFO, message, *args, **kwargs)
+
+    def warning(self, message: str, *args: Any, **kwargs: Any) -> None:
+        self.log(logging.WARNING, message, *args, **kwargs)
+
+    def error(self, message: str, *args: Any, **kwargs: Any) -> None:
+        self.log(logging.ERROR, message, *args, **kwargs)
+
+    def exception(self, message: str, *args: Any, **kwargs: Any) -> None:
+        kwargs.setdefault("exc_info", True)
+        self.log(logging.ERROR, message, *args, **kwargs)
+
+
+def get_hub_logger(logger: logging.Logger, entry_id: str) -> HubLogger:
+    return HubLogger(logger, entry_id)

sofapython/hub_versions.py

@@ -0,0 +1,112 @@
+# hub_versions.py — hub-variant classification and shared protocol-level
+# constants. This module is the library-side source of truth; the Home
+# Assistant integration's const.py re-exports these names for its own
+# call sites. Nothing here may import outside the library package.
+from __future__ import annotations
+
+MDNS_SERVICE_TYPES: tuple[str, ...] = (
+    "_x1hub._udp.local.",
+    "_sofabaton_hub._udp.local.",
+)
+MDNS_SERVICE_TYPE_X1 = MDNS_SERVICE_TYPES[0]
+MDNS_SERVICE_TYPE_X2 = MDNS_SERVICE_TYPES[1]
+
+# Hub version classification
+HVER_X1 = "1"
+HVER_X1S = "2"
+HVER_X2 = "3"
+
+HUB_VERSION_X1 = "X1"
+HUB_VERSION_X1S = "X1S"
+HUB_VERSION_X2 = "X2"
+
+# Backup-format schema versions. These gate restore: a payload whose
+# schema_version does not match is rejected so the slim, hand-editable
+# format stays an exact contract (no silent reads of a stale verbose
+# dump). Bump the matching constant whenever the corresponding export
+# shape changes, and update the restore gate + fixtures together.
+DEVICE_BACKUP_SCHEMA_VERSION = 4
+ACTIVITY_BACKUP_SCHEMA_VERSION = 4
+HUB_BUNDLE_SCHEMA_VERSION = 5
+
+HUB_VERSION_BY_HVER = {
+    HVER_X1: HUB_VERSION_X1,
+    HVER_X1S: HUB_VERSION_X1S,
+    HVER_X2: HUB_VERSION_X2,
+}
+
+HVER_BY_HUB_VERSION = {
+    HUB_VERSION_X1: HVER_X1,
+    HUB_VERSION_X1S: HVER_X1S,
+    HUB_VERSION_X2: HVER_X2,
+}
+
+MDNS_SERVICE_TYPE_BY_VERSION = {
+    HUB_VERSION_X1: MDNS_SERVICE_TYPE_X1,
+    HUB_VERSION_X1S: MDNS_SERVICE_TYPE_X1,
+    # X2 hubs continue to use the legacy _x1hub._udp.local. advertisement for compatibility
+    HUB_VERSION_X2: MDNS_SERVICE_TYPE_X1,
+}
+
+DEFAULT_PROXY_UDP_PORT = 8102
+DEFAULT_HUB_LISTEN_BASE = 8200
+
+# TXT record marker carried by proxy advertisements so discovery can
+# tell a proxy apart from a physical hub. The key spells "HA_PROXY" for
+# historical reasons (the Home Assistant integration shipped it first);
+# renaming would orphan existing installs, so it stays vendor-named.
+PROXY_TXT_KEY = "HA_PROXY"
+PROXY_TXT_VALUE = "1"
+
+
+def is_proxy_advertisement(props: dict[str, str]) -> bool:
+    """True when TXT properties mark the advertiser as one of our proxies."""
+
+    return props.get(PROXY_TXT_KEY) == PROXY_TXT_VALUE
+
+
+def classify_hub_version(props: dict[str, str]) -> str:
+    """Determine hub version from advertised mDNS / banner properties.
+
+    Raises :class:`ValueError` when ``props`` carries no ``HVER`` key
+    or its value does not map to a known hub line. The integration
+    deliberately refuses to default to a previously-known variant in
+    that case: a missing or unfamiliar advertisement signals either an
+    upstream firmware change or a misconfigured manual entry, and
+    silently inheriting the X1 layout would corrupt every write to
+    that hub. Callers that cannot guarantee an ``HVER`` (e.g. fully
+    manual entry before first connect) must pick a known variant
+    explicitly rather than relying on this helper.
+    """
+
+    hver = props.get("HVER")
+    if hver is None:
+        raise ValueError(
+            "classify_hub_version: advertisement is missing HVER; "
+            "cannot identify hub variant."
+        )
+    version = HUB_VERSION_BY_HVER.get(str(hver).strip())
+    if not version:
+        known = ", ".join(sorted(HUB_VERSION_BY_HVER))
+        raise ValueError(
+            f"classify_hub_version: unknown HVER={hver!r}; "
+            f"expected one of {known}."
+        )
+    return version
+
+
+def mdns_service_type_for_props(props: dict[str, str]) -> str:
+    """Map hub properties to the correct mDNS service type.
+
+    The integration advertises the same service type for every known
+    variant, so an unclassifiable advertisement falls back to the
+    shared narrow-line type rather than refusing to advertise -- the
+    transport envelope is byte-compatible across the family and the
+    connect banner reclassifies authoritatively.
+    """
+
+    try:
+        version = classify_hub_version(props)
+    except ValueError:
+        return MDNS_SERVICE_TYPE_X1
+    return MDNS_SERVICE_TYPE_BY_VERSION.get(version, MDNS_SERVICE_TYPE_X1)