tdl-xoa-driver 1.0.0b1__py3-none-any.whl

xoa_driver/internals/core/interfaces.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+import typing as t
+if t.TYPE_CHECKING:
+    from asyncio import Future
+    from .transporter._typings import ICommand
+    from .transporter.protocol.struct_request import Request
+
+
+# The defenition of generic Types
+
+
+T_ = t.TypeVar("T_", covariant=True)
+
+
+class IsDataclass(t.Protocol):
+    __dataclass_fields__: t.Dict[str, t.Any]
+    def __init__(self, *args, **kwargs) -> None: ...  # noqa: E704
+
+
+Inst = t.TypeVar('Inst')
+CallbackType = t.Callable[[Inst, t.Optional[IsDataclass]], t.Awaitable[None]]
+
+
+class IConnection(t.Protocol):
+    """Representation of TransportationHandler"""
+
+    @property
+    def is_connected(self) -> bool:
+        ...
+
+    def send(self, data: bytes | bytearray | memoryview) -> None:
+        ...
+
+    def close(self) -> None:
+        ...
+
+    async def prepare_data(self, request: "Request") -> t.Tuple[bytes, "Future"]:
+        ...
+
+    def subscribe(self, xmc_cls: "ICommand", callback: "t.Callable") -> None:
+        ...
+
+    def on_disconnected(self, callback: "t.Callable") -> None:
+        ...
+
+    def set_outdated(self) -> None:
+        ...

xoa_driver/internals/core/token.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+from typing import (
+    Any,
+    Awaitable,
+    TypeVar,
+    # Generic,
+    Generator
+)
+from dataclasses import dataclass
+
+from . import interfaces
+from .transporter.protocol.struct_request import Request
+
+
+AwaitableDataType = TypeVar("AwaitableDataType", covariant=True)
+
+
+@dataclass(frozen=True)
+class Token(Awaitable[AwaitableDataType]):
+    """
+    A wrapper of connection and request.
+    Which can be used for await an single command or organized in to the ordered
+    sequence of the commands which will be send to the server in single request.
+    """
+    __slots__ = ('connection', 'request',)
+
+    connection: interfaces.IConnection
+    request: Request
+
+    def __await__(self) -> Generator[Any, None, AwaitableDataType]:
+        return self.__ask().__await__()
+
+    async def __ask(self) -> AwaitableDataType:
+        (
+            data,
+            fut
+        ) = await self.connection.prepare_data(self.request)
+        self.connection.send(data)
+        try:
+            result = await fut
+        except Exception as e:
+            raise e
+        else:
+            return result

xoa_driver/internals/core/transporter/_processor.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+import asyncio
+from typing import (
+    AsyncIterator,
+    Callable,
+    Type,
+)
+from collections import UserDict
+from . import registry
+from . import exceptions
+from ._typings import XoaCommandType
+from .protocol.struct_header import ResponseHeader
+from .protocol.struct_response import Response
+
+
+def create_response_obj(cmd: Type[XoaCommandType], header: ResponseHeader, data: bytes) -> Response:
+    """Parse bytes retrieved from server to Response structure."""
+    return Response(
+        class_name=cmd.__name__,
+        header=header,
+        buffer=data,
+        response_struct=getattr(cmd, "GetDataAttr", None)
+    )
+
+
+class CommandsCodeMapper(UserDict):
+    data: dict[int, int]
+
+    def add_code(self, req_id: int, cmd_code: int) -> None:
+        self.data[req_id] = cmd_code
+
+    def pop_code(self, req_id: int) -> int:
+        if command_idx := self.data.pop(req_id, None):
+            return command_idx
+        raise exceptions.RepeatedRequestID(req_id)
+
+
+Publisher = Callable[[Response], None]
+
+
+class PacketsProcessor:
+    """Process reading packets from he stream and create a response object for each packet"""
+
+    __slots__ = ("__stream", "__cm_mapper", "__evt_do_job", "__consumer", "__publish",)
+
+    def __init__(self, stream: AsyncIterator[tuple[ResponseHeader, bytes]], publish_func: Publisher) -> None:
+        self.__stream = stream
+        self.__cm_mapper = CommandsCodeMapper()
+        self.__evt_do_job = asyncio.Event()
+        self.__consumer: asyncio.Task | None = None
+        self.__publish = publish_func
+
+    @property
+    def is_running(self) -> bool:
+        return not (self.__consumer is None or self.__consumer.done())
+
+    def start(self) -> None:
+        if self.is_running:
+            return None
+        self.__evt_do_job.set()
+        self.__consumer = asyncio.create_task(self.__consume())
+
+    def stop(self) -> None:
+        if not self.is_running:
+            return None
+        self.__evt_do_job.clear()
+        self.__consumer.cancel()  # type: ignore[ReportOptionalMemberAccess]
+        self.__consumer = None
+
+    def register(self, req_id: int, cmd_code: int) -> None:
+        self.__cm_mapper.add_code(req_id=req_id, cmd_code=cmd_code)
+
+    async def __task(self, header: ResponseHeader, body_bytes: bytes) -> None:
+        command_idx = header.cmd_code if header.is_pushed else self.__cm_mapper.pop_code(header.request_identifier)
+        xmc_type = registry.get_command(command_idx)
+        response = create_response_obj(xmc_type, header, body_bytes)
+        self.__publish(response)
+
+    async def __consume(self) -> None:
+        async for header, body_bytes in self.__stream:
+            asyncio.create_task(self.__task(header, body_bytes))
+            if not self.__evt_do_job.is_set():
+                return None

xoa_driver/internals/core/transporter/_publisher.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+import asyncio
+
+from collections import (
+    UserDict,
+    defaultdict,
+)
+from functools import partialmethod
+from typing import (
+    Any,
+    Callable,
+    Coroutine,
+    Final
+)
+from . import exceptions
+from .protocol.struct_response import Response
+
+ON_EVT_DISCONNECTED: Final[int] = -1
+
+CB = Callable[..., Coroutine[Any, None, None]]
+
+
+class FuturesMapper(UserDict):
+    data: dict[tuple[int, str], asyncio.Future]
+
+    def make_future(self, req_id: int, cmd_name: str) -> asyncio.Future:
+        fut = asyncio.Future()
+        self.data[(req_id, cmd_name)] = fut
+        return fut
+
+    def pop_future(self, req_id: int, cmd_name: str) -> asyncio.Future:
+        fut = self.data.pop((req_id, cmd_name), None)
+        if not fut:
+            raise exceptions.XoaLostFuture(req_id, cmd_name)
+        return fut
+
+
+class EventsObserver:
+    __slots__ = ("__events",)
+
+    def __init__(self) -> None:
+        self.__events: dict[int, list[CB]] = defaultdict(list)
+
+    def dispatch(self, evt: int, *args, **kwargs) -> None:
+        for evt_func in self.__events.get(evt, []):
+            asyncio.create_task(
+                evt_func(*args, **kwargs)
+            ).add_done_callback(self.__handle_exceptions)
+
+    def __handle_exceptions(self, fut: asyncio.Future) -> None:
+        if fut.cancelled():
+            return None
+        elif e := fut.exception():
+            raise e
+
+    def subscribe(self, evt: int, func: CB) -> None:
+        self.__events[evt].append(func)
+
+
+class ResponsePublisher:
+    __slots__ = ("__futures_mapper", "__observer", "__logger")
+
+    def __init__(self, logger) -> None:
+        self.__logger = logger
+        self.__futures_mapper = FuturesMapper()
+        self.__observer = EventsObserver()
+
+    def register_request(self, req_id: int, cmd_name: str) -> asyncio.Future:
+        return self.__futures_mapper.make_future(req_id, cmd_name)
+
+    def subscribe(self, evt: int, func: CB) -> None:
+        self.__observer.subscribe(evt, func)
+
+    subscribe_connection_lost = partialmethod(subscribe, ON_EVT_DISCONNECTED)
+
+    def publish(self, response: Response) -> None:
+        if response.is_pushed:
+            self.__publish_push_response(response)
+        else:
+            self.__publish_param_response(response)
+
+    def publish_connection_lost(self, info) -> None:
+        self.__observer.dispatch(ON_EVT_DISCONNECTED, info)
+
+    def __publish_push_response(self, response: Response) -> None:
+        self.__observer.dispatch(
+            response.cmd_code,
+            response
+        )
+        self.__logger.debug_push(response)
+
+    def __publish_param_response(self, response: Response) -> None:
+        future = self.__futures_mapper.pop_future(
+            req_id=response.request_identifier,
+            cmd_name=response.class_name
+        )
+        if exception := response.get_error():
+            future.set_exception(exception)
+        else:
+            future.set_result(response.values)
+        self.__logger.debug_response(response)

xoa_driver/internals/core/transporter/_request_id_counter.py

@@ -0,0 +1,28 @@
+import asyncio
+from enum import IntEnum
+
+
+class ReservedRequestID(IntEnum):
+    PUSH_REQUEST = 0x0
+    REQUEST_ID_LIMIT = 0xFFFFFFFF
+
+    @classmethod
+    def started(cls) -> int:
+        return max(list(cls)[:-1]).value
+
+
+class RequestIdCounter:
+    """Aggrigator of request ID."""
+    __slots__ = ("__req_id", "__lock",)
+
+    def __init__(self) -> None:
+        self.__req_id = ReservedRequestID.started()
+        self.__lock = asyncio.Lock()
+
+    async def get_number(self) -> int:
+        async with self.__lock:
+            if self.__req_id >= ReservedRequestID.REQUEST_ID_LIMIT:
+                self.__req_id = ReservedRequestID.started()
+            else:
+                self.__req_id += 1
+            return self.__req_id

xoa_driver/internals/core/transporter/_stream.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+from asyncio import Future
+from typing import Generic
+from typing_extensions import Self
+from ._typings import HeaderType
+
+
+class StreamReader(Generic[HeaderType]):
+    __slots__ = ("_buffer", "_eof", "_waiter", "__header_struct")
+
+    def __init__(self, header_struct: type[HeaderType]) -> None:
+        self._buffer = bytearray()
+        self._eof = False  # Whether we're done.
+        self._waiter = None  # A future used by _wait_for_data()
+        self.__header_struct = header_struct
+
+    def __aiter__(self) -> Self:
+        return self
+
+    async def __anext__(self) -> tuple[HeaderType, bytes]:
+        try:
+            val = await self.read_pkt()
+        except EOFError:
+            raise StopAsyncIteration
+        else:
+            return val
+
+    def _wakeup_waiter(self) -> None:
+        waiter = self._waiter
+        if waiter is not None:
+            self._waiter = None
+            if not waiter.cancelled():
+                waiter.set_result(None)
+
+    async def _wait_for_data(self, func_name: str) -> None:
+        """Wait until feed_data() or feed_eof() is called.
+        If stream was paused, automatically resume it.
+        """
+        if self._waiter is not None:
+            raise RuntimeError(
+                f'{func_name}() called while another coroutine is '
+                f'already waiting for incoming data'
+            )
+
+        assert not self._eof, '_wait_for_data after EOF'
+
+        self._waiter = Future()
+        try:
+            await self._waiter
+        finally:
+            self._waiter = None
+
+    def feed_eof(self) -> None:
+        self._eof = True
+        self._wakeup_waiter()
+
+    def at_eof(self) -> bool:
+        """Return True if the buffer is empty and 'feed_eof' was called."""
+        return self._eof and not self._buffer
+
+    def feed_data(self, data: bytes) -> None:
+        assert not self._eof, 'feed_data after feed_eof'
+
+        if not data:
+            return None
+
+        self._buffer.extend(data)
+        self._wakeup_waiter()
+
+    async def readexactly(self, n: int) -> bytes:
+        if n < 0:
+            raise ValueError('readexactly size can not be less than zero')
+
+        if n == 0:
+            return b''
+
+        while len(self._buffer) < n:
+            if self._eof:
+                incomplete = bytes(self._buffer)
+                self._buffer.clear()
+                raise EOFError(incomplete, n)
+
+            await self._wait_for_data('readexactly')
+
+        if len(self._buffer) == n:
+            data = bytes(self._buffer)
+            self._buffer.clear()
+        else:
+            data = bytes(self._buffer[:n])
+            del self._buffer[:n]
+        return data
+
+    async def read_pkt(self) -> tuple[HeaderType, bytes]:
+        h_buff = await self.readexactly(self.__header_struct.size)
+        header = self.__header_struct.from_bytes(h_buff)
+        if not header:
+            raise ValueError("Invalid Header")
+        body_bytes = await self.readexactly(header.body_size)
+        return (header, body_bytes)

xoa_driver/internals/core/transporter/_typings.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+import typing as t
+from .protocol.payload.base_struct import (
+    RequestBodyStruct,
+    ResponseBodyStruct
+)
+from .protocol.struct_header import ResponseHeader
+from ..token import Token
+
+
+# The defenition of generic Types
+
+HeaderType = t.TypeVar("HeaderType", bound="ResponseHeader", covariant=True)
+T_ = t.TypeVar("T_", covariant=True)
+
+
+class IsDataclass(t.Protocol):
+    __dataclass_fields__: t.Dict[str, t.Any]
+    def __init__(self, *args, **kwargs) -> None: ...  # noqa: E704
+
+
+class ICommand(t.Protocol):
+    code: t.ClassVar[int]
+    pushed: t.ClassVar[bool]
+
+
+SetStructType = t.TypeVar("SetStructType", bound="RequestBodyStruct", covariant=True)
+GetStructType = t.TypeVar("GetStructType", bound="ResponseBodyStruct", covariant=True)
+
+
+class ICmdOnlySet(ICommand, t.Protocol):
+    """A template class which provide only <cmd_set> method."""
+    SetDataAttr: t.Type[SetStructType]  # type: ignore
+    set: t.Callable[..., Token[None]]
+
+
+class ICmdOnlyGet(ICommand, t.Protocol):
+    """A template class which provide only <cmd_get> method."""
+    GetDataAttr: t.Type[GetStructType]  # type: ignore
+    get: t.Callable[[], Token[GetStructType]]  # type: ignore
+
+
+XoaCommandType = t.Union[ICmdOnlySet, ICmdOnlyGet]

xoa_driver/internals/core/transporter/exceptions.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+
+class XoaException(Exception):
+    ...
+
+
+class TransporterException(XoaException):
+    ...
+
+
+class XoaConnectionTimeoutError(XoaException):
+    def __init__(self, host: str, port: int, seconds_timeout: int) -> None:
+        self.host = host
+        self.port = port
+        self.seconds_timeout = seconds_timeout
+        self.msg = f"Can't establish the connect to {host}:{port}, in period of {seconds_timeout} sec."
+        super().__init__(self.msg)
+
+
+class XoaConnectionError(XoaException):
+    def __init__(self, host: str, port: int) -> None:
+        self.host = host
+        self.port = port
+        self.msg = f"Can't connect to {host}:{port}"
+        super().__init__(self.msg)
+
+
+class RepeatedRequestID(TransporterException):
+    def __init__(self, request_identifier: int,) -> None:
+        self.msg = f"""
+        Got repeated request id {request_identifier}.
+        This is a bug of xenaserver returning the same request identifier twice.
+        """
+        self.request_identifier = request_identifier
+        super().__init__(self.msg)
+
+
+class XoaLostFuture(XoaException):
+    def __init__(self, req_id: int, cls_name: str) -> None:
+        self.req_id = req_id
+        self.cls_name = cls_name
+        self.msg = f"Command was sent but the response handler was not registered {req_id} {cls_name}."
+        super().__init__(self.msg)

xoa_driver/internals/core/transporter/handler.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+import asyncio
+from typing import Callable
+from uuid import uuid4
+from .logger import (
+    TransportationLogger,
+    CustomLogger
+)
+from .protocol.struct_request import Request
+from .protocol.struct_header import ResponseHeader
+from ._request_id_counter import RequestIdCounter
+from ._stream import StreamReader
+from ._processor import PacketsProcessor
+from ._publisher import ResponsePublisher
+from ._typings import ICommand
+
+
+class TransportationHandler(asyncio.Protocol):
+    """Handling sending and receiving of the XMP commands."""
+
+    __slots__ = (
+        "identity",
+        "peername",
+        "__log",
+        "__transport",
+        "__id_counter",
+        "__stream",
+        "__resp_publisher",
+        "__pkt_processor"
+    )
+
+    def __init__(self, *, enable_logging: bool = False, custom_logger: CustomLogger | None = None) -> None:
+        self.identity = uuid4().hex[:6]
+        self.peername: tuple[str, int] | None = None
+        self.__transport: asyncio.Transport | None = None
+        self.__id_counter = RequestIdCounter()
+        self.__log = TransportationLogger(
+            cid=self.identity,
+            enabled=enable_logging,
+            logger=custom_logger
+        )
+        self.__stream = StreamReader(header_struct=ResponseHeader)
+        self.__resp_publisher = ResponsePublisher(logger=self.__log)
+        self.__pkt_processor = PacketsProcessor(
+            stream=self.__stream,
+            publish_func=self.__resp_publisher.publish
+        )
+
+    @property
+    def is_connected(self) -> bool:
+        return not (self.__transport is None or self.__transport.is_closing())
+
+    def connection_made(self, transport: asyncio.Transport) -> None:
+        self.__transport = transport
+        self.peername = transport.get_extra_info("peername")
+        self.__pkt_processor.start()
+        self.__log.info(f"Connected to {self.peername}")
+
+    def data_received(self, data: bytes) -> None:
+        """Process received data from xenaserver."""
+        try:
+            self.__stream.feed_data(data)
+        except AssertionError:
+            if self.is_connected:
+                self.__stream._eof = False
+                self.__stream.feed_data(data)
+            else:
+                self.close()
+
+    def eof_received(self) -> None:
+        self.__stream.feed_eof()
+        self.__log.info("EOF received")
+
+    def connection_lost(self, exc: Exception | None) -> None:
+        self.__resp_publisher.publish_connection_lost(self.peername)
+        self.__transport = None
+        self.__pkt_processor.stop()
+        if exc:
+            self.__log.error(exc)
+        else:
+            self.__log.info(f"The server {self.peername} closed the connection")
+
+    def send(self, data: bytes | bytearray | memoryview) -> None:
+        """
+        Send applied commands from sending queue to
+        xenaserver and liberate the sending queue.
+        """
+        if not self.is_connected:
+            raise BrokenPipeError("No socket!")
+        self.__transport.write(data)  # type: ignore[reportOptionalMemberAccess]
+
+    def close(self) -> None:
+        """Close connection with xenaserver."""
+        if self.is_connected:
+            self.__transport.close()  # type: ignore[reportOptionalMemberAccess]
+        self.__transport = None
+
+    async def prepare_data(self, request: Request) -> tuple[bytes, asyncio.Future]:
+        assert self.is_connected, "Cannot add command because Socket is disconnected"
+        request_id_ = await self.__id_counter.get_number()
+        request.update_identifier(request_id_)
+        self.__pkt_processor.register(
+            req_id=request_id_,
+            cmd_code=request.cmd_code
+        )
+        fut_ = self.__resp_publisher.register_request(
+            req_id=request_id_,
+            cmd_name=request.class_name
+        )
+        self.__log.debug_request(request)
+        return bytes(request), fut_
+
+    def subscribe(self, xmc_cls: ICommand, callback: Callable) -> None:
+        """Register the callback on the command which supports Server PUSH notification."""
+        assert xmc_cls.pushed, "Command is not subscribable."
+        assert callback, "Callback function is required."
+        self.__resp_publisher.subscribe(
+            evt=xmc_cls.code,
+            func=callback
+        )
+
+    def on_disconnected(self, callback: Callable) -> None:
+        """Regiser users callback which will be called after connection was terminated."""
+        self.__resp_publisher.subscribe_connection_lost(callback)
+
+    def set_outdated(self) -> None:
+        pass

xoa_driver/internals/core/transporter/logger/__init__.py

@@ -0,0 +1,10 @@
+from .__logger import (
+    TransportationLogger,
+    CustomLogger
+)
+
+
+__all__ = (
+    "TransportationLogger",
+    "CustomLogger",
+)