"""Minimal async XML-RPC client for the Riedel Router Control Software (RRCS).

RRCS speaks plain XML-RPC over HTTP, by default on TCP 8193. Every request
takes a transaction key ("TransKey") as its first parameter and echoes it back
in the response. See the RRCS Interface Specification, chapter 5.

Two shapes of reply are common:

    [TransKey, ErrorCode, ...]                  most Set*/Get* calls
    {"TransKey": ..., "ErrorCode": ..., ...}    the "dump" style calls

A handful of calls (RegisterForAllEvents, XpVolumeChangeRegistry*) return a
bare string TransKey with no error code at all, so error checking is opt-in per
call rather than automatic.
"""

from __future__ import annotations

import asyncio
import itertools
import json
import logging
import re
import xmlrpc.client
from dataclasses import dataclass
from typing import Any
from xml.parsers.expat import ExpatError

import aiohttp

from .const import ERROR_CODES

_LOGGER = logging.getLogger(__name__)

_XML_DECL_RE = re.compile(rb"<\?xml[^>]*\?>")


class RRCSError(Exception):
    """Base error for RRCS communication."""

    def __init__(self, message: str, code: int | None = None) -> None:
        """Initialise with an optional RRCS error code."""
        super().__init__(message)
        self.code = code


class RRCSConnectionError(RRCSError):
    """Raised when the gateway could not be reached."""


class RRCSProtocolError(RRCSError):
    """Raised when the gateway replied with something unparseable."""


class RRCSFaultError(RRCSError):
    """Raised when the gateway returned an XML-RPC fault."""


def describe_error(code: int) -> str:
    """Return the human readable text for an RRCS error code."""
    return ERROR_CODES.get(code, f"Unknown error code {code}")


def parse_xmlrpc(raw: bytes) -> tuple[tuple[Any, ...], str | None]:
    """Parse an XML-RPC document, tolerating a mismatched encoding declaration.

    Some RRCS builds declare UTF-8 but emit single-byte port labels, which makes
    expat refuse the document outright. Dropping the declaration and decoding
    leniently recovers those responses instead of losing the whole poll.
    """
    try:
        return xmlrpc.client.loads(raw)
    except ExpatError:
        stripped = _XML_DECL_RE.sub(b"", raw, count=1)
        text = stripped.decode("utf-8", errors="replace")
        try:
            return xmlrpc.client.loads(text)
        except ExpatError as err:
            raise RRCSProtocolError(f"Could not parse RRCS response: {err}") from err


def extract_error_code(result: Any) -> int | None:
    """Pull the ErrorCode out of a reply, if it has one in a known position."""
    if isinstance(result, dict):
        code = result.get("ErrorCode")
        return code if isinstance(code, int) else None
    if isinstance(result, (list, tuple)) and len(result) >= 2:
        code = result[1]
        return code if isinstance(code, int) and not isinstance(code, bool) else None
    return None


@dataclass(frozen=True)
class LogicSource:
    """A logic source as returned by GetAllLogicSources_v2."""

    object_id: int
    long_name: str
    label: str
    state: bool


@dataclass(frozen=True)
class GpioAddress:
    """Addressing tuple used by Set/GetGpOutput and GetGpInputState.

    Chapter 6.9: for a GPIO card the port is 128 and the slot selects the bay;
    for a panel GPIO the port is the panel's port address and the slot is
    ignored.
    """

    net: int
    node: int
    port: int
    slot: int
    index: int
    is_input: bool

    @property
    def key(self) -> str:
        """Stable identifier used for unique IDs."""
        direction = "in" if self.is_input else "out"
        return f"{self.net}_{self.node}_{self.port}_{self.slot}_{self.index}_{direction}"

    @property
    def pretty(self) -> str:
        """Human readable address."""
        return (
            f"Net {self.net} / Node {self.node} / Port {self.port} / "
            f"Slot {self.slot} / GPIO {self.index}"
        )


class RRCSClient:
    """Talks XML-RPC to an RRCS gateway.

    Requests are serialised behind a lock. RRCS is a single Windows service
    fronting a real intercom ring and it does not enjoy being hammered with
    concurrent RPCs; the specification's own timing notes (chapter 12) assume an
    otherwise idle gateway.
    """

    def __init__(
        self,
        session: aiohttp.ClientSession,
        host: str,
        port: int = 8193,
        path: str = "/",
        timeout: float = 15.0,
        transkey_prefix: str = "C",
    ) -> None:
        """Initialise the client."""
        self._session = session
        self.host = host
        self.port = port
        self.path = path if path.startswith("/") else f"/{path}"
        self.timeout = timeout
        self._prefix = (transkey_prefix or "C")[0]
        self._counter = itertools.count(1)
        self._lock = asyncio.Lock()

    @property
    def url(self) -> str:
        """Return the endpoint URL."""
        return f"http://{self.host}:{self.port}{self.path}"

    def next_transkey(self) -> str:
        """Return a fresh transaction key.

        The specification wants a single leading character followed by exactly
        ten digits. The counter wraps well before it runs out of room.
        """
        return f"{self._prefix}{next(self._counter) % 10_000_000_000:010d}"

    async def call(self, method: str, *args: Any, check: bool = False) -> Any:
        """Call an RRCS method, prepending a fresh transaction key.

        Set ``check=True`` for methods whose reply is known to be
        ``[TransKey, ErrorCode, ...]`` or a struct with an ``ErrorCode`` member.
        It is off by default because some replies put a payload integer in the
        same slot (GetLevelMeterValues returns the level there, for instance).
        """
        return await self.call_raw(method, (self.next_transkey(), *args), check=check)

    async def call_raw(
        self, method: str, params: tuple[Any, ...], *, check: bool = False
    ) -> Any:
        """Call an RRCS method with an explicit parameter tuple."""
        body = xmlrpc.client.dumps(tuple(params), method, encoding="utf-8")
        _LOGGER.debug("RRCS -> %s %s", method, params)

        async with self._lock:
            try:
                async with self._session.post(
                    self.url,
                    data=body.encode("utf-8"),
                    headers={"Content-Type": "text/xml; charset=utf-8"},
                    timeout=aiohttp.ClientTimeout(total=self.timeout),
                ) as response:
                    if response.status != 200:
                        raise RRCSConnectionError(
                            f"{method}: gateway returned HTTP {response.status}"
                        )
                    raw = await response.read()
            except asyncio.TimeoutError as err:
                raise RRCSConnectionError(f"{method}: timed out after {self.timeout}s") from err
            except aiohttp.ClientError as err:
                raise RRCSConnectionError(f"{method}: {err}") from err

        try:
            parsed, _ = parse_xmlrpc(raw)
        except xmlrpc.client.Fault as err:
            raise RRCSFaultError(
                f"{method}: fault {err.faultCode}: {err.faultString}", err.faultCode
            ) from err

        result = parsed[0] if parsed else None
        _LOGGER.debug("RRCS <- %s %s", method, result)

        if check:
            code = extract_error_code(result)
            if code:
                raise RRCSError(f"{method}: {describe_error(code)}", code)

        return result

    # --- Convenience wrappers ------------------------------------------------------

    async def get_version(self) -> str | None:
        """Return the RRCS version string."""
        result = await self.call("GetVersion")
        if isinstance(result, (list, tuple)) and len(result) >= 3:
            return str(result[2])
        return None

    async def get_state(self) -> str | None:
        """Return the gateway state, 'Working' or 'Standby'."""
        result = await self.call("GetState")
        if isinstance(result, (list, tuple)) and len(result) >= 3:
            return str(result[2])
        return None

    async def is_connected_to_artist(self) -> bool:
        """Return whether RRCS currently has a working link to the Artist net."""
        result = await self.call("IsConnectedToArtist")
        if isinstance(result, dict):
            return bool(result.get("IsConnected"))
        return False

    async def get_active_xp_count(self) -> int | None:
        """Return the number of crosspoints RRCS considers active."""
        result = await self.call("GetAllActiveXpsCount")
        if isinstance(result, (list, tuple)) and len(result) >= 3:
            value = result[2]
            if isinstance(value, int):
                return value
        if isinstance(result, dict):
            for key in ("XP Count", "XPCount", "Count"):
                if isinstance(result.get(key), int):
                    return result[key]
        return None

    async def get_logic_sources(self) -> dict[int, LogicSource]:
        """Return every logic source in the system, keyed by object ID.

        GetAllLogicSources_v2 returns a struct whose members are named
        ``LogicSource#1``, ``LogicSource#2`` and so on, each an array of
        ``[LongName, Label, ObjectID, State]``.
        """
        result = await self.call("GetAllLogicSources_v2")
        if not isinstance(result, dict):
            raise RRCSProtocolError("GetAllLogicSources_v2 did not return a struct")

        code = result.get("ErrorCode")
        if isinstance(code, int) and code:
            raise RRCSError(f"GetAllLogicSources_v2: {describe_error(code)}", code)

        sources: dict[int, LogicSource] = {}
        for name, value in result.items():
            if not name.startswith("LogicSource#") or not isinstance(value, (list, tuple)):
                continue
            if len(value) < 3:
                continue
            long_name, label, object_id = value[0], value[1], value[2]
            if not isinstance(object_id, int):
                continue
            state = bool(value[3]) if len(value) > 3 else False
            sources[object_id] = LogicSource(
                object_id=object_id,
                long_name=str(long_name or "").strip(),
                label=str(label or "").strip(),
                state=state,
            )
        return sources

    async def set_logic_source(self, object_id: int, state: bool) -> None:
        """Activate or deactivate a logic source."""
        await self.call("SetLogicSourceState", int(object_id), bool(state), check=True)

    async def get_gp_input_state(self, address: GpioAddress) -> bool:
        """Read a general purpose input."""
        result = await self.call(
            "GetGpInputState",
            address.net,
            address.node,
            address.port,
            address.slot,
            address.index,
        )
        return _trailing_bool(result)

    async def get_gp_output_state(self, address: GpioAddress) -> bool:
        """Read a general purpose output."""
        result = await self.call(
            "GetGpOutputState",
            address.net,
            address.node,
            address.port,
            address.slot,
            address.index,
        )
        return _trailing_bool(result)

    async def set_gp_output(self, address: GpioAddress, state: bool) -> None:
        """Drive a general purpose output."""
        await self.call(
            "SetGpOutput",
            address.net,
            address.node,
            address.port,
            address.slot,
            address.index,
            int(bool(state)),
            check=True,
        )

    async def discover_gpios(self) -> list[GpioAddress]:
        """Best-effort discovery of configured GPIOs (RRCS 8.8 and later).

        GetAllGpIns / GetAllGpOuts are documented only by name, not by return
        shape, so this walks whatever comes back looking for structs that carry
        an addressable GPIO. Anything it cannot make sense of is skipped and
        logged at debug level.
        """
        found: dict[str, GpioAddress] = {}
        for method, is_input in (("GetAllGpIns", True), ("GetAllGpOuts", False)):
            try:
                result = await self.call(method)
            except RRCSError as err:
                _LOGGER.debug("%s unavailable (%s); skipping GPIO discovery", method, err)
                continue
            _LOGGER.debug("%s raw payload: %r", method, result)
            for address in _walk_gpio_structs(result, is_input):
                found.setdefault(address.key, address)
        return list(found.values())

    # --- Notification registration -------------------------------------------------

    async def register_for_all_events(
        self,
        tcp_port: int,
        url_path: str,
        pipelining: bool = False,
        multicall: bool = False,
    ) -> None:
        """Ask RRCS to push every event to us.

        RRCS derives the destination host from the source address of this very
        request, so the gateway must be able to reach Home Assistant back on the
        same IP at ``tcp_port``.
        """
        await self.call(
            "RegisterForAllEvents",
            int(tcp_port),
            str(url_path),
            bool(pipelining),
            bool(multicall),
        )

    async def unregister_for_all_events(self, tcp_port: int, url_path: str) -> None:
        """Stop receiving notifications."""
        await self.call("UnregisterForAllEvents", int(tcp_port), str(url_path))

    async def is_registered_for_all_events(self, tcp_port: int, url_path: str) -> bool:
        """Return whether RRCS still has our notification registration."""
        result = await self.call(
            "IsRegisteredForAllEvents", int(tcp_port), str(url_path)
        )
        if isinstance(result, dict):
            return bool(result.get("IsRegistered"))
        return False


def parse_gpio_config(raw: Any) -> list[tuple[GpioAddress, str | None]]:
    """Parse the manual GPIO list from the options flow.

    Accepts a JSON array of objects, each with at minimum ``index`` and
    ``node``. ``direction`` is ``in`` or ``out`` and defaults to ``in``;
    ``net`` defaults to 1, ``port`` to 128 (the GPIO client card) and ``slot``
    to 0.
    """
    if not raw:
        return []
    if isinstance(raw, str):
        raw = raw.strip()
        if not raw:
            return []
        try:
            raw = json.loads(raw)
        except json.JSONDecodeError as err:
            raise ValueError(f"GPIO list is not valid JSON: {err}") from err
    if isinstance(raw, dict):
        raw = [raw]
    if not isinstance(raw, list):
        raise ValueError("GPIO list must be a JSON array of objects")

    result: list[tuple[GpioAddress, str | None]] = []
    for position, item in enumerate(raw, start=1):
        if not isinstance(item, dict):
            raise ValueError(f"GPIO entry {position} is not an object")
        try:
            node = int(item["node"])
            index = int(item["index"])
        except (KeyError, TypeError, ValueError) as err:
            raise ValueError(
                f"GPIO entry {position} needs numeric 'node' and 'index'"
            ) from err
        direction = str(item.get("direction", "in")).lower()
        if direction not in ("in", "out", "input", "output"):
            raise ValueError(
                f"GPIO entry {position}: direction must be 'in' or 'out'"
            )
        address = GpioAddress(
            net=int(item.get("net", 1)),
            node=node,
            port=int(item.get("port", 128)),
            slot=int(item.get("slot", 0)),
            index=index,
            is_input=direction.startswith("in"),
        )
        name = item.get("name")
        result.append((address, str(name) if name else None))
    return result


def _trailing_bool(result: Any) -> bool:
    """Pull the boolean state out of a ``[TransKey, ErrorCode, state]`` reply."""
    if isinstance(result, (list, tuple)):
        code = extract_error_code(result)
        if code:
            raise RRCSError(describe_error(code), code)
        for value in reversed(result):
            if isinstance(value, bool):
                return value
        if len(result) >= 3 and isinstance(result[2], int):
            return bool(result[2])
    return False


def _walk_gpio_structs(node: Any, is_input: bool) -> list[GpioAddress]:
    """Recursively collect GPIO addresses from an arbitrary decoded payload."""
    found: list[GpioAddress] = []
    if isinstance(node, dict):
        address = _gpio_from_struct(node, is_input)
        if address is not None:
            found.append(address)
        for value in node.values():
            found.extend(_walk_gpio_structs(value, is_input))
    elif isinstance(node, (list, tuple)):
        for value in node:
            found.extend(_walk_gpio_structs(value, is_input))
    return found


def _gpio_from_struct(struct: dict[str, Any], is_input: bool) -> GpioAddress | None:
    """Map one decoded struct onto the Net/Node/Port/Slot/Index addressing.

    Follows the three TGPIOAddress variants in chapter 6.7: a GPIO on a port
    carries a nested PortAddress, one on a client card carries a Bay, and one on
    a SIC carries only Node and Index.
    """
    index = struct.get("Index", struct.get("GpioNumber", struct.get("Gpio")))
    if not isinstance(index, int) or isinstance(index, bool):
        return None

    direction = struct.get("IsInput")
    if isinstance(direction, bool):
        is_input = direction

    net = struct.get("Net", 1)
    net = net if isinstance(net, int) and not isinstance(net, bool) else 1

    port_address = struct.get("PortAddress")
    if isinstance(port_address, dict):
        node = port_address.get("Node")
        port = port_address.get("Port")
        if isinstance(node, int) and isinstance(port, int):
            return GpioAddress(net, node, port, 0, index, is_input)
        return None

    node = struct.get("Node")
    if not isinstance(node, int) or isinstance(node, bool):
        return None

    bay = struct.get("Bay", struct.get("Slot"))
    if isinstance(bay, int) and not isinstance(bay, bool):
        # Bays are 1-based in TGPIOAddress, slots are 0-based in Set/GetGpOutput.
        slot = bay - 1 if "Bay" in struct else bay
        return GpioAddress(net, node, 128, max(slot, 0), index, is_input)

    port = struct.get("Port")
    if isinstance(port, int) and not isinstance(port, bool):
        return GpioAddress(net, node, port, 0, index, is_input)

    return None