lifx-async 4.7.5__py3-none-any.whl → 4.8.1__py3-none-any.whl

lifx/network/mdns/dns.py

@@ -0,0 +1,356 @@
+"""DNS wire format parser for mDNS discovery.
+
+This module provides minimal DNS parsing for mDNS service discovery,
+supporting PTR, SRV, A, and TXT record types.
+
+Uses only Python stdlib (struct, socket).
+"""
+
+from __future__ import annotations
+
+import socket
+import struct
+from dataclasses import dataclass, field
+from typing import Any
+
+# DNS record types
+DNS_TYPE_A = 1
+DNS_TYPE_PTR = 12
+DNS_TYPE_TXT = 16
+DNS_TYPE_AAAA = 28
+DNS_TYPE_SRV = 33
+
+# DNS classes
+DNS_CLASS_IN = 1
+DNS_CLASS_UNIQUE = 0x8001  # Cache flush bit set
+
+# Type names for display
+_TYPE_NAMES = {
+    DNS_TYPE_A: "A",
+    DNS_TYPE_PTR: "PTR",
+    DNS_TYPE_TXT: "TXT",
+    DNS_TYPE_AAAA: "AAAA",
+    DNS_TYPE_SRV: "SRV",
+}
+
+
+@dataclass
+class DnsHeader:
+    """DNS message header (12 bytes).
+
+    Attributes:
+        id: Transaction ID (0 for mDNS)
+        flags: DNS flags
+        qd_count: Question count
+        an_count: Answer count
+        ns_count: Authority count
+        ar_count: Additional count
+    """
+
+    id: int
+    flags: int
+    qd_count: int
+    an_count: int
+    ns_count: int
+    ar_count: int
+
+    @property
+    def is_response(self) -> bool:
+        """Check if this is a response (QR bit set)."""
+        return bool(self.flags & 0x8000)
+
+    @classmethod
+    def parse(cls, data: bytes) -> DnsHeader:
+        """Parse a DNS header from bytes.
+
+        Args:
+            data: At least 12 bytes of DNS header data
+
+        Returns:
+            Parsed DnsHeader
+
+        Raises:
+            ValueError: If data is too short
+        """
+        if len(data) < 12:
+            raise ValueError(f"DNS header too short: {len(data)} bytes")
+        id_, flags, qd, an, ns, ar = struct.unpack("!HHHHHH", data[:12])
+        return cls(id_, flags, qd, an, ns, ar)
+
+
+@dataclass
+class SrvData:
+    """Parsed SRV record data.
+
+    Attributes:
+        priority: Service priority
+        weight: Service weight
+        port: Service port
+        target: Target hostname
+    """
+
+    priority: int
+    weight: int
+    port: int
+    target: str
+
+
+@dataclass
+class TxtData:
+    """Parsed TXT record data.
+
+    Attributes:
+        strings: Raw TXT strings
+        pairs: Key-value pairs parsed from strings containing '='
+    """
+
+    strings: list[str] = field(default_factory=list)
+    pairs: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass
+class DnsResourceRecord:
+    """DNS resource record.
+
+    Attributes:
+        name: Record name
+        rtype: Record type (A, PTR, TXT, SRV, etc.)
+        rclass: Record class (usually IN)
+        ttl: Time to live in seconds
+        rdata: Raw record data bytes
+        parsed_data: Parsed record data (type varies by rtype)
+    """
+
+    name: str
+    rtype: int
+    rclass: int
+    ttl: int
+    rdata: bytes
+    parsed_data: Any = None
+
+    @property
+    def type_name(self) -> str:
+        """Get human-readable record type name."""
+        return _TYPE_NAMES.get(self.rtype, f"TYPE{self.rtype}")
+
+    @property
+    def cache_flush(self) -> bool:
+        """Check if cache flush bit is set (mDNS unique)."""
+        return bool(self.rclass & 0x8000)
+
+
+@dataclass
+class ParsedDnsResponse:
+    """Parsed DNS response message.
+
+    Attributes:
+        header: DNS header
+        records: All resource records (answers + authority + additional)
+    """
+
+    header: DnsHeader
+    records: list[DnsResourceRecord]
+
+
+def parse_name(data: bytes, offset: int) -> tuple[str, int]:
+    """Parse a DNS name with compression pointer support.
+
+    DNS names use length-prefixed labels, with 0xC0 prefix indicating
+    compression pointers to earlier positions in the message.
+
+    Args:
+        data: Complete DNS message bytes
+        offset: Starting offset in data
+
+    Returns:
+        Tuple of (parsed name, new offset after the name)
+
+    Raises:
+        ValueError: If name parsing fails
+    """
+    labels: list[str] = []
+    original_offset = offset
+    jumped = False
+    max_jumps = 10  # Prevent infinite loops
+    jumps = 0
+
+    while True:
+        if offset >= len(data):
+            raise ValueError(f"DNS name parsing ran off end of data at offset {offset}")
+
+        length = data[offset]
+
+        # Check for compression pointer (top 2 bits set)
+        if (length & 0xC0) == 0xC0:
+            if offset + 1 >= len(data):
+                raise ValueError("Compression pointer incomplete")
+            # Pointer to earlier in message
+            pointer = ((length & 0x3F) << 8) | data[offset + 1]
+            if not jumped:
+                original_offset = offset + 2
+            jumped = True
+            offset = pointer
+            jumps += 1
+            if jumps > max_jumps:
+                raise ValueError("Too many compression pointer jumps")
+            continue
+
+        offset += 1
+
+        if length == 0:
+            # End of name
+            break
+
+        if offset + length > len(data):
+            raise ValueError(
+                f"Label extends beyond data: offset={offset}, length={length}"
+            )
+
+        label = data[offset : offset + length].decode("utf-8", errors="replace")
+        labels.append(label)
+        offset += length
+
+    name = ".".join(labels) if labels else "."
+    final_offset = original_offset if jumped else offset
+
+    return name, final_offset
+
+
+def parse_txt_record(rdata: bytes) -> TxtData:
+    """Parse TXT record data.
+
+    TXT records contain one or more length-prefixed strings.
+    LIFX uses key=value format in these strings.
+
+    Args:
+        rdata: TXT record data bytes
+
+    Returns:
+        Parsed TxtData with strings and key-value pairs
+    """
+    txt_data = TxtData()
+    offset = 0
+
+    while offset < len(rdata):
+        str_len = rdata[offset]
+        offset += 1
+        if offset + str_len > len(rdata):
+            break
+        txt_str = rdata[offset : offset + str_len].decode("utf-8", errors="replace")
+        txt_data.strings.append(txt_str)
+        # Try to parse as key=value
+        if "=" in txt_str:
+            key, _, value = txt_str.partition("=")
+            txt_data.pairs[key] = value
+        offset += str_len
+
+    return txt_data
+
+
+def _parse_resource_record(data: bytes, offset: int) -> tuple[DnsResourceRecord, int]:
+    """Parse a single DNS resource record.
+
+    Args:
+        data: Complete DNS message bytes
+        offset: Starting offset of the record
+
+    Returns:
+        Tuple of (parsed record, new offset after the record)
+
+    Raises:
+        ValueError: If record parsing fails
+    """
+    name, offset = parse_name(data, offset)
+
+    if offset + 10 > len(data):
+        raise ValueError(f"Resource record header incomplete at offset {offset}")
+
+    rtype, rclass, ttl, rdlength = struct.unpack("!HHIH", data[offset : offset + 10])
+    offset += 10
+
+    if offset + rdlength > len(data):
+        available = len(data) - offset
+        raise ValueError(
+            f"Resource record data incomplete: need {rdlength}, have {available}"
+        )
+
+    rdata = data[offset : offset + rdlength]
+    offset += rdlength
+
+    # Parse specific record types
+    parsed_data: Any = None
+
+    if rtype == DNS_TYPE_A and rdlength == 4:
+        parsed_data = socket.inet_ntoa(rdata)
+
+    elif rtype == DNS_TYPE_AAAA and rdlength == 16:
+        parsed_data = socket.inet_ntop(socket.AF_INET6, rdata)
+
+    elif rtype == DNS_TYPE_PTR:
+        parsed_data, _ = parse_name(data, offset - rdlength)
+
+    elif rtype == DNS_TYPE_SRV and rdlength >= 6:
+        priority, weight, port = struct.unpack("!HHH", rdata[:6])
+        target, _ = parse_name(data, offset - rdlength + 6)
+        parsed_data = SrvData(priority, weight, port, target)
+
+    elif rtype == DNS_TYPE_TXT:
+        parsed_data = parse_txt_record(rdata)
+
+    return DnsResourceRecord(name, rtype, rclass, ttl, rdata, parsed_data), offset
+
+
+def parse_dns_response(data: bytes) -> ParsedDnsResponse:
+    """Parse a complete DNS response message.
+
+    Args:
+        data: Complete DNS message bytes
+
+    Returns:
+        ParsedDnsResponse containing header and all records
+
+    Raises:
+        ValueError: If message parsing fails
+    """
+    header = DnsHeader.parse(data)
+    offset = 12
+    records: list[DnsResourceRecord] = []
+
+    # Skip questions (we don't need them for responses)
+    for _ in range(header.qd_count):
+        _, offset = parse_name(data, offset)
+        offset += 4  # QTYPE + QCLASS
+
+    # Parse all resource records (answers, authority, additional)
+    total_records = header.an_count + header.ns_count + header.ar_count
+    for _ in range(total_records):
+        record, offset = _parse_resource_record(data, offset)
+        records.append(record)
+
+    return ParsedDnsResponse(header, records)
+
+
+def build_ptr_query(service: str) -> bytes:
+    """Build an mDNS PTR query for a service type.
+
+    Args:
+        service: Service name (e.g., "_lifx._udp.local")
+
+    Returns:
+        DNS query packet bytes ready to send
+
+    Example:
+        >>> query = build_ptr_query("_lifx._udp.local")
+        >>> # Send to 224.0.0.251:5353
+    """
+    # Header: ID=0 (mDNS), standard query, 1 question
+    header = struct.pack("!HHHHHH", 0, 0, 1, 0, 0, 0)
+
+    # Question: service name, PTR type, IN class
+    question = b""
+    for label in service.split("."):
+        question += bytes([len(label)]) + label.encode("utf-8")
+    question += b"\x00"  # Root label
+    question += struct.pack("!HH", DNS_TYPE_PTR, DNS_CLASS_IN)
+
+    return header + question

lifx/network/mdns/transport.py

@@ -0,0 +1,313 @@
+"""mDNS transport for multicast UDP communication.
+
+This module provides a UDP transport specifically for mDNS queries,
+with multicast group joining and appropriate socket configuration.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import socket
+import struct
+from asyncio import DatagramTransport
+from typing import TYPE_CHECKING
+
+from lifx.const import MDNS_ADDRESS, MDNS_PORT
+from lifx.exceptions import LifxNetworkError, LifxTimeoutError
+
+if TYPE_CHECKING:
+    pass
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class _MdnsProtocol(asyncio.DatagramProtocol):
+    """Asyncio protocol for mDNS UDP communication."""
+
+    def __init__(self) -> None:
+        """Initialize the protocol."""
+        self.queue: asyncio.Queue[tuple[bytes, tuple[str, int]]] = asyncio.Queue()
+        self._transport: DatagramTransport | None = None
+
+    def connection_made(self, transport: DatagramTransport) -> None:  # type: ignore[override]
+        """Called when connection is established."""
+        self._transport = transport
+
+    def datagram_received(self, data: bytes, addr: tuple[str, int]) -> None:
+        """Called when a datagram is received."""
+        self.queue.put_nowait((data, addr))
+
+    def error_received(self, exc: Exception) -> None:
+        """Called when an error is received."""
+        _LOGGER.debug(
+            {
+                "class": "_MdnsProtocol",
+                "method": "error_received",
+                "action": "error",
+                "error": str(exc),
+            }
+        )
+
+    def connection_lost(self, exc: Exception | None) -> None:
+        """Called when connection is lost."""
+        _LOGGER.debug(
+            {
+                "class": "_MdnsProtocol",
+                "method": "connection_lost",
+                "action": "lost",
+                "error": str(exc) if exc else None,
+            }
+        )
+
+
+class MdnsTransport:
+    """UDP transport for mDNS multicast communication.
+
+    This transport is specifically designed for mDNS queries and responses,
+    with support for multicast group membership and appropriate socket options.
+
+    Example:
+        >>> async with MdnsTransport() as transport:
+        ...     await transport.send(query, (MDNS_ADDRESS, MDNS_PORT))
+        ...     data, addr = await transport.receive(timeout=5.0)
+    """
+
+    def __init__(self) -> None:
+        """Initialize mDNS transport."""
+        self._protocol: _MdnsProtocol | None = None
+        self._transport: DatagramTransport | None = None
+        self._socket: socket.socket | None = None
+
+    async def __aenter__(self) -> MdnsTransport:
+        """Enter async context manager."""
+        await self.open()
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        """Exit async context manager."""
+        await self.close()
+
+    async def open(self) -> None:
+        """Open the mDNS socket with multicast configuration.
+
+        Creates a UDP socket, configures it for mDNS multicast,
+        and joins the mDNS multicast group.
+
+        Raises:
+            LifxNetworkError: If socket creation or configuration fails
+        """
+        if self._protocol is not None:
+            _LOGGER.debug(
+                {
+                    "class": "MdnsTransport",
+                    "method": "open",
+                    "action": "already_open",
+                }
+            )
+            return
+
+        try:
+            loop = asyncio.get_running_loop()
+
+            # Create and configure socket manually for multicast
+            sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM, socket.IPPROTO_UDP)
+            sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+
+            # Try to set SO_REUSEPORT if available (Linux/macOS)
+            try:
+                sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEPORT, 1)
+            except (AttributeError, OSError):
+                pass
+
+            # Bind to mDNS port (or ephemeral if busy)
+            try:
+                sock.bind(("", MDNS_PORT))
+                _LOGGER.debug(
+                    {
+                        "class": "MdnsTransport",
+                        "method": "open",
+                        "action": "bound_to_mdns_port",
+                        "port": MDNS_PORT,
+                    }
+                )
+            except OSError as e:
+                _LOGGER.debug(
+                    {
+                        "class": "MdnsTransport",
+                        "method": "open",
+                        "action": "mdns_port_busy",
+                        "error": str(e),
+                    }
+                )
+                # Fall back to ephemeral port
+                sock.bind(("", 0))
+                _LOGGER.debug(
+                    {
+                        "class": "MdnsTransport",
+                        "method": "open",
+                        "action": "bound_to_ephemeral_port",
+                        "port": sock.getsockname()[1],
+                    }
+                )
+
+            # Join mDNS multicast group
+            mreq = struct.pack("4sl", socket.inet_aton(MDNS_ADDRESS), socket.INADDR_ANY)
+            sock.setsockopt(socket.IPPROTO_IP, socket.IP_ADD_MEMBERSHIP, mreq)
+            _LOGGER.debug(
+                {
+                    "class": "MdnsTransport",
+                    "method": "open",
+                    "action": "joined_multicast_group",
+                    "group": MDNS_ADDRESS,
+                }
+            )
+
+            # Set multicast TTL (1 for link-local)
+            sock.setsockopt(socket.IPPROTO_IP, socket.IP_MULTICAST_TTL, 1)
+
+            # Make socket non-blocking
+            sock.setblocking(False)
+            self._socket = sock
+
+            # Create protocol
+            protocol = _MdnsProtocol()
+            self._protocol = protocol
+
+            # Create datagram endpoint using our configured socket
+            self._transport, _ = await loop.create_datagram_endpoint(
+                lambda: protocol,
+                sock=sock,
+            )
+
+            _LOGGER.debug(
+                {
+                    "class": "MdnsTransport",
+                    "method": "open",
+                    "action": "opened",
+                }
+            )
+
+        except OSError as e:
+            _LOGGER.debug(
+                {
+                    "class": "MdnsTransport",
+                    "method": "open",
+                    "action": "failed",
+                    "error": str(e),
+                }
+            )
+            raise LifxNetworkError(f"Failed to open mDNS socket: {e}") from e
+
+    async def send(self, data: bytes, address: tuple[str, int] | None = None) -> None:
+        """Send data to mDNS multicast address.
+
+        Args:
+            data: Bytes to send
+            address: Target address (defaults to mDNS multicast address)
+
+        Raises:
+            LifxNetworkError: If socket is not open or send fails
+        """
+        if self._transport is None or self._protocol is None:
+            raise LifxNetworkError("Socket not open")
+
+        if address is None:
+            address = (MDNS_ADDRESS, MDNS_PORT)
+
+        try:
+            self._transport.sendto(data, address)
+            _LOGGER.debug(
+                {
+                    "class": "MdnsTransport",
+                    "method": "send",
+                    "action": "sent",
+                    "size": len(data),
+                    "destination": address,
+                }
+            )
+        except OSError as e:
+            _LOGGER.debug(
+                {
+                    "class": "MdnsTransport",
+                    "method": "send",
+                    "action": "failed",
+                    "destination": address,
+                    "error": str(e),
+                }
+            )
+            raise LifxNetworkError(f"Failed to send mDNS data: {e}") from e
+
+    async def receive(self, timeout: float = 5.0) -> tuple[bytes, tuple[str, int]]:
+        """Receive data from socket.
+
+        Args:
+            timeout: Timeout in seconds
+
+        Returns:
+            Tuple of (data, address) where address is (host, port)
+
+        Raises:
+            LifxTimeoutError: If no data received within timeout
+            LifxNetworkError: If socket is not open or receive fails
+        """
+        if self._protocol is None:
+            raise LifxNetworkError("Socket not open")
+
+        try:
+            async with asyncio.timeout(timeout):
+                data, addr = await self._protocol.queue.get()
+                return data, addr
+        except TimeoutError as e:
+            raise LifxTimeoutError(f"No mDNS data received within {timeout}s") from e
+        except OSError as e:
+            _LOGGER.debug(
+                {
+                    "class": "MdnsTransport",
+                    "method": "receive",
+                    "action": "failed",
+                    "error": str(e),
+                }
+            )
+            raise LifxNetworkError(f"Failed to receive mDNS data: {e}") from e
+
+    async def close(self) -> None:
+        """Close the mDNS socket."""
+        if self._transport is not None:
+            _LOGGER.debug(
+                {
+                    "class": "MdnsTransport",
+                    "method": "close",
+                    "action": "closing",
+                }
+            )
+
+            # Leave multicast group
+            if self._socket is not None:
+                try:
+                    mreq = struct.pack(
+                        "4sl", socket.inet_aton(MDNS_ADDRESS), socket.INADDR_ANY
+                    )
+                    self._socket.setsockopt(
+                        socket.IPPROTO_IP, socket.IP_DROP_MEMBERSHIP, mreq
+                    )
+                except OSError:
+                    pass  # Ignore errors when leaving group
+
+            self._transport.close()
+            self._transport = None
+            self._protocol = None
+            self._socket = None
+
+            _LOGGER.debug(
+                {
+                    "class": "MdnsTransport",
+                    "method": "close",
+                    "action": "closed",
+                }
+            )
+
+    @property
+    def is_open(self) -> bool:
+        """Check if socket is open."""
+        return self._protocol is not None

lifx/network/mdns/types.py

@@ -0,0 +1,35 @@
+"""Type definitions for mDNS discovery.
+
+This module defines the data structures used for mDNS service discovery.
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class LifxServiceRecord:
+    """Information about a LIFX device discovered via mDNS.
+
+    Attributes:
+        serial: Device serial number as 12-digit hex string (e.g., "d073d5123456")
+        ip: Device IP address
+        port: Device UDP port (typically 56700)
+        product_id: Product ID from TXT record 'p' field
+        firmware: Firmware version from TXT record 'fw' field
+    """
+
+    serial: str
+    ip: str
+    port: int
+    product_id: int
+    firmware: str
+
+    def __hash__(self) -> int:
+        """Hash based on serial number for deduplication."""
+        return hash(self.serial)
+
+    def __eq__(self, other: object) -> bool:
+        """Equality based on serial number."""
+        if not isinstance(other, LifxServiceRecord):
+            return False
+        return self.serial == other.serial