"""Client for Hyperion servers."""
from __future__ import annotations

import asyncio
import collections
import collections.abc
import copy
import functools
import inspect
import json
import logging
import random
import string
import threading
from types import TracebackType

# pylint: disable=unused-import
from typing import (
    Any,
    Awaitable,
    Callable,
    Coroutine,
    Dict,
    Iterable,
    Mapping,
    Union,
    cast,
)

from hyperion import const

_LOGGER = logging.getLogger(__name__)

HyperionCallback = Union[
    Callable[[Dict[str, Any]], Awaitable[None]],
    Callable[[Dict[str, Any]], None],
]


class HyperionError(Exception):
    """Baseclass for all Hyperion exceptions."""


class HyperionClientTanNotAvailable(HyperionError):
    """An exception indicating the requested tan is not available."""


class HyperionClientState:
    """Class representing the Hyperion client state."""

    def __init__(self, state: dict[str, Any] | None = None) -> None:
        """Initialize state object."""
        self._state: dict[str, Any] = state or {}
        self._dirty: bool = False

    @property
    def dirty(self) -> bool:
        """Return whether or state has been modified."""
        return self._dirty

    @dirty.setter
    def dirty(self, val: bool) -> None:
        self._dirty = val

    def get(self, key: str) -> Any:
        """Retrieve a state element."""
        return self._state.get(key)

    def set(self, key: str, new_value: Any) -> None:
        """Set a new state value."""
        old_value = self.get(key)
        if old_value != new_value:
            self._state[key] = new_value
            self._dirty = True

    def update(self, new_values: dict[str, Any]) -> None:
        """Update the state with a dict of values."""
        for key in new_values:
            self.set(key, new_values[key])

    def get_all(self) -> dict[str, Any]:
        """Get a copy of all the state values."""
        return copy.copy(self._state)


class HyperionClient:
    """Hyperion Client."""

    # pylint: disable=too-many-arguments
    def __init__(
        self,
        host: str,
        port: int = const.DEFAULT_PORT_JSON,
        default_callback: HyperionCallback | Iterable[HyperionCallback] | None = None,
        callbacks: Mapping[str, HyperionCallback | Iterable[HyperionCallback]]
        | None = None,
        token: str | None = None,
        instance: int = const.DEFAULT_INSTANCE,
        origin: str = const.DEFAULT_ORIGIN,
        timeout_secs: float = const.DEFAULT_TIMEOUT_SECS,
        retry_secs: int = const.DEFAULT_CONNECTION_RETRY_DELAY_SECS,
        raw_connection: bool = False,
    ) -> None:
        """Initialize client."""
        _LOGGER.debug("HyperionClient initiated with: (%s:%i)", host, port)

        self._callbacks: dict[str, list[HyperionCallback]] = {}
        self.set_callbacks(callbacks or {})

        self._default_callback: list[HyperionCallback] = []
        self.set_default_callback(default_callback or [])

        self._host = host
        self._port = port
        self._token = token
        self._target_instance = instance
        self._origin = origin
        self._timeout_secs = timeout_secs
        self._retry_secs = retry_secs
        self._raw_connection = raw_connection

        self._serverinfo: dict[str, Any] | None = None

        self._receive_task: asyncio.Task[None] | None = None
        self._maintenance_task: asyncio.Task[None] | None = None
        self._maintenance_event: asyncio.Event = asyncio.Event()

        self._reader: asyncio.StreamReader | None = None
        self._writer: asyncio.StreamWriter | None = None

        # Start tan @ 1, as the zeroth tan is used by default.
        self._tan_cv = asyncio.Condition()
        self._tan_counter = 1
        self._tan_responses: dict[
            int, dict[str, Any] | None
        ] = collections.OrderedDict()

        self._client_state: HyperionClientState = HyperionClientState(
            state={
                const.KEY_CONNECTED: False,
                const.KEY_LOGGED_IN: False,
                const.KEY_INSTANCE: None,
                const.KEY_LOADED_STATE: False,
            }
        )

    async def __aenter__(self) -> "HyperionClient" | None:
        """Enter context manager and connect the client."""
        result = await self.async_client_connect()
        return self if result else None

    async def __aexit__(
        self,
        exc_type: type[BaseException] | None,
        exc: BaseException | None,
        traceback: TracebackType | None,
    ) -> None:
        """Leave context manager and disconnect the client."""
        await self.async_client_disconnect()

    async def _client_state_reset(self) -> None:
        self._client_state.update(
            {
                const.KEY_CONNECTED: False,
                const.KEY_LOGGED_IN: False,
                const.KEY_INSTANCE: None,
                const.KEY_LOADED_STATE: False,
            }
        )

    # ===================
    # || Callbacks     ||
    # ===================

    @classmethod
    def _set_or_add_callbacks(
        cls,
        callbacks: HyperionCallback | Iterable[HyperionCallback] | None,
        add: bool,
        target: list[HyperionCallback],
    ) -> None:
        """Set or add a single or list of callbacks."""
        if callbacks is not None and not isinstance(
            callbacks, collections.abc.Iterable
        ):
            callbacks = [callbacks]
        if not add:
            target.clear()
        if callbacks is not None:
            target.extend(callbacks)

    @classmethod
    def _remove_callbacks(
        cls,
        callbacks: HyperionCallback | Iterable[HyperionCallback],
        target: list[HyperionCallback],
    ) -> None:
        """Set or add a single or list of callbacks."""
        if not callbacks:
            return
        if not isinstance(callbacks, collections.abc.Iterable):
            callbacks = [callbacks]

        for callback in callbacks:
            if callback in target:
                target.remove(callback)

    def set_callbacks(
        self,
        callbacks: Mapping[str, HyperionCallback | Iterable[HyperionCallback]] | None,
    ) -> None:
        """Set update callbacks."""
        if not callbacks:
            self._callbacks = {}
            return
        for name, value in callbacks.items():
            HyperionClient._set_or_add_callbacks(
                value, False, self._callbacks.setdefault(name, [])
            )

    def add_callbacks(
        self,
        callbacks: Mapping[str, HyperionCallback | Iterable[HyperionCallback]],
    ) -> None:
        """Add update callbacks."""
        if not callbacks:
            return
        for name, value in callbacks.items():
            HyperionClient._set_or_add_callbacks(
                value, True, self._callbacks.setdefault(name, [])
            )

    def remove_callbacks(
        self,
        callbacks: Mapping[str, HyperionCallback | Iterable[HyperionCallback]],
    ) -> None:
        """Add update callbacks."""
        if not callbacks:
            return
        for name, value in callbacks.items():
            if name not in self._callbacks:
                continue
            HyperionClient._remove_callbacks(value, self._callbacks[name])

    def set_default_callback(
        self,
        default_callback: HyperionCallback | Iterable[HyperionCallback] | None,
    ) -> None:
        """Set the default callbacks."""
        HyperionClient._set_or_add_callbacks(
            default_callback, False, self._default_callback
        )

    def add_default_callback(
        self,
        default_callback: HyperionCallback | Iterable[HyperionCallback],
    ) -> None:
        """Set the default callbacks."""
        HyperionClient._set_or_add_callbacks(
            default_callback, True, self._default_callback
        )

    def remove_default_callback(
        self,
        default_callback: HyperionCallback | Iterable[HyperionCallback],
    ) -> None:
        """Set the default callbacks."""
        HyperionClient._remove_callbacks(default_callback, self._default_callback)

    async def _call_callbacks(self, command: str, arg: dict[str, Any]) -> None:
        """Call the relevant callbacks for the given command."""
        callbacks = self._callbacks.get(command, self._default_callback)
        for callback in callbacks:
            if inspect.iscoroutinefunction(callback):
                await cast(Awaitable[None], callback(arg))
            else:
                callback(arg)

    # ===================
    # || Networking    ||
    # ===================

    @property
    def is_connected(self) -> bool:
        """Return server availability."""
        return bool(self._client_state.get(const.KEY_CONNECTED))

    @property
    def is_logged_in(self) -> bool:
        """Return whether the client is logged in."""
        return bool(self._client_state.get(const.KEY_LOGGED_IN))

    @property
    def instance(self) -> int | None:
        """Return server instance."""
        instance: int | None = self._client_state.get(const.KEY_INSTANCE)
        return instance

    @property
    def target_instance(self) -> int:
        """Return server target instance."""
        return self._target_instance

    @property
    def has_loaded_state(self) -> bool:
        """Return whether the client has loaded state."""
        return bool(self._client_state.get(const.KEY_LOADED_STATE))

    @property
    def client_state(self) -> dict[str, Any]:
        """Return client state."""
        return self._client_state.get_all()

    @property
    def host(self) -> str:
        """Return host ip."""
        return self._host

    @property
    def remote_url(self) -> str:
        """Return remote control URL."""
        return f"http://{self._host}:{const.DEFAULT_PORT_UI}/#remote"

    async def async_client_connect(self) -> bool:
        """Connect to the Hyperion server."""

        if self._writer:
            return True

        future_streams = asyncio.open_connection(self._host, self._port)
        try:
            self._reader, self._writer = await asyncio.wait_for(
                future_streams, timeout=self._timeout_secs
            )
        except (asyncio.TimeoutError, ConnectionError, OSError) as exc:
            _LOGGER.debug("Could not connect to (%s): %s", self._host_port, repr(exc))
            return False

        _LOGGER.info("Connected to Hyperion server: %s", self._host_port)

        # Start the receive task to process inbound data from the server.
        await self._await_or_stop_task(self._receive_task, stop_task=True)
        self._receive_task = asyncio.create_task(self._receive_task_loop())

        await self._client_state_reset()
        self._client_state.update(
            {const.KEY_CONNECTED: True, const.KEY_INSTANCE: const.DEFAULT_INSTANCE}
        )
        await self._call_client_state_callback_if_necessary()

        if not self._raw_connection:
            if (
                not self._client_state.get(const.KEY_LOGGED_IN)
                and not await self.async_client_login()
            ):
                await self.async_client_disconnect()
                return False

            if (
                not self._client_state.get(const.KEY_INSTANCE)
                and not await self.async_client_switch_instance()
            ):
                await self.async_client_disconnect()
                return False

            if not self._client_state.get(
                const.KEY_LOADED_STATE
            ) and not ServerInfoResponseOK(await self.async_get_serverinfo()):
                await self.async_client_disconnect()
                return False

        # Start the maintenance task if it does not already exist.
        if not self._maintenance_task:
            self._maintenance_task = asyncio.create_task(self._maintenance_task_loop())

        return True

    async def _call_client_state_callback_if_necessary(self) -> None:
        """Call the client state callbacks if state has changed."""
        if not self._client_state.dirty:
            return
        data = HyperionClient._set_data(
            self._client_state.get_all(),
            hard={
                const.KEY_COMMAND: f"{const.KEY_CLIENT}-{const.KEY_UPDATE}",
            },
        )
        await self._call_callbacks(str(data[const.KEY_COMMAND]), data)
        self._client_state.dirty = False

    async def async_client_login(self) -> bool:
        """Log the client in if a token is provided."""
        if self._token is None:
            self._client_state.set(const.KEY_LOGGED_IN, True)
            await self._call_client_state_callback_if_necessary()
            return True
        return bool(LoginResponseOK(await self.async_login(token=self._token)))

    async def async_client_switch_instance(self) -> bool:
        """Select an instance the user has specified."""
        if (
            self._client_state.get(const.KEY_INSTANCE) is None
            and self._target_instance == const.DEFAULT_INSTANCE
        ) or self._client_state.get(const.KEY_INSTANCE) == self._target_instance:
            self._client_state.set(const.KEY_INSTANCE, self._target_instance)
            await self._call_client_state_callback_if_necessary()
            return True

        resp_json = await self.async_switch_instance(instance=self._target_instance)
        return (
            resp_json is not None
            and bool(SwitchInstanceResponseOK(resp_json))
            and resp_json[const.KEY_INFO][const.KEY_INSTANCE] == self._target_instance
        )

    async def async_client_disconnect(self) -> bool:
        """Close streams to the Hyperion server (no reconnect)."""
        # Cancel the maintenance task to ensure the connection is not re-established.
        await self._await_or_stop_task(self._maintenance_task, stop_task=True)
        self._maintenance_task = None

        return await self._async_client_disconnect_internal()

    async def _async_client_disconnect_internal(self) -> bool:
        """Close streams to the Hyperion server (may reconnect)."""
        if not self._writer:
            return True

        error = False
        writer = self._writer
        self._writer = self._reader = None
        try:
            writer.close()
            await writer.wait_closed()
        except ConnectionError as exc:
            _LOGGER.warning(
                "Could not close connection cleanly for Hyperion (%s): %s",
                self._host_port,
                repr(exc),
            )
            error = True

        await self._client_state_reset()
        await self._call_client_state_callback_if_necessary()

        # Tell the maintenance loop it may need to reconnect.
        self._maintenance_event.set()

        receive_task = self._receive_task
        self._receive_task = None
        await self._await_or_stop_task(receive_task, stop_task=True)
        return not error

    async def _async_send_json(self, request: dict[str, Any]) -> bool:
        """Send JSON to the server."""
        if not self._writer:
            return False

        output = json.dumps(request, sort_keys=True).encode("UTF-8") + b"\n"
        _LOGGER.debug("Send to server (%s): %s", self._host_port, output)
        try:
            self._writer.write(output)
            await self._writer.drain()
        except ConnectionError as exc:
            _LOGGER.warning(
                "Could not write data for Hyperion (%s): %s",
                self._host_port,
                repr(exc),
            )
            return False
        return True

    # pylint: disable=too-many-return-statements
    async def _async_safely_read_command(
        self, use_timeout: bool = True
    ) -> dict[str, Any] | None:
        """Safely read a command from the stream."""
        if not self._reader:
            return None

        timeout_secs = self._timeout_secs if use_timeout else None

        try:
            future_resp = self._reader.readline()
            resp = await asyncio.wait_for(future_resp, timeout=timeout_secs)
        except ConnectionError:
            _LOGGER.warning("Connection to Hyperion lost (%s) ...", self._host_port)
            await self._async_client_disconnect_internal()
            return None
        except asyncio.TimeoutError:
            _LOGGER.warning(
                "Read from Hyperion timed out (%s), disconnecting ...", self._host_port
            )
            await self._async_client_disconnect_internal()
            return None

        if not resp:
            # If there's no writer, we have disconnected, so skip the error message
            # and additional disconnect call.
            if self._writer:
                _LOGGER.warning("Connection to Hyperion lost (%s) ...", self._host_port)
                await self._async_client_disconnect_internal()
            return None

        _LOGGER.debug("Read from server (%s): %s", self._host_port, resp)

        try:
            resp_json = json.loads(resp)
        except json.decoder.JSONDecodeError:
            _LOGGER.warning(
                "Could not decode JSON from Hyperion (%s), skipping...",
                self._host_port,
            )
            return None

        try:
            resp_json = dict(resp_json)
        except ValueError:
            _LOGGER.warning(
                "Wrong data-type received from Hyperion (%s), skipping...",
                self._host_port,
            )
            return None

        if const.KEY_COMMAND not in resp_json:
            _LOGGER.warning(
                "JSON from Hyperion (%s) did not include expected '%s' "
                "parameter, skipping...",
                self._host_port,
                const.KEY_COMMAND,
            )
            return None
        return cast(Dict[str, Any], resp_json)

    async def _maintenance_task_loop(self) -> None:
        try:
            while True:
                await self._maintenance_event.wait()
                if not self._client_state.get(const.KEY_CONNECTED):
                    if not await self.async_client_connect():
                        _LOGGER.info(
                            "Could not estalish valid connection to Hyperion (%s), "
                            "retrying in %i seconds...",
                            self._host_port,
                            self._retry_secs,
                        )
                        await self._async_client_disconnect_internal()
                        await asyncio.sleep(const.DEFAULT_CONNECTION_RETRY_DELAY_SECS)
                        continue

                if self._client_state.get(const.KEY_CONNECTED):
                    self._maintenance_event.clear()

        except asyncio.CancelledError:  # pylint: disable=try-except-raise
            # Don't log CancelledError, but do propagate it upwards.
            raise
        except Exception:
            # Make sure exceptions are logged (for testing purposes, as this is
            # in a background task).
            _LOGGER.exception(
                "Exception in Hyperion (%s) background maintenance task",
                self._host_port,
            )
            raise

    async def _receive_task_loop(self) -> None:
        """Run receive task continually."""
        while await self._async_receive_once():
            pass

    async def _await_or_stop_task(
        self, task: "asyncio.Task[Any] | None", stop_task: bool = False
    ) -> bool:
        """Await task, optionally stopping it first.

        Returns True if the task is done.
        """
        if task is None:
            return False
        if stop_task:
            task.cancel()

        # Yield to the event loop, so the above cancellation can be processed.
        await asyncio.sleep(0)

        if task.done():
            try:
                await task
            except asyncio.CancelledError:
                pass
            return True
        return False

    async def _handle_changed_instance(self, instance: int) -> None:
        """Handle when instance changes (whether this client triggered that or not)."""
        if instance == self._client_state.get(const.KEY_INSTANCE):
            return
        self._target_instance = instance
        self._client_state.update(
            {const.KEY_INSTANCE: instance, const.KEY_LOADED_STATE: False}
        )
        self._update_serverinfo(None)
        await self._call_client_state_callback_if_necessary()

    # pylint: disable=too-many-branches
    async def _async_receive_once(self) -> bool:
        """Manage the bidirectional connection to the server."""
        resp_json = await self._async_safely_read_command(use_timeout=False)
        if not resp_json:
            return False
        command = resp_json[const.KEY_COMMAND]

        if not resp_json.get(const.KEY_SUCCESS, True):
            # If it's a failed authorization call, print a specific warning
            # message.
            if command == const.KEY_AUTHORIZE_LOGIN:
                _LOGGER.warning(
                    "Authorization failed for Hyperion (%s). "
                    "Check token is valid: %s",
                    self._host_port,
                    resp_json,
                )
            else:
                _LOGGER.warning(
                    "Failed Hyperion (%s) command: %s", self._host_port, resp_json
                )
        elif (
            command == f"{const.KEY_COMPONENTS}-{const.KEY_UPDATE}"
            and const.KEY_DATA in resp_json
        ):
            self._update_component(resp_json[const.KEY_DATA])
        elif (
            command == f"{const.KEY_ADJUSTMENT}-{const.KEY_UPDATE}"
            and const.KEY_DATA in resp_json
        ):
            self._update_adjustment(resp_json[const.KEY_DATA])
        elif (
            command == f"{const.KEY_EFFECTS}-{const.KEY_UPDATE}"
            and const.KEY_DATA in resp_json
        ):
            self._update_effects(resp_json[const.KEY_DATA])
        elif command == f"{const.KEY_PRIORITIES}-{const.KEY_UPDATE}":
            if const.KEY_PRIORITIES in resp_json.get(const.KEY_DATA, {}):
                self._update_priorities(resp_json[const.KEY_DATA][const.KEY_PRIORITIES])
            if const.KEY_PRIORITIES_AUTOSELECT in resp_json.get(const.KEY_DATA, {}):
                self._update_priorities_autoselect(
                    resp_json[const.KEY_DATA][const.KEY_PRIORITIES_AUTOSELECT]
                )
        elif (
            command == f"{const.KEY_INSTANCE}-{const.KEY_UPDATE}"
            and const.KEY_DATA in resp_json
        ):
            # If instances are changed, and the current instance is not listed
            # in the new instance update, then the client should disconnect.
            instances = resp_json[const.KEY_DATA]

            for instance in instances:
                if (
                    instance.get(const.KEY_INSTANCE)
                    == self._client_state.get(const.KEY_INSTANCE)
                    and instance.get(const.KEY_RUNNING) is True
                ):
                    self._update_instances(instances)
                    break
            else:
                await self.async_client_disconnect()
        elif SwitchInstanceResponseOK(resp_json):
            # Upon connection being successfully switched to another instance,
            # the client will receive:
            #
            # {
            #     "command":"instance-switchTo",
            #     "info": {
            #         "instance": 1
            #     },
            #     "success":true,
            #     "tan":0
            # }
            #
            # This is our cue to fully refresh our serverinfo so our internal
            # state is representing the correct instance.
            await self._handle_changed_instance(
                resp_json[const.KEY_INFO][const.KEY_INSTANCE]
            )
        elif (
            command == f"{const.KEY_LED_MAPPING}-{const.KEY_UPDATE}"
            and const.KEY_LED_MAPPING_TYPE in resp_json.get(const.KEY_DATA, {})
        ):
            self._update_led_mapping_type(
                resp_json[const.KEY_DATA][const.KEY_LED_MAPPING_TYPE]
            )
        elif (
            command == f"{const.KEY_SESSIONS}-{const.KEY_UPDATE}"
            and const.KEY_DATA in resp_json
        ):
            self._update_sessions(resp_json[const.KEY_DATA])
        elif (
            command == f"{const.KEY_VIDEOMODE}-{const.KEY_UPDATE}"
            and const.KEY_VIDEOMODE in resp_json.get(const.KEY_DATA, {})
        ):
            self._update_videomode(resp_json[const.KEY_DATA][const.KEY_VIDEOMODE])
        elif (
            command == f"{const.KEY_LEDS}-{const.KEY_UPDATE}"
            and const.KEY_LEDS in resp_json.get(const.KEY_DATA, {})
        ):
            self._update_leds(resp_json[const.KEY_DATA][const.KEY_LEDS])
        elif command == f"{const.KEY_AUTHORIZE_LOGOUT}":
            await self.async_client_disconnect()
        elif ServerInfoResponseOK(resp_json):
            self._update_serverinfo(resp_json[const.KEY_INFO])
            self._client_state.set(const.KEY_LOADED_STATE, True)
        elif LoginResponseOK(resp_json):
            self._client_state.set(const.KEY_LOGGED_IN, True)

        await self._call_callbacks(command, resp_json)
        await self._call_client_state_callback_if_necessary()
        await self._handle_response_for_caller(resp_json)
        return True

    async def _handle_response_for_caller(self, resp_json: dict[str, Any]) -> None:
        """Handle a server response for a caller."""

        tan = resp_json.get(const.KEY_TAN)
        if tan is not None:
            async with self._tan_cv:
                if tan in self._tan_responses:
                    self._tan_responses[tan] = resp_json
                    self._tan_cv.notify_all()
                # Note: The behavior is not perfect here, in cases of an older
                # Hyperion server and a malformed request. In that case, the
                # server will return tan==0 (regardless of the input tan), and
                # so the match here will fail. This will cause the callee to
                # time out awaiting a response (or wait forever if not timeout
                # is specified). This was addressed in:
                #
                # https://github.com/hyperion-project/hyperion.ng/issues/1001 .

    # ==================
    # || Helper calls ||
    # ==================

    @property
    def _host_port(self) -> str:
        """Return a host:port string for this server."""
        return "%s:%i" % (self._host, self._port)

    @classmethod
    def _set_data(
        cls,
        data: dict[Any, Any],
        hard: dict[Any, Any] | None = None,
        soft: dict[Any, Any] | None = None,
    ) -> dict[Any, Any]:
        """Override the data in the dictionary selectively."""
        output = soft or {}
        output.update(data)
        output.update(hard or {})
        return output

    async def _reserve_tan_slot(self, tan: int | None = None) -> int:
        """Increment and return the next tan to use."""
        async with self._tan_cv:
            if tan is None:
                # If tan is not specified, find the next available higher
                # value.
                while self._tan_counter in self._tan_responses:
                    self._tan_counter += 1
                tan = self._tan_counter
                self._tan_counter += 1
            if tan in self._tan_responses:
                raise HyperionClientTanNotAvailable(
                    "Requested tan '%i' is not available in Hyperion client (%s)"
                    % (tan, self._host_port)
                )
            self._tan_responses[tan] = None
            return tan

    async def _remove_tan_slot(self, tan: int) -> None:
        """Remove a tan slot that is no longer required."""
        async with self._tan_cv:
            if tan in self._tan_responses:
                del self._tan_responses[tan]

    async def _wait_for_tan_response(
        self, tan: int, timeout_secs: float
    ) -> dict[str, Any] | None:
        """Wait for a response to arrive."""
        await self._tan_cv.acquire()
        try:
            await asyncio.wait_for(
                self._tan_cv.wait_for(lambda: self._tan_responses.get(tan) is not None),
                timeout=timeout_secs,
            )
            return self._tan_responses[tan]
        except asyncio.TimeoutError:
            pass
        finally:
            # This should not be necessary, this function should be able to use
            # 'async with self._tan_cv', however this does not currently play nice
            # with Python 3.7/3.8 when the wait_for is canceled or times out,
            # (the condition lock is not reaquired before re-raising the exception).
            # See: https://bugs.python.org/issue39032
            if self._tan_cv.locked():
                self._tan_cv.release()
        return None

    class AwaitResponseWrapper:
        """Wrapper an async *send* coroutine and await the response."""

        def __init__(
            self, coro: Callable[..., Awaitable[bool]], timeout_secs: float = 0
        ):
            """Initialize the wrapper.

            Wait up to timeout_secs for a response. A timeout of 0
            will use the client default timeout specified in the constructor.
            A timeout of None will wait forever.
            """
            self._coro = coro
            self._timeout_secs = timeout_secs

        def _extract_timeout_secs(
            self, hyperion_client: HyperionClient, data: dict[str, Any]
        ) -> float:
            """Return the timeout value for a call.

            Modifies input! Removes the timeout key from the inbound data if
            present so that it is not passed on to the server. If not present,
            returns the wrapper default specified in the wrapper constructor.
            """
            # Timeout values:
            #    * None: Wait forever (default asyncio.wait_for behavior).
            #    * 0: Use the object default (self._timeout_secs)
            #    * >0: Wait that long.
            if const.KEY_TIMEOUT_SECS in data:
                timeout_secs = cast(float, data[const.KEY_TIMEOUT_SECS])
                del data[const.KEY_TIMEOUT_SECS]
                return timeout_secs
            if self._timeout_secs == 0:
                return hyperion_client._timeout_secs  # pylint: disable=protected-access
            return self._timeout_secs

        async def __call__(
            self, hyperion_client: "HyperionClient", *args: Any, **kwargs: Any
        ) -> dict[str, Any] | None:
            """Call the wrapper."""
            # The receive task should never be executing a call that uses the
            # AwaitResponseWrapper (as the response is itself handled by the receive
            # task, i.e. partial deadlock). This assertion defends against programmer
            # error in development of the client itself.
            assert asyncio.current_task() != hyperion_client._receive_task

            tan = await hyperion_client._reserve_tan_slot(kwargs.get(const.KEY_TAN))
            data = hyperion_client._set_data(kwargs, hard={const.KEY_TAN: tan})
            timeout_secs = self._extract_timeout_secs(hyperion_client, data)

            response = None
            if await self._coro(hyperion_client, *args, **data):
                response = await hyperion_client._wait_for_tan_response(
                    tan, timeout_secs
                )
            await hyperion_client._remove_tan_slot(tan)
            return response

        def __get__(
            self, instance: HyperionClient, instancetype: type[HyperionClient]
        ) -> functools.partial[Coroutine[Any, Any, dict[str, Any] | None]]:
            """Return a partial call that uses the correct 'self'."""
            # Need to ensure __call__ receives the 'correct' outer
            # 'self', which is 'instance' in this function.
            return functools.partial(self.__call__, instance)

    # =============================
    # || Authorization API calls ||
    # =============================

    # ================================================================================
    # ** Authorization Check **
    # https://docs.hyperion-project.org/en/json/Authorization.html#authorization-check
    # ================================================================================

    async def async_send_is_auth_required(self, *_: Any, **kwargs: Any) -> bool:
        """Determine if authorization is required."""
        data = HyperionClient._set_data(
            kwargs,
            hard={
                const.KEY_COMMAND: const.KEY_AUTHORIZE,
                const.KEY_SUBCOMMAND: const.KEY_TOKEN_REQUIRED,
            },
        )
        return await self._async_send_json(data)

    async_is_auth_required = AwaitResponseWrapper(async_send_is_auth_required)

    # =============================================================================
    # ** Login **
    # https://docs.hyperion-project.org/en/json/Authorization.html#login-with-token
    # =============================================================================

    async def async_send_login(self, *_: Any, **kwargs: Any) -> bool:
        """Login with token."""
        data = HyperionClient._set_data(
            kwargs,
            hard={
                const.KEY_COMMAND: const.KEY_AUTHORIZE,
                const.KEY_SUBCOMMAND: const.KEY_LOGIN,
            },
        )
        return await self._async_send_json(data)

    async_login = AwaitResponseWrapper(async_send_login)

    # =============================================================================
    # ** Logout **
    # https://docs.hyperion-project.org/en/json/Authorization.html#logout
    # =============================================================================

    async def async_send_logout(self, *_: Any, **kwargs: Any) -> bool:
        """Logout."""
        data = HyperionClient._set_data(
            kwargs,
            hard={
                const.KEY_COMMAND: const.KEY_AUTHORIZE,
                const.KEY_SUBCOMMAND: const.KEY_LOGOUT,
            },
        )
        return await self._async_send_json(data)

    async_logout = AwaitResponseWrapper(async_send_logout)

    # ============================================================================
    # ** Request Token **
    # https://docs.hyperion-project.org/en/json/Authorization.html#request-a-token
    # ============================================================================

    async def async_send_request_token(self, *_: Any, **kwargs: Any) -> bool:
        """Request an authorization token.

        The user will accept/deny the token request on the Web UI.
        """
        data = HyperionClient._set_data(
            kwargs,
            hard={
                const.KEY_COMMAND: const.KEY_AUTHORIZE,
                const.KEY_SUBCOMMAND: const.KEY_REQUEST_TOKEN,
            },
            soft={const.KEY_ID: generate_random_auth_id()},
        )
        return await self._async_send_json(data)

    # This call uses a custom (longer) timeout by default, as the user needs to interact
    # with the Hyperion UI before it will return.
    async_request_token = AwaitResponseWrapper(
        async_send_request_token, timeout_secs=const.DEFAULT_REQUEST_TOKEN_TIMEOUT_SECS
    )

    async def async_send_request_token_abort(self, *_: Any, **kwargs: Any) -> bool:
        """Abort a request for an authorization token."""
        data = HyperionClient._set_data(
            kwargs,
            hard={
                const.KEY_COMMAND: const.KEY_AUTHORIZE,
                const.KEY_SUBCOMMAND: const.KEY_REQUEST_TOKEN,
                const.KEY_ACCEPT: False,
            },
        )
        return await self._async_send_json(data)

    async_request_token_abort = AwaitResponseWrapper(async_send_request_token_abort)

    # ====================
    # || Data API calls ||
    # ====================

    # ================
    # ** Adjustment **
    # ================

    @property
    def adjustment(self) -> list[dict[str, Any]] | None:
        """Return adjustment."""
        return self._get_serverinfo_value(const.KEY_ADJUSTMENT)

    def _update_adjustment(self, adjustment: list[dict[str, Any]] | None) -> None:
        """Update adjustment."""
        if (
            self._serverinfo is None
            or not adjustment
            or not isinstance(adjustment, list)
        ):
            return
        self._serverinfo[const.KEY_ADJUSTMENT] = adjustment

    async def async_send_set_adjustment(self, *_: Any, **kwargs: Any) -> bool:
        """Request that a color be set."""
        data = HyperionClient._set_data(
            kwargs, hard={const.KEY_COMMAND: const.KEY_ADJUSTMENT}
        )
        return await self._async_send_json(data)

    async_set_adjustment = AwaitResponseWrapper(async_send_set_adjustment)

    # =====================================================================
    # ** Clear **
    # Set: https://docs.hyperion-project.org/en/json/Control.html#clear
    # =====================================================================

    async def async_send_clear(self, *_: Any, **kwargs: Any) -> bool:
        """Request that a priority be cleared."""
        data = HyperionClient._set_data(
            kwargs, hard={const.KEY_COMMAND: const.KEY_CLEAR}
        )
        return await self._async_send_json(data)

    async_clear = AwaitResponseWrapper(async_send_clear)

    # =====================================================================
    # ** Color **
    # Set: https://docs.hyperion-project.org/en/json/Control.html#set-color
    # =====================================================================

    async def async_send_set_color(self, *_: Any, **kwargs: Any) -> bool:
        """Request that a color be set."""
        data = HyperionClient._set_data(
            kwargs,
            hard={const.KEY_COMMAND: const.KEY_COLOR},
            soft={const.KEY_ORIGIN: self._origin},
        )
        return await self._async_send_json(data)

    async_set_color = AwaitResponseWrapper(async_send_set_color)

    # ==================================================================================
    # ** Component **
    # Full State: https://docs.hyperion-project.org/en/json/ServerInfo.html#components
    # Update: https://docs.hyperion-project.org/en/json/Subscribe.html#component-updates
    # Set: https://docs.hyperion-project.org/en/json/Control.html#control-components
    # ==================================================================================

    @property
    def components(self) -> list[dict[str, Any]] | None:
        """Return components."""
        return self._get_serverinfo_value(const.KEY_COMPONENTS)

    def _update_component(self, new_component: dict[str, Any]) -> None:
        """Update full Hyperion state."""
        if (
            self._serverinfo is None
            or not isinstance(new_component, dict)
            or const.KEY_NAME not in new_component
        ):
            return
        new_components = self._serverinfo.get(const.KEY_COMPONENTS, [])
        for component in new_components:
            if (
                const.KEY_NAME not in component
                or component[const.KEY_NAME] != new_component[const.KEY_NAME]
            ):
                continue
            # Update component in place.
            component.clear()
            component.update(new_component)
            break
        else:
            new_components.append(new_component)

    async def async_send_set_component(self, *_: Any, **kwargs: Any) -> bool:
        """Request that a color be set."""
        data = HyperionClient._set_data(
            kwargs, hard={const.KEY_COMMAND: const.KEY_COMPONENTSTATE}
        )
        return await self._async_send_json(data)

    async_set_component = AwaitResponseWrapper(async_send_set_component)

    def is_on(
        self,
        components: list[str] | None = None,
    ) -> bool:
        """Determine if components are on."""
        if components is None:
            components = [const.KEY_COMPONENTID_ALL, const.KEY_COMPONENTID_LEDDEVICE]
        elif not components:
            return False

        components_to_state = {}
        for component in self.components or []:
            name = component.get(const.KEY_NAME)
            state = component.get(const.KEY_ENABLED)
            if name is None or state is None:
                continue
            components_to_state[name] = state

        for component_target in components:
            if (
                component_target not in components_to_state
                or not components_to_state[component_target]
            ):
                return False
        return True

    # ==================================================================================
    # ** Effects **
    # Full State: https://docs.hyperion-project.org/en/json/ServerInfo.html#effect-list
    # Update: https://docs.hyperion-project.org/en/json/Subscribe.html#effects-updates
    # Set: https://docs.hyperion-project.org/en/json/Control.html#set-effect
    # ==================================================================================

    @property
    def effects(self) -> list[dict[str, Any]] | None:
        """Return effects."""
        return self._get_serverinfo_value(const.KEY_EFFECTS)

    def _update_effects(self, effects: list[dict[str, Any]] | None) -> None:
        """Update effects."""
        if self._serverinfo is None or not isinstance(effects, list):
            return
        self._serverinfo[const.KEY_EFFECTS] = effects

    async def async_send_set_effect(self, *_: Any, **kwargs: Any) -> bool:
        """Request that an effect be set."""
        data = HyperionClient._set_data(
            kwargs,
            hard={const.KEY_COMMAND: const.KEY_EFFECT},
            soft={const.KEY_ORIGIN: self._origin},
        )
        return await self._async_send_json(data)

    async_set_effect = AwaitResponseWrapper(async_send_set_effect)

    # =================================================================================
    # ** Image **
    # Set: https://docs.hyperion-project.org/en/json/Control.html#set-image
    # =================================================================================

    async def async_send_set_image(self, *_: Any, **kwargs: Any) -> bool:
        """Request that an image be set."""
        data = HyperionClient._set_data(
            kwargs,
            hard={const.KEY_COMMAND: const.KEY_IMAGE},
            soft={const.KEY_ORIGIN: self._origin},
        )
        return await self._async_send_json(data)

    async_set_image = AwaitResponseWrapper(async_send_set_image)

    # ================================================================================
    # ** Image Streaming **
    # Update: https://docs.hyperion-project.org/en/json/Control.html#live-image-stream
    # Set: https://docs.hyperion-project.org/en/json/Control.html#live-image-stream
    # ================================================================================

    async def async_send_image_stream_start(self, *_: Any, **kwargs: Any) -> bool:
        """Request a live image stream to start."""
        data = HyperionClient._set_data(
            kwargs,
            hard={
                const.KEY_COMMAND: const.KEY_LEDCOLORS,
                const.KEY_SUBCOMMAND: const.KEY_IMAGE_STREAM_START,
            },
        )
        return await self._async_send_json(data)

    async_image_stream_start = AwaitResponseWrapper(async_send_image_stream_start)

    async def async_send_image_stream_stop(self, *_: Any, **kwargs: Any) -> bool:
        """Request a live image stream to stop."""
        data = HyperionClient._set_data(
            kwargs,
            hard={
                const.KEY_COMMAND: const.KEY_LEDCOLORS,
                const.KEY_SUBCOMMAND: const.KEY_IMAGE_STREAM_STOP,
            },
        )
        return await self._async_send_json(data)

    async_image_stream_stop = AwaitResponseWrapper(async_send_image_stream_stop)

    # =================================================================================
    # ** Instances **
    # Full State: https://docs.hyperion-project.org/en/json/ServerInfo.html#instance
    # Update: https://docs.hyperion-project.org/en/json/Subscribe.html#instance-updates
    # Set: https://docs.hyperion-project.org/en/json/Control.html#control-instances
    # =================================================================================

    @property
    def instances(self) -> list[dict[str, Any]] | None:
        """Return instances."""
        return self._get_serverinfo_value(const.KEY_INSTANCE)

    def _update_instances(self, instances: list[dict[str, Any]] | None) -> None:
        """Update instances."""
        if self._serverinfo is None or not isinstance(instances, list):
            return
        self._serverinfo[const.KEY_INSTANCE] = instances

    async def async_send_start_instance(self, *_: Any, **kwargs: Any) -> bool:
        """Start an instance."""
        data = HyperionClient._set_data(
            kwargs,
            hard={
                const.KEY_COMMAND: const.KEY_INSTANCE,
                const.KEY_SUBCOMMAND: const.KEY_START_INSTANCE,
            },
        )
        return await self._async_send_json(data)

    async_start_instance = AwaitResponseWrapper(async_send_start_instance)

    async def async_send_stop_instance(self, *_: Any, **kwargs: Any) -> bool:
        """Stop an instance."""
        data = HyperionClient._set_data(
            kwargs,
            hard={
                const.KEY_COMMAND: const.KEY_INSTANCE,
                const.KEY_SUBCOMMAND: const.KEY_STOP_INSTANCE,
            },
        )
        return await self._async_send_json(data)

    async_stop_instance = AwaitResponseWrapper(async_send_stop_instance)

    async def async_send_switch_instance(self, *_: Any, **kwargs: Any) -> bool:
        """Stop an instance."""
        data = HyperionClient._set_data(
            kwargs,
            hard={
                const.KEY_COMMAND: const.KEY_INSTANCE,
                const.KEY_SUBCOMMAND: const.KEY_SWITCH_TO,
            },
        )
        return await self._async_send_json(data)

    async_switch_instance = AwaitResponseWrapper(async_send_switch_instance)

    # =============================================================================
    # ** LEDs **
    # Full State: https://docs.hyperion-project.org/en/json/ServerInfo.html#leds
    # Update: https://docs.hyperion-project.org/en/json/Subscribe.html#leds-updates
    # =============================================================================

    @property
    def leds(self) -> list[dict[str, Any]] | None:
        """Return LEDs."""
        return self._get_serverinfo_value(const.KEY_LEDS)

    def _update_leds(self, leds: list[dict[str, Any]] | None) -> None:
        """Update LEDs."""
        if self._serverinfo is None or not isinstance(leds, list):
            return
        self._serverinfo[const.KEY_LEDS] = leds

    # pylint: disable=line-too-long
    # =================================================================================
    # ** LED Mapping **
    # Full State: https://docs.hyperion-project.org/en/json/ServerInfo.html#led-mapping
    # Update: https://docs.hyperion-project.org/en/json/Subscribe.html#led-mapping-updates
    # Set: https://docs.hyperion-project.org/en/json/Control.html#led-mapping
    # =================================================================================

    @property
    def led_mapping_type(self) -> str | None:
        """Return LED mapping type."""
        return self._get_serverinfo_value(const.KEY_LED_MAPPING_TYPE)

    def _update_led_mapping_type(self, led_mapping_type: str) -> None:
        """Update LED mapping  type."""
        if self._serverinfo is None or not isinstance(led_mapping_type, str):
            return
        self._serverinfo[const.KEY_LED_MAPPING_TYPE] = led_mapping_type

    async def async_send_set_led_mapping_type(self, *_: Any, **kwargs: Any) -> bool:
        """Request the LED mapping type be set."""
        data = HyperionClient._set_data(
            kwargs, hard={const.KEY_COMMAND: const.KEY_PROCESSING}
        )
        return await self._async_send_json(data)

    async_set_led_mapping_type = AwaitResponseWrapper(async_send_set_led_mapping_type)

    # =================================================================================
    # ** Live LED Streaming **
    # Update: https://docs.hyperion-project.org/en/json/Control.html#live-led-color-stream
    # Set: https://docs.hyperion-project.org/en/json/Control.html#live-led-color-stream
    # =================================================================================

    async def async_send_led_stream_start(self, *_: Any, **kwargs: Any) -> bool:
        """Request a live led stream to start."""
        data = HyperionClient._set_data(
            kwargs,
            hard={
                const.KEY_COMMAND: const.KEY_LEDCOLORS,
                const.KEY_SUBCOMMAND: const.KEY_LED_STREAM_START,
            },
        )
        return await self._async_send_json(data)

    async_led_stream_start = AwaitResponseWrapper(async_send_led_stream_start)

    async def async_send_led_stream_stop(self, *_: Any, **kwargs: Any) -> bool:
        """Request a live led stream to stop."""
        data = HyperionClient._set_data(
            kwargs,
            hard={
                const.KEY_COMMAND: const.KEY_LEDCOLORS,
                const.KEY_SUBCOMMAND: const.KEY_LED_STREAM_STOP,
            },
        )
        return await self._async_send_json(data)

    async_led_stream_stop = AwaitResponseWrapper(async_send_led_stream_stop)

    # =================================================================================
    # ** Priorites **
    # Full State: https://docs.hyperion-project.org/en/json/ServerInfo.html#priorities
    # Update: https://docs.hyperion-project.org/en/json/Subscribe.html#priority-updates
    # =================================================================================

    @property
    def priorities(self) -> list[dict[str, Any]] | None:
        """Return priorites."""
        return self._get_serverinfo_value(const.KEY_PRIORITIES)

    def _update_priorities(self, priorities: list[dict[str, Any]]) -> None:
        """Update priorites."""
        if self._serverinfo is None or not isinstance(priorities, list):
            return
        self._serverinfo[const.KEY_PRIORITIES] = priorities

    @property
    def visible_priority(self) -> dict[str, Any] | None:
        """Return the visible priority, if any."""
        # The visible priority is supposed to be the first returned by the
        # API, but due to a bug the ordering is incorrect search for it
        # instead, see:
        # https://github.com/hyperion-project/hyperion.ng/issues/964
        for priority in self.priorities or []:
            if priority.get(const.KEY_VISIBLE, False):
                return priority
        return None

    # =================================================================================
    # ** Priorites Autoselect **
    # Full State: https://docs.hyperion-project.org/en/json/ServerInfo.html#priorities-selection-auto-manual
    # Update: https://docs.hyperion-project.org/en/json/Subscribe.html#priority-updates
    # Set: https://docs.hyperion-project.org/en/json/Control.html#source-selection
    # =================================================================================

    @property
    def priorities_autoselect(self) -> bool | None:
        """Return priorites."""
        return self._get_serverinfo_value(const.KEY_PRIORITIES_AUTOSELECT)

    def _update_priorities_autoselect(self, priorities_autoselect: bool) -> None:
        """Update priorites."""
        if self._serverinfo is None or not isinstance(priorities_autoselect, bool):
            return
        self._serverinfo[const.KEY_PRIORITIES_AUTOSELECT] = priorities_autoselect

    async def async_send_set_sourceselect(self, *_: Any, **kwargs: Any) -> bool:
        """Request the sourceselect be set."""
        data = HyperionClient._set_data(
            kwargs, hard={const.KEY_COMMAND: const.KEY_SOURCESELECT}
        )
        return await self._async_send_json(data)

    async_set_sourceselect = AwaitResponseWrapper(async_send_set_sourceselect)

    # ================================================================================
    # ** Sessions **
    # Full State: https://docs.hyperion-project.org/en/json/ServerInfo.html#sessions
    # Update: https://docs.hyperion-project.org/en/json/Subscribe.html#session-updates
    # ================================================================================

    @property
    def sessions(self) -> list[dict[str, Any]] | None:
        """Return sessions."""
        return self._get_serverinfo_value(const.KEY_SESSIONS)

    def _update_sessions(self, sessions: list[dict[str, Any]]) -> None:
        """Update sessions."""
        if self._serverinfo is None or not isinstance(sessions, list):
            return
        self._serverinfo[const.KEY_SESSIONS] = sessions

    # =====================================================================
    # ** Serverinfo (full state) **
    # Full State: https://docs.hyperion-project.org/en/json/ServerInfo.html
    # =====================================================================

    @property
    def serverinfo(self) -> dict[str, Any] | None:
        """Return current serverinfo."""
        return self._serverinfo

    def _update_serverinfo(self, state: dict[str, Any] | None) -> None:
        """Update full Hyperion state."""
        self._serverinfo = state

    def _get_serverinfo_value(self, key: str) -> Any | None:
        """Get a value from serverinfo structure given key."""
        if not self._serverinfo:
            return None
        return self._serverinfo.get(key)

    async def async_send_get_serverinfo(self, *_: Any, **kwargs: Any) -> bool:
        """Server a serverinfo full state/subscription request."""
        # Request full state ('serverinfo') and subscribe to relevant
        # future updates to keep this object state accurate without the need to
        # poll.
        data = HyperionClient._set_data(
            kwargs,
            hard={
                const.KEY_COMMAND: const.KEY_SERVERINFO,
                const.KEY_SUBSCRIBE: [
                    f"{const.KEY_ADJUSTMENT}-{const.KEY_UPDATE}",
                    f"{const.KEY_COMPONENTS}-{const.KEY_UPDATE}",
                    f"{const.KEY_EFFECTS}-{const.KEY_UPDATE}",
                    f"{const.KEY_LEDS}-{const.KEY_UPDATE}",
                    f"{const.KEY_LED_MAPPING}-{const.KEY_UPDATE}",
                    f"{const.KEY_INSTANCE}-{const.KEY_UPDATE}",
                    f"{const.KEY_PRIORITIES}-{const.KEY_UPDATE}",
                    f"{const.KEY_SESSIONS}-{const.KEY_UPDATE}",
                    f"{const.KEY_VIDEOMODE}-{const.KEY_UPDATE}",
                ],
            },
        )
        return await self._async_send_json(data)

    async_get_serverinfo = AwaitResponseWrapper(async_send_get_serverinfo)

    # ==================================================================================
    # ** Videomode **
    # Full State: https://docs.hyperion-project.org/en/json/ServerInfo.html#video-mode
    # Update: https://docs.hyperion-project.org/en/json/Subscribe.html#videomode-updates
    # Set: https://docs.hyperion-project.org/en/json/Control.html#video-mode
    # ==================================================================================

    @property
    def videomode(self) -> str | None:
        """Return videomode."""
        return self._get_serverinfo_value(const.KEY_VIDEOMODE)

    def _update_videomode(self, videomode: str) -> None:
        """Update videomode."""
        if self._serverinfo:
            self._serverinfo[const.KEY_VIDEOMODE] = videomode

    async def async_send_set_videomode(self, *_: Any, **kwargs: Any) -> bool:
        """Request the LED mapping type be set."""
        data = HyperionClient._set_data(
            kwargs, hard={const.KEY_COMMAND: const.KEY_VIDEOMODE}
        )
        return await self._async_send_json(data)

    async_set_videomode = AwaitResponseWrapper(async_send_set_videomode)

    # ==================================================================================
    # ** Sysinfo **
    # Full State: https://docs.hyperion-project.org/en/json/ServerInfo.html#system-hyperion
    # Returns system information from the Hyperion instance.
    # ==================================================================================

    async def async_send_sysinfo(self, *_: Any, **kwargs: Any) -> bool:
        """Request the sysinfo."""
        data = HyperionClient._set_data(
            kwargs, hard={const.KEY_COMMAND: const.KEY_SYSINFO}
        )
        return await self._async_send_json(data)

    async_sysinfo = AwaitResponseWrapper(async_send_sysinfo)

    async def async_sysinfo_id(self) -> str | None:
        """Return an ID representing this Hyperion server."""
        sysinfo = await self.async_sysinfo()
        if sysinfo is not None and ResponseOK(sysinfo):
            sysinfo_id = (
                sysinfo.get(const.KEY_INFO, {})
                .get(const.KEY_HYPERION, {})
                .get(const.KEY_ID, None)
            )
            if not sysinfo_id or not isinstance(sysinfo_id, str):
                return None
            return str(sysinfo_id)
        return None

    async def async_sysinfo_version(self) -> str | None:
        """Return the Hyperion server version."""
        sysinfo = await self.async_sysinfo()
        if sysinfo is not None and ResponseOK(sysinfo):
            sysinfo_version = (
                sysinfo.get(const.KEY_INFO, {})
                .get(const.KEY_HYPERION, {})
                .get(const.KEY_VERSION, None)
            )
            if not sysinfo_version or not isinstance(sysinfo_version, str):
                return None
            return str(sysinfo_version)
        return None


class ThreadedHyperionClient(threading.Thread):
    """Hyperion Client that runs in a dedicated thread."""

    # pylint: disable=too-many-arguments
    def __init__(
        self,
        host: str,
        port: int = const.DEFAULT_PORT_JSON,
        default_callback: HyperionCallback | Iterable[HyperionCallback] | None = None,
        callbacks: dict[str, HyperionCallback | Iterable[HyperionCallback]]
        | None = None,
        token: str | None = None,
        instance: int = const.DEFAULT_INSTANCE,
        origin: str = const.DEFAULT_ORIGIN,
        timeout_secs: float = const.DEFAULT_TIMEOUT_SECS,
        retry_secs: int = const.DEFAULT_CONNECTION_RETRY_DELAY_SECS,
        raw_connection: bool = False,
    ) -> None:
        """Initialize client."""
        super().__init__()
        self._loop: asyncio.AbstractEventLoop = asyncio.new_event_loop()
        self._hyperion_client: HyperionClient | None = None

        self._client_init_call: Callable[[], HyperionClient] = lambda: HyperionClient(
            host,
            port,
            default_callback=default_callback,
            callbacks=callbacks,
            token=token,
            instance=instance,
            origin=origin,
            timeout_secs=timeout_secs,
            retry_secs=retry_secs,
            raw_connection=raw_connection,
        )
        self._client_init_event = threading.Event()

    def wait_for_client_init(self) -> None:
        """Block until the HyperionClient is ready to interact."""
        self._client_init_event.wait()

    async def _async_init_client(self) -> None:
        """Initialize the client."""
        # Initialize the client in the new thread, using the new event loop.
        # Some asyncio elements of the client (e.g. Conditions / Events) bind
        # to asyncio.get_event_loop() on construction.

        self._hyperion_client = self._client_init_call()

        for name, value in inspect.getmembers(
            self._hyperion_client, inspect.iscoroutinefunction
        ):
            if name.startswith("async_"):
                new_name = name[len("async_") :]
                self._register_async_call(new_name, value)
        for name, value in inspect.getmembers(
            type(self._hyperion_client), lambda o: isinstance(o, property)
        ):
            self._copy_property(name)

    def _copy_property(self, name: str) -> None:
        """Register a property."""
        setattr(
            type(self), name, property(lambda _: getattr(self._hyperion_client, name))
        )

    def _register_async_call(
        self, name: str, value: Callable[..., Awaitable[Any]]
    ) -> None:
        """Register a wrapped async call."""
        setattr(
            self,
            name,
            lambda *args, **kwargs: self._async_wrapper(value, *args, **kwargs),
        )

    def _async_wrapper(
        self, coro: Callable[..., Awaitable[Any]], *args: Any, **kwargs: Any
    ) -> Any:
        """Convert a async call to synchronous by running it in the local event loop."""
        future = asyncio.run_coroutine_threadsafe(coro(*args, **kwargs), self._loop)
        return future.result()

    def __getattr__(self, name: str) -> Any:
        """Override getattr to allow generous mypy treatment for dynamic methods."""
        return getattr(self, name)

    def stop(self) -> None:
        """Stop the asyncio loop and thus the thread."""

        def inner_stop() -> None:
            asyncio.get_event_loop().stop()

        self._loop.call_soon_threadsafe(inner_stop)

    def run(self) -> None:
        """Run the asyncio loop until stop is called."""
        asyncio.set_event_loop(self._loop)
        asyncio.get_event_loop().run_until_complete(self._async_init_client())
        self._client_init_event.set()
        asyncio.get_event_loop().run_forever()
        asyncio.get_event_loop().close()


class ResponseOK:
    """Small wrapper class around a server response."""

    def __init__(
        self,
        response: dict[str, Any] | None,
        cmd: str | None = None,
        validators: list[Callable[[dict[str, Any]], bool]] | None = None,
    ):
        """Initialize a Response object."""
        self._response = response
        self._cmd = cmd
        self._validators = validators or []

    def __bool__(self) -> bool:
        """Determine if the response indicates success."""
        if not self._response:
            return False
        if not isinstance(self._response, dict):
            return False
        if not self._response.get(const.KEY_SUCCESS, False):
            return False
        if self._cmd is not None and self._response.get(const.KEY_COMMAND) != self._cmd:
            return False
        for validator in self._validators:
            if not validator(self._response):
                return False
        return True


class ServerInfoResponseOK(ResponseOK):
    """Wrapper class for ServerInfo responses."""

    def __init__(self, response: dict[str, Any] | None):
        """Initialize the wrapper class."""
        super().__init__(
            response,
            cmd=const.KEY_SERVERINFO,
            validators=[lambda r: bool(r.get(const.KEY_INFO))],
        )


class LoginResponseOK(ResponseOK):
    """Wrapper class for LoginResponse."""

    def __init__(self, response: dict[str, Any] | None):
        """Initialize the wrapper class."""
        super().__init__(response, cmd=const.KEY_AUTHORIZE_LOGIN)


class SwitchInstanceResponseOK(ResponseOK):
    """Wrapper class for SwitchInstanceResponse."""

    def __init__(self, response: dict[str, Any] | None):
        """Initialize the wrapper class."""
        super().__init__(
            response,
            cmd=f"{const.KEY_INSTANCE}-{const.KEY_SWITCH_TO}",
            validators=[
                lambda r: r.get(const.KEY_INFO, {}).get(const.KEY_INSTANCE) is not None
            ],
        )


def generate_random_auth_id() -> str:
    """Generate random authenticate ID."""
    return "".join(
        random.choice(string.ascii_letters + string.digits) for i in range(0, 5)
    )